@agentproto/sandbox 0.1.0-alpha.0 → 0.1.0

package/README.md

@@ -18,6 +18,32 @@ const x = defineSandbox({
 })
 ```
 
+## Running an agent step inside a sandbox
+
+`createSandboxAgentSessionHost` turns any `SandboxProvider` into an
+`AgentSessionHost` (`@agentproto/workflow-runtime`) — the seam `runWorkflow`
+injects for every `AgentStep`. It resolves the requested secrets into an env
+map, boots the sandbox with that env, then connects
+`connectDaemonAgentSessionHost` (`@agentproto/worktree`) to the sandbox's
+exposed agentproto daemon — reusing the same daemon-backed session host a
+local run would use, unchanged.
+
+```ts
+import { createSandboxAgentSessionHost } from "@agentproto/sandbox"
+import { e2bSandboxProvider } from "@agentproto/sandbox-e2b"
+
+const host = await createSandboxAgentSessionHost({
+  provider: e2bSandboxProvider,
+  spec: { provider: "e2b", config: {} },
+  secrets: { slugs: ["OPENROUTER_API_KEY"] },
+})
+try {
+  // await runWorkflow({ workflow, input, agents: host })
+} finally {
+  await host.stop()
+}
+```
+
 ## License
 
 MIT — see [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -1,5 +1,8 @@
-import { S as SandboxRuntimeInput, a as SandboxRuntimeHandle } from './types-CCVWFnWl.js';
-export { b as SandboxDefinition, c as SandboxHandle } from './types-CCVWFnWl.js';
+import { S as SandboxRuntimeInput, a as SandboxRuntimeHandle, b as SandboxHandle } from './schema-PGQIdcQ3.js';
+export { c as SandboxDefinition, s as SandboxSpecSchema } from './schema-PGQIdcQ3.js';
+import { SecretResolver } from '@agentproto/secrets/exposure';
+import { DaemonAgentSessionHost } from '@agentproto/worktree';
+import 'zod';
 
 /**
  * Type-aware wrapper preserving `TFactory` / `TCapabilities` generics
@@ -7,6 +10,117 @@ export { b as SandboxDefinition, c as SandboxHandle } from './types-CCVWFnWl.js'
  */
 declare function defineSandbox<TFactory = unknown, TCapabilities extends Record<string, unknown> = Record<string, unknown>>(definition: SandboxRuntimeInput<TFactory, TCapabilities>): SandboxRuntimeHandle<TFactory, TCapabilities>;
 
+/**
+ * AIP-36 sandbox-backed `AgentSessionHost`.
+ *
+ * The seam an `AgentStep` binds against (`AgentSessionHost`,
+ * `@agentproto/workflow-runtime`) is already satisfiable by a *remote*
+ * daemon via `connectDaemonAgentSessionHost` (`@agentproto/worktree`) —
+ * it just needs a reachable MCP URL. So running a coding-agent step
+ * inside a sandbox is: boot a provider-specific box that exposes an
+ * agentproto daemon's MCP endpoint as a URL, then hand that URL to the
+ * daemon host unchanged. No new session-host implementation, no
+ * bespoke spawn/prompt plumbing — this module only wires secrets → env
+ * → `provider.boot` → `connectDaemonAgentSessionHost`.
+ */
+
+/** AIP-36 sandbox manifest handle — provider id, config, env passthrough, limits. */
+type SandboxSpec = SandboxHandle;
+/** What a `SandboxProvider` hands back once the box is up and reachable. */
+interface BootedSandbox {
+    /** The booted agentproto daemon's MCP endpoint, reachable from this process. */
+    mcpUrl: string;
+    /** Provider-assigned sandbox id, for logging / lookup. */
+    sandboxId: string;
+    /** Tear down the sandbox. */
+    stop(): Promise<void>;
+    /** Pause the sandbox instead of killing it — keeps it reconnectable via
+     *  `SandboxProvider.connect(sandboxId, ...)` later. Optional: providers
+     *  that can't pause (or don't support reconnect at all) omit it; callers
+     *  that want to pause fall back to `stop()` when it's absent. */
+    pause?(): Promise<void>;
+}
+/** Env resolved from secrets, handed to `provider.boot`. */
+interface SandboxBootOpts {
+    env: Record<string, string>;
+}
+/**
+ * Backend-agnostic sandbox lifecycle. Concrete implementations (e2b, modal,
+ * daytona, blaxel, …) live in their own packages so this one stays free of
+ * vendor SDK dependencies — see `@agentproto/sandbox-e2b`.
+ */
+interface SandboxProvider {
+    boot(spec: SandboxSpec, opts: SandboxBootOpts): Promise<BootedSandbox>;
+    /** Reconnect to an already-booted (possibly paused) sandbox instead of
+     *  booting a fresh one — the reuse path (`agent_start.sandbox.reuse`).
+     *  Optional: providers that can't reconnect (e.g. the `local` passthrough,
+     *  which tears down its temp workspace on `stop()`) omit it; the runtime
+     *  errors clearly when reuse is requested against such a provider. */
+    connect?(sandboxId: string, spec: SandboxSpec, opts: SandboxBootOpts): Promise<BootedSandbox>;
+}
+/** Which secrets to resolve into the sandbox's env, and how. */
+interface SandboxSecretsConfig {
+    /** Secret slugs to resolve (e.g. `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`). */
+    slugs: readonly string[];
+    /** Resolves a slug to its value. Defaults to reading `process.env[slug]`. */
+    resolver?: SecretResolver;
+}
+interface CreateSandboxAgentSessionHostOpts {
+    provider: SandboxProvider;
+    spec: SandboxSpec;
+    secrets: SandboxSecretsConfig;
+    /** Reconnect to this existing sandbox id instead of booting a fresh box —
+     *  requires `provider.connect`; throws a clear error otherwise. */
+    sandboxId?: string;
+}
+type SandboxAgentSessionHost = DaemonAgentSessionHost & {
+    /** Provider-assigned sandbox id (`BootedSandbox.sandboxId`) — surfaced so a
+     *  caller can record it (there's no local PID for a sandboxed session). */
+    sandboxId: string;
+    /** Close the daemon connection AND tear down the sandbox. */
+    stop(): Promise<void>;
+    /** Close the daemon connection and PAUSE the sandbox instead of killing
+     *  it — only present when the booted sandbox supports `pause()`. */
+    pause?(): Promise<void>;
+};
+/**
+ * Resolve `secrets` into an env map, boot (or, when `opts.sandboxId` is set,
+ * reconnect to) the sandbox with it, then connect the #202 daemon host to
+ * the sandbox's exposed MCP URL. `stop()` closes the daemon connection
+ * before tearing down the sandbox (never leaks the box on a client-side
+ * error); `pause()` does the same but pauses rather than kills.
+ */
+declare function createSandboxAgentSessionHost(opts: CreateSandboxAgentSessionHostOpts): Promise<SandboxAgentSessionHost>;
+
+/**
+ * AIP-36 `lifecycle` policy resolution — maps a `SandboxHandle`'s
+ * `lifecycle.pause_after_idle` / `lifecycle.destroy_on` (plus whether this
+ * boot is a request to reconnect to an existing box) to a concrete
+ * teardown decision. Pure and host-agnostic: the actual pause-vs-kill call
+ * happens in `@agentproto/runtime`'s sandbox proxy, which just reads this
+ * policy back off.
+ */
+
+interface SandboxLifecyclePolicy {
+    /** What session close should do to the box: kill it (ephemeral, the
+     *  default) or pause it (keeps it reconnectable via `SandboxProvider.
+     *  connect`). */
+    teardown: "kill" | "pause";
+    /** Idle window in milliseconds, parsed from the AIP-37 `idle-<seconds>`
+     *  event name. Undefined when the spec doesn't declare
+     *  `lifecycle.pause_after_idle`. */
+    pauseAfterIdleMs?: number;
+}
+/**
+ * `reuse` is true when this spawn asked to reconnect to an existing
+ * sandbox id (`agent_start.sandbox.reuse`) — such a box defaults to
+ * "pause" on close even absent an explicit `lifecycle` block, since
+ * killing it would defeat the point of having reconnected. An explicit
+ * `destroy_on` always wins over both `reuse` and `pause_after_idle`: the
+ * spec is stating outright that this box must not survive session close.
+ */
+declare function resolveLifecyclePolicy(spec: SandboxHandle, reuse: boolean): SandboxLifecyclePolicy;
+
 /**
  * @agentproto/sandbox — AIP-36 SANDBOX.md `defineSandbox` reference impl.
  *
@@ -21,4 +135,4 @@ declare function defineSandbox<TFactory = unknown, TCapabilities extends Record<
 declare const SPEC_NAME: "agentsandbox/v1";
 declare const SPEC_VERSION: "1.0.0-alpha";
 
-export { SPEC_NAME, SPEC_VERSION, SandboxRuntimeHandle, SandboxRuntimeInput, defineSandbox };
+export { type BootedSandbox, type CreateSandboxAgentSessionHostOpts, SPEC_NAME, SPEC_VERSION, type SandboxAgentSessionHost, type SandboxBootOpts, SandboxHandle, type SandboxLifecyclePolicy, type SandboxProvider, SandboxRuntimeHandle, SandboxRuntimeInput, type SandboxSecretsConfig, type SandboxSpec, createSandboxAgentSessionHost, defineSandbox, resolveLifecyclePolicy };

package/dist/index.mjs

@@ -1,14 +1,82 @@
-export { defineSandbox } from './chunk-VSYQ4BUI.mjs';
+export { sandboxFrontmatterSchema as SandboxSpecSchema, defineSandbox } from './chunk-VSYQ4BUI.mjs';
+import { assertSafeSecretValue } from '@agentproto/secrets/exposure';
+import { connectDaemonAgentSessionHost } from '@agentproto/worktree';
 
 /**
  * @agentproto/sandbox v0.1.0-alpha
  * AIP-36 SANDBOX.md `defineSandbox` reference implementation.
  */
+async function createSandboxAgentSessionHost(opts) {
+  const env = await resolveSandboxSecretsEnv(opts.secrets);
+  let booted;
+  if (opts.sandboxId !== void 0) {
+    if (!opts.provider.connect) {
+      throw new Error(
+        `createSandboxAgentSessionHost: reuse requested for sandbox "${opts.sandboxId}", but this provider has no connect() \u2014 it can only boot fresh sandboxes.`
+      );
+    }
+    booted = await opts.provider.connect(opts.sandboxId, opts.spec, { env });
+  } else {
+    booted = await opts.provider.boot(opts.spec, { env });
+  }
+  let host;
+  try {
+    host = await connectDaemonAgentSessionHost({ url: booted.mcpUrl });
+  } catch (err) {
+    await booted.stop();
+    throw err;
+  }
+  return {
+    ...host,
+    sandboxId: booted.sandboxId,
+    async stop() {
+      await host.close();
+      await booted.stop();
+    },
+    ...booted.pause ? {
+      async pause() {
+        await host.close();
+        await booted.pause();
+      }
+    } : {}
+  };
+}
+var defaultProcessEnvResolver = (name) => process.env[name] ?? null;
+async function resolveSandboxSecretsEnv(config) {
+  const resolver = config.resolver ?? defaultProcessEnvResolver;
+  const env = {};
+  for (const slug of config.slugs) {
+    const value = await resolver(slug);
+    if (value === null || value === void 0) {
+      throw new Error(
+        `createSandboxAgentSessionHost: missing secret "${slug}" \u2014 set it in the host process's environment, or pass a resolver that can supply it.`
+      );
+    }
+    assertSafeSecretValue(slug, value);
+    env[slug] = value;
+  }
+  return env;
+}
+
+// src/lifecycle.ts
+var IDLE_EVENT_PATTERN = /^idle-(\d+)$/;
+function resolveLifecyclePolicy(spec, reuse) {
+  if (spec.lifecycle?.destroy_on) return { teardown: "kill" };
+  const pauseAfterIdleMs = parseIdleAfterMs(spec.lifecycle?.pause_after_idle);
+  const teardown = reuse || pauseAfterIdleMs !== void 0 ? "pause" : "kill";
+  return { teardown, ...pauseAfterIdleMs !== void 0 ? { pauseAfterIdleMs } : {} };
+}
+function parseIdleAfterMs(event) {
+  if (!event) return void 0;
+  const match = IDLE_EVENT_PATTERN.exec(event);
+  if (!match) return void 0;
+  return Number(match[1]) * 1e3;
+}
 
 // src/index.ts
 var SPEC_NAME = "agentsandbox/v1";
 var SPEC_VERSION = "1.0.0-alpha";
 
