Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 7 additions & 4 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ copy, when a contract changes.
| API callers, credentials and route inventory | [API index](docs/api/README.md) |
| Public wire types and qualified behavior | [Agents API contracts](contracts/agents-api/README.md), [pinned upstream](contracts/agents-api/upstream.json), and linked operation contracts |
| Core service implementation constraints | [Agents API implementation constraints](services/agents-api/IMPLEMENTATION.md) and [service README](services/agents-api/README.md) |
| Provider-to-Runtime startup input | [Runtime bootstrap](docs/runtime-bootstrap.md) and `internal/runtimebootstrap` |
| Runtime messages, Executor/Turn lifetimes, receipts and failure ownership | [Core–Runtime protocol](docs/runtime-protocol.md) and `internal/agentdaemon/proto` |
| Environment ownership and capability preparation (Skills, Plugins, MCP, `packages.system`) | [Environments](contracts/agents-api/environments.md) |
| Adding a Harness (steps) | [Harness onboarding](contracts/agents-api/harness-onboarding.md), `apps/parsar-daemon/internal/agent/harness.go` and `internal/harnessconfig/harness.go` |
Expand Down Expand Up @@ -205,14 +206,18 @@ The Runtime is not a sandbox; see
Environment source. Platform support requires native CI builds and automated
tests; cross-compilation alone is insufficient.
- Evolve shared contracts and their implementations together, document
ownership and validate the same contract across implementations. This rule
ownership and validate the same contract across implementations. Each rule has
one authored definition; cross-language projections are generated from it or
checked against common fixtures. Bootstrap credentials use the Runtime-owned
launch input, never a Provider-authored private auth file. This rule
does not claim every implementation already meets every target, change the
pinned public API, or authorize unrelated refactors.

### Extension contracts

| Boundary | Canonical guide | Code entry point |
| --- | --- | --- |
| Provider–Runtime startup | [Runtime bootstrap](docs/runtime-bootstrap.md) | `internal/runtimebootstrap` |
| Core–Runtime wire | [Core–Runtime protocol](docs/runtime-protocol.md) | `internal/agentdaemon/proto` |
| Harness | [Harness onboarding](contracts/agents-api/harness-onboarding.md) | `apps/parsar-daemon/internal/agent/harness.go`, `internal/harnessconfig/harness.go` |
| Sandbox Provider | [Sandbox Provider guide](docs/sandbox-provider.md) | `services/agents-api/internal/sandbox/sandbox_provider.go` |
Expand Down Expand Up @@ -359,9 +364,7 @@ The dormant Pi adapter keeps its `parsar` provider slug because the separate
Parsar product pins model selections to that identity. This is a product
boundary exception for the name guard, like the skill-upload integration.

Build the MiniMax companion from this revision's patched native sources when
packaging a renamed Runtime. An older companion still uses the old
model-provider, workspace and subagent names and cannot be reused.
Build the MiniMax companion from this revision's pinned patched native sources.

## Branding

Expand Down
1 change: 1 addition & 0 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,7 @@ check-go:
check-runtime-contract:
go test ./internal/agentdaemon/proto ./internal/agentdaemon/gateway ./apps/parsar-daemon/internal/transport ./apps/parsar-daemon/internal/dispatch ./apps/parsar-daemon/internal/contracttest -count=1
go test ./services/agents-api/internal/execution -run '^TestRuntimeProtocol' -count=1
go test ./apps/parsar-daemon/internal/agent/... -run '^TestSharedTextLifecycle$$' -count=1

build-daemon:
@set -e; output="$${OAC_DEV_HOME:-$$HOME/.oac}/build/daemon"; \
Expand Down
2 changes: 1 addition & 1 deletion apps/docs/content/docs/bootstrap-projects-keys.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ The console endpoint and the public application endpoint serve different purpose
even if they share a host.

