@mutagent/sdk 0.3.40 → 0.3.42

package/dist/esm/sdk/sandbox.js

@@ -2,6 +2,7 @@
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
  */
 import { sandboxDeleteApiSandboxById } from "../funcs/sandbox-delete-api-sandbox-by-id.js";
+import { sandboxGetApiSandboxByIdCheckpoints } from "../funcs/sandbox-get-api-sandbox-by-id-checkpoints.js";
 import { sandboxGetApiSandboxByIdSessions } from "../funcs/sandbox-get-api-sandbox-by-id-sessions.js";
 import { sandboxGetApiSandboxByIdStream } from "../funcs/sandbox-get-api-sandbox-by-id-stream.js";
 import { sandboxGetApiSandboxByIdTraces } from "../funcs/sandbox-get-api-sandbox-by-id-traces.js";
@@ -10,8 +11,10 @@ import { sandboxGetApiSandboxPresets } from "../funcs/sandbox-get-api-sandbox-pr
 import { sandboxGetApiSandboxProviders } from "../funcs/sandbox-get-api-sandbox-providers.js";
 import { sandboxGetApiSandbox } from "../funcs/sandbox-get-api-sandbox.js";
 import { sandboxPostApiSandboxAgentRun } from "../funcs/sandbox-post-api-sandbox-agent-run.js";
+import { sandboxPostApiSandboxByIdCheckpoint } from "../funcs/sandbox-post-api-sandbox-by-id-checkpoint.js";
 import { sandboxPostApiSandboxByIdExec } from "../funcs/sandbox-post-api-sandbox-by-id-exec.js";
 import { sandboxPostApiSandboxByIdInput } from "../funcs/sandbox-post-api-sandbox-by-id-input.js";
+import { sandboxPostApiSandboxByIdRestore } from "../funcs/sandbox-post-api-sandbox-by-id-restore.js";
 import { sandboxPostApiSandboxByIdSession } from "../funcs/sandbox-post-api-sandbox-by-id-session.js";
 import { sandboxPostApiSandboxByIdSignal } from "../funcs/sandbox-post-api-sandbox-by-id-signal.js";
 import { sandboxPostApiSandboxPreflight } from "../funcs/sandbox-post-api-sandbox-preflight.js";
