@mutagent/sdk 0.5.12 → 0.5.13

package/dist/commonjs/sdk/sandbox.d.ts

@@ -6,247 +6,135 @@ export declare class Sandbox extends ClientSDK {
      * List sandbox providers
      *
      * @remarks
-     * Providers this backend can reach and which is the default. A CLI that has no provider configured uses the default.
+     * Sandbox providers this server can use, and the default. A launch that names no sandbox provider uses the default.
      */
-    getApiSandboxProviders(options?: RequestOptions): Promise<operations.GetApiSandboxProvidersResponse>;
+    listSandboxProviders(options?: RequestOptions): Promise<models.SandboxProviderList>;
     /**
      * Preflight a sandbox definition
      *
      * @remarks
-     * Validate a definition against a provider without creating anything. Returns every violation, not just the first.
+     * Validate a sandbox definition against a sandbox provider without creating anything. Returns every violation, not just the first.
      */
-    postApiSandboxPreflight(request: models.DefinitionProvider, options?: RequestOptions): Promise<operations.PostApiSandboxPreflightResponse>;
+    preflightSandbox(request: models.SandboxPreflightRequest, options?: RequestOptions): Promise<models.SandboxPreflightResult>;
     /**
      * List sandbox presets
      *
      * @remarks
-     * Named definitions a one-shot run can name. A preset is what lets a caller run something without knowing our registry, region or image tag. Image references are deliberately not returned.
+     * Named sandbox definitions that a launch (`preset`) or a single-command run can use. Image references are not returned.
      */
-    getApiSandboxPresets(options?: RequestOptions): Promise<operations.GetApiSandboxPresetsResponse>;
+    listSandboxPresets(options?: RequestOptions): Promise<models.SandboxPresetList>;
     /**
      * Run one command in a fresh sandbox
      *
      * @remarks
-     * Spawns from a preset, runs the command, tears the sandbox down. Requires an operator token — a one-shot run creates a sandbox. 200, not 201: the durable outcome is a result, and the sandbox it names is already gone unless `keep` was set. Blocking, and therefore bounded by the provider invocation timeout — long or interactive runs belong on POST /api/sandbox + /:id/exec.
+     * A single-command run: starts a sandbox from a preset, runs the command and deletes the sandbox. Requires an operator token. Returns 200 with the command result; the sandbox is already deleted unless `keep` is true. The call blocks and is limited by the sandbox provider's invocation timeout; for long commands, create a sandbox with `POST /api/sandbox` and call `POST /api/sandbox/{id}/exec`.
      */
-    postApiSandboxRun(request: models.PresetTimeoutMsKeep, options?: RequestOptions): Promise<operations.PostApiSandboxRunResponse>;
+    runSandboxCommand(request: models.SandboxRunRequest, options?: RequestOptions): Promise<models.SandboxRunResult>;
     /**
      * Spawn a sandbox
      *
      * @remarks
      * Requires an operator token. A session or task token is rejected with 403.
      */
-    postApiSandbox(request: models.DefinitionRunId, options?: RequestOptions): Promise<operations.PostApiSandboxResponse>;
+    createSandbox(request: models.SandboxSpawnRequest, options?: RequestOptions): Promise<models.Sandbox>;
     /**
      * List sandboxes
      *
      * @remarks
      * Always tenant-scoped. There is no unscoped listing path.
      */
-    getApiSandbox(options?: RequestOptions): Promise<Array<operations.GetApiSandboxResponse>>;
+    listSandboxes(options?: RequestOptions): Promise<Array<models.Sandbox>>;
     /**
      * Get sandbox status
      */
-    getApiSandboxById(request: operations.GetApiSandboxByIdRequest, options?: RequestOptions): Promise<operations.GetApiSandboxByIdResponse>;
+    getSandbox(request: operations.GetSandboxRequest, options?: RequestOptions): Promise<operations.GetSandboxResponse>;
     /**
      * Tear down a sandbox
      *
      * @remarks
-     * Idempotent. The record is forgotten even if the provider teardown fails.
+     * Idempotent. The sandbox record is deleted even when the sandbox provider fails to stop the sandbox.
      */
-    deleteApiSandboxById(request: operations.DeleteApiSandboxByIdRequest, options?: RequestOptions): Promise<operations.DeleteApiSandboxByIdResponse>;
+    deleteSandbox(request: operations.DeleteSandboxRequest, options?: RequestOptions): Promise<operations.DeleteSandboxResponse>;
     /**
      * Watch a sandbox's output live
      *
      * @remarks
-     * Server-sent events: `stdout`, `stderr`, `rpc`, `unrecognised`, `session`, `live`, `status`, `ping` (every 15s), `error`. `rpc` carries one complete NDJSON frame from a Helix session running in RPC mode, verbatim — parse it client-side. `unrecognised` carries a line the backend could not classify; receiving one means this server and the sandbox image disagree about the protocol, and it is forwarded rather than dropped so that drift is visible instead of silent. Those four output events share the `{seq, ts, text}` shape and one sequence counter, so their interleaving is the order the box produced them. `session` shares that counter too but carries flat fields instead of `text` — `{sessionId, status: "started"|"exited", exitCode, lastSeq, generation}` — and is how a client learns a Helix session began or ended; it is persisted and replayed like any output event, and `exitCode` is the session's real code (the terminal `status` event describes the SANDBOX and reports null by contract). `live` is emitted at most once, before the opening `status`, and only when this instance cannot follow the sandbox: it replays the log and ends rather than tailing. `seq` is monotonic per sandbox and starts at 1, and every seq-bearing event also carries it as the SSE `id:` field; pass the last one seen as `?since=` to resume. A resume is served from the persisted event log first and the live buffer only for the tail, so it survives a restart and can be answered by an instance that never spawned the box. If the requested range has been TRIMMED from that log, an `error` event names the lost range rather than skipping it silently — it carries `code: 'gap'` with the inclusive `from`/`to` wire seqs, and the stream continues past the gap; a source failure instead carries `code: 'upstream'` and is the end of the stream. Branch on `code`, never on `message`. Disconnecting tears down the upstream.
+     * Server-sent events: `stdout`, `stderr`, `rpc`, `unrecognised`, `session`, `live`, `status`, `ping` (every 15s), `error`. `rpc` carries one JSON line from an interactive Helix session, unchanged; parse it client-side. The event is named after the JSON-lines RPC protocol Helix speaks on stdin and stdout, not after the session mode. `unrecognised` carries a line the backend could not classify; receiving one means this server and the sandbox image disagree about the protocol, and it is forwarded unchanged. Those four output events share the `{seq, ts, text}` shape and one sequence counter, so their order is the order the sandbox produced them. `session` shares that counter too but carries flat fields instead of `text` — `{sessionId, status: "started"|"exited", exitCode, lastSeq, generation}` — and is how a client learns a Helix session began or ended; it is persisted and replayed like any output event, and `exitCode` is the session's real code (the final `status` event describes the sandbox, and its `exitCode` is null). `live` is emitted at most once, before the opening `status`, and only when this instance cannot follow the sandbox: it replays the log and ends rather than tailing. `seq` is monotonic per sandbox and starts at 1, and every seq-bearing event also carries it as the SSE `id:` field; pass the last one seen as `?since=` to resume. A resume is served from the persisted event log first and the live buffer only for the tail, so it survives a restart and can be answered by an API instance that did not start the sandbox. If the requested range has been TRIMMED from that log, an `error` event names the lost range rather than skipping it silently — it carries `code: 'gap'` with the inclusive `from`/`to` wire seqs, and the stream continues past the gap; a source failure instead carries `code: 'upstream'` and is the end of the stream. Use `code`, not `message`, to tell errors apart. Disconnecting closes the stream.
      */
-    getApiSandboxByIdStream(request: operations.GetApiSandboxByIdStreamRequest, options?: RequestOptions): Promise<operations.GetApiSandboxByIdStreamResponse>;
+    streamSandbox(request: operations.StreamSandboxRequest, options?: RequestOptions): Promise<string>;
     /**
      * Run a command in a sandbox
      *
      * @remarks
-     * Returns the command's real exit code. A task token is rejected — in-sandbox code reports on itself, it does not drive the box. With `?stream=1` the same result comes back as the event stream of `GET /:id/stream`, scoped to this one invocation and terminated by a `status` event carrying the exit code.
+     * Returns the command's real exit code. A task token is refused with 403. With `?stream=1` the same result comes back as the event stream of `GET /:id/stream`, scoped to this one invocation and terminated by a `status` event carrying the exit code.
      */
-    postApiSandboxByIdExec(request: operations.PostApiSandboxByIdExecRequest, options?: RequestOptions): Promise<operations.PostApiSandboxByIdExecResponse>;
+    execSandboxCommand(request: operations.ExecSandboxCommandRequest, options?: RequestOptions): Promise<models.SandboxExecResult>;
     /**
      * Ingest OTLP spans from inside a sandbox
      *
      * @remarks
      * OTLP/HTTP JSON. Requires a task token; spans are attributed to the sandbox the token is bound to, never to the sandbox named in the payload.
      */
-    postApiSandboxTelemetryV1Traces(options?: RequestOptions): Promise<operations.PostApiSandboxTelemetryV1TracesResponse>;
+    ingestSandboxTraces(options?: RequestOptions): Promise<operations.IngestSandboxTracesResponse>;
     /**
      * Read a sandbox's captured spans
      */
-    getApiSandboxByIdTraces(request: operations.GetApiSandboxByIdTracesRequest, options?: RequestOptions): Promise<operations.GetApiSandboxByIdTracesResponse>;
-    /**
-     * List workspace Environments
-     *
-     * @remarks
-     * Every Environment in the token's workspace: its name, the names of its variables and secrets with a `sha256(value)[:8]` fingerprint each, and timestamps. No value is ever returned — compare fingerprints to tell whether what you hold is what is stored. Environments carry the variables and secrets an agent's TOOLS need; LLM provider credentials are `/api/providers`, a different thing. 503 when the deployment has not migrated the table.
-     */
-    getApiSandboxEnvironments(options?: RequestOptions): Promise<operations.GetApiSandboxEnvironmentsResponse>;
-    /**
-     * Describe one workspace Environment
-     *
-     * @remarks
-     * Names and fingerprints only — the same shape as one entry of the list. 404 for a name this workspace does not have, including one another workspace does.
-     */
-    getApiSandboxEnvironmentsByName(request: operations.GetApiSandboxEnvironmentsByNameRequest, options?: RequestOptions): Promise<models.NameVarsSecrets>;
-    /**
-     * Create or replace a workspace Environment
-     *
-     * @remarks
-     * The whole Environment. Entries the body omits are REMOVED, secrets included. Values are accepted here and never returned by any route; secrets are encrypted at rest with the same key as provider credentials. Names: Environment `^[A-Za-z0-9._-]{1,64}$`, variables `^[A-Z_][A-Z0-9_]*$`, 64 KiB per Environment. 409 for a variable named like a harness provider key unless `?allowProviderKey=1`.
-     */
-    putApiSandboxEnvironmentsByName(request: operations.PutApiSandboxEnvironmentsByNameRequest, options?: RequestOptions): Promise<models.NameVarsSecrets>;
-    /**
-     * Set or unset entries of a workspace Environment
-     *
-     * @remarks
-     * Merges into the existing Environment: a string value sets the entry, `null` unsets it, entries not mentioned stay. Creates the Environment when it does not exist yet, so `mutagent env set` is one step. Same rules and the same 409 as PUT.
-     */
-    patchApiSandboxEnvironmentsByName(request: operations.PatchApiSandboxEnvironmentsByNameRequest, options?: RequestOptions): Promise<models.NameVarsSecrets>;
-    /**
-     * Delete a workspace Environment
-     *
-     * @remarks
-     * Removes the Environment and its encrypted secrets. Boxes already running keep what they were handed; the next spawn naming this Environment answers 404. 404 when there is nothing to delete — a retried delete is not a success.
-     */
-    deleteApiSandboxEnvironmentsByName(request: operations.DeleteApiSandboxEnvironmentsByNameRequest, options?: RequestOptions): Promise<operations.DeleteApiSandboxEnvironmentsByNameResponse>;
-    /**
-     * Provision and launch a headless Helix session
-     *
-     * @remarks
-     * Uses the configured Helix preset and destination. Defaults to classic/rpc. With `agent`, runs a managed agent: the slot (agent × `environment`) resolves the revision, the revision is staged into the box and started on the agent arm, and the answer names `agent.slug` and `agent.revision`. Returns a live execution reference, not a durable logical conversation identity. Disconnect detaches; the existing idle policy retains and eventually releases the box.
-     */
-    launchHelixSession(request: models.ModeArmModel, options?: RequestOptions): Promise<operations.LaunchHelixSessionResponse>;
-    /**
-     * List the workspace's Helix sessions across all sandboxes
-     *
-     * @remarks
-     * Every Helix session the workspace has — live and ended, on every box it owns — newest activity first, without naming a sandbox first. Assembled from the persisted event log and the sandbox records: live rows reflect a session with no terminal frame on a live box, ended rows carry the box's own exit code, a session whose box was reaped for idling says `stopped-for-idling`, and a session running on a restored box says `restored`. Rows carry addressing (reference, sandboxId), shape (arm, mode when known) and position (seqHighWater, activity) — and no environment material. `sandbox:read`, like the box-addressed session list: asking what exists is not driving the box. Paged: pass `nextCursor` back as `?cursor=`.
-     */
-    listHelixWorkspaceSessions(request?: operations.ListHelixWorkspaceSessionsRequest | undefined, options?: RequestOptions): Promise<operations.ListHelixWorkspaceSessionsResponse>;
-    /**
-     * Write native JSONL to a live Helix session
-     *
-     * @remarks
-     * One serialized JSON object. The reference is an address; normal workspace ownership and sandbox:exec authorization still apply. Harness responses arrive over SSE.
-     */
-    inputHelixSession(request: operations.InputHelixSessionRequest, options?: RequestOptions): Promise<operations.InputHelixSessionResponse>;
-    /**
-     * Explicitly close native RPC stdin
-     *
-     * @remarks
-     * Idempotent EOF for exactly this execution, distinct from abort, signal, or SSE/client detach. Older images without advertised closeInput capability return 422; no signal is substituted. Native exit and remaining output arrive on the stream.
-     */
-    closeHelixSessionInput(request: operations.CloseHelixSessionInputRequest, options?: RequestOptions): Promise<operations.CloseHelixSessionInputResponse>;
-    /**
-     * Stop a live Helix process
-     *
-     * @remarks
-     * Signals only the referenced execution, retaining its box. Already-ended executions return 409.
-     */
-    signalHelixSession(request: operations.SignalHelixSessionRequest, options?: RequestOptions): Promise<operations.SignalHelixSessionResponse>;
-    /**
-     * Checkpoint a live Helix session
-     *
-     * @remarks
-     * Captures the referenced execution through the existing checkpoint service. This does not confer durable logical identity on the live reference.
-     */
-    checkpointHelixSession(request: operations.CheckpointHelixSessionRequest, options?: RequestOptions): Promise<operations.CheckpointHelixSessionResponse>;
-    /**
-     * List the checkpoints of the box a session runs on
-     *
-     * @remarks
-     * Newest first, without the stored bytes. Addressed by the session reference; the list covers every session the referenced box has hosted, each row naming its session. `sandbox:read`.
-     */
-    listHelixSessionCheckpoints(request: operations.ListHelixSessionCheckpointsRequest, options?: RequestOptions): Promise<operations.ListHelixSessionCheckpointsResponse>;
-    /**
-     * Rebuild the box a session runs on from a checkpoint
-     *
-     * @remarks
-     * The reference-addressed form of the sandbox restore: same body, same behaviour, and the answer adds the new session reference. The box need not still exist. A box running a managed agent is refused with 409 `MANAGED_AGENT_RESTORE_UNSUPPORTED` (its package cannot be re-staged yet).
-     */
-    restoreHelixSession(request: operations.RestoreHelixSessionRequest, options?: RequestOptions): Promise<operations.RestoreHelixSessionResponse>;
-    /**
-     * Follow one Helix execution
-     *
-     * @remarks
-     * Replayable SSE, filtered by producer-attributed session identity after box cursor validation. Only this execution's exit closes its stream. RPC text contains native JSONL verbatim; transport metadata belongs to the client adapter. Disconnect detaches without signalling or destroying work. A restarted API can report live:false and replay only.
-     */
-    streamHelixSession(request: operations.StreamHelixSessionRequest, options?: RequestOptions): Promise<operations.StreamHelixSessionResponse>;
+    listSandboxSpans(request: operations.ListSandboxSpansRequest, options?: RequestOptions): Promise<operations.ListSandboxSpansResponse>;
     /**
      * Start a Helix session in a sandbox
      *
      * @remarks
-     * Returns as soon as the session is running — the run continues in the background and its output arrives on `GET /:id/stream`, not in this response. With `mode: "rpc"` the session is duplex: it emits `rpc` events on the stream and accepts `POST /:id/input`. `mode` defaults to `oneshot`, which is the pre-existing behaviour and has no stdin. A task token is rejected: starting an agent is driving the box.
-     */
-    postApiSandboxByIdSession(request: operations.PostApiSandboxByIdSessionRequest, options?: RequestOptions): Promise<operations.PostApiSandboxByIdSessionResponse>;
-    /**
-     * List the workspace's Helix Cloud models and its default
-     *
-     * @remarks
-     * The platform model catalog restricted to the workspace’s active LLM providers, each as `provider/model` in the harness spelling, plus the stored ordered defaults and the one a run naming no model would use now. Providers the box cannot credential are named in `unmapped`. `sandbox:read`.
-     */
-    getApiSandboxHelixDefaults(options?: RequestOptions): Promise<operations.GetApiSandboxHelixDefaultsResponse>;
-    /**
-     * Set the workspace's default Helix Cloud models
-     *
-     * @remarks
-     * Replaces the ordered list; the first entry becomes the default for session starts and agent runs that name no model. Every entry must be in the workspace’s list (422 names the list). `[]` clears the defaults, after which such runs answer 428 NO_PROVIDER_CONFIGURED. Operator tokens only. 409 `HELIX_DEFAULTS_UNAVAILABLE` when this server has no Helix Cloud model source configured.
+     * Returns as soon as the session is running. The session's output arrives on `GET /api/sandbox/{id}/stream`, not in this response. With `mode: "interactive"` the session emits `rpc` events on the stream and accepts `POST /api/sandbox/{id}/input`. `mode` defaults to `headless`, which takes no input. A task token is refused with 403.
      */
-    putApiSandboxHelixDefaults(request: operations.PutApiSandboxHelixDefaultsRequest, options?: RequestOptions): Promise<operations.PutApiSandboxHelixDefaultsResponse>;
+    startSandboxHelixSession(request: operations.StartSandboxHelixSessionRequest, options?: RequestOptions): Promise<models.SandboxSession>;
     /**
      * List the Helix sessions a sandbox is hosting
      *
      * @remarks
-     * Ids only — attach to one for detail. `sandbox:read`, unlike the other two session routes: asking which sessions exist is not driving the box.
+     * Session ids only. Requires `sandbox:read`.
      */
-    getApiSandboxByIdSessions(request: operations.GetApiSandboxByIdSessionsRequest, options?: RequestOptions): Promise<operations.GetApiSandboxByIdSessionsResponse>;
+    listSandboxHelixSessions(request: operations.ListSandboxHelixSessionsRequest, options?: RequestOptions): Promise<models.SandboxSessionIdList>;
     /**
      * Write one line to a Helix session's stdin
      *
      * @remarks
-     * The write half of the duplex session channel — the read half is the `rpc` events on `GET /:id/stream`. Use it to answer a HITL request or send a follow-up turn to a session started in RPC mode. `line` must be exactly one JSON object with no newline in it: the channel is newline-delimited, so one call carries one command. A 200 means the line reached the session, nothing more — whether the agent accepted it comes back on the stream, asynchronously. 400 if the line is not a single JSON object, 409 if the session is not running.
+     * Writes one JSON command to an interactive session's stdin. Replies arrive as `rpc` events on `GET /api/sandbox/{id}/stream`. Use it to answer an approval request or send the next prompt. `line` must be exactly one JSON object with no newline in it: one call carries one command. A 200 means the line reached the session; whether Helix accepted it is reported on the stream. 400 if the line is not a single JSON object, 409 if the session is not running.
      */
-    postApiSandboxByIdInput(request: operations.PostApiSandboxByIdInputRequest, options?: RequestOptions): Promise<operations.PostApiSandboxByIdInputResponse>;
+    sendSandboxHelixSessionInput(request: operations.SendSandboxHelixSessionInputRequest, options?: RequestOptions): Promise<models.SessionInputAccepted>;
     /**
      * Stop a running Helix session without destroying its sandbox
      *
      * @remarks
-     * The remote equivalent of Ctrl-C on a local agent: the SESSION stops and the box — its filesystem, its other sessions, its event log — stays up. `DELETE /:id` remains the only thing that destroys a sandbox. Distinct from sending an `abort` command via `POST /:id/input`, which politely asks a cooperating agent to end its turn and only works while it is still reading stdin; a signal reaches a process that has stopped listening. 200 means the signal was delivered to a LIVE process, never merely that the request was well-formed. 409 if the session has already ended, 404 if the box has never heard of it.
+     * Stops the session's Helix process. The sandbox, its files, its other sessions and its event log remain; `DELETE /api/sandbox/{id}` is the only call that deletes a sandbox. An `abort` command sent with `POST /api/sandbox/{id}/input` ends only the current turn and works only while Helix reads stdin; a signal also stops a process that has stopped reading. 200 means the signal reached a running process. 409 when the session has already ended, 404 when the sandbox has no session with that id.
      */
-    postApiSandboxByIdSignal(request: operations.PostApiSandboxByIdSignalRequest, options?: RequestOptions): Promise<operations.PostApiSandboxByIdSignalResponse>;
+    signalSandboxHelixSession(request: operations.SignalSandboxHelixSessionRequest, options?: RequestOptions): Promise<models.SessionSignalled>;
     /**
      * Capture a Helix session's own transcript
      *
      * @remarks
-     * Copies the HARNESS's session file off the box, verbatim, and stores it. This is what a NEW box needs to CONTINUE the conversation — distinct from `GET /:id/stream?since=`, which replays what the client observed and restores no agent state at all. 409 when the session has not completed a turn: the harness writes its file lazily, so there is genuinely nothing to capture yet, and storing an empty snapshot would produce a restore that succeeds and restores nothing. 503 when the deployment has no snapshot store.
+     * Copies Helix's session file out of the sandbox and stores it; a new sandbox needs it to continue the conversation. `GET /api/sandbox/{id}/stream?since=` replays output only and restores no agent state. 409 when the session has not finished a turn, because Helix has not written the file yet. 503 when checkpoint storage is not configured.
      */
-    postApiSandboxByIdCheckpoint(request: operations.PostApiSandboxByIdCheckpointRequest, options?: RequestOptions): Promise<operations.PostApiSandboxByIdCheckpointResponse>;
+    checkpointSandboxHelixSession(request: operations.CheckpointSandboxHelixSessionRequest, options?: RequestOptions): Promise<models.Checkpoint>;
     /**
      * List checkpoints captured from this sandbox
      *
      * @remarks
-     * Newest first, tenant-scoped, WITHOUT the stored bytes. `messageCount` is how much conversation each one holds.
+     * Newest first, scoped to the workspace, without the stored bytes. `messageCount` is how many messages each one holds.
      */
-    getApiSandboxByIdCheckpoints(request: operations.GetApiSandboxByIdCheckpointsRequest, options?: RequestOptions): Promise<operations.GetApiSandboxByIdCheckpointsResponse>;
+    listSandboxCheckpoints(request: operations.ListSandboxCheckpointsRequest, options?: RequestOptions): Promise<models.CheckpointList>;
     /**
      * Rebuild this sandbox from a checkpoint, with full state
      *
      * @remarks
-     * A cloud equivalent of a local `/resume`, and it does NOT require the old box to still exist — a reaped or torn-down sandbox is the ordinary input. In order: a fresh box is spawned for the SAME sandbox id at generation+1 with the same secret NAMES (values are re-minted, never stored); the relay's seq counter is seeded from the persisted high-water mark so a client's `?since=` cursor stays valid; the workspace and `$HOME/.mutagent` are extracted BEFORE Helix starts; a session is started in the checkpoint's cwd; the conversation is written in, its sha256 compared against the box's own, and only then switched onto; the runtime settings and pending queue are replayed; and a `session {status:"restored"}` frame is appended to the stream with a real seq. A digest mismatch is a 422 and the session is NOT switched. 404 if the snapshot is not in this workspace. Read `notRestored` — a restore that carried only the conversation is legitimate and says so there. A DEFAULTED restore uses the newest checkpoint that has a manifest and lists newer rows it passed over in `skippedSnapshots`. `partial: true` restores the incremental transcript prefix beyond the checkpoint when one exists (the frame then carries `partial: true`); its tail may end on a tool call with no result, which the harness answers with a synthetic error on the next turn — the accepted risk of asking for it. ENVIRONMENT: `environment` and `env` layer onto the restored session exactly as on session start (provider keys, then the Environment, then per-call `env`, then platform-owned variables). The Environment a session was started with is recorded by NAME in the checkpoint manifest and re-resolved when `environment` is omitted; a name in the body wins, and an unknown one is a 404 before the old box is touched. Per-call `env` values are NEVER stored, so a restore that omits `env` does not bring them back — send a model key given as `env` again.
+     * Restores a sandbox from a checkpoint. The old sandbox does not need to exist. Steps: a new sandbox starts under the same sandbox id at the next generation, with the same secret names and newly issued values; the event sequence continues from the stored position, so `?since=` cursors stay valid; the working directory and `$HOME/.mutagent` are extracted before Helix starts; a session starts in the checkpoint's working directory; the conversation is written and its SHA-256 compared; the runtime settings and pending queue are replayed; a `session` event with `status: "restored"` is appended. A digest mismatch answers 422 and the session is not switched. 404 when the checkpoint is not in this workspace. `notRestored` lists what did not come back. Without `snapshotId`, the newest checkpoint that has a manifest is used and newer ones are listed in `skippedSnapshots`. `partial: true` also restores turns written after the checkpoint; the transcript can end on a tool call with no result, which Helix answers with an error on the next turn. Environment: `environment` and `env` apply as on session start. The Environment name recorded in the checkpoint is used when `environment` is omitted; an unknown name answers 404 before anything is changed. Per-call `env` values are not stored; send them again.
      */
-    postApiSandboxByIdRestore(request: operations.PostApiSandboxByIdRestoreRequest, options?: RequestOptions): Promise<operations.PostApiSandboxByIdRestoreResponse>;
+    restoreSandbox(request: operations.RestoreSandboxRequest, options?: RequestOptions): Promise<models.SandboxRestoreResult>;
     /**
      * Exchange a platform API key for a sandbox operator token
      *
      * @remarks
      * Trades a platform credential — an API key (`x-api-key: mg_live_…`) or a Better-Auth session cookie — for a short-lived operator token scoped to one workspace. The caller must be able to create resources in that workspace, and a workspace- or organization-restricted key can only mint within its own scope. The minted token is the scoped bearer the other sandbox operations require; this route itself never accepts one.
      */
-    postApiSandboxToken(security: operations.PostApiSandboxTokenSecurity, request: operations.PostApiSandboxTokenRequest, options?: RequestOptions): Promise<operations.PostApiSandboxTokenResponse>;
+    createSandboxToken(security: operations.CreateSandboxTokenSecurity, request: models.SandboxTokenRequest, options?: RequestOptions): Promise<models.SandboxToken>;
 }
 //# sourceMappingURL=sandbox.d.ts.map

package/dist/commonjs/sdk/sandbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../../src/sdk/sandbox.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../../src/sdk/sandbox.ts"],"names":[],"mappings":"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"}