@agentproto/sandbox 0.1.5 → 0.2.1

package/dist/index.d.ts

@@ -32,6 +32,24 @@ interface BootedSandbox {
     mcpUrl: string;
     /** Provider-assigned sandbox id, for logging / lookup. */
     sandboxId: string;
+    /** Opaque secret gating `mcpUrl`, present when `opts.expose === "private"`
+     *  was honoured (see `SandboxBootOpts.expose`). Absent for the default
+     *  public-exposure path (boot-and-drive) and for providers/paths that
+     *  can't gate the port at all — a caller that needs a gated URL (e.g.
+     *  `attachSandbox`) MUST treat a missing token as "not gated", not as
+     *  "no auth needed". The token is the raw secret; how a client must
+     *  PRESENT it (bearer header, cookie, …) is provider-specific — see
+     *  `authHeaders`. */
+    token?: string;
+    /** Exact HTTP header(s) a client must send to authenticate against the
+     *  gated `mcpUrl` — the provider's own answer to "how do I present the
+     *  token". Box, for instance, gates its private hostname with a
+     *  `Cookie: _port_auth=<token>` (verified live: bearer/query are ignored,
+     *  the port edge only honours the cookie), so it returns that here rather
+     *  than leaving the caller to guess a scheme. Present iff `token` is; a
+     *  token-only provider that omits this is treated by `buildMcpConfigSnippet`
+     *  as `Authorization: Bearer <token>`. */
+    authHeaders?: Record<string, string>;
     /** Tear down the sandbox. */
     stop(): Promise<void>;
     /** Pause the sandbox instead of killing it — keeps it reconnectable via
@@ -43,6 +61,26 @@ interface BootedSandbox {
 /** Env resolved from secrets, handed to `provider.boot`. */
 interface SandboxBootOpts {
     env: Record<string, string>;
+    /**
+     * How the provider should expose the daemon's port. `"public"` (the
+     * default when omitted) is boot-and-drive's ephemeral, provider-owned,
+     * ungated URL. `"private"` asks the provider for a PERSISTENT,
+     * token-gated URL instead — set by `attachSandbox`, which produces a
+     * durable connection descriptor and must never emit an ungated one.
+     * Providers that don't support gating simply ignore this and omit
+     * `BootedSandbox.token`; the caller is responsible for treating that as
+     * a failure when it needed a gated URL.
+     */
+    expose?: "public" | "private";
+    /**
+     * Keep the sandbox awake indefinitely for the always-on rendezvous model
+     * — set by `attachSandbox` when its own `keepAlive` opt is true. A
+     * provider that supports an explicit no-auto-stop/no-expiry assertion
+     * (e.g. Box's `ttlSeconds: null`) should (re-)apply it as part of
+     * `connect()`, defensively, even if the sandbox already defaults to it.
+     * Providers with no such concept simply ignore this.
+     */
+    keepAlive?: boolean;
 }
 /**
  * Backend-agnostic sandbox lifecycle. Concrete implementations (e2b, modal,

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/agent-session-host.ts","../src/lifecycle.ts","../src/index.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * AIP-36 sandbox-backed `AgentSessionHost`.\n *\n * The seam an `AgentStep` binds against (`AgentSessionHost`,\n * `@agentproto/workflow-runtime`) is already satisfiable by a *remote*\n * daemon via `connectDaemonAgentSessionHost` (`@agentproto/worktree`) —\n * it just needs a reachable MCP URL. So running a coding-agent step\n * inside a sandbox is: boot a provider-specific box that exposes an\n * agentproto daemon's MCP endpoint as a URL, then hand that URL to the\n * daemon host unchanged. No new session-host implementation, no\n * bespoke spawn/prompt plumbing — this module only wires secrets → env\n * → `provider.boot` → `connectDaemonAgentSessionHost`.\n */\n\nimport { assertSafeSecretValue, type SecretResolver } from \"@agentproto/secrets/exposure\"\nimport { connectDaemonAgentSessionHost, type DaemonAgentSessionHost } from \"@agentproto/worktree\"\nimport type { SandboxHandle } from \"./types.js\"\n\n/** AIP-36 sandbox manifest handle — provider id, config, env passthrough, limits. */\nexport type SandboxSpec = SandboxHandle\n\n/** What a `SandboxProvider` hands back once the box is up and reachable. */\nexport interface BootedSandbox {\n  /** The booted agentproto daemon's MCP endpoint, reachable from this process. */\n  mcpUrl: string\n  /** Provider-assigned sandbox id, for logging / lookup. */\n  sandboxId: string\n  /** Tear down the sandbox. */\n  stop(): Promise<void>\n  /** Pause the sandbox instead of killing it — keeps it reconnectable via\n   *  `SandboxProvider.connect(sandboxId, ...)` later. Optional: providers\n   *  that can't pause (or don't support reconnect at all) omit it; callers\n   *  that want to pause fall back to `stop()` when it's absent. */\n  pause?(): Promise<void>\n}\n\n/** Env resolved from secrets, handed to `provider.boot`. */\nexport interface SandboxBootOpts {\n  env: Record<string, string>\n}\n\n/**\n * Backend-agnostic sandbox lifecycle. Concrete implementations (e2b, modal,\n * daytona, blaxel, …) live in their own packages so this one stays free of\n * vendor SDK dependencies — see `@agentproto/sandbox-e2b`.\n */\nexport interface SandboxProvider {\n  boot(spec: SandboxSpec, opts: SandboxBootOpts): Promise<BootedSandbox>\n  /** Reconnect to an already-booted (possibly paused) sandbox instead of\n   *  booting a fresh one — the reuse path (`agent_start.sandbox.reuse`).\n   *  Optional: providers that can't reconnect (e.g. the `local` passthrough,\n   *  which tears down its temp workspace on `stop()`) omit it; the runtime\n   *  errors clearly when reuse is requested against such a provider. */\n  connect?(sandboxId: string, spec: SandboxSpec, opts: SandboxBootOpts): Promise<BootedSandbox>\n}\n\n/** Which secrets to resolve into the sandbox's env, and how. */\nexport interface SandboxSecretsConfig {\n  /** Secret slugs to resolve (e.g. `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`). */\n  slugs: readonly string[]\n  /** Resolves a slug to its value. Defaults to reading `process.env[slug]`. */\n  resolver?: SecretResolver\n}\n\nexport interface CreateSandboxAgentSessionHostOpts {\n  provider: SandboxProvider\n  spec: SandboxSpec\n  secrets: SandboxSecretsConfig\n  /** Reconnect to this existing sandbox id instead of booting a fresh box —\n   *  requires `provider.connect`; throws a clear error otherwise. */\n  sandboxId?: string\n}\n\nexport type SandboxAgentSessionHost = DaemonAgentSessionHost & {\n  /** Provider-assigned sandbox id (`BootedSandbox.sandboxId`) — surfaced so a\n   *  caller can record it (there's no local PID for a sandboxed session). */\n  sandboxId: string\n  /** Close the daemon connection AND tear down the sandbox. */\n  stop(): Promise<void>\n  /** Close the daemon connection and PAUSE the sandbox instead of killing\n   *  it — only present when the booted sandbox supports `pause()`. */\n  pause?(): Promise<void>\n}\n\n/**\n * Resolve `secrets` into an env map, boot (or, when `opts.sandboxId` is set,\n * reconnect to) the sandbox with it, then connect the #202 daemon host to\n * the sandbox's exposed MCP URL. `stop()` closes the daemon connection\n * before tearing down the sandbox (never leaks the box on a client-side\n * error); `pause()` does the same but pauses rather than kills.\n */\nexport async function createSandboxAgentSessionHost(\n  opts: CreateSandboxAgentSessionHostOpts,\n): Promise<SandboxAgentSessionHost> {\n  const env = await resolveSandboxSecretsEnv(opts.secrets)\n  let booted: BootedSandbox\n  if (opts.sandboxId !== undefined) {\n    if (!opts.provider.connect) {\n      throw new Error(\n        `createSandboxAgentSessionHost: reuse requested for sandbox \"${opts.sandboxId}\", ` +\n          \"but this provider has no connect() — it can only boot fresh sandboxes.\",\n      )\n    }\n    booted = await opts.provider.connect(opts.sandboxId, opts.spec, { env })\n  } else {\n    booted = await opts.provider.boot(opts.spec, { env })\n  }\n  let host: DaemonAgentSessionHost\n  try {\n    host = await connectDaemonAgentSessionHost({ url: booted.mcpUrl })\n  } catch (err) {\n    await booted.stop()\n    throw err\n  }\n  return {\n    ...host,\n    sandboxId: booted.sandboxId,\n    async stop(): Promise<void> {\n      await host.close()\n      await booted.stop()\n    },\n    ...(booted.pause\n      ? {\n          async pause(): Promise<void> {\n            await host.close()\n            await booted.pause!()\n          },\n        }\n      : {}),\n  }\n}\n\nconst defaultProcessEnvResolver: SecretResolver = name => process.env[name] ?? null\n\n/** Resolve every configured slug, failing loudly (no silent gaps in the sandbox env). */\nasync function resolveSandboxSecretsEnv(\n  config: SandboxSecretsConfig,\n): Promise<Record<string, string>> {\n  const resolver = config.resolver ?? defaultProcessEnvResolver\n  const env: Record<string, string> = {}\n  for (const slug of config.slugs) {\n    const value = await resolver(slug)\n    if (value === null || value === undefined) {\n      throw new Error(\n        `createSandboxAgentSessionHost: missing secret \"${slug}\" — set it in the ` +\n          \"host process's environment, or pass a resolver that can supply it.\",\n      )\n    }\n    assertSafeSecretValue(slug, value)\n    env[slug] = value\n  }\n  return env\n}\n","/**\n * AIP-36 `lifecycle` policy resolution — maps a `SandboxHandle`'s\n * `lifecycle.pause_after_idle` / `lifecycle.destroy_on` (plus whether this\n * boot is a request to reconnect to an existing box) to a concrete\n * teardown decision. Pure and host-agnostic: the actual pause-vs-kill call\n * happens in `@agentproto/runtime`'s sandbox proxy, which just reads this\n * policy back off.\n */\n\nimport type { SandboxHandle } from \"./types.js\"\n\nexport interface SandboxLifecyclePolicy {\n  /** What session close should do to the box: kill it (ephemeral, the\n   *  default) or pause it (keeps it reconnectable via `SandboxProvider.\n   *  connect`). */\n  teardown: \"kill\" | \"pause\"\n  /** Idle window in milliseconds, parsed from the AIP-37 `idle-<seconds>`\n   *  event name. Undefined when the spec doesn't declare\n   *  `lifecycle.pause_after_idle`. */\n  pauseAfterIdleMs?: number\n}\n\nconst IDLE_EVENT_PATTERN = /^idle-(\\d+)$/\n\n/**\n * `reuse` is true when this spawn asked to reconnect to an existing\n * sandbox id (`agent_start.sandbox.reuse`) — such a box defaults to\n * \"pause\" on close even absent an explicit `lifecycle` block, since\n * killing it would defeat the point of having reconnected. An explicit\n * `destroy_on` always wins over both `reuse` and `pause_after_idle`: the\n * spec is stating outright that this box must not survive session close.\n */\nexport function resolveLifecyclePolicy(spec: SandboxHandle, reuse: boolean): SandboxLifecyclePolicy {\n  if (spec.lifecycle?.destroy_on) return { teardown: \"kill\" }\n\n  const pauseAfterIdleMs = parseIdleAfterMs(spec.lifecycle?.pause_after_idle)\n  const teardown: \"kill\" | \"pause\" = reuse || pauseAfterIdleMs !== undefined ? \"pause\" : \"kill\"\n  return { teardown, ...(pauseAfterIdleMs !== undefined ? { pauseAfterIdleMs } : {}) }\n}\n\nfunction parseIdleAfterMs(event: string | undefined): number | undefined {\n  if (!event) return undefined\n  const match = IDLE_EVENT_PATTERN.exec(event)\n  if (!match) return undefined\n  return Number(match[1]) * 1000\n}\n","/**\n * @agentproto/sandbox — AIP-36 SANDBOX.md `defineSandbox` reference impl.\n *\n * A composable schema block defining the `sandbox` field — provider, config, command env, network egress, resource limits — for any manifest that names a compute environment for agent-issued shell commands. Sibling primitive to STORAGE.md (AIP-35); inline or ref, mirroring AIP-17 RUNNER and AIP-19 SECRETS.\n *\n * Spec: https://agentproto.sh/docs/aip-36\n *\n * Authoring paths:\n *   - TS:  `defineSandbox({...})` → `SandboxHandle`\n *   - MD:  `parseSandboxManifest(src) → sandboxFromManifest({...})` → `SandboxHandle`\n */\n\nexport const SPEC_NAME = \"agentsandbox/v1\" as const\nexport const SPEC_VERSION = \"1.0.0-alpha\" as const\n\nexport { defineSandbox } from \"./define-sandbox.js\"\nexport type {\n  SandboxDefinition,\n  SandboxHandle,\n  SandboxRuntimeInput,\n  SandboxRuntimeHandle,\n} from \"./types.js\"\n\n/** The AIP-36 frontmatter zod schema, under the name consumers that accept\n *  an inline `SandboxSpec` (e.g. `@agentproto/runtime`'s `agent_start.sandbox`)\n *  validate against. Same schema `define-sandbox.ts`/`manifest/index.ts` use. */\nexport { sandboxFrontmatterSchema as SandboxSpecSchema } from \"./schema.js\"\n\nexport {\n  createSandboxAgentSessionHost,\n  type SandboxSpec,\n  type BootedSandbox,\n  type SandboxBootOpts,\n  type SandboxProvider,\n  type SandboxSecretsConfig,\n  type CreateSandboxAgentSessionHostOpts,\n  type SandboxAgentSessionHost,\n} from \"./agent-session-host.js\"\n\nexport { resolveLifecyclePolicy, type SandboxLifecyclePolicy } from \"./lifecycle.js\"\n"]}
+{"version":3,"sources":["../src/agent-session-host.ts","../src/lifecycle.ts","../src/index.ts"],"names":[],"mappings":";;;;;;;;AAiIA,eAAsB,8BACpB,IAAA,EACkC;AAClC,EAAA,MAAM,GAAA,GAAM,MAAM,wBAAA,CAAyB,IAAA,CAAK,OAAO,CAAA;AACvD,EAAA,IAAI,MAAA;AACJ,EAAA,IAAI,IAAA,CAAK,cAAc,MAAA,EAAW;AAChC,IAAA,IAAI,CAAC,IAAA,CAAK,QAAA,CAAS,OAAA,EAAS;AAC1B,MAAA,MAAM,IAAI,KAAA;AAAA,QACR,CAAA,4DAAA,EAA+D,KAAK,SAAS,CAAA,8EAAA;AAAA,OAE/E;AAAA,IACF;AACA,IAAA,MAAA,GAAS,MAAM,IAAA,CAAK,QAAA,CAAS,OAAA,CAAQ,IAAA,CAAK,WAAW,IAAA,CAAK,IAAA,EAAM,EAAE,GAAA,EAAK,CAAA;AAAA,EACzE,CAAA,MAAO;AACL,IAAA,MAAA,GAAS,MAAM,KAAK,QAAA,CAAS,IAAA,CAAK,KAAK,IAAA,EAAM,EAAE,KAAK,CAAA;AAAA,EACtD;AACA,EAAA,IAAI,IAAA;AACJ,EAAA,IAAI;AACF,IAAA,IAAA,GAAO,MAAM,6BAAA,CAA8B,EAAE,GAAA,EAAK,MAAA,CAAO,QAAQ,CAAA;AAAA,EACnE,SAAS,GAAA,EAAK;AACZ,IAAA,MAAM,OAAO,IAAA,EAAK;AAClB,IAAA,MAAM,GAAA;AAAA,EACR;AACA,EAAA,OAAO;AAAA,IACL,GAAG,IAAA;AAAA,IACH,WAAW,MAAA,CAAO,SAAA;AAAA,IAClB,MAAM,IAAA,GAAsB;AAC1B,MAAA,MAAM,KAAK,KAAA,EAAM;AACjB,MAAA,MAAM,OAAO,IAAA,EAAK;AAAA,IACpB,CAAA;AAAA,IACA,GAAI,OAAO,KAAA,GACP;AAAA,MACE,MAAM,KAAA,GAAuB;AAC3B,QAAA,MAAM,KAAK,KAAA,EAAM;AACjB,QAAA,MAAM,OAAO,KAAA,EAAO;AAAA,MACtB;AAAA,QAEF;AAAC,GACP;AACF;AAEA,IAAM,yBAAA,GAA4C,CAAA,IAAA,KAAQ,OAAA,CAAQ,GAAA,CAAI,IAAI,CAAA,IAAK,IAAA;AAG/E,eAAe,yBACb,MAAA,EACiC;AACjC,EAAA,MAAM,QAAA,GAAW,OAAO,QAAA,IAAY,yBAAA;AACpC,EAAA,MAAM,MAA8B,EAAC;AACrC,EAAA,KAAA,MAAW,IAAA,IAAQ,OAAO,KAAA,EAAO;AAC/B,IAAA,MAAM,KAAA,GAAQ,MAAM,QAAA,CAAS,IAAI,CAAA;AACjC,IAAA,IAAI,KAAA,KAAU,IAAA,IAAQ,KAAA,KAAU,MAAA,EAAW;AACzC,MAAA,MAAM,IAAI,KAAA;AAAA,QACR,kDAAkD,IAAI,CAAA,yFAAA;AAAA,OAExD;AAAA,IACF;AACA,IAAA,qBAAA,CAAsB,MAAM,KAAK,CAAA;AACjC,IAAA,GAAA,CAAI,IAAI,CAAA,GAAI,KAAA;AAAA,EACd;AACA,EAAA,OAAO,GAAA;AACT;;;ACxKA,IAAM,kBAAA,GAAqB,cAAA;AAUpB,SAAS,sBAAA,CAAuB,MAAqB,KAAA,EAAwC;AAClG,EAAA,IAAI,KAAK,SAAA,EAAW,UAAA,EAAY,OAAO,EAAE,UAAU,MAAA,EAAO;AAE1D,EAAA,MAAM,gBAAA,GAAmB,gBAAA,CAAiB,IAAA,CAAK,SAAA,EAAW,gBAAgB,CAAA;AAC1E,EAAA,MAAM,QAAA,GAA6B,KAAA,IAAS,gBAAA,KAAqB,MAAA,GAAY,OAAA,GAAU,MAAA;AACvF,EAAA,OAAO,EAAE,UAAU,GAAI,gBAAA,KAAqB,SAAY,EAAE,gBAAA,EAAiB,GAAI,EAAC,EAAG;AACrF;AAEA,SAAS,iBAAiB,KAAA,EAA+C;AACvE,EAAA,IAAI,CAAC,OAAO,OAAO,MAAA;AACnB,EAAA,MAAM,KAAA,GAAQ,kBAAA,CAAmB,IAAA,CAAK,KAAK,CAAA;AAC3C,EAAA,IAAI,CAAC,OAAO,OAAO,MAAA;AACnB,EAAA,OAAO,MAAA,CAAO,KAAA,CAAM,CAAC,CAAC,CAAA,GAAI,GAAA;AAC5B;;;ACjCO,IAAM,SAAA,GAAY;AAClB,IAAM,YAAA,GAAe","file":"index.mjs","sourcesContent":["/**\n * AIP-36 sandbox-backed `AgentSessionHost`.\n *\n * The seam an `AgentStep` binds against (`AgentSessionHost`,\n * `@agentproto/workflow-runtime`) is already satisfiable by a *remote*\n * daemon via `connectDaemonAgentSessionHost` (`@agentproto/worktree`) —\n * it just needs a reachable MCP URL. So running a coding-agent step\n * inside a sandbox is: boot a provider-specific box that exposes an\n * agentproto daemon's MCP endpoint as a URL, then hand that URL to the\n * daemon host unchanged. No new session-host implementation, no\n * bespoke spawn/prompt plumbing — this module only wires secrets → env\n * → `provider.boot` → `connectDaemonAgentSessionHost`.\n */\n\nimport { assertSafeSecretValue, type SecretResolver } from \"@agentproto/secrets/exposure\"\nimport { connectDaemonAgentSessionHost, type DaemonAgentSessionHost } from \"@agentproto/worktree\"\nimport type { SandboxHandle } from \"./types.js\"\n\n/** AIP-36 sandbox manifest handle — provider id, config, env passthrough, limits. */\nexport type SandboxSpec = SandboxHandle\n\n/** What a `SandboxProvider` hands back once the box is up and reachable. */\nexport interface BootedSandbox {\n  /** The booted agentproto daemon's MCP endpoint, reachable from this process. */\n  mcpUrl: string\n  /** Provider-assigned sandbox id, for logging / lookup. */\n  sandboxId: string\n  /** Opaque secret gating `mcpUrl`, present when `opts.expose === \"private\"`\n   *  was honoured (see `SandboxBootOpts.expose`). Absent for the default\n   *  public-exposure path (boot-and-drive) and for providers/paths that\n   *  can't gate the port at all — a caller that needs a gated URL (e.g.\n   *  `attachSandbox`) MUST treat a missing token as \"not gated\", not as\n   *  \"no auth needed\". The token is the raw secret; how a client must\n   *  PRESENT it (bearer header, cookie, …) is provider-specific — see\n   *  `authHeaders`. */\n  token?: string\n  /** Exact HTTP header(s) a client must send to authenticate against the\n   *  gated `mcpUrl` — the provider's own answer to \"how do I present the\n   *  token\". Box, for instance, gates its private hostname with a\n   *  `Cookie: _port_auth=<token>` (verified live: bearer/query are ignored,\n   *  the port edge only honours the cookie), so it returns that here rather\n   *  than leaving the caller to guess a scheme. Present iff `token` is; a\n   *  token-only provider that omits this is treated by `buildMcpConfigSnippet`\n   *  as `Authorization: Bearer <token>`. */\n  authHeaders?: Record<string, string>\n  /** Tear down the sandbox. */\n  stop(): Promise<void>\n  /** Pause the sandbox instead of killing it — keeps it reconnectable via\n   *  `SandboxProvider.connect(sandboxId, ...)` later. Optional: providers\n   *  that can't pause (or don't support reconnect at all) omit it; callers\n   *  that want to pause fall back to `stop()` when it's absent. */\n  pause?(): Promise<void>\n}\n\n/** Env resolved from secrets, handed to `provider.boot`. */\nexport interface SandboxBootOpts {\n  env: Record<string, string>\n  /**\n   * How the provider should expose the daemon's port. `\"public\"` (the\n   * default when omitted) is boot-and-drive's ephemeral, provider-owned,\n   * ungated URL. `\"private\"` asks the provider for a PERSISTENT,\n   * token-gated URL instead — set by `attachSandbox`, which produces a\n   * durable connection descriptor and must never emit an ungated one.\n   * Providers that don't support gating simply ignore this and omit\n   * `BootedSandbox.token`; the caller is responsible for treating that as\n   * a failure when it needed a gated URL.\n   */\n  expose?: \"public\" | \"private\"\n  /**\n   * Keep the sandbox awake indefinitely for the always-on rendezvous model\n   * — set by `attachSandbox` when its own `keepAlive` opt is true. A\n   * provider that supports an explicit no-auto-stop/no-expiry assertion\n   * (e.g. Box's `ttlSeconds: null`) should (re-)apply it as part of\n   * `connect()`, defensively, even if the sandbox already defaults to it.\n   * Providers with no such concept simply ignore this.\n   */\n  keepAlive?: boolean\n}\n\n/**\n * Backend-agnostic sandbox lifecycle. Concrete implementations (e2b, modal,\n * daytona, blaxel, …) live in their own packages so this one stays free of\n * vendor SDK dependencies — see `@agentproto/sandbox-e2b`.\n */\nexport interface SandboxProvider {\n  boot(spec: SandboxSpec, opts: SandboxBootOpts): Promise<BootedSandbox>\n  /** Reconnect to an already-booted (possibly paused) sandbox instead of\n   *  booting a fresh one — the reuse path (`agent_start.sandbox.reuse`).\n   *  Optional: providers that can't reconnect (e.g. the `local` passthrough,\n   *  which tears down its temp workspace on `stop()`) omit it; the runtime\n   *  errors clearly when reuse is requested against such a provider. */\n  connect?(sandboxId: string, spec: SandboxSpec, opts: SandboxBootOpts): Promise<BootedSandbox>\n}\n\n/** Which secrets to resolve into the sandbox's env, and how. */\nexport interface SandboxSecretsConfig {\n  /** Secret slugs to resolve (e.g. `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`). */\n  slugs: readonly string[]\n  /** Resolves a slug to its value. Defaults to reading `process.env[slug]`. */\n  resolver?: SecretResolver\n}\n\nexport interface CreateSandboxAgentSessionHostOpts {\n  provider: SandboxProvider\n  spec: SandboxSpec\n  secrets: SandboxSecretsConfig\n  /** Reconnect to this existing sandbox id instead of booting a fresh box —\n   *  requires `provider.connect`; throws a clear error otherwise. */\n  sandboxId?: string\n}\n\nexport type SandboxAgentSessionHost = DaemonAgentSessionHost & {\n  /** Provider-assigned sandbox id (`BootedSandbox.sandboxId`) — surfaced so a\n   *  caller can record it (there's no local PID for a sandboxed session). */\n  sandboxId: string\n  /** Close the daemon connection AND tear down the sandbox. */\n  stop(): Promise<void>\n  /** Close the daemon connection and PAUSE the sandbox instead of killing\n   *  it — only present when the booted sandbox supports `pause()`. */\n  pause?(): Promise<void>\n}\n\n/**\n * Resolve `secrets` into an env map, boot (or, when `opts.sandboxId` is set,\n * reconnect to) the sandbox with it, then connect the #202 daemon host to\n * the sandbox's exposed MCP URL. `stop()` closes the daemon connection\n * before tearing down the sandbox (never leaks the box on a client-side\n * error); `pause()` does the same but pauses rather than kills.\n */\nexport async function createSandboxAgentSessionHost(\n  opts: CreateSandboxAgentSessionHostOpts,\n): Promise<SandboxAgentSessionHost> {\n  const env = await resolveSandboxSecretsEnv(opts.secrets)\n  let booted: BootedSandbox\n  if (opts.sandboxId !== undefined) {\n    if (!opts.provider.connect) {\n      throw new Error(\n        `createSandboxAgentSessionHost: reuse requested for sandbox \"${opts.sandboxId}\", ` +\n          \"but this provider has no connect() — it can only boot fresh sandboxes.\",\n      )\n    }\n    booted = await opts.provider.connect(opts.sandboxId, opts.spec, { env })\n  } else {\n    booted = await opts.provider.boot(opts.spec, { env })\n  }\n  let host: DaemonAgentSessionHost\n  try {\n    host = await connectDaemonAgentSessionHost({ url: booted.mcpUrl })\n  } catch (err) {\n    await booted.stop()\n    throw err\n  }\n  return {\n    ...host,\n    sandboxId: booted.sandboxId,\n    async stop(): Promise<void> {\n      await host.close()\n      await booted.stop()\n    },\n    ...(booted.pause\n      ? {\n          async pause(): Promise<void> {\n            await host.close()\n            await booted.pause!()\n          },\n        }\n      : {}),\n  }\n}\n\nconst defaultProcessEnvResolver: SecretResolver = name => process.env[name] ?? null\n\n/** Resolve every configured slug, failing loudly (no silent gaps in the sandbox env). */\nasync function resolveSandboxSecretsEnv(\n  config: SandboxSecretsConfig,\n): Promise<Record<string, string>> {\n  const resolver = config.resolver ?? defaultProcessEnvResolver\n  const env: Record<string, string> = {}\n  for (const slug of config.slugs) {\n    const value = await resolver(slug)\n    if (value === null || value === undefined) {\n      throw new Error(\n        `createSandboxAgentSessionHost: missing secret \"${slug}\" — set it in the ` +\n          \"host process's environment, or pass a resolver that can supply it.\",\n      )\n    }\n    assertSafeSecretValue(slug, value)\n    env[slug] = value\n  }\n  return env\n}\n","/**\n * AIP-36 `lifecycle` policy resolution — maps a `SandboxHandle`'s\n * `lifecycle.pause_after_idle` / `lifecycle.destroy_on` (plus whether this\n * boot is a request to reconnect to an existing box) to a concrete\n * teardown decision. Pure and host-agnostic: the actual pause-vs-kill call\n * happens in `@agentproto/runtime`'s sandbox proxy, which just reads this\n * policy back off.\n */\n\nimport type { SandboxHandle } from \"./types.js\"\n\nexport interface SandboxLifecyclePolicy {\n  /** What session close should do to the box: kill it (ephemeral, the\n   *  default) or pause it (keeps it reconnectable via `SandboxProvider.\n   *  connect`). */\n  teardown: \"kill\" | \"pause\"\n  /** Idle window in milliseconds, parsed from the AIP-37 `idle-<seconds>`\n   *  event name. Undefined when the spec doesn't declare\n   *  `lifecycle.pause_after_idle`. */\n  pauseAfterIdleMs?: number\n}\n\nconst IDLE_EVENT_PATTERN = /^idle-(\\d+)$/\n\n/**\n * `reuse` is true when this spawn asked to reconnect to an existing\n * sandbox id (`agent_start.sandbox.reuse`) — such a box defaults to\n * \"pause\" on close even absent an explicit `lifecycle` block, since\n * killing it would defeat the point of having reconnected. An explicit\n * `destroy_on` always wins over both `reuse` and `pause_after_idle`: the\n * spec is stating outright that this box must not survive session close.\n */\nexport function resolveLifecyclePolicy(spec: SandboxHandle, reuse: boolean): SandboxLifecyclePolicy {\n  if (spec.lifecycle?.destroy_on) return { teardown: \"kill\" }\n\n  const pauseAfterIdleMs = parseIdleAfterMs(spec.lifecycle?.pause_after_idle)\n  const teardown: \"kill\" | \"pause\" = reuse || pauseAfterIdleMs !== undefined ? \"pause\" : \"kill\"\n  return { teardown, ...(pauseAfterIdleMs !== undefined ? { pauseAfterIdleMs } : {}) }\n}\n\nfunction parseIdleAfterMs(event: string | undefined): number | undefined {\n  if (!event) return undefined\n  const match = IDLE_EVENT_PATTERN.exec(event)\n  if (!match) return undefined\n  return Number(match[1]) * 1000\n}\n","/**\n * @agentproto/sandbox — AIP-36 SANDBOX.md `defineSandbox` reference impl.\n *\n * A composable schema block defining the `sandbox` field — provider, config, command env, network egress, resource limits — for any manifest that names a compute environment for agent-issued shell commands. Sibling primitive to STORAGE.md (AIP-35); inline or ref, mirroring AIP-17 RUNNER and AIP-19 SECRETS.\n *\n * Spec: https://agentproto.sh/docs/aip-36\n *\n * Authoring paths:\n *   - TS:  `defineSandbox({...})` → `SandboxHandle`\n *   - MD:  `parseSandboxManifest(src) → sandboxFromManifest({...})` → `SandboxHandle`\n */\n\nexport const SPEC_NAME = \"agentsandbox/v1\" as const\nexport const SPEC_VERSION = \"1.0.0-alpha\" as const\n\nexport { defineSandbox } from \"./define-sandbox.js\"\nexport type {\n  SandboxDefinition,\n  SandboxHandle,\n  SandboxRuntimeInput,\n  SandboxRuntimeHandle,\n} from \"./types.js\"\n\n/** The AIP-36 frontmatter zod schema, under the name consumers that accept\n *  an inline `SandboxSpec` (e.g. `@agentproto/runtime`'s `agent_start.sandbox`)\n *  validate against. Same schema `define-sandbox.ts`/`manifest/index.ts` use. */\nexport { sandboxFrontmatterSchema as SandboxSpecSchema } from \"./schema.js\"\n\nexport {\n  createSandboxAgentSessionHost,\n  type SandboxSpec,\n  type BootedSandbox,\n  type SandboxBootOpts,\n  type SandboxProvider,\n  type SandboxSecretsConfig,\n  type CreateSandboxAgentSessionHostOpts,\n  type SandboxAgentSessionHost,\n} from \"./agent-session-host.js\"\n\nexport { resolveLifecyclePolicy, type SandboxLifecyclePolicy } from \"./lifecycle.js\"\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentproto/sandbox",
-  "version": "0.1.5",
+  "version": "0.2.1",
   "description": "@agentproto/sandbox — AIP-36 SANDBOX.md reference implementation. A composable schema block defining the `sandbox` field — provider, config, command env, network egress, resource limits — for any manifest that names a compute environment for agent-issued shell commands. Sibling primitive to STORAGE.md (AIP-35); inline or ref, mirroring AIP-17 RUNNER and AIP-19 SECRETS. Also ships createSandboxAgentSessionHost — the provider-agnostic seam that runs an AgentStep's coding-agent turn inside a booted sandbox by pointing the existing daemon-backed AgentSessionHost at its MCP URL.",
   "keywords": [
     "agentproto",
@@ -49,9 +49,9 @@
     "gray-matter": "^4.0.3",
     "zod": "^4.4.3",
     "@agentproto/define-doctype": "0.1.1",
-    "@agentproto/secrets": "0.2.1",
-    "@agentproto/worktree": "0.4.2",
-    "@agentproto/workflow-runtime": "0.5.0"
+    "@agentproto/secrets": "0.2.2",
+    "@agentproto/worktree": "0.5.0",
+    "@agentproto/workflow-runtime": "0.6.0"
   },
   "devDependencies": {
     "@types/node": "^25.6.2",