managed-deepagents 0.0.1 → 0.0.3-dev.13

package/README.md

@@ -0,0 +1,95 @@
+<!-- markdownlint-disable MD033 MD041 -->
+
+<div align="center">
+  <a href="https://www.langchain.com/langsmith-managed-deep-agents-waitlist">
+    <img alt="Managed Deep Agents logo" src="https://raw.githubusercontent.com/langchain-ai/managed-deepagents-sdk/main/.github/assets/logo.png" width="70%">
+  </a>
+</div>
+
+<div align="center">
+  <h3>TypeScript authoring package and CLI launcher for Managed Deep Agents.</h3>
+</div>
+
+> [!IMPORTANT]
+> **Active development / private beta.** Managed Deep Agents is in active
+> development and currently in private beta. The npm package API and managed
+> runtime contract may change. [Join the
+> waitlist](https://www.langchain.com/langsmith-managed-deep-agents-waitlist)
+> for access and updates.
+
+`managed-deepagents` is the npm package for authoring Managed Deep Agents in
+TypeScript and Node.js. It includes:
+
+- `defineDeepAgent`, the TypeScript authoring contract for managed agents.
+- `mda`, the CLI used to build and deploy your agent to LangSmith.
+- `managed-deepagents/runtime`, the runtime helper used by generated managed
+  entry modules.
+
+## Install
+
+```bash
+npm install managed-deepagents
+```
+
+> [!NOTE]
+> **Private beta: dev releases only.** We currently publish under the `dev`
+> dist-tag and have no stable `latest` version yet. Install the dev channel
+> explicitly:
+>
+> ```bash
+> npm install managed-deepagents@dev
+> ```
+
+This package requires Node.js 22 or newer. The `mda` binary is delivered through
+per-platform optional dependencies, so install only downloads the binary for your
+OS and CPU architecture.
+
+## Define an Agent
+
+Create an `agent.ts` that exports a named `agent` definition:
+
+```ts
+import { defineDeepAgent } from "managed-deepagents";
+import instructions from "./instructions.md" with { type: "text" };
+import { queryDB } from "./tools/query-db";
+
+export const agent = defineDeepAgent({
+  model: "openai:gpt-5.5",
+  systemPrompt: instructions,
+  tools: [queryDB],
+});
+```
+
+`defineDeepAgent` accepts the `createDeepAgent` configuration surface minus the
+managed keys: `backend`, `store`, and `checkpointer`. Those are provided by the
+managed runtime when your agent is deployed.
+
+## Project Shape
+
+```text
+my-agent/
+  agent.ts
+  instructions.md
+  tools/
+  middleware/
+  skills/
+```
+
+The CLI copies your project files into the managed build and generates the entry
+module that connects your definition to the hosted runtime.
+
+## CLI
+
+Build locally:
+
+```bash
+mda build ./my-agent
+```
+
+Deploy to LangSmith:
+
+```bash
+mda deploy ./my-agent
+```
+
+The generated build is written to `<root>/.mda/build` by default.

package/bin/mda.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+
+// Thin launcher that forwards all arguments to the prebuilt `mda` binary for
+// the current platform. The binary is distributed via per-platform packages
+// (see src/resolve.ts, compiled to dist/resolve.js).
+
+import { spawnSync } from "node:child_process";
+
+import { resolveBinary } from "../dist/resolve.js";
+
+function main() {
+  let binary;
+  try {
+    binary = resolveBinary();
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    process.exit(1);
+  }
+
+  const result = spawnSync(binary, process.argv.slice(2), { stdio: "inherit" });
+
+  if (result.error) {
+    process.stderr.write(`failed to launch mda: ${result.error.message}\n`);
+    process.exit(1);
+  }
+
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+main();

package/dist/define-deep-agent.d.ts

@@ -0,0 +1,28 @@
+import type { DeepAgentDefinition, DefineDeepAgentConfig } from "./types.js";
+/**
+ * Define a Managed Deep Agent.
+ *
+ * `defineDeepAgent` is the v0 authoring contract for MDA. It accepts the full
+ * `createDeepAgent` surface except the managed keys (`backend`, `store`,
+ * `checkpointer`, `systemPrompt`) and returns a pre-runtime spec — not a
+ * compiled graph.
+ *
+ * At deploy time, `mda` generates an entry module that hands this definition to
+ * the managed runtime, which injects the platform-owned backend/store/
+ * checkpointer, embeds the system prompt from `instructions.md`, and compiles
+ * it into a Deep Agent.
+ *
+ * @example
+ * ```ts
+ * import { defineDeepAgent } from "managed-deepagents";
+ * import { queryDB } from "./tools/query-db";
+ *
+ * // The system prompt comes from instructions.md next to this file.
+ * export const agent = defineDeepAgent({
+ *   model: "openai:gpt-5.5",
+ *   tools: [queryDB],
+ * });
+ * ```
+ */
+export declare function defineDeepAgent(config: DefineDeepAgentConfig): DeepAgentDefinition;
+//# sourceMappingURL=define-deep-agent.d.ts.map

package/dist/define-deep-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-deep-agent.d.ts","sourceRoot":"","sources":["../src/define-deep-agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,qBAAqB,GAAG,mBAAmB,CAKlF"}

package/dist/define-deep-agent.js

@@ -0,0 +1,32 @@
+/**
+ * Define a Managed Deep Agent.
+ *
+ * `defineDeepAgent` is the v0 authoring contract for MDA. It accepts the full
+ * `createDeepAgent` surface except the managed keys (`backend`, `store`,
+ * `checkpointer`, `systemPrompt`) and returns a pre-runtime spec — not a
+ * compiled graph.
+ *
+ * At deploy time, `mda` generates an entry module that hands this definition to
+ * the managed runtime, which injects the platform-owned backend/store/
+ * checkpointer, embeds the system prompt from `instructions.md`, and compiles
+ * it into a Deep Agent.
+ *
+ * @example
+ * ```ts
+ * import { defineDeepAgent } from "managed-deepagents";
+ * import { queryDB } from "./tools/query-db";
+ *
+ * // The system prompt comes from instructions.md next to this file.
+ * export const agent = defineDeepAgent({
+ *   model: "openai:gpt-5.5",
+ *   tools: [queryDB],
+ * });
+ * ```
+ */
+export function defineDeepAgent(config) {
+    return {
+        kind: "deep-agent",
+        config: config,
+    };
+}
+//# sourceMappingURL=define-deep-agent.js.map

package/dist/define-deep-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-deep-agent.js","sourceRoot":"","sources":["../src/define-deep-agent.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,eAAe,CAAC,MAA6B;IAC3D,OAAO;QACL,IAAI,EAAE,YAAY;QAClB,MAAM,EAAE,MAAuC;KAChD,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { defineDeepAgent } from "./define-deep-agent.js";
+export { defineSandbox } from "./sandbox.js";
+export type { ChannelAttachment, ChannelDestination, ChannelEvent, ChannelMessage, ChannelPostOptions, DeepAgentDefinition, DefineDeepAgentConfig, ManagedDeepAgentKey, PostedChannelMessage, Runtime, RuntimeChannel, } from "./types.js";
+export type { DefineSandboxOptions, ManagedSandboxOptionKey, SandboxDefinition, SandboxProviderClass, SandboxProviderOptions, SandboxScope, } from "./sandbox.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,YAAY,EACV,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,EACZ,cAAc,EACd,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,OAAO,EACP,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,oBAAoB,EACpB,uBAAuB,EACvB,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,EACtB,YAAY,GACb,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { defineDeepAgent } from "./define-deep-agent.js";
+export { defineSandbox } from "./sandbox.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}

package/dist/resolve.d.ts

@@ -0,0 +1,11 @@
+interface PlatformPackage {
+    pkg: string;
+    bin: string;
+}
+export declare const PLATFORM_PACKAGES: Record<string, PlatformPackage>;
+/**
+ * Resolve the absolute path to the platform-specific `mda` binary.
+ */
+export declare function resolveBinary(): string;
+export {};
+//# sourceMappingURL=resolve.d.ts.map

package/dist/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AASA,UAAU,eAAe;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAM7D,CAAC;AAEF;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAqBtC"}

package/dist/resolve.js

@@ -0,0 +1,33 @@
+// Maps Node's process.platform/process.arch to the per-platform npm package
+// that ships the matching prebuilt `mda` binary. These packages are published
+// as optionalDependencies of the main `managed-deepagents` package, so npm only
+// installs the one relevant to the host.
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+export const PLATFORM_PACKAGES = {
+    "darwin arm64": { pkg: "@langchain/managed-deepagents-darwin-arm64", bin: "mda" },
+    "darwin x64": { pkg: "@langchain/managed-deepagents-darwin-x64", bin: "mda" },
+    "linux arm64": { pkg: "@langchain/managed-deepagents-linux-arm64", bin: "mda" },
+    "linux x64": { pkg: "@langchain/managed-deepagents-linux-x64", bin: "mda" },
+    "win32 x64": { pkg: "@langchain/managed-deepagents-win32-x64", bin: "mda.exe" },
+};
+/**
+ * Resolve the absolute path to the platform-specific `mda` binary.
+ */
+export function resolveBinary() {
+    const key = `${process.platform} ${process.arch}`;
+    const entry = PLATFORM_PACKAGES[key];
+    if (!entry) {
+        throw new Error(`managed-deepagents does not ship a prebuilt binary for ${key}.\n` +
+            `Supported platforms: ${Object.keys(PLATFORM_PACKAGES).join(", ")}.`);
+    }
+    try {
+        return require.resolve(`${entry.pkg}/bin/${entry.bin}`);
+    }
+    catch (cause) {
+        throw new Error(`The platform package "${entry.pkg}" is not installed.\n` +
+            `This usually means optional dependencies were skipped during install.\n` +
+            `Reinstall with optional dependencies enabled (e.g. \`npm install managed-deepagents\`).`, { cause });
+    }
+}
+//# sourceMappingURL=resolve.js.map

package/dist/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,8EAA8E;AAC9E,gFAAgF;AAChF,yCAAyC;AAEzC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAO/C,MAAM,CAAC,MAAM,iBAAiB,GAAoC;IAChE,cAAc,EAAE,EAAE,GAAG,EAAE,4CAA4C,EAAE,GAAG,EAAE,KAAK,EAAE;IACjF,YAAY,EAAE,EAAE,GAAG,EAAE,0CAA0C,EAAE,GAAG,EAAE,KAAK,EAAE;IAC7E,aAAa,EAAE,EAAE,GAAG,EAAE,2CAA2C,EAAE,GAAG,EAAE,KAAK,EAAE;IAC/E,WAAW,EAAE,EAAE,GAAG,EAAE,yCAAyC,EAAE,GAAG,EAAE,KAAK,EAAE;IAC3E,WAAW,EAAE,EAAE,GAAG,EAAE,yCAAyC,EAAE,GAAG,EAAE,SAAS,EAAE;CAChF,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;IAClD,MAAM,KAAK,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;IAErC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,0DAA0D,GAAG,KAAK;YAChE,wBAAwB,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACvE,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,KAAK,CAAC,GAAG,QAAQ,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;IAC1D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,yBAAyB,KAAK,CAAC,GAAG,uBAAuB;YACvD,yEAAyE;YACzE,yFAAyF,EAC3F,EAAE,KAAK,EAAE,CACV,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/runtime/credentials.d.ts

@@ -0,0 +1,42 @@
+import type { SandboxDefinition } from "../sandbox.js";
+/**
+ * Per-provider environment variables MDA expects to hold the credentials each
+ * sandbox provider needs. Keyed by the provider's `providerId` (when set) or
+ * its class name.
+ *
+ * The value is a list of alternative credential *sets*: a provider is
+ * considered credentialed if **every** variable in **any one** set is present.
+ * An empty list means the provider needs no credentials (e.g. it runs locally).
+ *
+ * Sources: the deepagents sandbox docs and each provider's own SDK docs.
+ * - LangSmith: https://docs.langchain.com/langsmith/sandboxes
+ * - Daytona / E2B / Modal / Runloop / Vercel / AgentCore / Deno: provider SDK docs.
+ */
+export declare const PROVIDER_CREDENTIAL_ENV_VARS: Record<string, string[][]>;
+export interface ProviderCredentialStatus {
+    /**
+     * - `available`: required credentials are present (or none are needed).
+     * - `missing`: a known provider's credentials are absent.
+     * - `unknown`: provider is not in {@link PROVIDER_CREDENTIAL_ENV_VARS}.
+     */
+    status: "available" | "missing" | "unknown";
+    /** The provider id / class name used for the lookup. */
+    provider: string;
+    /** Env vars from the primary credential set, surfaced when `missing`. */
+    missing: string[];
+}
+/**
+ * Whether MDA is running under `mda dev`. The CLI sets `MDA_DEV` when it
+ * launches the local LangGraph dev server; it is never set for `mda deploy`.
+ */
+export declare function isDevMode(): boolean;
+/** Resolve the lookup key for a sandbox provider (its id, else class name). */
+export declare function providerKey(provider: SandboxDefinition["provider"]): string;
+/** Whether every variable in a credential set is set and non-empty. */
+export declare function credentialSetSatisfied(envVars: string[]): boolean;
+/**
+ * Determine whether the configured provider's credentials are available so
+ * `mda dev` can decide between the real provider and the local fallback.
+ */
+export declare function providerCredentialStatus(provider: SandboxDefinition["provider"]): ProviderCredentialStatus;
+//# sourceMappingURL=credentials.d.ts.map

package/dist/runtime/credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../../src/runtime/credentials.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,4BAA4B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,CAsBnE,CAAC;AAEF,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,SAAS,CAAC;IAC5C,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAGnC;AAED,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,QAAQ,EAAE,iBAAiB,CAAC,UAAU,CAAC,GAAG,MAAM,CAG3E;AAED,uEAAuE;AACvE,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAEjE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,iBAAiB,CAAC,UAAU,CAAC,GACtC,wBAAwB,CAU1B"}

package/dist/runtime/credentials.js

@@ -0,0 +1,69 @@
+/**
+ * Per-provider environment variables MDA expects to hold the credentials each
+ * sandbox provider needs. Keyed by the provider's `providerId` (when set) or
+ * its class name.
+ *
+ * The value is a list of alternative credential *sets*: a provider is
+ * considered credentialed if **every** variable in **any one** set is present.
+ * An empty list means the provider needs no credentials (e.g. it runs locally).
+ *
+ * Sources: the deepagents sandbox docs and each provider's own SDK docs.
+ * - LangSmith: https://docs.langchain.com/langsmith/sandboxes
+ * - Daytona / E2B / Modal / Runloop / Vercel / AgentCore / Deno: provider SDK docs.
+ */
+export const PROVIDER_CREDENTIAL_ENV_VARS = {
+    // LangSmith managed sandboxes.
+    LangSmithSandbox: [["LANGSMITH_API_KEY"]],
+    // Daytona (`langchain-daytona` / deepagents `DaytonaSandbox`).
+    DaytonaSandbox: [["DAYTONA_API_KEY"]],
+    // E2B (`langchain-e2b` / deepagents `E2BSandbox`).
+    E2BSandbox: [["E2B_API_KEY"]],
+    // Modal requires both a token id and secret.
+    ModalSandbox: [["MODAL_TOKEN_ID", "MODAL_TOKEN_SECRET"]],
+    // Runloop devboxes.
+    RunloopSandbox: [["RUNLOOP_API_KEY"]],
+    // Vercel: either an OIDC token, or an access token + team + project ids.
+    VercelSandbox: [
+        ["VERCEL_OIDC_TOKEN"],
+        ["VERCEL_TOKEN", "VERCEL_TEAM_ID", "VERCEL_PROJECT_ID"],
+    ],
+    // AWS Bedrock AgentCore: standard AWS credential resolution.
+    AgentCoreSandbox: [["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY"], ["AWS_PROFILE"]],
+    // Deno Deploy microVMs (`@langchain/deno`) need an organization token.
+    DenoSandbox: [["DENO_DEPLOY_TOKEN"]],
+    // Node VFS runs locally and needs no credentials.
+    NodeVFSSandbox: [],
+};
+/**
+ * Whether MDA is running under `mda dev`. The CLI sets `MDA_DEV` when it
+ * launches the local LangGraph dev server; it is never set for `mda deploy`.
+ */
+export function isDevMode() {
+    const value = process.env.MDA_DEV;
+    return typeof value === "string" && value.length > 0;
+}
+/** Resolve the lookup key for a sandbox provider (its id, else class name). */
+export function providerKey(provider) {
+    const p = provider;
+    return (p.providerId ?? p.name ?? "").trim();
+}
+/** Whether every variable in a credential set is set and non-empty. */
+export function credentialSetSatisfied(envVars) {
+    return envVars.every((name) => (process.env[name] ?? "").trim().length > 0);
+}
+/**
+ * Determine whether the configured provider's credentials are available so
+ * `mda dev` can decide between the real provider and the local fallback.
+ */
+export function providerCredentialStatus(provider) {
+    const key = providerKey(provider);
+    const sets = PROVIDER_CREDENTIAL_ENV_VARS[key];
+    if (sets === undefined) {
+        return { status: "unknown", provider: key || "unknown", missing: [] };
+    }
+    if (sets.length === 0 || sets.some(credentialSetSatisfied)) {
+        return { status: "available", provider: key, missing: [] };
+    }
+    return { status: "missing", provider: key, missing: sets[0] ?? [] };
+}
+//# sourceMappingURL=credentials.js.map

package/dist/runtime/credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.js","sourceRoot":"","sources":["../../src/runtime/credentials.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAA+B;IACtE,+BAA+B;IAC/B,gBAAgB,EAAE,CAAC,CAAC,mBAAmB,CAAC,CAAC;IACzC,+DAA+D;IAC/D,cAAc,EAAE,CAAC,CAAC,iBAAiB,CAAC,CAAC;IACrC,mDAAmD;IACnD,UAAU,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC;IAC7B,6CAA6C;IAC7C,YAAY,EAAE,CAAC,CAAC,gBAAgB,EAAE,oBAAoB,CAAC,CAAC;IACxD,oBAAoB;IACpB,cAAc,EAAE,CAAC,CAAC,iBAAiB,CAAC,CAAC;IACrC,yEAAyE;IACzE,aAAa,EAAE;QACb,CAAC,mBAAmB,CAAC;QACrB,CAAC,cAAc,EAAE,gBAAgB,EAAE,mBAAmB,CAAC;KACxD;IACD,6DAA6D;IAC7D,gBAAgB,EAAE,CAAC,CAAC,mBAAmB,EAAE,uBAAuB,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC;IACnF,uEAAuE;IACvE,WAAW,EAAE,CAAC,CAAC,mBAAmB,CAAC,CAAC;IACpC,kDAAkD;IAClD,cAAc,EAAE,EAAE;CACnB,CAAC;AAeF;;;GAGG;AACH,MAAM,UAAU,SAAS;IACvB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;IAClC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;AACvD,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,WAAW,CAAC,QAAuC;IACjE,MAAM,CAAC,GAAG,QAAkD,CAAC;IAC7D,OAAO,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AAC/C,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,sBAAsB,CAAC,OAAiB;IACtD,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAC9E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CACtC,QAAuC;IAEvC,MAAM,GAAG,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IAClC,MAAM,IAAI,GAAG,4BAA4B,CAAC,GAAG,CAAC,CAAC;IAC/C,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,IAAI,SAAS,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IACxE,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,sBAAsB,CAAC,EAAE,CAAC;QAC3D,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IAC7D,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;AACtE,CAAC"}

package/dist/runtime/dev-notice.d.ts

@@ -0,0 +1,7 @@
+export declare function logDevSandboxNoticeOnce(message: string): void;
+/**
+ * Reset the one-time notice guard. Test-only: the guard is module-level state
+ * that otherwise persists across test cases in the same module instance.
+ */
+export declare function resetDevSandboxNoticeForTests(): void;
+//# sourceMappingURL=dev-notice.d.ts.map

package/dist/runtime/dev-notice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-notice.d.ts","sourceRoot":"","sources":["../../src/runtime/dev-notice.ts"],"names":[],"mappings":"AAaA,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAK7D;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,IAAI,IAAI,CAEpD"}

package/dist/runtime/dev-notice.js

@@ -0,0 +1,27 @@
+/**
+ * Emit a one-time notice describing which dev sandbox mode is in effect.
+ *
+ * Deduped for the lifetime of the process because the managed sandbox is
+ * created once per sandbox *scope key* (thread/tenant/actor), not once per
+ * process. The `mda dev` LangGraph server is long-lived and serves many
+ * threads, so each new thread misses the sandbox cache and provisions a fresh
+ * sandbox — without this guard the banner would reprint on the first turn of
+ * every new thread (and could interleave when threads start concurrently). The
+ * message is session-level context, so once is enough.
+ */
+let loggedDevSandboxNotice = false;
+export function logDevSandboxNoticeOnce(message) {
+    if (loggedDevSandboxNotice)
+        return;
+    loggedDevSandboxNotice = true;
+    // eslint-disable-next-line no-console
+    console.log(message);
+}
+/**
+ * Reset the one-time notice guard. Test-only: the guard is module-level state
+ * that otherwise persists across test cases in the same module instance.
+ */
+export function resetDevSandboxNoticeForTests() {
+    loggedDevSandboxNotice = false;
+}
+//# sourceMappingURL=dev-notice.js.map

package/dist/runtime/dev-notice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-notice.js","sourceRoot":"","sources":["../../src/runtime/dev-notice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,IAAI,sBAAsB,GAAG,KAAK,CAAC;AAEnC,MAAM,UAAU,uBAAuB,CAAC,OAAe;IACrD,IAAI,sBAAsB;QAAE,OAAO;IACnC,sBAAsB,GAAG,IAAI,CAAC;IAC9B,sCAAsC;IACtC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AACvB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,6BAA6B;IAC3C,sBAAsB,GAAG,KAAK,CAAC;AACjC,CAAC"}

package/dist/runtime/index.d.ts

@@ -0,0 +1,14 @@
+import type { DeepAgentDefinition } from "../types.js";
+import type { ManagedAgentOptions, ManagedRunConfig } from "./types.js";
+export type { ManagedAgentOptions, ManagedRunConfig } from "./types.js";
+export { announceSandboxPlan } from "./sandbox-manager.js";
+/**
+ * Compile a {@link DeepAgentDefinition} into a runnable Deep Agent.
+ *
+ * This is the seam where MDA injects the platform-owned backend (the configured
+ * sandbox), the system prompt embedded from `instructions.md`, and — in a later
+ * milestone — the managed store and checkpointer. It is consumed only by the
+ * entry module that `mda deploy` generates; agent authors never call it.
+ */
+export declare function compileManagedAgent(definition: DeepAgentDefinition, config?: ManagedRunConfig, options?: ManagedAgentOptions): Promise<unknown>;
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAExE,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACxE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,mBAAmB,EAC/B,MAAM,CAAC,EAAE,gBAAgB,EACzB,OAAO,CAAC,EAAE,mBAAmB,oBAgB9B"}

package/dist/runtime/index.js

@@ -0,0 +1,25 @@
+import { createDeepAgent } from "deepagents";
+import { resolveManagedSandbox } from "./sandbox-manager.js";
+export { announceSandboxPlan } from "./sandbox-manager.js";
+/**
+ * Compile a {@link DeepAgentDefinition} into a runnable Deep Agent.
+ *
+ * This is the seam where MDA injects the platform-owned backend (the configured
+ * sandbox), the system prompt embedded from `instructions.md`, and — in a later
+ * milestone — the managed store and checkpointer. It is consumed only by the
+ * entry module that `mda deploy` generates; agent authors never call it.
+ */
+export async function compileManagedAgent(definition, config, options) {
+    const { systemPrompt, sandbox, setupScript } = options ?? {};
+    const params = {
+        ...definition.config,
+        ...(systemPrompt !== undefined ? { systemPrompt } : {}),
+    };
+    // TODO(mda): inject the managed { store, checkpointer } here, scoped by
+    // `config.configurable.identity` / `thread_id`.
+    if (sandbox) {
+        params.backend = await resolveManagedSandbox(sandbox, setupScript, config);
+    }
+    return createDeepAgent(params);
+}
+//# sourceMappingURL=index.js.map

package/dist/runtime/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAG7C,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAI7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,UAA+B,EAC/B,MAAyB,EACzB,OAA6B;IAE7B,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;IAE7D,MAAM,MAAM,GAA4B;QACtC,GAAG,UAAU,CAAC,MAAM;QACpB,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxD,CAAC;IAEF,wEAAwE;IACxE,gDAAgD;IAChD,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,CAAC,OAAO,GAAG,MAAM,qBAAqB,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;IAC7E,CAAC;IAED,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC;AACjC,CAAC"}

package/dist/runtime/local-dev-sandbox.d.ts

@@ -0,0 +1,13 @@
+import type { ManagedSandboxBackend } from "./types.js";
+/**
+ * Provision a local, throwaway sandbox rooted at a fresh OS temp directory.
+ *
+ * Uses `deepagents`' `LocalShellBackend`, which runs commands and file
+ * operations against the host within the temp dir — no remote sandbox, no
+ * credentials, no network. Intended only for `mda dev`.
+ *
+ * `reason` explains *why* the local sandbox is being used (missing credentials,
+ * provider creation failure, …) and is logged once alongside the temp dir path.
+ */
+export declare function createLocalDevSandbox(reason: string): Promise<ManagedSandboxBackend>;
+//# sourceMappingURL=local-dev-sandbox.d.ts.map

package/dist/runtime/local-dev-sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-dev-sandbox.d.ts","sourceRoot":"","sources":["../../src/runtime/local-dev-sandbox.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAexD;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CA+B1F"}

package/dist/runtime/local-dev-sandbox.js

@@ -0,0 +1,39 @@
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { logDevSandboxNoticeOnce } from "./dev-notice.js";
+/**
+ * Provision a local, throwaway sandbox rooted at a fresh OS temp directory.
+ *
+ * Uses `deepagents`' `LocalShellBackend`, which runs commands and file
+ * operations against the host within the temp dir — no remote sandbox, no
+ * credentials, no network. Intended only for `mda dev`.
+ *
+ * `reason` explains *why* the local sandbox is being used (missing credentials,
+ * provider creation failure, …) and is logged once alongside the temp dir path.
+ */
+export async function createLocalDevSandbox(reason) {
+    const dir = await mkdtemp(join(tmpdir(), "mda-dev-sandbox-"));
+    logDevSandboxNoticeOnce(`[mda dev] ${reason}:\n  ${dir}`);
+    // Loaded dynamically (rather than a static named import) so the build does
+    // not depend on `LocalShellBackend` being present in the resolved
+    // `deepagents` type surface; it is provided by the runtime's `deepagents`.
+    const deepagentsModule = (await import("deepagents"));
+    const LocalShellBackend = deepagentsModule.LocalShellBackend;
+    if (typeof LocalShellBackend !== "function") {
+        throw new Error("the installed `deepagents` does not export `LocalShellBackend`; upgrade " +
+            "`deepagents` to use the local `mda dev` sandbox, or set the provider credentials.");
+    }
+    const backend = new LocalShellBackend({
+        rootDir: dir,
+        virtualMode: true,
+        inheritEnv: true,
+    });
+    // Initialize eagerly when the backend supports it, mirroring how the provider
+    // `create(...)` factory hands back a ready-to-use backend.
+    if (typeof backend.initialize === "function") {
+        await backend.initialize();
+    }
+    return backend;
+}
+//# sourceMappingURL=local-dev-sandbox.js.map

package/dist/runtime/local-dev-sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-dev-sandbox.js","sourceRoot":"","sources":["../../src/runtime/local-dev-sandbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAgB1D;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,MAAc;IACxD,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAC9D,uBAAuB,CAAC,aAAa,MAAM,QAAQ,GAAG,EAAE,CAAC,CAAC;IAE1D,2EAA2E;IAC3E,kEAAkE;IAClE,2EAA2E;IAC3E,MAAM,gBAAgB,GAAG,CAAC,MAAM,MAAM,CAAC,YAAY,CAAC,CAA4B,CAAC;IACjF,MAAM,iBAAiB,GAAG,gBAAgB,CAAC,iBAE9B,CAAC;IACd,IAAI,OAAO,iBAAiB,KAAK,UAAU,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CACb,0EAA0E;YACxE,mFAAmF,CACtF,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,iBAAiB,CAAC;QACpC,OAAO,EAAE,GAAG;QACZ,WAAW,EAAE,IAAI;QACjB,UAAU,EAAE,IAAI;KACjB,CAAC,CAAC;IAEH,8EAA8E;IAC9E,2DAA2D;IAC3D,IAAI,OAAO,OAAO,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;QAC7C,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC;IAC7B,CAAC;IAED,OAAO,OAA2C,CAAC;AACrD,CAAC"}

package/dist/runtime/sandbox-manager.d.ts

@@ -0,0 +1,30 @@
+import type { SandboxDefinition } from "../sandbox.js";
+import type { ManagedRunConfig, ManagedSandboxBackend } from "./types.js";
+/**
+ * Resolve (and cache) the scoped sandbox backend for this run, provisioning it
+ * with `setup.sh` the first time it is created.
+ */
+export declare function resolveManagedSandbox(sandbox: SandboxDefinition, setupScript: string | undefined, config: ManagedRunConfig | undefined): Promise<ManagedSandboxBackend>;
+/**
+ * Derive the reuse key from the run. Without runtime identity, sandboxes are
+ * keyed by thread; with identity, by the configured tenant/actor scope.
+ */
+export declare function sandboxScopeKey(sandbox: SandboxDefinition, config: ManagedRunConfig | undefined): string;
+/** Clear the process-level sandbox cache. Test-only. */
+export declare function clearManagedSandboxCacheForTests(): void;
+/**
+ * Eagerly resolve the `mda dev` sandbox at startup so the developer sees the
+ * definitive decision — local vs. the configured provider, and the temp dir
+ * path when local — right when the dev server boots, not on the first run.
+ *
+ * Sandboxes are otherwise created lazily (on first run), so with `--browser`
+ * off nothing would print until the agent is invoked. The generated entry
+ * calls this at module load (graph registration); because dev shares one
+ * sandbox ({@link DEV_SANDBOX_SCOPE_KEY}), the first real run reuses what is
+ * created here rather than provisioning a second sandbox. The authoritative
+ * "created" log (with the temp dir) is emitted by {@link createDevSandbox}.
+ *
+ * No-op outside `mda dev`, so the generated entry can always call it.
+ */
+export declare function announceSandboxPlan(sandbox: SandboxDefinition, setupScript?: string): Promise<void>;
+//# sourceMappingURL=sandbox-manager.d.ts.map

package/dist/runtime/sandbox-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-manager.d.ts","sourceRoot":"","sources":["../../src/runtime/sandbox-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAKvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAoB1E;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,iBAAiB,EAC1B,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,MAAM,EAAE,gBAAgB,GAAG,SAAS,GACnC,OAAO,CAAC,qBAAqB,CAAC,CAYhC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,iBAAiB,EAC1B,MAAM,EAAE,gBAAgB,GAAG,SAAS,GACnC,MAAM,CAcR;AAED,wDAAwD;AACxD,wBAAgB,gCAAgC,IAAI,IAAI,CAEvD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,iBAAiB,EAC1B,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CAGf"}

package/dist/runtime/sandbox-manager.js

@@ -0,0 +1,143 @@
+import { isDevMode, providerCredentialStatus } from "./credentials.js";
+import { logDevSandboxNoticeOnce } from "./dev-notice.js";
+import { createLocalDevSandbox } from "./local-dev-sandbox.js";
+import { runSetupScript, runSetupScriptInline } from "./setup-script.js";
+/**
+ * Created sandboxes, keyed by scope, reused for the lifetime of this runtime
+ * process. Storing the in-flight promise dedupes concurrent runs and guarantees
+ * `setup.sh` is executed only once per newly created sandbox.
+ */
+const managedSandboxes = new Map();
+/**
+ * Cache key for the single, process-wide sandbox used under `mda dev`.
+ *
+ * Deploys key sandboxes per scope (thread/tenant/actor) for isolation. Dev is a
+ * single developer iterating locally, so it shares one sandbox across every
+ * thread: that lets `announceSandboxPlan` create it eagerly at startup (to
+ * report local-vs-remote and the temp dir up front) and have the first real run
+ * reuse it instead of provisioning a second one.
+ */
+const DEV_SANDBOX_SCOPE_KEY = "__mda_dev__";
+/**
+ * Resolve (and cache) the scoped sandbox backend for this run, provisioning it
+ * with `setup.sh` the first time it is created.
+ */
+export function resolveManagedSandbox(sandbox, setupScript, config) {
+    const key = isDevMode() ? DEV_SANDBOX_SCOPE_KEY : sandboxScopeKey(sandbox, config);
+    let pending = managedSandboxes.get(key);
+    if (!pending) {
+        pending = createManagedSandbox(sandbox, setupScript).catch((error) => {
+            // Don't cache a failed provisioning attempt — let the next run retry.
+            managedSandboxes.delete(key);
+            throw error;
+        });
+        managedSandboxes.set(key, pending);
+    }
+    return pending;
+}
+/**
+ * Derive the reuse key from the run. Without runtime identity, sandboxes are
+ * keyed by thread; with identity, by the configured tenant/actor scope.
+ */
+export function sandboxScopeKey(sandbox, config) {
+    const configurable = (config?.configurable ?? {});
+    const identity = configurable.identity;
+    const scope = sandbox.options?.scope ?? "thread";
+    let key;
+    if (scope === "tenant")
+        key = identity?.tenant?.id;
+    else if (scope === "actor")
+        key = identity?.actor?.id;
+    else
+        key = configurable.thread_id;
+    return key ?? identity?.tenant?.id ?? identity?.actor?.id ?? configurable.thread_id ?? "default";
+}
+/** Clear the process-level sandbox cache. Test-only. */
+export function clearManagedSandboxCacheForTests() {
+    managedSandboxes.clear();
+}
+/**
+ * Eagerly resolve the `mda dev` sandbox at startup so the developer sees the
+ * definitive decision — local vs. the configured provider, and the temp dir
+ * path when local — right when the dev server boots, not on the first run.
+ *
+ * Sandboxes are otherwise created lazily (on first run), so with `--browser`
+ * off nothing would print until the agent is invoked. The generated entry
+ * calls this at module load (graph registration); because dev shares one
+ * sandbox ({@link DEV_SANDBOX_SCOPE_KEY}), the first real run reuses what is
+ * created here rather than provisioning a second sandbox. The authoritative
+ * "created" log (with the temp dir) is emitted by {@link createDevSandbox}.
+ *
+ * No-op outside `mda dev`, so the generated entry can always call it.
+ */
+export async function announceSandboxPlan(sandbox, setupScript) {
+    if (!isDevMode())
+        return;
+    await resolveManagedSandbox(sandbox, setupScript, undefined);
+}
+function createManagedSandbox(sandbox, setupScript) {
+    // `mda dev` never provisions a real provider sandbox the same way a deploy
+    // does (it builds no snapshot/image), so it gets its own resolution path with
+    // a local fallback. The flag gating ensures a real deployment can never be
+    // silently downgraded to local shell execution.
+    return isDevMode()
+        ? createDevSandbox(sandbox, setupScript)
+        : createProviderSandbox(sandbox, setupScript);
+}
+/**
+ * Production path: construct the configured provider's sandbox and provision it.
+ * Any failure propagates — a misconfigured deployment must surface, not degrade.
+ */
+async function createProviderSandbox(sandbox, setupScript) {
+    const backend = await createProviderBackend(sandbox);
+    if (setupScript && setupScript.trim().length > 0) {
+        await runSetupScript(backend, setupScript);
+    }
+    return backend;
+}
+/**
+ * Dev path: prefer the configured provider when its credentials are present,
+ * but fall back to a local temp-directory sandbox when credentials are missing
+ * *or* the provider cannot be created (e.g. `LangSmithSandbox`, which needs a
+ * snapshot that only `mda deploy` builds). This keeps `mda dev` working offline
+ * and resilient to provider/config gaps while still exercising real providers
+ * that can spin up from an API key alone.
+ */
+async function createDevSandbox(sandbox, setupScript) {
+    const cred = providerCredentialStatus(sandbox.provider);
+    if (cred.status !== "missing") {
+        try {
+            const backend = await createProviderSandbox(sandbox, setupScript);
+            logDevSandboxNoticeOnce(cred.status === "available"
+                ? `[mda dev] using the configured ${cred.provider} sandbox.`
+                : `[mda dev] using the configured sandbox provider (${cred.provider}).`);
+            return backend;
+        }
+        catch (error) {
+            return createLocalSandbox(setupScript, `the configured ${cred.provider} sandbox could not be created ` +
+                `(${errorMessage(error)}); using a local temporary directory instead`);
+        }
+    }
+    const missing = cred.missing.join(", ") || "the provider credentials";
+    return createLocalSandbox(setupScript, `no credentials found for the configured sandbox provider (${cred.provider}); ` +
+        `using a local temporary directory instead — set ${missing} to use it`);
+}
+/** Provision the local dev sandbox and run `setup.sh` inline inside it. */
+async function createLocalSandbox(setupScript, reason) {
+    const backend = await createLocalDevSandbox(reason);
+    if (setupScript && setupScript.trim().length > 0) {
+        await runSetupScriptInline(backend, setupScript);
+    }
+    return backend;
+}
+/** Construct the configured provider's backend, stripping MDA-managed knobs. */
+async function createProviderBackend(sandbox) {
+    const { scope: _scope, idleTtlSeconds: _idleTtlSeconds, ...providerOptions } = sandbox.options ?? {};
+    void _scope;
+    void _idleTtlSeconds;
+    return (await sandbox.provider.create(providerOptions));
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=sandbox-manager.js.map

package/dist/runtime/sandbox-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-manager.js","sourceRoot":"","sources":["../../src/runtime/sandbox-manager.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAGzE;;;;GAIG;AACH,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAA0C,CAAC;AAE3E;;;;;;;;GAQG;AACH,MAAM,qBAAqB,GAAG,aAAa,CAAC;AAE5C;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAA0B,EAC1B,WAA+B,EAC/B,MAAoC;IAEpC,MAAM,GAAG,GAAG,SAAS,EAAE,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,eAAe,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACnF,IAAI,OAAO,GAAG,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACxC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,GAAG,oBAAoB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YACnE,sEAAsE;YACtE,gBAAgB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC7B,MAAM,KAAK,CAAC;QACd,CAAC,CAAC,CAAC;QACH,gBAAgB,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,OAA0B,EAC1B,MAAoC;IAEpC,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,YAAY,IAAI,EAAE,CAG/C,CAAC;IACF,MAAM,QAAQ,GAAG,YAAY,CAAC,QAAQ,CAAC;IACvC,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,EAAE,KAAK,IAAI,QAAQ,CAAC;IAEjD,IAAI,GAAuB,CAAC;IAC5B,IAAI,KAAK,KAAK,QAAQ;QAAE,GAAG,GAAG,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC;SAC9C,IAAI,KAAK,KAAK,OAAO;QAAE,GAAG,GAAG,QAAQ,EAAE,KAAK,EAAE,EAAE,CAAC;;QACjD,GAAG,GAAG,YAAY,CAAC,SAAS,CAAC;IAElC,OAAO,GAAG,IAAI,QAAQ,EAAE,MAAM,EAAE,EAAE,IAAI,QAAQ,EAAE,KAAK,EAAE,EAAE,IAAI,YAAY,CAAC,SAAS,IAAI,SAAS,CAAC;AACnG,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,gCAAgC;IAC9C,gBAAgB,CAAC,KAAK,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAA0B,EAC1B,WAAoB;IAEpB,IAAI,CAAC,SAAS,EAAE;QAAE,OAAO;IACzB,MAAM,qBAAqB,CAAC,OAAO,EAAE,WAAW,EAAE,SAAS,CAAC,CAAC;AAC/D,CAAC;AAED,SAAS,oBAAoB,CAC3B,OAA0B,EAC1B,WAA+B;IAE/B,2EAA2E;IAC3E,8EAA8E;IAC9E,2EAA2E;IAC3E,gDAAgD;IAChD,OAAO,SAAS,EAAE;QAChB,CAAC,CAAC,gBAAgB,CAAC,OAAO,EAAE,WAAW,CAAC;QACxC,CAAC,CAAC,qBAAqB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;AAClD,CAAC;AAED;;;GAGG;AACH,KAAK,UAAU,qBAAqB,CAClC,OAA0B,EAC1B,WAA+B;IAE/B,MAAM,OAAO,GAAG,MAAM,qBAAqB,CAAC,OAAO,CAAC,CAAC;IACrD,IAAI,WAAW,IAAI,WAAW,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjD,MAAM,cAAc,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;GAOG;AACH,KAAK,UAAU,gBAAgB,CAC7B,OAA0B,EAC1B,WAA+B;IAE/B,MAAM,IAAI,GAAG,wBAAwB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAExD,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC9B,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,qBAAqB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;YAClE,uBAAuB,CACrB,IAAI,CAAC,MAAM,KAAK,WAAW;gBACzB,CAAC,CAAC,kCAAkC,IAAI,CAAC,QAAQ,WAAW;gBAC5D,CAAC,CAAC,oDAAoD,IAAI,CAAC,QAAQ,IAAI,CAC1E,CAAC;YACF,OAAO,OAAO,CAAC;QACjB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,kBAAkB,CACvB,WAAW,EACX,kBAAkB,IAAI,CAAC,QAAQ,gCAAgC;gBAC7D,IAAI,YAAY,CAAC,KAAK,CAAC,8CAA8C,CACxE,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,0BAA0B,CAAC;IACtE,OAAO,kBAAkB,CACvB,WAAW,EACX,6DAA6D,IAAI,CAAC,QAAQ,KAAK;QAC7E,mDAAmD,OAAO,YAAY,CACzE,CAAC;AACJ,CAAC;AAED,2EAA2E;AAC3E,KAAK,UAAU,kBAAkB,CAC/B,WAA+B,EAC/B,MAAc;IAEd,MAAM,OAAO,GAAG,MAAM,qBAAqB,CAAC,MAAM,CAAC,CAAC;IACpD,IAAI,WAAW,IAAI,WAAW,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjD,MAAM,oBAAoB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,gFAAgF;AAChF,KAAK,UAAU,qBAAqB,CAAC,OAA0B;IAC7D,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,eAAe,EAAE,GAAG,eAAe,EAAE,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;IACrG,KAAK,MAAM,CAAC;IACZ,KAAK,eAAe,CAAC;IACrB,OAAO,CAAC,MAAM,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,eAAe,CAAC,CAA0B,CAAC;AACnF,CAAC;AAED,SAAS,YAAY,CAAC,KAAc;IAClC,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC"}

package/dist/runtime/setup-script.d.ts

@@ -0,0 +1,23 @@
+import type { ManagedSandboxBackend } from "./types.js";
+/**
+ * Provision a freshly created sandbox by running `setup.sh` inside it. Reused
+ * sandboxes never reach this path, so the script runs once per new sandbox.
+ *
+ * When the backend supports file transfer, the script is uploaded and executed
+ * by path; otherwise it is run inline (see {@link runSetupScriptInline}).
+ */
+export declare function runSetupScript(backend: ManagedSandboxBackend, script: string): Promise<void>;
+/**
+ * Run `setup.sh` by piping its contents straight to the backend's shell.
+ *
+ * Used for the local dev sandbox: that backend virtualizes file paths (uploads
+ * land under the temp root) but executes shell commands against the real
+ * filesystem, so an uploaded `/tmp/mda-setup.sh` would not be found by `bash`.
+ * Executed inline, the script runs with the temp root as its working directory.
+ */
+export declare function runSetupScriptInline(backend: ManagedSandboxBackend, script: string): Promise<void>;
+export declare function assertSetupSucceeded(result: {
+    output?: string;
+    exitCode?: number | null;
+}): void;
+//# sourceMappingURL=setup-script.d.ts.map

package/dist/runtime/setup-script.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-script.d.ts","sourceRoot":"","sources":["../../src/runtime/setup-script.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAKxD;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,EAC9B,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,qBAAqB,EAC9B,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,GAAG,IAAI,CAOP"}

package/dist/runtime/setup-script.js

@@ -0,0 +1,35 @@
+/** Absolute path the provisioning script is uploaded to inside the sandbox. */
+const SETUP_REMOTE_PATH = "/tmp/mda-setup.sh";
+/**
+ * Provision a freshly created sandbox by running `setup.sh` inside it. Reused
+ * sandboxes never reach this path, so the script runs once per new sandbox.
+ *
+ * When the backend supports file transfer, the script is uploaded and executed
+ * by path; otherwise it is run inline (see {@link runSetupScriptInline}).
+ */
+export async function runSetupScript(backend, script) {
+    if (typeof backend.uploadFiles === "function") {
+        await backend.uploadFiles([[SETUP_REMOTE_PATH, new TextEncoder().encode(script)]]);
+        assertSetupSucceeded(await backend.execute(`bash ${SETUP_REMOTE_PATH}`));
+        return;
+    }
+    await runSetupScriptInline(backend, script);
+}
+/**
+ * Run `setup.sh` by piping its contents straight to the backend's shell.
+ *
+ * Used for the local dev sandbox: that backend virtualizes file paths (uploads
+ * land under the temp root) but executes shell commands against the real
+ * filesystem, so an uploaded `/tmp/mda-setup.sh` would not be found by `bash`.
+ * Executed inline, the script runs with the temp root as its working directory.
+ */
+export async function runSetupScriptInline(backend, script) {
+    assertSetupSucceeded(await backend.execute(script));
+}
+export function assertSetupSucceeded(result) {
+    if (typeof result.exitCode === "number" && result.exitCode !== 0) {
+        const detail = (result.output ?? "").trim();
+        throw new Error(`sandbox setup.sh failed with exit code ${result.exitCode}${detail ? `: ${detail}` : ""}`);
+    }
+}
+//# sourceMappingURL=setup-script.js.map

package/dist/runtime/setup-script.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-script.js","sourceRoot":"","sources":["../../src/runtime/setup-script.ts"],"names":[],"mappings":"AAEA,+EAA+E;AAC/E,MAAM,iBAAiB,GAAG,mBAAmB,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAA8B,EAC9B,MAAc;IAEd,IAAI,OAAO,OAAO,CAAC,WAAW,KAAK,UAAU,EAAE,CAAC;QAC9C,MAAM,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,iBAAiB,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QACnF,oBAAoB,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,QAAQ,iBAAiB,EAAE,CAAC,CAAC,CAAC;QACzE,OAAO;IACT,CAAC;IACD,MAAM,oBAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,OAA8B,EAC9B,MAAc;IAEd,oBAAoB,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,MAGpC;IACC,IAAI,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;QACjE,MAAM,MAAM,GAAG,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CACb,0CAA0C,MAAM,CAAC,QAAQ,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAC1F,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/runtime/types.d.ts

@@ -0,0 +1,43 @@
+import type { SandboxDefinition } from "../sandbox.js";
+/**
+ * The LangGraph runnable config passed to a graph factory at invocation time.
+ *
+ * Kept loose for v0; the managed runtime reads identity and thread metadata
+ * from here to scope the store/sandbox.
+ */
+export interface ManagedRunConfig {
+    configurable?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * Managed values the CLI injects into the generated entry module.
+ *
+ * The system prompt is embedded from `instructions.md` at deploy time, and the
+ * sandbox definition + `setup.sh` come from the project's `sandbox/` folder, so
+ * they live here rather than in the authored {@link DeepAgentDefinition}.
+ */
+export interface ManagedAgentOptions {
+    systemPrompt?: string;
+    /** The `sandbox/index.ts` declaration, if the project configures a sandbox. */
+    sandbox?: SandboxDefinition;
+    /**
+     * Contents of `sandbox/setup.sh`, embedded by the CLI. It runs exactly once,
+     * the first time a sandbox is provisioned for a given scope.
+     */
+    setupScript?: string;
+}
+/**
+ * The subset of a created sandbox backend the managed runtime relies on to run
+ * `setup.sh`. Mirrors `deepagents`' `SandboxBackendProtocol`.
+ */
+export interface ManagedSandboxBackend {
+    readonly id?: string;
+    execute(command: string, options?: {
+        timeout?: number;
+    }): Promise<{
+        output?: string;
+        exitCode?: number | null;
+    }>;
+    uploadFiles?(files: Array<[string, Uint8Array]>): Promise<unknown>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/runtime/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/runtime/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAChE,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAC1B,CAAC,CAAC;IACH,WAAW,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACpE"}

package/dist/runtime/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/runtime/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/runtime/types.ts"],"names":[],"mappings":""}

package/dist/sandbox.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The managed `sandbox/` declaration primitive.
+ *
+ * A Managed Deep Agent declares its execution environment in `sandbox/index.ts`
+ * by importing a real provider class (e.g. `LangSmithSandbox` from `deepagents`)
+ * and handing it to {@link defineSandbox}. The options are typed straight from
+ * the provider's own `create(...)` signature — MDA invents no schema. MDA owns
+ * how the sandbox is *resolved*: construction, run-scoped naming, reuse across
+ * turns, the provisioning `setup.sh`, and lifecycle/TTL.
+ *
+ * @example
+ * ```ts
+ * // sandbox/index.ts
+ * import { defineSandbox } from "managed-deepagents";
+ * import { LangSmithSandbox } from "deepagents";
+ *
+ * export const sandbox = defineSandbox(LangSmithSandbox, {
+ *   defaultTimeout: 600,
+ * });
+ * ```
+ */
+/**
+ * A sandbox provider class MDA knows how to instantiate.
+ *
+ * Providers expose a static async `create(options)` factory. MDA calls it after
+ * merging the developer's typed options with managed fields. This matches the
+ * shape of `deepagents`' `LangSmithSandbox.create(...)`.
+ */
+export interface SandboxProviderClass<TOptions extends Record<string, any>, TInstance> {
+    create(options: TOptions): Promise<TInstance>;
+    /** Optional stable provider id for debugging, validation, and traces. */
+    readonly providerId?: string;
+}
+/** Reuse boundary for a managed sandbox. Defaults to `"thread"`. */
+export type SandboxScope = "thread" | "tenant" | "actor";
+/**
+ * Provider options MDA owns and developers must not set directly.
+ *
+ * MDA supplies the image/snapshot (built from `sandbox/Dockerfile` or the
+ * provider default) and the run-scoped sandbox name when it calls `create(...)`.
+ */
+export type ManagedSandboxOptionKey = "name" | "image" | "snapshot" | "imageName";
+/** Extracts the option type accepted by a provider's static `create(...)`. */
+export type SandboxProviderOptions<TProvider> = TProvider extends {
+    create(options: infer TOptions): Promise<unknown>;
+} ? TOptions extends object ? TOptions : never : never;
+/**
+ * Developer-provided options for the selected sandbox provider.
+ *
+ * Inferred from the provider's own `create(...)` options, minus the fields MDA
+ * owns, plus the managed reuse/lifecycle knobs.
+ */
+export type DefineSandboxOptions<TProvider extends SandboxProviderClass<any, any>> = Omit<SandboxProviderOptions<TProvider>, ManagedSandboxOptionKey> & {
+    /**
+     * Sandbox reuse scope. Defaults to `"thread"`.
+     *
+     * - `"thread"`: one sandbox per durable thread/conversation.
+     * - `"tenant"`: one sandbox shared across threads for the current tenant.
+     * - `"actor"`: one sandbox shared across threads for the current actor.
+     */
+    scope?: SandboxScope;
+    /**
+     * Idle TTL in seconds. MDA may reclaim the sandbox after this period of
+     * inactivity.
+     */
+    idleTtlSeconds?: number;
+};
+/** The object exported from `sandbox/index.ts`. */
+export interface SandboxDefinition<TProvider extends SandboxProviderClass<any, any> = SandboxProviderClass<any, any>> {
+    readonly kind: "sandbox";
+    readonly provider: TProvider;
+    readonly options?: DefineSandboxOptions<TProvider>;
+}
+/**
+ * Declare the managed sandbox provider for a Managed Deep Agent.
+ *
+ * The developer chooses the provider and its typed options; MDA owns naming,
+ * scoping, lifecycle, image/snapshot construction, reuse, the provisioning
+ * `setup.sh`, and cleanup. The agent file stays clean — it never sets `backend`.
+ */
+export declare function defineSandbox<TProvider extends SandboxProviderClass<any, any>>(provider: TProvider, options?: DefineSandboxOptions<TProvider>): SandboxDefinition<TProvider>;
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;GAMG;AAEH,MAAM,WAAW,oBAAoB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,SAAS;IACnF,MAAM,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAC9C,yEAAyE;IACzE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,oEAAoE;AACpE,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,WAAW,CAAC;AAElF,8EAA8E;AAC9E,MAAM,MAAM,sBAAsB,CAAC,SAAS,IAAI,SAAS,SAAS;IAChE,MAAM,CAAC,OAAO,EAAE,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACnD,GACG,QAAQ,SAAS,MAAM,GACrB,QAAQ,GACR,KAAK,GACP,KAAK,CAAC;AAEV;;;;;GAKG;AAEH,MAAM,MAAM,oBAAoB,CAAC,SAAS,SAAS,oBAAoB,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,IAAI,CACvF,sBAAsB,CAAC,SAAS,CAAC,EACjC,uBAAuB,CACxB,GAAG;IACF;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,mDAAmD;AAEnD,MAAM,WAAW,iBAAiB,CAAC,SAAS,SAAS,oBAAoB,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,oBAAoB,CAAC,GAAG,EAAE,GAAG,CAAC;IAClH,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,oBAAoB,CAAC,SAAS,CAAC,CAAC;CACpD;AAED;;;;;;GAMG;AAEH,wBAAgB,aAAa,CAAC,SAAS,SAAS,oBAAoB,CAAC,GAAG,EAAE,GAAG,CAAC,EAC5E,QAAQ,EAAE,SAAS,EACnB,OAAO,CAAC,EAAE,oBAAoB,CAAC,SAAS,CAAC,GACxC,iBAAiB,CAAC,SAAS,CAAC,CAE9B"}

package/dist/sandbox.js

@@ -0,0 +1,33 @@
+/**
+ * The managed `sandbox/` declaration primitive.
+ *
+ * A Managed Deep Agent declares its execution environment in `sandbox/index.ts`
+ * by importing a real provider class (e.g. `LangSmithSandbox` from `deepagents`)
+ * and handing it to {@link defineSandbox}. The options are typed straight from
+ * the provider's own `create(...)` signature — MDA invents no schema. MDA owns
+ * how the sandbox is *resolved*: construction, run-scoped naming, reuse across
+ * turns, the provisioning `setup.sh`, and lifecycle/TTL.
+ *
+ * @example
+ * ```ts
+ * // sandbox/index.ts
+ * import { defineSandbox } from "managed-deepagents";
+ * import { LangSmithSandbox } from "deepagents";
+ *
+ * export const sandbox = defineSandbox(LangSmithSandbox, {
+ *   defaultTimeout: 600,
+ * });
+ * ```
+ */
+/**
+ * Declare the managed sandbox provider for a Managed Deep Agent.
+ *
+ * The developer chooses the provider and its typed options; MDA owns naming,
+ * scoping, lifecycle, image/snapshot construction, reuse, the provisioning
+ * `setup.sh`, and cleanup. The agent file stays clean — it never sets `backend`.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function defineSandbox(provider, options) {
+    return { kind: "sandbox", provider, options };
+}
+//# sourceMappingURL=sandbox.js.map

package/dist/sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAsEH;;;;;;GAMG;AACH,8DAA8D;AAC9D,MAAM,UAAU,aAAa,CAC3B,QAAmB,EACnB,OAAyC;IAEzC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;AAChD,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,102 @@
+import type { CreateDeepAgentParams } from "deepagents";
+/**
+ * Properties the managed runtime owns. Agent authors never set these — MDA
+ * wires the backend, store, and checkpointer at deploy time, and embeds the
+ * system prompt from `instructions.md`.
+ */
+export type ManagedDeepAgentKey = "backend" | "store" | "checkpointer" | "systemPrompt";
+/**
+ * Configuration accepted by {@link defineDeepAgent}.
+ *
+ * This is the full `createDeepAgent` parameter surface minus the managed keys.
+ * Setting a managed key is a compile-time error, pointing authors at the
+ * managed `sandbox/`, store, checkpointer, and `instructions.md` wiring instead.
+ */
+export type DefineDeepAgentConfig = Omit<CreateDeepAgentParams, ManagedDeepAgentKey> & {
+    /** Managed: the runtime owns the backend. Configure it under `sandbox/`. */
+    backend?: never;
+    /** Managed: the runtime owns the durable store. */
+    store?: never;
+    /** Managed: the runtime owns the checkpointer. */
+    checkpointer?: never;
+    /**
+     * Managed: the system prompt is embedded from `instructions.md` next to the
+     * agent file at deploy time. Write your prompt there instead.
+     */
+    systemPrompt?: never;
+};
+/**
+ * The pre-runtime spec returned by {@link defineDeepAgent}.
+ *
+ * It is intentionally *not* a compiled graph: the CLI generates an entry module
+ * that hands this definition to the managed runtime, which injects the managed
+ * backend/store/checkpointer and compiles it into a Deep Agent.
+ */
+export interface DeepAgentDefinition {
+    readonly kind: "deep-agent";
+    readonly config: Omit<CreateDeepAgentParams, ManagedDeepAgentKey>;
+}
+/**
+ * Metadata about the inbound channel event that created or resumed a run.
+ */
+export interface ChannelEvent {
+    id?: string;
+    type: string;
+    timestamp?: string;
+}
+export type ChannelDestination = {
+    type: "current_thread";
+} | {
+    type: "provider_thread";
+    providerChannelId: string;
+    providerThreadId: string;
+} | {
+    type: "provider_channel";
+    providerChannelId: string;
+};
+export interface ChannelAttachment {
+    name: string;
+    contentType?: string;
+    data: Uint8Array | string;
+}
+export interface ChannelMessage {
+    text: string;
+    blocks?: unknown[];
+    attachments?: ChannelAttachment[];
+    to?: ChannelDestination;
+    providerOptions?: Record<string, unknown>;
+}
+export interface ChannelPostOptions {
+    /**
+     * Mark this post as the final agent message for the channel, used when
+     * `autoReply` is enabled.
+     */
+    final?: boolean;
+}
+export interface PostedChannelMessage {
+    id: string;
+    providerMessageId?: string;
+    url?: string;
+}
+/**
+ * The channel that triggered the current run, available on `runtime.channel`.
+ *
+ * Tools and middleware can post back without knowing any provider specifics —
+ * the originating channel and thread ride along on the run.
+ */
+export interface RuntimeChannel {
+    name: string;
+    provider: "slack" | "discord" | "email" | "webhook" | "http" | "schedule";
+    event: ChannelEvent;
+    post(message: ChannelMessage, options?: ChannelPostOptions): Promise<PostedChannelMessage>;
+}
+/**
+ * The managed runtime surface available to tools and middleware.
+ *
+ * This is intentionally narrow for v0; channels, identity, and connections grow
+ * as those parts of the spec land.
+ */
+export interface Runtime {
+    channel: RuntimeChannel;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,OAAO,GAAG,cAAc,GAAG,cAAc,CAAC;AAExF;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,qBAAqB,EAAE,mBAAmB,CAAC,GAAG;IACrF,4EAA4E;IAC5E,OAAO,CAAC,EAAE,KAAK,CAAC;IAChB,mDAAmD;IACnD,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,kDAAkD;IAClD,YAAY,CAAC,EAAE,KAAK,CAAC;IACrB;;;OAGG;IACH,YAAY,CAAC,EAAE,KAAK,CAAC;CACtB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,qBAAqB,EAAE,mBAAmB,CAAC,CAAC;CACnE;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAC1B;IACE,IAAI,EAAE,iBAAiB,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC;CAC1B,GACD;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5D,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;IACnB,WAAW,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAClC,EAAE,CAAC,EAAE,kBAAkB,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,UAAU,CAAC;IAC1E,KAAK,EAAE,YAAY,CAAC;IACpB,IAAI,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAC5F;AAED;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,cAAc,CAAC;CACzB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,12 +1,68 @@
 {
   "name": "managed-deepagents",
-  "version": "0.0.1",
-  "description": "Something amazing based on LangGraph",
-  "main": "index.js",
-  "keywords": [],
-  "author": "",
+  "version": "0.0.3-dev.13",
+  "description": "Managed Deep Agents — the `defineDeepAgent` authoring interface plus the CLI that compiles and deploys a code-first Deep Agent repository to a managed LangGraph runtime.",
+  "keywords": [
+    "langchain",
+    "langgraph",
+    "deepagents",
+    "agents",
+    "cli"
+  ],
+  "homepage": "https://github.com/langchain-ai/managed-deepagents-sdk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/langchain-ai/managed-deepagents-sdk.git"
+  },
   "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "default": "./dist/runtime/index.js"
+    }
+  },
+  "bin": {
+    "mda": "bin/mda.mjs"
+  },
+  "files": [
+    "dist",
+    "bin/mda.mjs"
+  ],
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "deepagents": ">=1.10.4"
+  },
+  "peerDependenciesMeta": {
+    "deepagents": {
+      "optional": true
+    }
+  },
+  "optionalDependencies": {
+    "@langchain/managed-deepagents-darwin-arm64": "0.0.3-dev.13",
+    "@langchain/managed-deepagents-darwin-x64": "0.0.3-dev.13",
+    "@langchain/managed-deepagents-linux-arm64": "0.0.3-dev.13",
+    "@langchain/managed-deepagents-linux-x64": "0.0.3-dev.13",
+    "@langchain/managed-deepagents-win32-x64": "0.0.3-dev.13"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.9"
   }
-}
+}

package/index.js

@@ -1 +0,0 @@
-console.log("Nothing to see yet, come back later!");