@agentproto/sandbox 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agentproto contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+# @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.
+
+> **Status: 0.1.0-alpha.** Generated by `scripts/scaffold-aip.mjs` — `build()` and `validate()` bodies are TODOs.
+
+Spec: <https://agentproto.sh/docs/aip-36>
+
+## Usage
+
+```ts
+import { defineSandbox } from "@agentproto/sandbox"
+
+const x = defineSandbox({
+  id: "my-sandbox",
+  description: "Short purpose.",
+  // ...
+})
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/chunk-VSYQ4BUI.mjs

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { createDoctype } from '@agentproto/define-doctype';
+
+/**
+ * @agentproto/sandbox v0.1.0-alpha
+ * AIP-36 SANDBOX.md `defineSandbox` reference implementation.
+ */
+
+var sandboxFrontmatterSchema = z.object({ "schema": z.literal("sandbox/v1").describe("Standalone-only. Identifies the doctype + version. Absent when the block is inlined.").optional(), "id": z.string().regex(new RegExp("^@[a-z0-9][a-z0-9-]*/[a-z0-9][a-z0-9-]*$")).describe("Standalone-only. Globally addressable id `@<owner-slug>/<sandbox-slug>`.").optional(), "version": z.string().regex(new RegExp("^\\d+\\.\\d+\\.\\d+(?:[-+][\\w.\\-]+)?$")).describe("Standalone-only. Spec version of THIS file.").optional(), "provider": z.string().min(1).describe("Backend kind. Day-1 enumerated set: local | mastra-e2b | mastra-modal | mastra-daytona | mastra-blaxel | node-permission. Hosts MAY register additional ids."), "config": z.record(z.string(), z.any()).describe("Provider-specific connection fields. Shape varies per provider (see AIP-36 \xA7Provider config shapes)."), "limits": z.object({ "timeout_ms": z.number().int().gte(1).optional(), "memory_mb": z.number().int().gte(1).optional(), "cpu_ms": z.number().int().gte(1).optional() }).strict().describe("Resource caps per command.").optional(), "env": z.object({ "auth": z.any().optional(), "passthrough": z.array(z.string()).describe("Static host env-var names to forward into the sandbox.").default([]) }).strict().optional(), "network": z.object({ "egress": z.array(z.string()).describe("Hostnames the sandbox MAY reach. Empty / missing = no egress.").default([]) }).strict().optional(), "mounts": z.array(z.any()).describe("Filesystems mounted inside the sandbox at declared paths. Maps to Mastra Workspace.mounts.").default([]), "identity": z.any().describe("AIP-23 identity-ref \u2014 owner of the sandbox processes.").optional(), "lifecycle": z.object({ "pause_after_idle": z.string().min(1).describe("AIP-37 event name (e.g. `idle-600` for 10 min). Provider-supported only (modal, daytona).").optional(), "destroy_on": z.string().min(1).describe("AIP-37 event name (e.g. `workspace-close`).").optional() }).strict().optional(), "read_only": z.boolean().describe("Reject command execution at the sandbox layer. Read-only sandbox calls fail with `sandbox_read_only`.").default(false), "metadata": z.record(z.string(), z.any()).describe("Free-form, namespaced. Adapter hints under `metadata.<adapter>.*`.").optional() }).strict().describe("Validates the YAML frontmatter portion of an AIP-36 SANDBOX.md manifest, OR the inline form embedded in any other manifest's `sandbox:` block. Compute-only \u2014 durable filesystem backings live in AIP-35 STORAGE.md.");
+var defineSandboxInner = createDoctype({
+  aip: 36,
+  name: "sandbox",
+  readDescription: false,
+  // AIP-36 makes `id` standalone-only — inline sandbox blocks fall
+  // back to `provider` for the cross-AIP id-pattern check (mirrors
+  // AIP-43 § Identity).
+  readIdentity: (def) => {
+    if (typeof def.id === "string" && def.id.length > 0) return def.id;
+    return def.provider;
+  },
+  validate(def) {
+    const { factory: _factory, capabilities: _capabilities, ...manifest } = def;
+    const result = sandboxFrontmatterSchema.safeParse(manifest);
+    if (!result.success) {
+      throw new Error(
+        `defineSandbox (AIP-36): ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+      );
+    }
+  },
+  build(def) {
+    const { factory, capabilities, ...manifest } = def;
+    return {
+      ...manifest,
+      ...factory !== void 0 ? { factory } : {},
+      ...capabilities !== void 0 ? { capabilities: Object.freeze({ ...capabilities }) } : {}
+    };
+  }
+});
+function defineSandbox(definition) {
+  return defineSandboxInner(
+    definition
+  );
+}
+
+export { defineSandbox, sandboxFrontmatterSchema };
+//# sourceMappingURL=chunk-VSYQ4BUI.mjs.map
+//# sourceMappingURL=chunk-VSYQ4BUI.mjs.map