@@ -58,15 +61,6 @@ export class Sandbox extends ClientSDK {
     async postApiSandboxRun(request, options) {
         return unwrapAsync(sandboxPostApiSandboxRun(this, request, options));
     }
-    /**
-     * Run one agent turn in a fresh sandbox
-     *
-     * @remarks
-     * `prompt` is WHO the agent is (the agent definition) and `task` is WHAT to do this turn. They are two different prompts and are never concatenated. The turn's output comes back on stdout with the agent's real exit code. With `?stream=1` the same turn is delivered as it happens, in the event framing of `GET /:id/stream`: a `sandbox` event naming the box, then `stdout`/`stderr` as the agent produces them, then a `result` event carrying the exit code and whether the sandbox was torn down, then the terminal `status`. Disconnecting mid-stream releases the sandbox.
-     */
-    async postApiSandboxAgentRun(request, options) {
-        return unwrapAsync(sandboxPostApiSandboxAgentRun(this, request, options));
-    }
     /**
      * Spawn a sandbox
      *
@@ -104,7 +98,7 @@ export class Sandbox extends ClientSDK {
      * Watch a sandbox's output live
      *
      * @remarks
-     * Server-sent events: `stdout`, `stderr`, `rpc`, `unrecognised`, `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. All four output events share the `{seq, ts, text}` shape and one sequence counter, so their interleaving is the order the box produced them. `seq` is monotonic per sandbox and starts at 1; pass the last one seen as `?since=` to resume. If the buffer has already rolled past `since`, an `error` event names the lost range rather than skipping it silently. Disconnecting tears down the upstream.
+     * 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.
      */
     async getApiSandboxByIdStream(request, options) {
         return unwrapAsync(sandboxGetApiSandboxByIdStream(this, request, options));
@@ -118,6 +112,21 @@ export class Sandbox extends ClientSDK {
     async postApiSandboxByIdExec(request, options) {
         return unwrapAsync(sandboxPostApiSandboxByIdExec(this, request, options));
     }
+    /**
+     * 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.
+     */
+    async postApiSandboxTelemetryV1Traces(options) {
+        return unwrapAsync(sandboxPostApiSandboxTelemetryV1Traces(this, options));
+    }
+    /**
+     * Read a sandbox's captured spans
+     */
+    async getApiSandboxByIdTraces(request, options) {
+        return unwrapAsync(sandboxGetApiSandboxByIdTraces(this, request, options));
+    }
     /**
      * Start a Helix session in a sandbox
      *
@@ -155,19 +164,40 @@ export class Sandbox extends ClientSDK {
         return unwrapAsync(sandboxPostApiSandboxByIdSignal(this, request, options));
     }
     /**
-     * Ingest OTLP spans from inside a sandbox
+     * Capture a Helix session's own transcript
      *
      * @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.
+     * 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.
      */
-    async postApiSandboxTelemetryV1Traces(options) {
-        return unwrapAsync(sandboxPostApiSandboxTelemetryV1Traces(this, options));
+    async postApiSandboxByIdCheckpoint(request, options) {
+        return unwrapAsync(sandboxPostApiSandboxByIdCheckpoint(this, request, options));
     }
     /**
-     * Read a sandbox's captured spans
+     * List checkpoints captured from this sandbox
+     *
+     * @remarks
+     * Newest first, tenant-scoped, WITHOUT the stored bytes. `messageCount` is how much conversation each one holds.
      */
-    async getApiSandboxByIdTraces(request, options) {
-        return unwrapAsync(sandboxGetApiSandboxByIdTraces(this, request, options));
+    async getApiSandboxByIdCheckpoints(request, options) {
+        return unwrapAsync(sandboxGetApiSandboxByIdCheckpoints(this, request, options));
+    }
+    /**
+     * 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.
+     */
+    async postApiSandboxByIdRestore(request, options) {
+        return unwrapAsync(sandboxPostApiSandboxByIdRestore(this, request, options));
+    }
+    /**
+     * Run one agent turn in a fresh sandbox
+     *
+     * @remarks
+     * `prompt` is WHO the agent is (the agent definition) and `task` is WHAT to do this turn. They are two different prompts and are never concatenated. The turn's output comes back on stdout with the agent's real exit code. With `?stream=1` the same turn is delivered as it happens, in the event framing of `GET /:id/stream`: a `sandbox` event naming the box, then `stdout`/`stderr` as the agent produces them, then a `result` event carrying the exit code and whether the sandbox was torn down, then the terminal `status`. Disconnecting mid-stream releases the sandbox.
+     */
+    async postApiSandboxAgentRun(request, options) {
+        return unwrapAsync(sandboxPostApiSandboxAgentRun(this, request, options));
     }
     /**
      * Exchange a platform API key for a sandbox operator token

package/dist/esm/sdk/sandbox.js.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../../../src/sdk/sandbox.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,2BAA2B,EAAE,MAAM,8CAA8C,CAAC;AAC3F,OAAO,EAAE,gCAAgC,EAAE,MAAM,oDAAoD,CAAC;AACtG,OAAO,EAAE,8BAA8B,EAAE,MAAM,kDAAkD,CAAC;AAClG,OAAO,EAAE,8BAA8B,EAAE,MAAM,kDAAkD,CAAC;AAClG,OAAO,EAAE,wBAAwB,EAAE,MAAM,2CAA2C,CAAC;AACrF,OAAO,EAAE,2BAA2B,EAAE,MAAM,6CAA6C,CAAC;AAC1F,OAAO,EAAE,6BAA6B,EAAE,MAAM,+CAA+C,CAAC;AAC9F,OAAO,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAC3E,OAAO,EAAE,6BAA6B,EAAE,MAAM,gDAAgD,CAAC;AAC/F,OAAO,EAAE,6BAA6B,EAAE,MAAM,iDAAiD,CAAC;AAChG,OAAO,EAAE,8BAA8B,EAAE,MAAM,kDAAkD,CAAC;AAClG,OAAO,EAAE,gCAAgC,EAAE,MAAM,oDAAoD,CAAC;AACtG,OAAO,EAAE,+BAA+B,EAAE,MAAM,mDAAmD,CAAC;AACpG,OAAO,EAAE,8BAA8B,EAAE,MAAM,gDAAgD,CAAC;AAChG,OAAO,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AACpF,OAAO,EAAE,sCAAsC,EAAE,MAAM,0DAA0D,CAAC;AAClH,OAAO,EAAE,0BAA0B,EAAE,MAAM,4CAA4C,CAAC;AACxF,OAAO,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AAC7E,OAAO,EAAE,SAAS,EAAkB,MAAM,gBAAgB,CAAC;AAG3D,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,MAAM,OAAO,OAAQ,SAAQ,SAAS;IACpC;;;;;OAKG;IACH,KAAK,CAAC,sBAAsB,CAC1B,OAAwB;QAExB,OAAO,WAAW,CAAC,6BAA6B,CAC9C,IAAI,EACJ,OAAO,CACR,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,uBAAuB,CAC3B,OAAkC,EAClC,OAAwB;QAExB,OAAO,WAAW,CAAC,8BAA8B,CAC/C,IAAI,EACJ,OAAO,EACP,OAAO,CACR,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,oBAAoB,CACxB,OAAwB;QAExB,OAAO,WAAW,CAAC,2BAA2B,CAC5C,IAAI,EACJ,OAAO,CACR,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,iBAAiB,CACrB,OAAmC,EACnC,OAAwB;QAExB,OAAO,WAAW,CAAC,wBAAwB,CACzC,IAAI,EACJ,OAAO,EACP,OAAO,CACR,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,sBAAsB,CAC1B,OAAiD,EACjD,OAAwB;QAExB,OAAO,WAAW,CAAC,6BAA6B,CAC9C,IAAI,EACJ,OAAO,EACP,OAAO,CACR,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,cAAc,CAClB,OAA+B,EAC/B,OAAwB;QAExB,OAAO,WAAW,CAAC,qBAAqB,CACtC,IAAI,EACJ,OAAO,EACP,OAAO,CACR,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,aAAa,CACjB,OAAwB;QAExB,OAAO,WAAW,CAAC,oBAAoB,CACrC,IAAI,EACJ,OAAO,CACR,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,iBAAiB,CACrB,OAA4C,EAC5C,OAAwB;QAExB,OAAO,WAAW,CAAC,wBAAwB,CACzC,IAAI,EACJ,OAAO,EACP,OAAO,CACR,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,oBAAoB,CACxB,OAA+C,EAC/C,OAAwB;QAExB,OAAO,WAAW,CAAC,2BAA2B,CAC5C,IAAI,EACJ,OAAO,EACP,OAAO,CACR,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,uBAAuB,CAC3B,OAAkD,EAClD,OAAwB;QAExB,OAAO,WAAW,CAAC,8BAA8B,CAC/C,IAAI,EACJ,OAAO,EACP,OAAO,CACR,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,sBAAsB,CAC1B,OAAiD,EACjD,OAAwB;QAExB,OAAO,WAAW,CAAC,6BAA6B,CAC9C,IAAI,EACJ,OAAO,EACP,OAAO,CACR,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,yBAAyB,CAC7B,OAAoD,EACpD,OAAwB;QAExB,OAAO,WAAW,CAAC,gCAAgC,CACjD,IAAI,EACJ,OAAO,EACP,OAAO,CACR,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,yBAAyB,CAC7B,OAAoD,EACpD,OAAwB;QAExB,OAAO,WAAW,CAAC,gCAAgC,CACjD,IAAI,EACJ,OAAO,EACP,OAAO,CACR,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,uBAAuB,CAC3B,OAAkD,EAClD,OAAwB;QAExB,OAAO,WAAW,CAAC,8BAA8B,CAC/C,IAAI,EACJ,OAAO,EACP,OAAO,CACR,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,wBAAwB,CAC5B,OAAmD,EACnD,OAAwB;QAExB,OAAO,WAAW,CAAC,+BAA+B,CAChD,IAAI,EACJ,OAAO,EACP,OAAO,CACR,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,+BAA+B,CACnC,OAAwB;QAExB,OAAO,WAAW,CAAC,sCAAsC,CACvD,IAAI,EACJ,OAAO,CACR,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,uBAAuB,CAC3B,OAAkD,EAClD,OAAwB;QAExB,OAAO,WAAW,CAAC,8BAA8B,CAC/C,IAAI,EACJ,OAAO,EACP,OAAO,CACR,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,mBAAmB,CACvB,OAA8C,EAC9C,OAAwB;QAExB,OAAO,WAAW,CAAC,0BAA0B,CAC3C,IAAI,EACJ,OAAO,EACP,OAAO,CACR,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../../../src/sdk/sandbox.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutagent/sdk",
-  "version": "0.3.40",
+  "version": "0.3.42",
   "author": "Speakeasy",
   "tshy": {
     "sourceDialects": [

package/src/funcs/sandbox-get-api-sandbox-by-id-checkpoints.ts

@@ -0,0 +1,184 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v4-mini";
+import { MutagentCore } from "../core.js";
+import { encodeSimple } from "../lib/encodings.js";
+import { matchStatusCode } from "../lib/http.js";
+import * as M from "../lib/matchers.js";
+import { compactMap } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
+import { pathToFunc } from "../lib/url.js";
+import {
+  ConnectionError,
+  InvalidRequestError,
+  RequestAbortedError,
+  RequestTimeoutError,
+  UnexpectedClientError,
+} from "../models/errors/http-client-errors.js";
+import * as errors from "../models/errors/index.js";
+import { MutagentError } from "../models/errors/mutagent-error.js";
+import { ResponseValidationError } from "../models/errors/response-validation-error.js";
+import { SDKValidationError } from "../models/errors/sdk-validation-error.js";
+import * as operations from "../models/operations/index.js";
+import { APICall, APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+
+/**
+ * List checkpoints captured from this sandbox
+ *
+ * @remarks
+ * Newest first, tenant-scoped, WITHOUT the stored bytes. `messageCount` is how much conversation each one holds.
+ */
+export function sandboxGetApiSandboxByIdCheckpoints(
+  client: MutagentCore,
+  request: operations.GetApiSandboxByIdCheckpointsRequest,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    operations.GetApiSandboxByIdCheckpointsResponse,
+    | errors.ErrorMessage
+    | errors.ErrorMessageStatusCode
+    | MutagentError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >
+> {
+  return new APIPromise($do(
+    client,
+    request,
+    options,
+  ));
+}
+
+async function $do(
+  client: MutagentCore,
+  request: operations.GetApiSandboxByIdCheckpointsRequest,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      operations.GetApiSandboxByIdCheckpointsResponse,
+      | errors.ErrorMessage
+      | errors.ErrorMessageStatusCode
+      | MutagentError
+      | ResponseValidationError
+      | ConnectionError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | InvalidRequestError
+      | UnexpectedClientError
+      | SDKValidationError
+    >,
+    APICall,
+  ]
+> {
+  const parsed = safeParse(
+    request,
+    (value) =>
+      z.parse(
+        operations.GetApiSandboxByIdCheckpointsRequest$outboundSchema,
+        value,
+      ),
+    "Input validation failed",
+  );
+  if (!parsed.ok) {
+    return [parsed, { status: "invalid" }];
+  }
+  const payload = parsed.value;
+  const body = null;
+
+  const pathParams = {
+    id: encodeSimple("id", payload.id, {
+      explode: false,
+      charEncoding: "percent",
+    }),
+  };
+  const path = pathToFunc("/api/sandbox/{id}/checkpoints")(pathParams);
+
+  const headers = new Headers(compactMap({
+    Accept: "application/json",
+  }));
+
+  const securityInput = await extractSecurity(client._options.security);
+  const requestSecurity = resolveGlobalSecurity(securityInput);
+
+  const context = {
+    options: client._options,
+    baseURL: options?.serverURL ?? client._baseURL ?? "",
+    operationID: "getApiSandboxByIdCheckpoints",
+    oAuth2Scopes: null,
+
+    resolvedSecurity: requestSecurity,
+
+    securitySource: client._options.security,
+    retryConfig: options?.retries
+      || client._options.retryConfig
+      || { strategy: "none" },
+    retryCodes: options?.retryCodes || ["429", "500", "502", "503", "504"],
+  };
+
+  const requestRes = client._createRequest(context, {
+    security: requestSecurity,
+    method: "GET",
+    baseURL: options?.serverURL,
+    path: path,
+    headers: headers,
+    body: body,
+    userAgent: client._options.userAgent,
+    timeoutMs: options?.timeoutMs || client._options.timeoutMs || -1,
+  }, options);
+  if (!requestRes.ok) {
+    return [requestRes, { status: "invalid" }];
+  }
+  const req = requestRes.value;
+
+  const doResult = await client._do(req, {
+    context,
+    isErrorStatusCode: (statusCode: number) =>
+      matchStatusCode({ status: statusCode } as Response, ["4XX", "5XX"]),
+    retryConfig: context.retryConfig,
+    retryCodes: context.retryCodes,
+  });
+  if (!doResult.ok) {
+    return [doResult, { status: "request-error", request: req }];
+  }
+  const response = doResult.value;
+
+  const responseFields = {
+    HttpMeta: { Response: response, Request: req },
+  };
+
+  const [result] = await M.match<
+    operations.GetApiSandboxByIdCheckpointsResponse,
+    | errors.ErrorMessage
+    | errors.ErrorMessageStatusCode
+    | MutagentError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >(
+    M.json(200, operations.GetApiSandboxByIdCheckpointsResponse$inboundSchema),
+    M.jsonErr([400, 401, 403, 404], errors.ErrorMessage$inboundSchema),
+    M.jsonErr(500, errors.ErrorMessageStatusCode$inboundSchema),
+    M.fail("4XX"),
+    M.fail("5XX"),
+  )(response, req, { extraFields: responseFields });
+  if (!result.ok) {
+    return [result, { status: "complete", request: req, response }];
+  }
+
+  return [result, { status: "complete", request: req, response }];
+}

package/src/funcs/sandbox-get-api-sandbox-by-id-stream.ts

@@ -31,7 +31,7 @@ import { Result } from "../types/fp.js";
  * Watch a sandbox's output live
  *
  * @remarks
- * Server-sent events: `stdout`, `stderr`, `rpc`, `unrecognised`, `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. All four output events share the `{seq, ts, text}` shape and one sequence counter, so their interleaving is the order the box produced them. `seq` is monotonic per sandbox and starts at 1; pass the last one seen as `?since=` to resume. If the buffer has already rolled past `since`, an `error` event names the lost range rather than skipping it silently. Disconnecting tears down the upstream.
+ * 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.
  */
 export function sandboxGetApiSandboxByIdStream(
   client: MutagentCore,

package/src/funcs/sandbox-post-api-sandbox-by-id-checkpoint.ts

@@ -0,0 +1,186 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v4-mini";
+import { MutagentCore } from "../core.js";
+import { encodeJSON, encodeSimple } from "../lib/encodings.js";
+import { matchStatusCode } from "../lib/http.js";
+import * as M from "../lib/matchers.js";
+import { compactMap } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
+import { pathToFunc } from "../lib/url.js";
+import {
+  ConnectionError,
+  InvalidRequestError,
+  RequestAbortedError,
+  RequestTimeoutError,
+  UnexpectedClientError,
+} from "../models/errors/http-client-errors.js";
+import * as errors from "../models/errors/index.js";
+import { MutagentError } from "../models/errors/mutagent-error.js";
+import { ResponseValidationError } from "../models/errors/response-validation-error.js";
+import { SDKValidationError } from "../models/errors/sdk-validation-error.js";
+import * as operations from "../models/operations/index.js";
+import { APICall, APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+
+/**
+ * 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.
+ */
+export function sandboxPostApiSandboxByIdCheckpoint(
+  client: MutagentCore,
+  request: operations.PostApiSandboxByIdCheckpointRequest,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    operations.PostApiSandboxByIdCheckpointResponse,
+    | errors.ErrorMessage
+    | errors.ErrorMessageStatusCode
+    | MutagentError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >
+> {
+  return new APIPromise($do(
+    client,
+    request,
+    options,
+  ));
+}
+
+async function $do(
+  client: MutagentCore,
+  request: operations.PostApiSandboxByIdCheckpointRequest,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      operations.PostApiSandboxByIdCheckpointResponse,
+      | errors.ErrorMessage
+      | errors.ErrorMessageStatusCode
+      | MutagentError
+      | ResponseValidationError
+      | ConnectionError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | InvalidRequestError
+      | UnexpectedClientError
+      | SDKValidationError
+    >,
+    APICall,
+  ]
+> {
+  const parsed = safeParse(
+    request,
+    (value) =>
+      z.parse(
+        operations.PostApiSandboxByIdCheckpointRequest$outboundSchema,
+        value,
+      ),
+    "Input validation failed",
+  );
+  if (!parsed.ok) {
+    return [parsed, { status: "invalid" }];
+  }
+  const payload = parsed.value;
+  const body = encodeJSON("body", payload.body, { explode: true });
+
+  const pathParams = {
+    id: encodeSimple("id", payload.id, {
+      explode: false,
+      charEncoding: "percent",
+    }),
+  };
+  const path = pathToFunc("/api/sandbox/{id}/checkpoint")(pathParams);
+
+  const headers = new Headers(compactMap({
+    "Content-Type": "application/json",
+    Accept: "application/json",
+  }));
+
+  const securityInput = await extractSecurity(client._options.security);
+  const requestSecurity = resolveGlobalSecurity(securityInput);
+
+  const context = {
+    options: client._options,
+    baseURL: options?.serverURL ?? client._baseURL ?? "",
+    operationID: "postApiSandboxByIdCheckpoint",
+    oAuth2Scopes: null,
+
+    resolvedSecurity: requestSecurity,
+
+    securitySource: client._options.security,
+    retryConfig: options?.retries
+      || client._options.retryConfig
+      || { strategy: "none" },
+    retryCodes: options?.retryCodes || ["429", "500", "502", "503", "504"],
+  };
+
+  const requestRes = client._createRequest(context, {
+    security: requestSecurity,
+    method: "POST",
+    baseURL: options?.serverURL,
+    path: path,
+    headers: headers,
+    body: body,
+    userAgent: client._options.userAgent,
+    timeoutMs: options?.timeoutMs || client._options.timeoutMs || -1,
+  }, options);
+  if (!requestRes.ok) {
+    return [requestRes, { status: "invalid" }];
+  }
+  const req = requestRes.value;
+
+  const doResult = await client._do(req, {
+    context,
+    isErrorStatusCode: (statusCode: number) =>
+      matchStatusCode({ status: statusCode } as Response, ["4XX", "5XX"]),
+    retryConfig: context.retryConfig,
+    retryCodes: context.retryCodes,
+  });
+  if (!doResult.ok) {
+    return [doResult, { status: "request-error", request: req }];
+  }
+  const response = doResult.value;
+
+  const responseFields = {
+    HttpMeta: { Response: response, Request: req },
+  };
+
+  const [result] = await M.match<
+    operations.PostApiSandboxByIdCheckpointResponse,
+    | errors.ErrorMessage
+    | errors.ErrorMessageStatusCode
+    | MutagentError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >(
+    M.json(200, operations.PostApiSandboxByIdCheckpointResponse$inboundSchema),
+    M.jsonErr([400, 401, 403, 404], errors.ErrorMessage$inboundSchema),
+    M.jsonErr(409, errors.ErrorMessageStatusCode$inboundSchema),
+    M.jsonErr(500, errors.ErrorMessageStatusCode$inboundSchema),
+    M.fail("4XX"),
+    M.fail("5XX"),
+  )(response, req, { extraFields: responseFields });
+  if (!result.ok) {
+    return [result, { status: "complete", request: req, response }];
+  }
+
+  return [result, { status: "complete", request: req, response }];
+}