-export { SPEC_NAME, SPEC_VERSION };
+export { SPEC_NAME, SPEC_VERSION, createSandboxAgentSessionHost, resolveLifecyclePolicy };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;AAYO,IAAM,SAAA,GAAY;AAClB,IAAM,YAAA,GAAe","file":"index.mjs","sourcesContent":["/**\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"]}
+{"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"]}

package/dist/manifest/index.d.ts

@@ -1,47 +1,6 @@
-import { z } from 'zod';
-import { c as SandboxHandle } from '../types-CCVWFnWl.js';
-
-/**
- * AIP-36 SANDBOX.md frontmatter zod schema.
- *
- * Generated from `resources/aip-36/draft/SANDBOX.schema.json` via
- * json-schema-to-zod. Imported by both `define-sandbox.ts` (TS path
- * validation) and `manifest/index.ts` (.md path validation) so every
- * field-level constraint runs in both authoring paths from a single
- * source of truth — re-run scaffold-aip to refresh after spec changes.
- *
- * Cross-field rules (if/then/allOf in JSON Schema) don't translate
- * cleanly and live in `define-sandbox.ts`'s `validate(def)` instead.
- */
-
-declare const sandboxFrontmatterSchema: z.ZodObject<{
-    schema: z.ZodOptional<z.ZodLiteral<"sandbox/v1">>;
-    id: z.ZodOptional<z.ZodString>;
-    version: z.ZodOptional<z.ZodString>;
-    provider: z.ZodString;
-    config: z.ZodRecord<z.ZodString, z.ZodAny>;
-    limits: z.ZodOptional<z.ZodObject<{
-        timeout_ms: z.ZodOptional<z.ZodNumber>;
-        memory_mb: z.ZodOptional<z.ZodNumber>;
-        cpu_ms: z.ZodOptional<z.ZodNumber>;
-    }, z.core.$strict>>;
-    env: z.ZodOptional<z.ZodObject<{
-        auth: z.ZodOptional<z.ZodAny>;
-        passthrough: z.ZodDefault<z.ZodArray<z.ZodString>>;
-    }, z.core.$strict>>;
-    network: z.ZodOptional<z.ZodObject<{
-        egress: z.ZodDefault<z.ZodArray<z.ZodString>>;
-    }, z.core.$strict>>;
-    mounts: z.ZodDefault<z.ZodArray<z.ZodAny>>;
-    identity: z.ZodOptional<z.ZodAny>;
-    lifecycle: z.ZodOptional<z.ZodObject<{
-        pause_after_idle: z.ZodOptional<z.ZodString>;
-        destroy_on: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>;
-    read_only: z.ZodDefault<z.ZodBoolean>;
-    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
-}, z.core.$strict>;
-type SandboxFrontmatter = z.infer<typeof sandboxFrontmatterSchema>;
+import { d as SandboxFrontmatter, b as SandboxHandle } from '../schema-PGQIdcQ3.js';
+export { s as sandboxFrontmatterSchema } from '../schema-PGQIdcQ3.js';
+import 'zod';
 
 /**
  * AIP-36 SANDBOX.md sidecar parser + manifest-to-handle constructor.
@@ -66,4 +25,4 @@ interface SandboxManifest {
 declare function parseSandboxManifest(source: string): SandboxManifest;
 declare function sandboxFromManifest(manifest: SandboxManifest): SandboxHandle;
 
-export { type SandboxFrontmatter, type SandboxManifest, parseSandboxManifest, sandboxFromManifest, sandboxFrontmatterSchema };
+export { SandboxFrontmatter, type SandboxManifest, parseSandboxManifest, sandboxFromManifest };

package/dist/{types-CCVWFnWl.d.ts → schema-PGQIdcQ3.d.ts}

@@ -1,3 +1,5 @@
+import { z } from 'zod';
+
 /**
  * AIP-36 SandboxDefinition + SandboxHandle.
  *
@@ -297,4 +299,46 @@ type SandboxRuntimeHandle<TFactory = unknown, TCapabilities extends Record<strin
     readonly capabilities?: Readonly<TCapabilities>;
 };
 
-export type { SandboxRuntimeInput as S, SandboxRuntimeHandle as a, SandboxDefinition as b, SandboxHandle as c };
+/**
+ * AIP-36 SANDBOX.md frontmatter zod schema.
+ *
+ * Generated from `resources/aip-36/draft/SANDBOX.schema.json` via
+ * json-schema-to-zod. Imported by both `define-sandbox.ts` (TS path
+ * validation) and `manifest/index.ts` (.md path validation) so every
+ * field-level constraint runs in both authoring paths from a single
+ * source of truth — re-run scaffold-aip to refresh after spec changes.
+ *
+ * Cross-field rules (if/then/allOf in JSON Schema) don't translate
+ * cleanly and live in `define-sandbox.ts`'s `validate(def)` instead.
+ */
+
+declare const sandboxFrontmatterSchema: z.ZodObject<{
+    schema: z.ZodOptional<z.ZodLiteral<"sandbox/v1">>;
+    id: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodString>;
+    provider: z.ZodString;
+    config: z.ZodRecord<z.ZodString, z.ZodAny>;
+    limits: z.ZodOptional<z.ZodObject<{
+        timeout_ms: z.ZodOptional<z.ZodNumber>;
+        memory_mb: z.ZodOptional<z.ZodNumber>;
+        cpu_ms: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    env: z.ZodOptional<z.ZodObject<{
+        auth: z.ZodOptional<z.ZodAny>;
+        passthrough: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    network: z.ZodOptional<z.ZodObject<{
+        egress: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    mounts: z.ZodDefault<z.ZodArray<z.ZodAny>>;
+    identity: z.ZodOptional<z.ZodAny>;
+    lifecycle: z.ZodOptional<z.ZodObject<{
+        pause_after_idle: z.ZodOptional<z.ZodString>;
+        destroy_on: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    read_only: z.ZodDefault<z.ZodBoolean>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, z.core.$strict>;
+type SandboxFrontmatter = z.infer<typeof sandboxFrontmatterSchema>;
+
+export { type SandboxRuntimeInput as S, type SandboxRuntimeHandle as a, type SandboxHandle as b, type SandboxDefinition as c, type SandboxFrontmatter as d, sandboxFrontmatterSchema as s };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agentproto/sandbox",
-  "version": "0.1.0-alpha.0",
-  "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.",
+  "version": "0.1.0",
+  "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",
     "aip-36",
@@ -48,7 +48,10 @@
   "dependencies": {
     "gray-matter": "^4.0.3",
     "zod": "^4.4.3",
-    "@agentproto/define-doctype": "0.1.0"
+    "@agentproto/define-doctype": "0.1.0",
+    "@agentproto/secrets": "0.1.0",
+    "@agentproto/worktree": "0.2.0",
+    "@agentproto/workflow-runtime": "0.3.0"
   },
   "devDependencies": {
     "@types/node": "^25.6.2",