package/dist/chunk-VSYQ4BUI.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema.ts","../src/define-sandbox.ts"],"names":[],"mappings":"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","file":"chunk-VSYQ4BUI.mjs","sourcesContent":["/**\n * AIP-36 SANDBOX.md frontmatter zod schema.\n *\n * Generated from `resources/aip-36/draft/SANDBOX.schema.json` via\n * json-schema-to-zod. Imported by both `define-sandbox.ts` (TS path\n * validation) and `manifest/index.ts` (.md path validation) so every\n * field-level constraint runs in both authoring paths from a single\n * source of truth — re-run scaffold-aip to refresh after spec changes.\n *\n * Cross-field rules (if/then/allOf in JSON Schema) don't translate\n * cleanly and live in `define-sandbox.ts`'s `validate(def)` instead.\n */\n\nimport { z } from \"zod\"\n\nexport const sandboxFrontmatterSchema = z.object({ \"schema\": z.literal(\"sandbox/v1\").describe(\"Standalone-only. Identifies the doctype + version. Absent when the block is inlined.\").optional(), \"id\": z.string().regex(new RegExp(\"^@[a-z0-9][a-z0-9-]*/[a-z0-9][a-z0-9-]*$\")).describe(\"Standalone-only. Globally addressable id `@<owner-slug>/<sandbox-slug>`.\").optional(), \"version\": z.string().regex(new RegExp(\"^\\\\d+\\\\.\\\\d+\\\\.\\\\d+(?:[-+][\\\\w.\\\\-]+)?$\")).describe(\"Standalone-only. Spec version of THIS file.\").optional(), \"provider\": z.string().min(1).describe(\"Backend kind. Day-1 enumerated set: local | mastra-e2b | mastra-modal | mastra-daytona | mastra-blaxel | node-permission. Hosts MAY register additional ids.\"), \"config\": z.record(z.string(), z.any()).describe(\"Provider-specific connection fields. Shape varies per provider (see AIP-36 §Provider config shapes).\"), \"limits\": z.object({ \"timeout_ms\": z.number().int().gte(1).optional(), \"memory_mb\": z.number().int().gte(1).optional(), \"cpu_ms\": z.number().int().gte(1).optional() }).strict().describe(\"Resource caps per command.\").optional(), \"env\": z.object({ \"auth\": z.any().optional(), \"passthrough\": z.array(z.string()).describe(\"Static host env-var names to forward into the sandbox.\").default([] as never) }).strict().optional(), \"network\": z.object({ \"egress\": z.array(z.string()).describe(\"Hostnames the sandbox MAY reach. Empty / missing = no egress.\").default([] as never) }).strict().optional(), \"mounts\": z.array(z.any()).describe(\"Filesystems mounted inside the sandbox at declared paths. Maps to Mastra Workspace.mounts.\").default([] as never), \"identity\": z.any().describe(\"AIP-23 identity-ref — owner of the sandbox processes.\").optional(), \"lifecycle\": z.object({ \"pause_after_idle\": z.string().min(1).describe(\"AIP-37 event name (e.g. `idle-600` for 10 min). Provider-supported only (modal, daytona).\").optional(), \"destroy_on\": z.string().min(1).describe(\"AIP-37 event name (e.g. `workspace-close`).\").optional() }).strict().optional(), \"read_only\": z.boolean().describe(\"Reject command execution at the sandbox layer. Read-only sandbox calls fail with `sandbox_read_only`.\").default(false), \"metadata\": z.record(z.string(), z.any()).describe(\"Free-form, namespaced. Adapter hints under `metadata.<adapter>.*`.\").optional() }).strict().describe(\"Validates the YAML frontmatter portion of an AIP-36 SANDBOX.md manifest, OR the inline form embedded in any other manifest's `sandbox:` block. Compute-only — durable filesystem backings live in AIP-35 STORAGE.md.\")\n\nexport type SandboxFrontmatter = z.infer<typeof sandboxFrontmatterSchema>\n","import { createDoctype } from \"@agentproto/define-doctype\"\nimport { sandboxFrontmatterSchema } from \"./schema.js\"\nimport type {\n  SandboxRuntimeHandle,\n  SandboxRuntimeInput,\n} from \"./types.js\"\n\n/**\n * AIP-36 reference implementation of `defineSandbox`.\n *\n * Built on `createDoctype` so the cross-AIP invariants (id pattern,\n * description length, top-level freeze, \"defineSandbox (AIP-36): …\"\n * error prefix) run uniformly with every other AIP defineX.\n *\n * Field-level validation runs the schema-derived zod from\n * `./schema.ts` against the manifest portion of the input. The\n * AIP-43 runtime slots (`factory`, `capabilities`) are HOST-OPAQUE\n * TS-runtime metadata stripped before validation and re-attached in\n * `build` — same pattern as `@agentproto/storage`'s `defineStorage`.\n *\n * Generic params:\n *   TFactory      — host-typed factory (e.g. `(input) => WorkspaceSandbox`\n *                   for the Guilde host). Defaults to `unknown`.\n *   TCapabilities — opaque metadata the registry queries on. Per\n *                   AIP-43 § Capability metadata namespace.\n */\nconst defineSandboxInner = createDoctype<\n  SandboxRuntimeInput,\n  SandboxRuntimeHandle\n>({\n  aip: 36,\n  name: \"sandbox\",\n  readDescription: false,\n  // AIP-36 makes `id` standalone-only — inline sandbox blocks fall\n  // back to `provider` for the cross-AIP id-pattern check (mirrors\n  // AIP-43 § Identity).\n  readIdentity: def => {\n    if (typeof def.id === \"string\" && def.id.length > 0) return def.id\n    return def.provider\n  },\n  validate(def) {\n    const { factory: _factory, capabilities: _capabilities, ...manifest } = def\n    const result = sandboxFrontmatterSchema.safeParse(manifest)\n    if (!result.success) {\n      throw new Error(\n        `defineSandbox (AIP-36): ${result.error.issues\n          .map(i => `${i.path.join(\".\")}: ${i.message}`)\n          .join(\"; \")}`,\n      )\n    }\n    // TODO: spec-36-specific cross-field rules (if/then/allOf in\n    // the JSON Schema) — those don't translate to zod cleanly and\n    // belong here. See @agentproto/operator's autonomy=gated rule.\n  },\n  build(def) {\n    const { factory, capabilities, ...manifest } = def\n    return {\n      ...manifest,\n      ...(factory !== undefined ? { factory } : {}),\n      ...(capabilities !== undefined\n        ? { capabilities: Object.freeze({ ...capabilities }) }\n        : {}),\n    } as SandboxRuntimeHandle\n  },\n})\n\n/**\n * Type-aware wrapper preserving `TFactory` / `TCapabilities` generics\n * across the call.\n */\nexport function defineSandbox<\n  TFactory = unknown,\n  TCapabilities extends Record<string, unknown> = Record<string, unknown>,\n>(\n  definition: SandboxRuntimeInput<TFactory, TCapabilities>,\n): SandboxRuntimeHandle<TFactory, TCapabilities> {\n  return defineSandboxInner(\n    definition as SandboxRuntimeInput,\n  ) as SandboxRuntimeHandle<TFactory, TCapabilities>\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import { S as SandboxRuntimeInput, a as SandboxRuntimeHandle } from './types-CCVWFnWl.js';
+export { b as SandboxDefinition, c as SandboxHandle } from './types-CCVWFnWl.js';
+
+/**
+ * Type-aware wrapper preserving `TFactory` / `TCapabilities` generics
+ * across the call.
+ */
+declare function defineSandbox<TFactory = unknown, TCapabilities extends Record<string, unknown> = Record<string, unknown>>(definition: SandboxRuntimeInput<TFactory, TCapabilities>): SandboxRuntimeHandle<TFactory, TCapabilities>;
+
+/**
+ * @agentproto/sandbox — AIP-36 SANDBOX.md `defineSandbox` reference impl.
+ *
+ * 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.
+ *
+ * Spec: https://agentproto.sh/docs/aip-36
+ *
+ * Authoring paths:
+ *   - TS:  `defineSandbox({...})` → `SandboxHandle`
+ *   - MD:  `parseSandboxManifest(src) → sandboxFromManifest({...})` → `SandboxHandle`
+ */
+declare const SPEC_NAME: "agentsandbox/v1";
+declare const SPEC_VERSION: "1.0.0-alpha";
+
+export { SPEC_NAME, SPEC_VERSION, SandboxRuntimeHandle, SandboxRuntimeInput, defineSandbox };