Use the [installation guide](/install) for deployment and the
[operations guide](/troubleshooting) for storage, upgrades and node
[operations guide](/troubleshooting) for storage, same-release repair and node
management. A Core, Web and PostgreSQL installation may have zero execution nodes.
Opening the console neither allocates compute nor invokes a model. Deployment
sandbox management selects E2B, Docker or microsandbox independently of an
Expand Down
11 changes: 5 additions & 6 deletions apps/docs/content/docs/configure.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -177,9 +177,9 @@ Same-team E2B template, resource and key changes apply online through the Core A
new allocations use the new generation, while existing sandboxes retain their
original specification. Omit the key to preserve it; explicitly submitting a key,
even the same value, verifies the replacement and advances the generation. Keep the
old key valid until the update succeeds. Initial setup requires a team-owned template;
a legacy public-template configuration or an already revoked old key requires reset
when Core cannot verify the committed ownership anchor.
old key valid until the update succeeds. Initial setup requires a team-owned template.
If Core cannot verify the committed ownership anchor, reset the deployment before
setting it up again.

Docker and microsandbox size/Runtime edits advance the target generation online.
They require neither zero held resources nor node retirement or reenrollment.
Expand All @@ -190,9 +190,8 @@ preparing or has failed. Target rollout and serving readiness are separate facts
Use **System** → **Sandbox backend** → **Change resources** to edit the target;
**Nodes** owns node management and readiness.