package/dist/index.mjs

@@ -0,0 +1,14 @@
+export { defineSandbox } from './chunk-VSYQ4BUI.mjs';
+
+/**
+ * @agentproto/sandbox v0.1.0-alpha
+ * AIP-36 SANDBOX.md `defineSandbox` reference implementation.
+ */
+
+// src/index.ts
+var SPEC_NAME = "agentsandbox/v1";
+var SPEC_VERSION = "1.0.0-alpha";
+
+export { SPEC_NAME, SPEC_VERSION };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +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"]}

package/dist/manifest/index.d.ts

@@ -0,0 +1,69 @@
+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>;
+
+/**
+ * AIP-36 SANDBOX.md sidecar parser + manifest-to-handle constructor.
+ *
+ * Mirror of `@agentproto/tool/manifest` and `@agentproto/driver/manifest`:
+ * the .md provides metadata; the TS module supplies any spec-specific
+ * runtime bits (schemas, execute bodies, …) that can't live in
+ * frontmatter. Both inputs end up in `defineSandbox` so the cross-AIP
+ * invariants run uniformly.
+ *
+ *
+ * The frontmatter zod schema below was generated from
+ * `resources/aip-36/draft/SANDBOX.schema.json` via json-schema-to-zod.
+ * Re-run scaffold-aip to refresh after spec changes (or hand-tune
+ * any constraint the converter doesn't capture cleanly).
+ */
+
+interface SandboxManifest {
+    frontmatter: SandboxFrontmatter;
+    body: string;
+}
+declare function parseSandboxManifest(source: string): SandboxManifest;
+declare function sandboxFromManifest(manifest: SandboxManifest): SandboxHandle;
+
+export { type SandboxFrontmatter, type SandboxManifest, parseSandboxManifest, sandboxFromManifest, sandboxFrontmatterSchema };

package/dist/manifest/index.mjs

@@ -0,0 +1,28 @@
+import { sandboxFrontmatterSchema, defineSandbox } from '../chunk-VSYQ4BUI.mjs';
+export { sandboxFrontmatterSchema } from '../chunk-VSYQ4BUI.mjs';
+import matter from 'gray-matter';
+
+/**
+ * @agentproto/sandbox v0.1.0-alpha
+ * AIP-36 SANDBOX.md `defineSandbox` reference implementation.
+ */
+function parseSandboxManifest(source) {
+  const parsed = matter(source);
+  if (Object.keys(parsed.data).length === 0) {
+    throw new Error("parseSandboxManifest: missing or empty frontmatter");
+  }
+  const result = sandboxFrontmatterSchema.safeParse(parsed.data);
+  if (!result.success) {
+    throw new Error(
+      `parseSandboxManifest: invalid frontmatter \u2014 ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+    );
+  }
+  return { frontmatter: result.data, body: parsed.content };
+}
+function sandboxFromManifest(manifest) {
+  return defineSandbox(manifest.frontmatter);
+}
+
+export { parseSandboxManifest, sandboxFromManifest };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/manifest/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/manifest/index.ts"],"names":[],"mappings":";;;;;;;;AA8BO,SAAS,qBAAqB,MAAA,EAAiC;AACpE,EAAA,MAAM,MAAA,GAAS,OAAO,MAAM,CAAA;AAC5B,EAAA,IAAI,OAAO,IAAA,CAAK,MAAA,CAAO,IAAI,CAAA,CAAE,WAAW,CAAA,EAAG;AACzC,IAAA,MAAM,IAAI,MAAM,oDAAoD,CAAA;AAAA,EACtE;AACA,EAAA,MAAM,MAAA,GAAS,wBAAA,CAAyB,SAAA,CAAU,MAAA,CAAO,IAAI,CAAA;AAC7D,EAAA,IAAI,CAAC,OAAO,OAAA,EAAS;AACnB,IAAA,MAAM,IAAI,KAAA;AAAA,MACR,CAAA,iDAAA,EAA+C,OAAO,KAAA,CAAM,MAAA,CACzD,IAAI,CAAC,CAAA,KAAM,GAAG,CAAA,CAAE,IAAA,CAAK,KAAK,GAAG,CAAC,KAAK,CAAA,CAAE,OAAO,EAAE,CAAA,CAC9C,IAAA,CAAK,IAAI,CAAC,CAAA;AAAA,KACf;AAAA,EACF;AACA,EAAA,OAAO,EAAE,WAAA,EAAa,MAAA,CAAO,IAAA,EAAM,IAAA,EAAM,OAAO,OAAA,EAAQ;AAC1D;AAEO,SAAS,oBAAoB,QAAA,EAA0C;AAK5E,EAAA,OAAO,aAAA,CAAc,SAAS,WAA2C,CAAA;AAC3E","file":"index.mjs","sourcesContent":["/**\n * AIP-36 SANDBOX.md sidecar parser + manifest-to-handle constructor.\n *\n * Mirror of `@agentproto/tool/manifest` and `@agentproto/driver/manifest`:\n * the .md provides metadata; the TS module supplies any spec-specific\n * runtime bits (schemas, execute bodies, …) that can't live in\n * frontmatter. Both inputs end up in `defineSandbox` so the cross-AIP\n * invariants run uniformly.\n *\n *\n * The frontmatter zod schema below was generated from\n * `resources/aip-36/draft/SANDBOX.schema.json` via json-schema-to-zod.\n * Re-run scaffold-aip to refresh after spec changes (or hand-tune\n * any constraint the converter doesn't capture cleanly).\n */\n\nimport matter from \"gray-matter\"\nimport { sandboxFrontmatterSchema, type SandboxFrontmatter } from \"../schema.js\"\nimport { defineSandbox } from \"../define-sandbox.js\"\nimport type { SandboxDefinition, SandboxHandle } from \"../types.js\"\n\n// Re-export so consumers can import the schema + inferred type either\n// from \"@@agentproto/sandbox/manifest\" or directly from \"@@agentproto/sandbox/schema\".\nexport { sandboxFrontmatterSchema, type SandboxFrontmatter }\n\nexport interface SandboxManifest {\n  frontmatter: SandboxFrontmatter\n  body: string\n}\n\nexport function parseSandboxManifest(source: string): SandboxManifest {\n  const parsed = matter(source)\n  if (Object.keys(parsed.data).length === 0) {\n    throw new Error(\"parseSandboxManifest: missing or empty frontmatter\")\n  }\n  const result = sandboxFrontmatterSchema.safeParse(parsed.data)\n  if (!result.success) {\n    throw new Error(\n      `parseSandboxManifest: invalid frontmatter — ${result.error.issues\n        .map((i) => `${i.path.join(\".\")}: ${i.message}`)\n        .join(\"; \")}`,\n    )\n  }\n  return { frontmatter: result.data, body: parsed.content }\n}\n\nexport function sandboxFromManifest(manifest: SandboxManifest): SandboxHandle {\n  // The zod-validated frontmatter is structurally compatible with\n  // SandboxDefinition; the cast pins the typing once the manifest\n  // schema and the TS interface diverge (e.g. handle has frozen fields\n  // a literal config doesn't carry yet).\n  return defineSandbox(manifest.frontmatter as unknown as SandboxDefinition)\n}\n"]}

package/dist/types-CCVWFnWl.d.ts

@@ -0,0 +1,300 @@
+/**
+ * AIP-36 SandboxDefinition + SandboxHandle.
+ *
+ * `SandboxDefinition` was generated from
+ * `resources/aip-36/draft/SANDBOX.schema.json` via json-schema-to-typescript.
+ * `SandboxHandle` is the readonly view of the same shape; tighten it
+ * by hand for fields that get defaults applied in build().
+ */
+type IdentityRefEntry = {
+    name: string;
+    email: string;
+    avatar?: string;
+    gpg_key?: string;
+    role?: string;
+    metadata?: {};
+    [k: string]: unknown;
+} | {
+    ref: string;
+    role?: string;
+    [k: string]: unknown;
+} | {
+    file: string;
+    role?: string;
+    [k: string]: unknown;
+};
+/**
+ * Validates the YAML frontmatter portion of an AIP-36 SANDBOX.md manifest, OR the inline form embedded in any other manifest's `sandbox:` block. Compute-only — durable filesystem backings live in AIP-35 STORAGE.md.
+ */
+interface SandboxDefinition {
+    /**
+     * Standalone-only. Identifies the doctype + version. Absent when the block is inlined.
+     */
+    schema?: "sandbox/v1";
+    /**
+     * Standalone-only. Globally addressable id `@<owner-slug>/<sandbox-slug>`.
+     */
+    id?: string;
+    /**
+     * Standalone-only. Spec version of THIS file.
+     */
+    version?: string;
+    /**
+     * Backend kind. Day-1 enumerated set: local | mastra-e2b | mastra-modal | mastra-daytona | mastra-blaxel | node-permission. Hosts MAY register additional ids.
+     */
+    provider: string;
+    /**
+     * Provider-specific connection fields. Shape varies per provider (see AIP-36 §Provider config shapes).
+     */
+    config: {};
+    /**
+     * Resource caps per command.
+     */
+    limits?: {
+        timeout_ms?: number;
+        memory_mb?: number;
+        cpu_ms?: number;
+    };
+    env?: {
+        auth?: AuthBlock;
+        /**
+         * Static host env-var names to forward into the sandbox.
+         */
+        passthrough?: string[];
+    };
+    network?: {
+        /**
+         * Hostnames the sandbox MAY reach. Empty / missing = no egress.
+         */
+        egress?: string[];
+    };
+    /**
+     * Filesystems mounted inside the sandbox at declared paths. Maps to Mastra Workspace.mounts.
+     */
+    mounts?: MountEntry[];
+    /**
+     * AIP-23 identity-ref — owner of the sandbox processes.
+     */
+    identity?: IdentityRefEntry | [IdentityRefEntry, ...IdentityRefEntry[]];
+    lifecycle?: {
+        /**
+         * AIP-37 event name (e.g. `idle-600` for 10 min). Provider-supported only (modal, daytona).
+         */
+        pause_after_idle?: string;
+        /**
+         * AIP-37 event name (e.g. `workspace-close`).
+         */
+        destroy_on?: string;
+    };
+    /**
+     * Reject command execution at the sandbox layer. Read-only sandbox calls fail with `sandbox_read_only`.
+     */
+    read_only?: boolean;
+    /**
+     * Free-form, namespaced. Adapter hints under `metadata.<adapter>.*`.
+     */
+    metadata?: {
+        [k: string]: unknown;
+    };
+}
+interface AuthBlock {
+    ref?: string;
+    state?: {
+        env?: string[];
+    };
+}
+interface MountEntry {
+    /**
+     * What to mount. `"workspace"` shortcut for the parent workspace storage.
+     */
+    source: "workspace" | {
+        ref: string;
+    } | {
+        inline: STORAGEMdFrontmatterAgentstorageV1FilesystemPolicyBlock;
+    } | {
+        file: string;
+    };
+    /**
+     * Absolute path inside the sandbox where the mount appears.
+     */
+    at: string;
+    mode?: "read-write" | "read-only";
+}
+/**
+ * Validates the YAML frontmatter portion of an AIP-35 STORAGE.md manifest, OR the inline form embedded in any other manifest's `storage:` block. Filesystem-only — sandbox-shaped backends (e2b/modal/...) live in AIP-36 SANDBOX.md.
+ */
+interface STORAGEMdFrontmatterAgentstorageV1FilesystemPolicyBlock {
+    /**
+     * Standalone-only. Identifies the doctype + version. Absent when the block is inlined in another manifest.
+     */
+    schema?: "storage/v1";
+    /**
+     * Standalone-only. Globally addressable id `@<owner-slug>/<storage-slug>`.
+     */
+    id?: string;
+    /**
+     * Standalone-only. Spec version of THIS file. Bump on breaking shape change.
+     */
+    version?: string;
+    /**
+     * Backend kind. Day-1 enumerated set: cloud-bucket | self-bucket | github | local-fs | dev-local | mastra-s3 | mastra-azure. Hosts MAY register additional ids; the schema accepts any non-empty string and host-side validation narrows.
+     */
+    provider: string;
+    /**
+     * Provider-specific connection fields. Shape varies per provider (see AIP-35 §Provider config shapes).
+     */
+    config: {};
+    sync?: SyncBlock;
+    auth?: AuthBlock1;
+    /**
+     * AIP-23 identity-ref block — commit author(s) for syncing providers (github). Supports multi-attribution (primary + co-authors).
+     */
+    identity?: ({
+        name: string;
+        email: string;
+        avatar?: string;
+        gpg_key?: string;
+        role?: string;
+        metadata?: {};
+        [k: string]: unknown;
+    } | {
+        ref: string;
+        role?: string;
+        [k: string]: unknown;
+    } | {
+        file: string;
+        role?: string;
+        [k: string]: unknown;
+    }) | [
+        ({
+            name: string;
+            email: string;
+            avatar?: string;
+            gpg_key?: string;
+            role?: string;
+            metadata?: {};
+            [k: string]: unknown;
+        } | {
+            ref: string;
+            role?: string;
+            [k: string]: unknown;
+        } | {
+            file: string;
+            role?: string;
+            [k: string]: unknown;
+        }),
+        ...({
+            name: string;
+            email: string;
+            avatar?: string;
+            gpg_key?: string;
+            role?: string;
+            metadata?: {};
+            [k: string]: unknown;
+        } | {
+            ref: string;
+            role?: string;
+            [k: string]: unknown;
+        } | {
+            file: string;
+            role?: string;
+            [k: string]: unknown;
+        })[]
+    ];
+    /**
+     * Paths NOT mirrored to the backing store. Glob-ish, prefix-matched.
+     */
+    exclude?: string[];
+    /**
+     * Reject writes at the storage layer.
+     */
+    read_only?: boolean;
+    /**
+     * Free-form, namespaced. Authors MAY stash adapter-specific hints under namespaced keys.
+     */
+    metadata?: {
+        [k: string]: unknown;
+    };
+}
+/**
+ * Sync semantics. Lifecycle triggers reference AIP-37 event names.
+ */
+interface SyncBlock {
+    mode?: "canonical" | "pull-push" | "watch";
+    pull?: {
+        /**
+         * AIP-37 lifecycle event name. Standard: workspace-open | turn-start | manual. Aliases (per-turn, each-write) resolve via AIP-37.
+         */
+        on?: string;
+        /**
+         * Cache validity for pull-push providers (e.g. github clone).
+         */
+        ttl_seconds?: number;
+    };
+    commit?: {
+        /**
+         * AIP-37 event name. Common: each-write | per-turn | per-conversation | manual.
+         */
+        on?: string;
+        /**
+         * Debounce window for each-write commit mode.
+         */
+        batch_window_ms?: number;
+        /**
+         * Template for commit message. Provider-specific tokens (e.g. {{operator}}, {{summary}}).
+         */
+        message_template?: string;
+    };
+    push?: {
+        /**
+         * AIP-37 event name. Common: per-commit | per-turn | per-conversation | manual.
+         */
+        on?: string;
+        /**
+         * Github only. Where commits land.
+         */
+        branch_policy?: "main" | "per-conversation" | "per-turn";
+        /**
+         * Github only. Whether to open PRs automatically.
+         */
+        pr_policy?: "none" | "auto" | "manual";
+    };
+    conflict?: {
+        policy?: "rebase" | "merge" | "abort" | "manual" | "last-writer-wins" | "split-conflicts";
+    };
+}
+/**
+ * Reference to AIP-19 SECRETS.md (or future ENV.md) for credentials.
+ */
+interface AuthBlock1 {
+    /**
+     * Path or registry slug pointing to a SECRETS.md (or future ENV.md) inventory.
+     */
+    ref?: string;
+    state?: {
+        /**
+         * Env-var names this consumer expects to be revealed from the referenced inventory.
+         */
+        env?: string[];
+    };
+}
+type SandboxHandle = Readonly<SandboxDefinition>;
+/**
+ * In-TS authoring shape — what callers pass to `defineSandbox(...)`
+ * when constructing a handle programmatically. Extends
+ * `SandboxDefinition` with two optional host-runtime slots.
+ */
+interface SandboxRuntimeInput<TFactory = unknown, TCapabilities extends Record<string, unknown> = Record<string, unknown>> extends SandboxDefinition {
+    factory?: TFactory;
+    capabilities?: TCapabilities;
+}
+/**
+ * What `defineSandbox(...)` returns. Carries `factory` + `capabilities`
+ * through unchanged so registry consumers can read them off the handle.
+ */
+type SandboxRuntimeHandle<TFactory = unknown, TCapabilities extends Record<string, unknown> = Record<string, unknown>> = Readonly<SandboxDefinition> & {
+    readonly factory?: TFactory;
+    readonly capabilities?: Readonly<TCapabilities>;
+};
+
+export type { SandboxRuntimeInput as S, SandboxRuntimeHandle as a, SandboxDefinition as b, SandboxHandle as c };

package/package.json

@@ -0,0 +1,68 @@
+{
+  "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.",
+  "keywords": [
+    "agentproto",
+    "aip-36",
+    "sandbox",
+    "defineSandbox",
+    "open-standard",
+    "agentic"
+  ],
+  "homepage": "https://agentproto.sh/docs/aip-36",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentproto/ts",
+    "directory": "packages/sandbox"
+  },
+  "bugs": {
+    "url": "https://github.com/agentproto/ts/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./manifest": {
+      "types": "./dist/manifest/index.d.ts",
+      "import": "./dist/manifest/index.mjs",
+      "default": "./dist/manifest/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "zod": "^4.4.3",
+    "@agentproto/define-doctype": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "@agentproto/tooling": "0.1.0-alpha.0"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  }
+}