Current Runtime generation coexistence and ownership-scoped garbage collection
remain supported. They do not upgrade the installed node program or convert an old
installation. History stays, and existing Sessions never move between providers.
Runtime generation coexistence and ownership-scoped garbage collection operate
within the installed node release. Existing Sessions retain their placement and history.
See the [nodes guide](/hosted-providers#change-the-sandbox-backend-or-size),
[operator reference](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/services/agents-api/HOSTED-SANDBOX-MANAGER.md#removal-and-reset)
and [deployment contract](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/sandbox-deployment.md).
Expand Down
2 changes: 2 additions & 0 deletions apps/docs/content/docs/development.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,7 @@ site; `pnpm dev:docs` starts its development server.
| `services/agents-api/internal/execution` | Durable Turn dispatch and scheduling | [Runtime protocol](/runtime-protocol) |
| `services/agents-api/internal/engine` | Pure qualification of harness operations and placements | [Harness onboarding](/harness-onboarding) |
| `internal/agentdaemon/proto` and `gateway` | Shared wire types, validators and authenticated Runtime connections | [Runtime protocol](/runtime-protocol) |
| `internal/runtimebootstrap` | Provider-to-Runtime startup input | [Runtime bootstrap](/runtime-bootstrap) |
| `apps/parsar-daemon/internal/dispatch` | Runtime preparation, Executor reuse, Turn and cleanup ownership | [Harness lifecycle](/harness-onboarding#required-adapter-interfaces) |
| `apps/parsar-daemon/internal/agent` | Native harness adapters | [Native references](/harness-onboarding#native-references) |
| `services/agents-api/internal/sandbox` | Provider interfaces and managed compute lifecycle | [Provider onboarding](/sandbox-provider) |
Expand All @@ -112,6 +113,7 @@ only helps you pick the right one.
| --- | --- | --- |
| Harness adapter | A native agent engine behind the Runtime | [Harness onboarding](/harness-onboarding) |
| Sandbox Provider | Outer compute that creates and reclaims Environments | [Sandbox Provider guide](/sandbox-provider) |
| Runtime bootstrap | Starting a managed Runtime with its connection identity | [Runtime bootstrap](/runtime-bootstrap) |
| Core–Runtime protocol | A message, receipt or lifecycle rule between Core and the daemon | [Core–Runtime protocol](/runtime-protocol) |
| Public API operation | A `/v1`, `/core/v1` or `/api/v1` route | [API index](/public-api) and [contracts](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/README.md) |
| Environment capability | Skills, Plugins, MCP or `packages.system` preparation | [Environments](/environments-and-files#runtime-capability-preparation) |
Expand Down
13 changes: 5 additions & 8 deletions apps/docs/content/docs/environments-and-files.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -143,9 +143,8 @@ Mixed events and non-text input remain unsupported. Local capability directories
use the same Runtime parser and installed snapshot as managed Skills and Plugins;
preparation must finish before native execution. Reconnect reuses installed bytes,
while new Sessions capture their own sources. Directory aliases and protected Runtime
state are rejected. The current implementation uses the packaged Linux Runtime
layout; cross-platform installation and isolation are not part of this profile.
The public field types are unchanged. Enrollment must match either the `/workspace`
state are rejected. Platform support and isolation follow
[Platforms and isolation](#platforms-and-isolation). Enrollment must match either the `/workspace`
logical alias or the exact canonical directory bound by the Runtime; selecting an
arbitrary path does not grant access. `remote_url` is the configured daemon WebSocket URL,
returned unchanged. This is our private connection contract and does not claim
Expand Down Expand Up @@ -189,7 +188,7 @@ compute replacement; never silently move a bound Session or replay unknown work.
Self-hosted compute/files remain caller-owned, with explicit cleanup separate from
Session deletion. The full Environment implementation remains pending; follow the
[pinned contract and acceptance sequence](/environments-and-files)
and the [two-engine placement prerequisites](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/workspace-placement.md).
and the [workspace placement map](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/workspace-placement.md).
For co-location, qualify the outer deployment boundary and the shared Runtime
lifecycle. Native tools use the starting account's permissions; do not claim a
daemon or harness sandbox. Host operators choose their own outer isolation.
Expand Down Expand Up @@ -483,10 +482,8 @@ tools, files or network access. Outer Environments own managed isolation, and
unsupported network restrictions reject instead of silently running unrestricted.

Native installation and validation limits are in the
[native guide](/self-hosted-native). No project-version upgrade or
historical manifest compatibility is introduced. These rules do not establish
new real-deployment acceptance; historical evidence stays limited to its
recorded binaries and inputs.
[native guide](/self-hosted-native). Historical acceptance evidence
stays limited to its recorded binaries and inputs.

### Allocation initialization lifecycle

Expand Down
16 changes: 12 additions & 4 deletions apps/docs/content/docs/harness-onboarding.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,12 @@ model communication configuration, not Turn scheduling or native process ownersh
the [qualification table](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/harnesses.md#current-qualified-operations).

Start with the mandatory text lifecycle, then qualify optional operations one at
a time. Do not copy an adapter's native limitations into the shared Core protocol.
a time. Call the reusable `agent/contracttest.TextLifecycle` assertions with the
adapter's prepared Executor and deterministic native fixture. These assertions
cover healthy reuse, durable input and cancellation; keep native fault and live
acceptance separate. Name the entry test `TestSharedTextLifecycle` so
`make check-runtime-contract` includes it. Do not copy an adapter's native
limitations into the shared Core protocol.

## Architecture rules

Expand Down Expand Up @@ -215,12 +220,15 @@ never attribute a late result to whichever Turn is currently active.
Initial input and steering use ordered `proto.MessageInput`. Preserve user-message
and content order. Text-only adapters reject images through `TextOnly()` instead
of dropping them. A successful transport write is distinct from confirmed native
application. Resume only the exact history bound to the Session; missing or
ambiguous required history fails before new model input.
application. User-choice answers use the emitted question ID and an array of
values; shared `PromptForUserChoiceDecisionPayload.AnswersFor` validates identity
before consuming a pending interaction. Do not map answers by header or position.
Resume only the exact history bound to the Session; missing or ambiguous required
history fails before new model input.

| Interface or contract | When required | Obligation |
| --- | --- | --- |
| `agent.DurableSteerer` | Current public text execution | Distinguish write and application receipts; preserve retry identity |
| `agent.DurableSteerer` | Current public text execution | Distinguish write and application receipts; preserve retry identity; independent of the optional non-durable `Steerer` |
| `agent.FunctionResultSubmitter` | Public function tools | Match call/result identity and acknowledge native application |
| `agent.PermissionResponder`, `agent.UserChoiceResponder` | When emitting these interactions | Route exact identities and settle receipts |
| `agent.WorkspaceReader`, `agent.WorkspaceDirectoryLister`, `agent.WorkspaceWriter` | Qualified workspace operations | Use the fixed authorized workspace and retain accepted operations through close |
Expand Down
10 changes: 4 additions & 6 deletions apps/docs/content/docs/hosted-providers.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -268,12 +268,10 @@ describes reset and API behavior. Same-team E2B edits have a separate online Cor
API path and do not involve node installation.


## Historical node installations
## Installation scope

An older node installation is unsupported by the current installer. Retained state
under the old `parsar-node` names is a refusal condition, not an invitation to
convert or delete it. Preserve the old installation, Runtime resources and history;
provision a fresh node separately through **Add node**. The current installer does
not adopt historical resources or remove another installation's state.
Nodes and Core must come from the same distribution. Provision nodes through
**Add node**; the installer never adopts or removes another installation's
resources. See the [installation version policy](/troubleshooting#installation-version-policy).

[Repository source](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/docs/getting-started/nodes.md)
1 change: 1 addition & 0 deletions apps/docs/content/docs/meta.json
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@
"---Development---",
"development",
"harness-onboarding",
"runtime-bootstrap",
"runtime-protocol",
"sandbox-provider"
]
Expand Down
2 changes: 1 addition & 1 deletion apps/docs/content/docs/public-api.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ public release content.
| --- | --- | --- | --- | --- |
| `/v1` | Applications (business systems, SDKs) | Project API key | Exactly the pinned official Agents API routes. Core-only fields live only in `x_agents_core` (`harness`, `model_provider`, `harness_config`, Session `installation`) | [Agents API guide](/sessions) |
| `/core/v1` | Core Web's server and operator scripts | [Core key](/troubleshooting#core-key) | Installation facts, Projects and keys, resource reads and deletion, Session archive, credential issuance, metrics, audit, sandbox deployment and nodes, deployment model providers | [Core API](#core-api), [Web API](/admin-api), [Core OpenAPI](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/core.openapi.yaml) |
| `/api/v1` | Nodes, Runtime daemons, self-hosted executors | Machine credentials: short-lived Session installation grants, node enrollment tokens and executor credentials issued through `/core/v1` or claimed by installation, node credentials registered with an enrollment token, and daemon credentials Core writes into hosted sandboxes | Machine bootstrap and connections: `/api/v1/sandbox-node/*` and `/api/v1/agent-daemon/*`, including WebSockets; each credential works only on its own routes | [Node operations](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/services/agents-api/HOSTED-SANDBOX-MANAGER.md#register-a-host), [executor credentials](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/environment-executor-credentials.md), [machine OpenAPI](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/runtime.openapi.yaml) |
| `/api/v1` | Nodes, Runtime daemons, self-hosted executors | Machine credentials: short-lived Session installation grants, node enrollment tokens and executor credentials issued through `/core/v1` or claimed by installation, node credentials registered with an enrollment token, and daemon credentials Core issues for hosted sandboxes | Machine bootstrap and connections: `/api/v1/sandbox-node/*` and `/api/v1/agent-daemon/*`, including WebSockets; each credential works only on its own routes | [Node operations](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/services/agents-api/HOSTED-SANDBOX-MANAGER.md#register-a-host), [executor credentials](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/environment-executor-credentials.md), [machine OpenAPI](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/runtime.openapi.yaml) |

A credential used in another namespace gets 401: a Project API key on `/core/v1` or
`/api/v1`, the Core key on `/v1` or `/api/v1`. How Projects and keys behave is in
Expand Down
Loading
Loading