@tanstack/ai-sandbox 0.1.0

package/README.md

@@ -0,0 +1,182 @@
+# @tanstack/ai-sandbox
+
+Provider-agnostic sandbox layer for [TanStack AI](https://tanstack.com/ai). Run coding-agent harness adapters (Grok Build, Claude Code, Codex, OpenCode, Gemini CLI) **inside** an isolated environment with a real filesystem, shell, and cloned repo — and stream their work back through `chat()`.
+
+```typescript
+import { chat } from '@tanstack/ai'
+import { grokBuildText } from '@tanstack/ai-grok-build'
+import {
+  createSecrets,
+  defineSandbox,
+  defineWorkspace,
+  githubRepo,
+  withSandbox,
+} from '@tanstack/ai-sandbox'
+import { dockerSandbox } from '@tanstack/ai-sandbox-docker'
+
+const sandbox = defineSandbox({
+  id: 'repo-agent',
+  provider: dockerSandbox({ image: 'node:22' }),
+  workspace: defineWorkspace({
+    source: githubRepo({ repo: 'owner/repo', ref: 'main' }),
+    packageManager: 'pnpm',
+    setup: ['corepack enable', 'pnpm install'],
+    scripts: { test: 'pnpm test', build: 'pnpm build' },
+    secrets: createSecrets({
+      XAI_API_KEY: process.env.XAI_API_KEY ?? '',
+    }),
+  }),
+  lifecycle: { reuse: 'thread', snapshot: 'after-setup' },
+})
+
+const stream = chat({
+  threadId: 'my-thread',
+  adapter: grokBuildText('grok-build'),
+  messages: [{ role: 'user', content: 'Fix the failing test.' }],
+  middleware: [withSandbox(sandbox)],
+})
+```
+
+## Installation
+
+```bash
+npm install @tanstack/ai @tanstack/ai-sandbox @tanstack/ai-grok-build
+```
+
+Pick a **provider** package for where the sandbox runs:
+
+| Package                              | Use when                               |
+| ------------------------------------ | -------------------------------------- |
+| `@tanstack/ai-sandbox-local-process` | Dev loop on your host (no isolation)   |
+| `@tanstack/ai-sandbox-docker`        | Isolated containers, snapshots, resume |
+| `@tanstack/ai-sandbox-cloudflare`    | Cloudflare Workers + Containers        |
+| `@tanstack/ai-sandbox-vercel`        | Vercel Sandbox                         |
+| `@tanstack/ai-sandbox-daytona`       | Daytona dev environments               |
+
+**Harness adapters** are separate packages. The default path is **Grok Build** (`@tanstack/ai-grok-build`); others include `@tanstack/ai-claude-code`, `@tanstack/ai-codex`, and `@tanstack/ai-opencode`. All require `withSandbox(...)` middleware — `chat()` fails fast without it.
+
+## Three moving parts
+
+| Part                | What it is                                               | How you configure it                                              |
+| ------------------- | -------------------------------------------------------- | ----------------------------------------------------------------- |
+| **Provider**        | Isolation primitive — host, container, cloud VM          | `dockerSandbox()`, `localProcessSandbox()`, …                     |
+| **Workspace**       | What the agent boots into — repo, setup, secrets, skills | `defineWorkspace({ … })`                                          |
+| **Harness adapter** | Which agent CLI runs and how output is translated        | `grokBuildText()` (default), `claudeCodeText()`, `codexText()`, … |
+
+`defineSandbox()` binds provider + workspace (+ optional policy, lifecycle, hooks). `withSandbox(definition)` is the `chat()` middleware that creates or resumes the sandbox for each run.
+
+## Core APIs
+
+### Workspace
+
+Describe the working tree once, portably:
+
+```typescript
+defineWorkspace({
+  source: githubRepo({ repo: 'owner/app' }), // shallow clone by default
+  setup: ({ serial, parallel }) => {
+    serial('pnpm install')
+    parallel(['pnpm build', 'pnpm typecheck'])
+  },
+  scripts: { test: 'pnpm test' }, // surfaced in AGENTS.md; policy aliases
+  instructions: 'Run tests before proposing changes.',
+  skills: [
+    gitSkill({ repo: 'owner/skills', secret: secrets.GH }),
+    mcpSkill('api', {
+      url: 'https://mcp.example.com',
+      headers: { Authorization: bearer(secrets.TOKEN) },
+    }),
+    fileSkill({ path: '.hints.md', content: '# Hints\nPrefer pnpm.' }),
+  ],
+  plugins: ['@anthropic/plugin-foo'], // Claude Code only; other harnesses warn+skip
+  secrets: createSecrets({ GH: process.env.GH_TOKEN ?? '' }),
+})
+```
+
+Skills and plugins are **projected** into each harness's native format at run time (`.grok/config.toml`, `.mcp.json`, `.codex/config.toml`, `opencode.json`, …). Bootstrap writes `AGENTS.md` and clones `gitSkill` repos; harness adapters handle the rest.
+
+### Policy
+
+Guard what the agent may run:
+
+```typescript
+const policy = defineSandboxPolicy({
+  commands: {
+    allow: ['pnpm test', 'git diff'],
+    ask: ['pnpm install'],
+    deny: ['sudo *', 'rm -rf *'],
+  },
+  capabilities: { fileWrite: 'allow', network: 'ask' },
+  default: 'ask',
+})
+
+defineSandbox({ id: 'agent', provider, workspace, policy })
+```
+
+Precedence is `deny` > `ask` > `allow`. Each harness adapter maps policy onto its native permission system (coarse flags for Grok Build/Codex; full interactive `approval-requested` on Claude Code).
+
+### Lifecycle
+
+```typescript
+lifecycle: {
+  reuse: 'thread',           // resume one sandbox per threadId
+  snapshot: 'after-setup',   // skip bootstrap on subsequent runs (when provider supports it)
+  keepAlive: '30m',
+  destroyOnComplete: false,
+}
+```
+
+### Secrets
+
+Use `createSecrets()` so values stay behind opaque `SecretRef` tokens — never written to snapshots, the sandbox store, or event logs:
+
+```typescript
+const secrets = createSecrets({ XAI_API_KEY: process.env.XAI_API_KEY ?? '' })
+// secrets.XAI_API_KEY is a ref, not the string
+```
+
+### Host tool bridge
+
+`chat()` server tools can be bridged into the in-sandbox agent over MCP. The agent calls `mcp__tanstack__<tool>`; execution runs back on the host where your closures, DB, and secrets live.
+
+## Run flow
+
+```text
+chat({ adapter: grokBuildText(), middleware: [withSandbox(sandbox)] })
+  │
+  ├─ withSandbox.setup     → resume → restore snapshot → create + bootstrap
+  ├─ adapter.chatStream    → spawn `grok` (or other harness CLI) inside sandbox; stream AG-UI chunks
+  └─ withSandbox.onFinish  → snapshot / destroy per lifecycle
+```
+
+## Subpath exports
+
+| Import                       | Purpose                                               |
+| ---------------------------- | ----------------------------------------------------- |
+| `@tanstack/ai-sandbox`       | Core sandbox APIs                                     |
+| `@tanstack/ai-sandbox/ngrok` | Optional ngrok tunnel helper for remote tool bridging |
+
+## Documentation
+
+Full guides on [tanstack.com/ai](https://tanstack.com/ai/latest/docs/sandbox/overview):
+
+- [Quick Start](https://tanstack.com/ai/latest/docs/sandbox/quick-start) — Grok Build in Docker
+- [Providers](https://tanstack.com/ai/latest/docs/sandbox/providers)
+- [Workspace](https://tanstack.com/ai/latest/docs/sandbox/workspace)
+- [Provisioning](https://tanstack.com/ai/latest/docs/sandbox/provisioning) (skills, MCP, plugins)
+- [Policy](https://tanstack.com/ai/latest/docs/sandbox/policy)
+- [Tools](https://tanstack.com/ai/latest/docs/sandbox/tools) (host tool bridge)
+- [Lifecycle & snapshots](https://tanstack.com/ai/latest/docs/sandbox/lifecycle)
+
+## Examples
+
+| Example                       | What it demonstrates                                                  |
+| ----------------------------- | --------------------------------------------------------------------- |
+| `examples/sandbox-web`        | Build-and-preview with harness × provider matrix (Grok default in UI) |
+| `examples/sandbox-cloudflare` | Edge deploy with live preview URL                                     |
+
+## When to use a sandbox
+
+Use a sandbox when the agent needs to **act on a real codebase** — run commands, edit files, clone repos, start dev servers. For read-only Q&A over code you already have in context, a normal `chat()` with server tools is enough.
+
+Persistence (durable `SandboxStore` / `LockStore`, event-log replay) is out of scope for v1 but every seam is persistence-ready via optional capabilities.

package/dist/esm/agents-file.d.ts

@@ -0,0 +1,36 @@
+import { SandboxHandle } from './contracts.js';
+import { WorkspaceSkill } from './workspace.js';
+/**
+ * Resolve the directory a `gitSkill` repo is cloned into when no explicit
+ * `into` override is provided. The convention is:
+ *
+ *   `<root>/.tanstack-skills/<basename>`
+ *
+ * where `basename` is derived from the `repo` field by taking the last
+ * path segment and stripping a trailing `.git` suffix.
+ *
+ * Per-harness projectors (e.g. the Claude Code adapter) import this helper
+ * so they can locate cloned skill repos consistently.
+ *
+ * @param root  - Workspace root inside the sandbox (e.g. `/workspace`).
+ * @param skill - A `WorkspaceSkill` of `kind === 'git'`.
+ */
+export declare function resolveGitSkillDir(root: string, skill: Extract<WorkspaceSkill, {
+    kind: 'git';
+}>): string;
+/** Format workspace scripts as a `## Workspace scripts` markdown section. */
+export declare function formatWorkspaceScriptsSection(scripts: Record<string, string>): string;
+/**
+ * Merge base AGENTS.md content with an optional workspace scripts section.
+ * Returns `undefined` when there is nothing to write.
+ */
+export declare function mergeAgentsContent(base: string | undefined, scripts: Record<string, string> | undefined): string | undefined;
+/**
+ * Write `AGENTS.md` under `root` and create per-CLI symlinks (or copies as a
+ * fallback when `ln -s` is unavailable).
+ *
+ * @param handle - The sandbox handle providing `fs` and `process`.
+ * @param root   - Absolute path inside the sandbox under which to write.
+ * @param content - Markdown content for the instruction file.
+ */
+export declare function writeAgentsFile(handle: SandboxHandle, root: string, content: string): Promise<void>;

package/dist/esm/agents-file.js

@@ -0,0 +1,44 @@
+const SYMLINK_NAMES = ["CLAUDE.md", "GEMINI.md"];
+function resolveGitSkillDir(root, skill) {
+  const rawBasename = skill.repo.split("/").pop() ?? skill.repo;
+  const basename = rawBasename.endsWith(".git") ? rawBasename.slice(0, -4) : rawBasename;
+  return `${root}/.tanstack-skills/${basename}`;
+}
+function formatWorkspaceScriptsSection(scripts) {
+  const names = Object.keys(scripts).sort();
+  if (names.length === 0) return "";
+  const lines = names.map((name) => `- ${name} → ${scripts[name]}`);
+  return `## Workspace scripts
+
+${lines.join("\n")}`;
+}
+function mergeAgentsContent(base, scripts) {
+  const scriptsSection = scripts !== void 0 ? formatWorkspaceScriptsSection(scripts) : "";
+  if (base === void 0 && scriptsSection.length === 0) return void 0;
+  if (base === void 0) return scriptsSection;
+  if (scriptsSection.length === 0) return base;
+  return `${base.trimEnd()}
+
+${scriptsSection}`;
+}
+function sqEscape(value) {
+  return value.replace(/'/g, `'\\''`);
+}
+async function writeAgentsFile(handle, root, content) {
+  const agentsPath = `${root}/AGENTS.md`;
+  await handle.fs.write(agentsPath, content);
+  for (const name of SYMLINK_NAMES) {
+    const lnCmd = `ln -s '${sqEscape("AGENTS.md")}' '${sqEscape(name)}'`;
+    const result = await handle.process.exec(lnCmd, { cwd: root });
+    if (result.exitCode !== 0) {
+      await handle.fs.write(`${root}/${name}`, content);
+    }
+  }
+}
+export {
+  formatWorkspaceScriptsSection,
+  mergeAgentsContent,
+  resolveGitSkillDir,
+  writeAgentsFile
+};
+//# sourceMappingURL=agents-file.js.map

package/dist/esm/agents-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents-file.js","sources":["../../src/agents-file.ts"],"sourcesContent":["/**\n * Universal AGENTS.md writer with per-CLI symlink projection, plus the\n * canonical helper for locating cloned gitSkill repositories inside a sandbox.\n *\n * The known-names set below lists the canonical instruction-file names for\n * each AI coding assistant CLI. Keep the list in one place so it is easy to\n * extend. The copy fallback ensures correctness on platforms without symlink\n * support (e.g. Windows).\n *\n * External per-CLI convention: each assistant looks for its own instruction\n * file by name (CLAUDE.md for Claude Code, GEMINI.md for Gemini CLI, …).\n * We write a single authoritative AGENTS.md and point each name at it.\n */\nimport type { SandboxHandle } from './contracts'\nimport type { WorkspaceSkill } from './workspace'\n\n/** CLI instruction-file names that should resolve to AGENTS.md. */\nconst SYMLINK_NAMES: ReadonlyArray<string> = ['CLAUDE.md', 'GEMINI.md']\n\n/**\n * Resolve the directory a `gitSkill` repo is cloned into when no explicit\n * `into` override is provided. The convention is:\n *\n *   `<root>/.tanstack-skills/<basename>`\n *\n * where `basename` is derived from the `repo` field by taking the last\n * path segment and stripping a trailing `.git` suffix.\n *\n * Per-harness projectors (e.g. the Claude Code adapter) import this helper\n * so they can locate cloned skill repos consistently.\n *\n * @param root  - Workspace root inside the sandbox (e.g. `/workspace`).\n * @param skill - A `WorkspaceSkill` of `kind === 'git'`.\n */\nexport function resolveGitSkillDir(\n  root: string,\n  skill: Extract<WorkspaceSkill, { kind: 'git' }>,\n): string {\n  const rawBasename = skill.repo.split('/').pop() ?? skill.repo\n  const basename = rawBasename.endsWith('.git')\n    ? rawBasename.slice(0, -4)\n    : rawBasename\n  return `${root}/.tanstack-skills/${basename}`\n}\n\n/** Format workspace scripts as a `## Workspace scripts` markdown section. */\nexport function formatWorkspaceScriptsSection(\n  scripts: Record<string, string>,\n): string {\n  const names = Object.keys(scripts).sort()\n  if (names.length === 0) return ''\n  const lines = names.map((name) => `- ${name} → ${scripts[name]}`)\n  return `## Workspace scripts\\n\\n${lines.join('\\n')}`\n}\n\n/**\n * Merge base AGENTS.md content with an optional workspace scripts section.\n * Returns `undefined` when there is nothing to write.\n */\nexport function mergeAgentsContent(\n  base: string | undefined,\n  scripts: Record<string, string> | undefined,\n): string | undefined {\n  const scriptsSection =\n    scripts !== undefined ? formatWorkspaceScriptsSection(scripts) : ''\n  if (base === undefined && scriptsSection.length === 0) return undefined\n  if (base === undefined) return scriptsSection\n  if (scriptsSection.length === 0) return base\n  return `${base.trimEnd()}\\n\\n${scriptsSection}`\n}\n\n/** Escape a string for safe use as a single-quoted shell argument. */\nfunction sqEscape(value: string): string {\n  return value.replace(/'/g, `'\\\\''`)\n}\n\n/**\n * Write `AGENTS.md` under `root` and create per-CLI symlinks (or copies as a\n * fallback when `ln -s` is unavailable).\n *\n * @param handle - The sandbox handle providing `fs` and `process`.\n * @param root   - Absolute path inside the sandbox under which to write.\n * @param content - Markdown content for the instruction file.\n */\nexport async function writeAgentsFile(\n  handle: SandboxHandle,\n  root: string,\n  content: string,\n): Promise<void> {\n  const agentsPath = `${root}/AGENTS.md`\n  await handle.fs.write(agentsPath, content)\n\n  for (const name of SYMLINK_NAMES) {\n    const lnCmd = `ln -s '${sqEscape('AGENTS.md')}' '${sqEscape(name)}'`\n    const result = await handle.process.exec(lnCmd, { cwd: root })\n    if (result.exitCode !== 0) {\n      // Symlinks are not supported on this platform — fall back to a copy.\n      await handle.fs.write(`${root}/${name}`, content)\n    }\n  }\n}\n"],"names":[],"mappings":"AAiBA,MAAM,gBAAuC,CAAC,aAAa,WAAW;AAiB/D,SAAS,mBACd,MACA,OACQ;AACR,QAAM,cAAc,MAAM,KAAK,MAAM,GAAG,EAAE,SAAS,MAAM;AACzD,QAAM,WAAW,YAAY,SAAS,MAAM,IACxC,YAAY,MAAM,GAAG,EAAE,IACvB;AACJ,SAAO,GAAG,IAAI,qBAAqB,QAAQ;AAC7C;AAGO,SAAS,8BACd,SACQ;AACR,QAAM,QAAQ,OAAO,KAAK,OAAO,EAAE,KAAA;AACnC,MAAI,MAAM,WAAW,EAAG,QAAO;AAC/B,QAAM,QAAQ,MAAM,IAAI,CAAC,SAAS,KAAK,IAAI,MAAM,QAAQ,IAAI,CAAC,EAAE;AAChE,SAAO;AAAA;AAAA,EAA2B,MAAM,KAAK,IAAI,CAAC;AACpD;AAMO,SAAS,mBACd,MACA,SACoB;AACpB,QAAM,iBACJ,YAAY,SAAY,8BAA8B,OAAO,IAAI;AACnE,MAAI,SAAS,UAAa,eAAe,WAAW,EAAG,QAAO;AAC9D,MAAI,SAAS,OAAW,QAAO;AAC/B,MAAI,eAAe,WAAW,EAAG,QAAO;AACxC,SAAO,GAAG,KAAK,QAAA,CAAS;AAAA;AAAA,EAAO,cAAc;AAC/C;AAGA,SAAS,SAAS,OAAuB;AACvC,SAAO,MAAM,QAAQ,MAAM,OAAO;AACpC;AAUA,eAAsB,gBACpB,QACA,MACA,SACe;AACf,QAAM,aAAa,GAAG,IAAI;AAC1B,QAAM,OAAO,GAAG,MAAM,YAAY,OAAO;AAEzC,aAAW,QAAQ,eAAe;AAChC,UAAM,QAAQ,UAAU,SAAS,WAAW,CAAC,MAAM,SAAS,IAAI,CAAC;AACjE,UAAM,SAAS,MAAM,OAAO,QAAQ,KAAK,OAAO,EAAE,KAAK,MAAM;AAC7D,QAAI,OAAO,aAAa,GAAG;AAEzB,YAAM,OAAO,GAAG,MAAM,GAAG,IAAI,IAAI,IAAI,IAAI,OAAO;AAAA,IAClD;AAAA,EACF;AACF;"}

package/dist/esm/approvals.d.ts

@@ -0,0 +1,38 @@
+import { SandboxPolicy } from './policy.js';
+import { StreamChunk } from '@tanstack/ai';
+/** CUSTOM event name emitted when a harness action needs client approval. */
+export declare const APPROVAL_REQUESTED_EVENT = "approval-requested";
+/** A stable, opaque approval id for a harness action. */
+export declare function approvalId(input: {
+    provider: string;
+    kind: 'command' | 'fileWrite' | 'network' | 'tool';
+    target: string;
+}): string;
+export interface ResolveApprovalInput {
+    policy: SandboxPolicy | undefined;
+    /** Client approval decisions, keyed by `approvalId`. */
+    approvals: ReadonlyMap<string, boolean> | undefined;
+    /** Precomputed approval id for this action. */
+    id: string;
+    /** A shell command to match against `policy.commands`. */
+    command?: string;
+    /** Named workspace scripts for policy alias resolution. */
+    scripts?: Record<string, string>;
+    /** A coarse capability to match against `policy.capabilities`. */
+    capability?: 'fileWrite' | 'network';
+}
+export interface ApprovalOutcome {
+    decision: 'allow' | 'deny';
+    /** True when policy said `ask` and the client hasn't decided yet. */
+    needsApproval: boolean;
+}
+/** Resolve a harness permission request against policy + client approvals. */
+export declare function resolveApproval(input: ResolveApprovalInput): ApprovalOutcome;
+/** Build the AG-UI `approval-requested` CUSTOM event for a harness action. */
+export declare function buildApprovalRequestedEvent(input: {
+    approvalId: string;
+    title: string;
+    threadId: string;
+    runId: string;
+    detail?: Record<string, unknown>;
+}): StreamChunk;

package/dist/esm/approvals.js

@@ -0,0 +1,36 @@
+import { EventType } from "@tanstack/ai";
+import { evaluateCommand } from "./policy.js";
+const APPROVAL_REQUESTED_EVENT = "approval-requested";
+function approvalId(input) {
+  return `${input.provider}:${input.kind}:${input.target}`;
+}
+function resolveApproval(input) {
+  const base = input.command !== void 0 ? evaluateCommand(input.command, input.policy, input.scripts) : input.capability !== void 0 ? input.policy?.capabilities?.[input.capability] ?? input.policy?.default ?? "ask" : input.policy?.default ?? "ask";
+  if (base === "allow") return { decision: "allow", needsApproval: false };
+  if (base === "deny") return { decision: "deny", needsApproval: false };
+  const granted = input.approvals?.get(input.id);
+  if (granted === true) return { decision: "allow", needsApproval: false };
+  if (granted === false) return { decision: "deny", needsApproval: false };
+  return { decision: "deny", needsApproval: true };
+}
+function buildApprovalRequestedEvent(input) {
+  return {
+    type: EventType.CUSTOM,
+    name: APPROVAL_REQUESTED_EVENT,
+    value: {
+      approvalId: input.approvalId,
+      title: input.title,
+      ...input.detail ?? {}
+    },
+    timestamp: Date.now(),
+    threadId: input.threadId,
+    runId: input.runId
+  };
+}
+export {
+  APPROVAL_REQUESTED_EVENT,
+  approvalId,
+  buildApprovalRequestedEvent,
+  resolveApproval
+};
+//# sourceMappingURL=approvals.js.map

package/dist/esm/approvals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approvals.js","sources":["../../src/approvals.ts"],"sourcesContent":["/**\n * Shared interactive-approval logic for harness adapters.\n *\n * Flow (rides chat()'s existing resume-based approval mechanism):\n *  1. The agent (inside the sandbox) asks to run a risky action; the harness's\n *     host-side permission callback fires.\n *  2. `resolveApproval` evaluates the sandbox policy: `allow`/`deny` are final;\n *     `ask` consults the client's approval decisions (threaded via\n *     `TextOptions.approvals`, keyed by a stable `approvalId`).\n *  3. On `ask` with no decision yet, the adapter emits an `approval-requested`\n *     CUSTOM event (carrying the `approvalId`) and denies the action this turn.\n *     The client shows UI, then re-runs chat() with the decision in the message;\n *     the engine surfaces it as `approvals`, and the next run allows it.\n *\n * `approvalId` is stable for a given (provider, kind, target) so a client grant\n * matches the same action on the resumed run.\n */\nimport { EventType } from '@tanstack/ai'\nimport { evaluateCommand } from './policy'\nimport type { SandboxPolicy } from './policy'\nimport type { StreamChunk } from '@tanstack/ai'\n\n/** CUSTOM event name emitted when a harness action needs client approval. */\nexport const APPROVAL_REQUESTED_EVENT = 'approval-requested'\n\n/** A stable, opaque approval id for a harness action. */\nexport function approvalId(input: {\n  provider: string\n  kind: 'command' | 'fileWrite' | 'network' | 'tool'\n  target: string\n}): string {\n  return `${input.provider}:${input.kind}:${input.target}`\n}\n\nexport interface ResolveApprovalInput {\n  policy: SandboxPolicy | undefined\n  /** Client approval decisions, keyed by `approvalId`. */\n  approvals: ReadonlyMap<string, boolean> | undefined\n  /** Precomputed approval id for this action. */\n  id: string\n  /** A shell command to match against `policy.commands`. */\n  command?: string\n  /** Named workspace scripts for policy alias resolution. */\n  scripts?: Record<string, string>\n  /** A coarse capability to match against `policy.capabilities`. */\n  capability?: 'fileWrite' | 'network'\n}\n\nexport interface ApprovalOutcome {\n  decision: 'allow' | 'deny'\n  /** True when policy said `ask` and the client hasn't decided yet. */\n  needsApproval: boolean\n}\n\n/** Resolve a harness permission request against policy + client approvals. */\nexport function resolveApproval(input: ResolveApprovalInput): ApprovalOutcome {\n  const base =\n    input.command !== undefined\n      ? evaluateCommand(input.command, input.policy, input.scripts)\n      : input.capability !== undefined\n        ? (input.policy?.capabilities?.[input.capability] ??\n          input.policy?.default ??\n          'ask')\n        : (input.policy?.default ?? 'ask')\n\n  if (base === 'allow') return { decision: 'allow', needsApproval: false }\n  if (base === 'deny') return { decision: 'deny', needsApproval: false }\n\n  // base === 'ask' — consult the client's decision.\n  const granted = input.approvals?.get(input.id)\n  if (granted === true) return { decision: 'allow', needsApproval: false }\n  if (granted === false) return { decision: 'deny', needsApproval: false }\n  return { decision: 'deny', needsApproval: true }\n}\n\n/** Build the AG-UI `approval-requested` CUSTOM event for a harness action. */\nexport function buildApprovalRequestedEvent(input: {\n  approvalId: string\n  title: string\n  threadId: string\n  runId: string\n  detail?: Record<string, unknown>\n}): StreamChunk {\n  return {\n    type: EventType.CUSTOM,\n    name: APPROVAL_REQUESTED_EVENT,\n    value: {\n      approvalId: input.approvalId,\n      title: input.title,\n      ...(input.detail ?? {}),\n    },\n    timestamp: Date.now(),\n    threadId: input.threadId,\n    runId: input.runId,\n  }\n}\n"],"names":[],"mappings":";;AAuBO,MAAM,2BAA2B;AAGjC,SAAS,WAAW,OAIhB;AACT,SAAO,GAAG,MAAM,QAAQ,IAAI,MAAM,IAAI,IAAI,MAAM,MAAM;AACxD;AAuBO,SAAS,gBAAgB,OAA8C;AAC5E,QAAM,OACJ,MAAM,YAAY,SACd,gBAAgB,MAAM,SAAS,MAAM,QAAQ,MAAM,OAAO,IAC1D,MAAM,eAAe,SAClB,MAAM,QAAQ,eAAe,MAAM,UAAU,KAC9C,MAAM,QAAQ,WACd,QACC,MAAM,QAAQ,WAAW;AAElC,MAAI,SAAS,QAAS,QAAO,EAAE,UAAU,SAAS,eAAe,MAAA;AACjE,MAAI,SAAS,OAAQ,QAAO,EAAE,UAAU,QAAQ,eAAe,MAAA;AAG/D,QAAM,UAAU,MAAM,WAAW,IAAI,MAAM,EAAE;AAC7C,MAAI,YAAY,KAAM,QAAO,EAAE,UAAU,SAAS,eAAe,MAAA;AACjE,MAAI,YAAY,MAAO,QAAO,EAAE,UAAU,QAAQ,eAAe,MAAA;AACjE,SAAO,EAAE,UAAU,QAAQ,eAAe,KAAA;AAC5C;AAGO,SAAS,4BAA4B,OAM5B;AACd,SAAO;AAAA,IACL,MAAM,UAAU;AAAA,IAChB,MAAM;AAAA,IACN,OAAO;AAAA,MACL,YAAY,MAAM;AAAA,MAClB,OAAO,MAAM;AAAA,MACb,GAAI,MAAM,UAAU,CAAA;AAAA,IAAC;AAAA,IAEvB,WAAW,KAAK,IAAA;AAAA,IAChB,UAAU,MAAM;AAAA,IAChB,OAAO,MAAM;AAAA,EAAA;AAEjB;"}

package/dist/esm/bootstrap.d.ts

@@ -0,0 +1,17 @@
+import { SandboxHandle } from './contracts.js';
+import { PackageManager, WorkspaceDefinition } from './workspace.js';
+export declare const DEFAULT_WORKSPACE_ROOT = "/workspace";
+/** Resolve the package manager, detecting from a lockfile when `'auto'`. */
+export declare function detectPackageManager(handle: SandboxHandle, workspace: WorkspaceDefinition, root: string): Promise<Exclude<PackageManager, 'auto'> | undefined>;
+export interface BootstrapResult {
+    packageManager?: Exclude<PackageManager, 'auto'>;
+    ranSetup: Array<string>;
+}
+/**
+ * Bootstrap a freshly created sandbox's workspace. Idempotent enough to be safe
+ * on restore: a git clone into a populated dir is skipped by checking for the
+ * target dir first.
+ */
+export declare function bootstrapWorkspace(handle: SandboxHandle, workspace: WorkspaceDefinition, options?: {
+    signal?: AbortSignal;
+}): Promise<BootstrapResult>;

package/dist/esm/bootstrap.js

@@ -0,0 +1,124 @@
+import { buildSetupPlan } from "./setup-plan.js";
+import { createBootstrapShell } from "./shell.js";
+import { resolveGitSkillDir, mergeAgentsContent, writeAgentsFile } from "./agents-file.js";
+import { resolveAllSecrets, resolveSecret } from "./secrets.js";
+const LOCKFILES = {
+  pnpm: "pnpm-lock.yaml",
+  yarn: "yarn.lock",
+  bun: "bun.lockb",
+  npm: "package-lock.json"
+};
+const DEFAULT_WORKSPACE_ROOT = "/workspace";
+async function detectPackageManager(handle, workspace, root) {
+  const pm = workspace.packageManager ?? "auto";
+  if (pm !== "auto") return pm;
+  for (const [manager, lockfile] of Object.entries(LOCKFILES)) {
+    if (await handle.fs.exists(`${root}/${lockfile}`)) return manager;
+  }
+  return void 0;
+}
+async function bootstrapWorkspace(handle, workspace, options = {}) {
+  const root = workspace.root ?? DEFAULT_WORKSPACE_ROOT;
+  if (workspace.secrets !== void 0) {
+    const resolved = resolveAllSecrets(workspace.secrets);
+    if (Object.keys(resolved).length > 0) {
+      await handle.env.set(resolved);
+    }
+  }
+  if (workspace.source.type === "git") {
+    const alreadyCloned = await handle.fs.exists(`${root}/.git`);
+    if (!alreadyCloned) {
+      await handle.git.clone({
+        url: workspace.source.url,
+        ref: workspace.source.ref,
+        auth: workspace.source.auth,
+        ...workspace.source.depth !== void 0 ? { depth: workspace.source.depth } : {}
+      });
+    }
+  }
+  const skills = workspace.skills ?? [];
+  for (const skill of skills) {
+    if (skill.kind === "git") {
+      const url = skill.repo.startsWith("http") ? skill.repo : `https://github.com/${skill.repo}.git`;
+      const dir = skill.into ?? resolveGitSkillDir(root, skill);
+      const auth = skill.secret !== void 0 && workspace.secrets !== void 0 ? { token: resolveSecret(workspace.secrets, skill.secret) } : void 0;
+      await handle.git.clone({
+        url,
+        dir,
+        ...auth !== void 0 ? { auth } : {},
+        depth: 1
+      });
+    }
+  }
+  let agentsContent;
+  if (workspace.instructions !== void 0 && workspace.instructions.length > 0) {
+    agentsContent = workspace.instructions;
+  } else {
+    const agentsFileSkill = skills.find(
+      (s) => s.kind === "file" && s.path === "AGENTS.md"
+    );
+    if (agentsFileSkill !== void 0) {
+      agentsContent = agentsFileSkill.content;
+    }
+  }
+  agentsContent = mergeAgentsContent(agentsContent, workspace.scripts);
+  if (agentsContent !== void 0) {
+    await writeAgentsFile(handle, root, agentsContent);
+  }
+  for (const skill of skills) {
+    if (skill.kind === "file" && skill.path !== "AGENTS.md") {
+      await handle.fs.write(`${root}/${skill.path}`, skill.content);
+    }
+  }
+  const packageManager = await detectPackageManager(handle, workspace, root);
+  const ranSetup = [];
+  const plan = buildSetupPlan(workspace.setup);
+  if (plan.length > 0) {
+    const shell = await createBootstrapShell(handle, { cwd: root });
+    try {
+      for (const group of plan) {
+        if (group.kind === "serial") {
+          const result = await shell.run(group.command);
+          if (result.exitCode !== 0) {
+            const tail = result.stdout.trim().slice(-1500);
+            throw new Error(
+              `setup step failed: ${group.command} (exit ${result.exitCode})${tail ? `
+${tail}` : ""}`
+            );
+          }
+          ranSetup.push(group.command);
+        } else {
+          const { cwd, env } = await shell.forkState();
+          const results = await Promise.all(
+            group.commands.map(
+              (command) => handle.process.exec(command, {
+                cwd,
+                env,
+                ...options.signal ? { signal: options.signal } : {}
+              }).then((res) => ({ command, res }))
+            )
+          );
+          const failed = results.find((entry) => entry.res.exitCode !== 0);
+          if (failed !== void 0) {
+            const tail = `${failed.res.stdout}
+${failed.res.stderr}`.trim().slice(-1500);
+            throw new Error(
+              `setup step failed: ${failed.command} (exit ${failed.res.exitCode})${tail ? `
+${tail}` : ""}`
+            );
+          }
+          ranSetup.push(...group.commands);
+        }
+      }
+    } finally {
+      await shell.dispose();
+    }
+  }
+  return { packageManager, ranSetup };
+}
+export {
+  DEFAULT_WORKSPACE_ROOT,
+  bootstrapWorkspace,
+  detectPackageManager
+};
+//# sourceMappingURL=bootstrap.js.map

package/dist/esm/bootstrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.js","sources":["../../src/bootstrap.ts"],"sourcesContent":["/**\n * Workspace bootstrap engine — provider-agnostic because it only uses the\n * {@link SandboxHandle} contract. Runs once when a sandbox is freshly created\n * (or restored without its working tree): land the source, inject secrets,\n * detect the package manager, and run setup commands.\n *\n * Harness-specific projection (CLAUDE.md, agent skills, MCP config) is NOT done\n * here — that's each adapter's `projectWorkspace()` hook, since the format\n * differs per harness.\n */\nimport { buildSetupPlan } from './setup-plan'\nimport { createBootstrapShell } from './shell'\nimport {\n  mergeAgentsContent,\n  resolveGitSkillDir,\n  writeAgentsFile,\n} from './agents-file'\nimport { resolveAllSecrets, resolveSecret } from './secrets'\nimport type { SandboxHandle } from './contracts'\nimport type { PackageManager, WorkspaceDefinition } from './workspace'\n\nconst LOCKFILES: Record<Exclude<PackageManager, 'auto'>, string> = {\n  pnpm: 'pnpm-lock.yaml',\n  yarn: 'yarn.lock',\n  bun: 'bun.lockb',\n  npm: 'package-lock.json',\n}\n\nexport const DEFAULT_WORKSPACE_ROOT = '/workspace'\n\n/** Resolve the package manager, detecting from a lockfile when `'auto'`. */\nexport async function detectPackageManager(\n  handle: SandboxHandle,\n  workspace: WorkspaceDefinition,\n  root: string,\n): Promise<Exclude<PackageManager, 'auto'> | undefined> {\n  const pm = workspace.packageManager ?? 'auto'\n  if (pm !== 'auto') return pm\n  for (const [manager, lockfile] of Object.entries(LOCKFILES) as Array<\n    [Exclude<PackageManager, 'auto'>, string]\n  >) {\n    if (await handle.fs.exists(`${root}/${lockfile}`)) return manager\n  }\n  return undefined\n}\n\nexport interface BootstrapResult {\n  packageManager?: Exclude<PackageManager, 'auto'>\n  ranSetup: Array<string>\n}\n\n/**\n * Bootstrap a freshly created sandbox's workspace. Idempotent enough to be safe\n * on restore: a git clone into a populated dir is skipped by checking for the\n * target dir first.\n */\nexport async function bootstrapWorkspace(\n  handle: SandboxHandle,\n  workspace: WorkspaceDefinition,\n  options: { signal?: AbortSignal } = {},\n): Promise<BootstrapResult> {\n  const root = workspace.root ?? DEFAULT_WORKSPACE_ROOT\n\n  // Secrets live only in the running sandbox env (never persisted).\n  if (workspace.secrets !== undefined) {\n    const resolved = resolveAllSecrets(workspace.secrets)\n    if (Object.keys(resolved).length > 0) {\n      await handle.env.set(resolved)\n    }\n  }\n\n  // Land the source. Clone into the handle's own default root (each provider\n  // maps the conventional `/workspace` virtual root to its real backing dir),\n  // rather than passing a virtual `dir` that can't be remapped inside a shell\n  // command string.\n  if (workspace.source.type === 'git') {\n    const alreadyCloned = await handle.fs.exists(`${root}/.git`)\n    if (!alreadyCloned) {\n      await handle.git.clone({\n        url: workspace.source.url,\n        ref: workspace.source.ref,\n        auth: workspace.source.auth,\n        ...(workspace.source.depth !== undefined\n          ? { depth: workspace.source.depth }\n          : {}),\n      })\n    }\n  }\n  // 'local' is provider-pre-populated at create; 'none' starts empty.\n\n  // Clone git-skill repos so setup steps (and the harness projector) can use\n  // them. gitSkill clones are always shallow (depth 1) unless the skill's own\n  // repo entry carries a depth override — the WorkspaceSkill `git` variant\n  // does not expose one, so depth always defaults to 1 inside git.clone.\n  const skills = workspace.skills ?? []\n  for (const skill of skills) {\n    if (skill.kind === 'git') {\n      const url = skill.repo.startsWith('http')\n        ? skill.repo\n        : `https://github.com/${skill.repo}.git`\n      const dir = skill.into ?? resolveGitSkillDir(root, skill)\n      const auth =\n        skill.secret !== undefined && workspace.secrets !== undefined\n          ? { token: resolveSecret(workspace.secrets, skill.secret) }\n          : undefined\n      await handle.git.clone({\n        url,\n        dir,\n        ...(auth !== undefined ? { auth } : {}),\n        depth: 1,\n      })\n    }\n  }\n\n  // Write AGENTS.md (and its per-CLI symlinks) when instructions are provided\n  // directly on the workspace, via a fileSkill whose path is `AGENTS.md`, or\n  // when named workspace scripts should be surfaced for the agent.\n  let agentsContent: string | undefined\n  if (\n    workspace.instructions !== undefined &&\n    workspace.instructions.length > 0\n  ) {\n    agentsContent = workspace.instructions\n  } else {\n    const agentsFileSkill = skills.find(\n      (s): s is Extract<typeof s, { kind: 'file' }> =>\n        s.kind === 'file' && s.path === 'AGENTS.md',\n    )\n    if (agentsFileSkill !== undefined) {\n      agentsContent = agentsFileSkill.content\n    }\n  }\n  agentsContent = mergeAgentsContent(agentsContent, workspace.scripts)\n  if (agentsContent !== undefined) {\n    await writeAgentsFile(handle, root, agentsContent)\n  }\n\n  // Write all other fileSkills directly into the workspace root.\n  for (const skill of skills) {\n    if (skill.kind === 'file' && skill.path !== 'AGENTS.md') {\n      await handle.fs.write(`${root}/${skill.path}`, skill.content)\n    }\n  }\n\n  const packageManager = await detectPackageManager(handle, workspace, root)\n\n  // Run setup over a single persistent shell so `cd`/exports persist across\n  // serial steps. Parallel groups fork the shell's current cwd+env into\n  // concurrent one-shot exec calls.\n  const ranSetup: Array<string> = []\n  const plan = buildSetupPlan(workspace.setup)\n  if (plan.length > 0) {\n    const shell = await createBootstrapShell(handle, { cwd: root })\n    try {\n      for (const group of plan) {\n        if (group.kind === 'serial') {\n          const result = await shell.run(group.command)\n          if (result.exitCode !== 0) {\n            const tail = result.stdout.trim().slice(-1500)\n            throw new Error(\n              `setup step failed: ${group.command} (exit ${result.exitCode})${tail ? `\\n${tail}` : ''}`,\n            )\n          }\n          ranSetup.push(group.command)\n        } else {\n          const { cwd, env } = await shell.forkState()\n          const results = await Promise.all(\n            group.commands.map((command) =>\n              handle.process\n                .exec(command, {\n                  cwd,\n                  env,\n                  ...(options.signal ? { signal: options.signal } : {}),\n                })\n                .then((res) => ({ command, res })),\n            ),\n          )\n          const failed = results.find((entry) => entry.res.exitCode !== 0)\n          if (failed !== undefined) {\n            const tail = `${failed.res.stdout}\\n${failed.res.stderr}`\n              .trim()\n              .slice(-1500)\n            throw new Error(\n              `setup step failed: ${failed.command} (exit ${failed.res.exitCode})${tail ? `\\n${tail}` : ''}`,\n            )\n          }\n          ranSetup.push(...group.commands)\n        }\n      }\n    } finally {\n      await shell.dispose()\n    }\n  }\n\n  return { packageManager, ranSetup }\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/bridge-events.d.ts

@@ -0,0 +1,21 @@
+import { StreamChunk } from '@tanstack/ai';
+export interface BridgeEventChannel {
+    /** Pass as the bridge's `emitCustomEvent`; buffers a CUSTOM chunk for the stream. */
+    emitCustomEvent: (eventName: string, value: Record<string, unknown>) => void;
+    /** Live CUSTOM-chunk stream; ends after {@link close} once drained. */
+    stream: AsyncIterable<StreamChunk>;
+    /** Stop the stream (call when the run's main output is done). */
+    close: () => void;
+}
+/** Create a channel whose emitted events become CUSTOM {@link StreamChunk}s. */
+export declare function createBridgeEventChannel(meta: {
+    model: string;
+    threadId?: string;
+    runId?: string;
+}): BridgeEventChannel;
+/**
+ * Merge a `side` chunk stream into a `base` chunk stream, yielding from whichever
+ * settles first. Terminates when `base` ends (the run is over), then releases the
+ * side iterator — so a never-ending channel (until closed) doesn't hang the merge.
+ */
+export declare function mergeChunkStreams(base: AsyncIterable<StreamChunk>, side: AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>;

package/dist/esm/bridge-events.js

@@ -0,0 +1,76 @@
+import { EventType } from "@tanstack/ai";
+function createBridgeEventChannel(meta) {
+  const buffer = [];
+  let notify = null;
+  let closed = false;
+  async function* stream() {
+    for (; ; ) {
+      const next = buffer.shift();
+      if (next !== void 0) {
+        yield next;
+        continue;
+      }
+      if (closed) return;
+      await new Promise((resolve) => {
+        notify = resolve;
+      });
+      notify = null;
+    }
+  }
+  return {
+    emitCustomEvent(eventName, value) {
+      if (closed) return;
+      buffer.push({
+        type: EventType.CUSTOM,
+        name: eventName,
+        value,
+        timestamp: Date.now(),
+        model: meta.model,
+        ...meta.threadId !== void 0 && { threadId: meta.threadId },
+        ...meta.runId !== void 0 && { runId: meta.runId }
+      });
+      notify?.();
+    },
+    close() {
+      closed = true;
+      notify?.();
+    },
+    stream: stream()
+  };
+}
+async function* mergeChunkStreams(base, side) {
+  const baseIt = base[Symbol.asyncIterator]();
+  const sideIt = side[Symbol.asyncIterator]();
+  let baseNext = baseIt.next().then((r) => ({ from: "base", r }));
+  let sideNext = sideIt.next().then((r) => ({ from: "side", r }));
+  let sideLive = true;
+  try {
+    for (; ; ) {
+      const winner = await Promise.race(
+        sideLive ? [baseNext, sideNext] : [baseNext]
+      );
+      if (winner.from === "base") {
+        if (winner.r.done) return;
+        yield winner.r.value;
+        baseNext = baseIt.next().then((r) => ({ from: "base", r }));
+      } else if (winner.r.done) {
+        sideLive = false;
+      } else {
+        yield winner.r.value;
+        sideNext = sideIt.next().then((r) => ({ from: "side", r }));
+      }
+    }
+  } finally {
+    const baseReturn = baseIt.return?.(void 0);
+    if (baseReturn) void baseReturn.catch(() => {
+    });
+    const sideReturn = sideIt.return?.(void 0);
+    if (sideReturn) void sideReturn.catch(() => {
+    });
+  }
+}
+export {
+  createBridgeEventChannel,
+  mergeChunkStreams
+};
+//# sourceMappingURL=bridge-events.js.map

package/dist/esm/bridge-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-events.js","sources":["../../src/bridge-events.ts"],"sourcesContent":["/**\n * Helpers that let a harness adapter surface custom events emitted by BRIDGED\n * tools (via {@link ToolBridgeCoreOptions.emitCustomEvent}) on its live output\n * stream.\n *\n * The bridge runs out-of-band from the harness's own event stream, so a bridged\n * tool's progress/console events have no path to the client on their own. An\n * adapter creates a {@link BridgeEventChannel}, hands its `emitCustomEvent` to\n * the bridge provisioner, and {@link mergeChunkStreams | merges} the channel's\n * stream into its translated output — so events interleave live while the agent\n * runs (e.g. code mode's `code_mode:console` logs during a long execution).\n */\nimport { EventType } from '@tanstack/ai'\nimport type { StreamChunk } from '@tanstack/ai'\n\nexport interface BridgeEventChannel {\n  /** Pass as the bridge's `emitCustomEvent`; buffers a CUSTOM chunk for the stream. */\n  emitCustomEvent: (eventName: string, value: Record<string, unknown>) => void\n  /** Live CUSTOM-chunk stream; ends after {@link close} once drained. */\n  stream: AsyncIterable<StreamChunk>\n  /** Stop the stream (call when the run's main output is done). */\n  close: () => void\n}\n\n/** Create a channel whose emitted events become CUSTOM {@link StreamChunk}s. */\nexport function createBridgeEventChannel(meta: {\n  model: string\n  threadId?: string\n  runId?: string\n}): BridgeEventChannel {\n  const buffer: Array<StreamChunk> = []\n  let notify: (() => void) | null = null\n  let closed = false\n\n  async function* stream(): AsyncIterable<StreamChunk> {\n    for (;;) {\n      const next = buffer.shift()\n      if (next !== undefined) {\n        yield next\n        continue\n      }\n      if (closed) return\n      await new Promise<void>((resolve) => {\n        notify = resolve\n      })\n      notify = null\n    }\n  }\n\n  return {\n    emitCustomEvent(eventName, value) {\n      if (closed) return\n      buffer.push({\n        type: EventType.CUSTOM,\n        name: eventName,\n        value,\n        timestamp: Date.now(),\n        model: meta.model,\n        ...(meta.threadId !== undefined && { threadId: meta.threadId }),\n        ...(meta.runId !== undefined && { runId: meta.runId }),\n      })\n      notify?.()\n    },\n    close() {\n      closed = true\n      notify?.()\n    },\n    stream: stream(),\n  }\n}\n\n/**\n * Merge a `side` chunk stream into a `base` chunk stream, yielding from whichever\n * settles first. Terminates when `base` ends (the run is over), then releases the\n * side iterator — so a never-ending channel (until closed) doesn't hang the merge.\n */\nexport async function* mergeChunkStreams(\n  base: AsyncIterable<StreamChunk>,\n  side: AsyncIterable<StreamChunk>,\n): AsyncIterable<StreamChunk> {\n  const baseIt = base[Symbol.asyncIterator]()\n  const sideIt = side[Symbol.asyncIterator]()\n  let baseNext = baseIt.next().then((r) => ({ from: 'base' as const, r }))\n  let sideNext = sideIt.next().then((r) => ({ from: 'side' as const, r }))\n  let sideLive = true\n  try {\n    for (;;) {\n      const winner = await Promise.race(\n        sideLive ? [baseNext, sideNext] : [baseNext],\n      )\n      if (winner.from === 'base') {\n        if (winner.r.done) return\n        yield winner.r.value\n        baseNext = baseIt.next().then((r) => ({ from: 'base' as const, r }))\n      } else if (winner.r.done) {\n        sideLive = false\n      } else {\n        yield winner.r.value\n        sideNext = sideIt.next().then((r) => ({ from: 'side' as const, r }))\n      }\n    }\n  } finally {\n    // Fire-and-forget: do NOT await the side return. The channel generator is\n    // suspended on a promise that only `close()` resolves, and `close()` runs in\n    // the adapter's `finally` AFTER this merge completes — awaiting here would\n    // deadlock. The adapter's `close()` lets the generator unwind afterwards.\n    const baseReturn = baseIt.return?.(undefined)\n    if (baseReturn) void baseReturn.catch(() => {})\n    const sideReturn = sideIt.return?.(undefined)\n    if (sideReturn) void sideReturn.catch(() => {})\n  }\n}\n"],"names":[],"mappings":";AAyBO,SAAS,yBAAyB,MAIlB;AACrB,QAAM,SAA6B,CAAA;AACnC,MAAI,SAA8B;AAClC,MAAI,SAAS;AAEb,kBAAgB,SAAqC;AACnD,eAAS;AACP,YAAM,OAAO,OAAO,MAAA;AACpB,UAAI,SAAS,QAAW;AACtB,cAAM;AACN;AAAA,MACF;AACA,UAAI,OAAQ;AACZ,YAAM,IAAI,QAAc,CAAC,YAAY;AACnC,iBAAS;AAAA,MACX,CAAC;AACD,eAAS;AAAA,IACX;AAAA,EACF;AAEA,SAAO;AAAA,IACL,gBAAgB,WAAW,OAAO;AAChC,UAAI,OAAQ;AACZ,aAAO,KAAK;AAAA,QACV,MAAM,UAAU;AAAA,QAChB,MAAM;AAAA,QACN;AAAA,QACA,WAAW,KAAK,IAAA;AAAA,QAChB,OAAO,KAAK;AAAA,QACZ,GAAI,KAAK,aAAa,UAAa,EAAE,UAAU,KAAK,SAAA;AAAA,QACpD,GAAI,KAAK,UAAU,UAAa,EAAE,OAAO,KAAK,MAAA;AAAA,MAAM,CACrD;AACD,eAAA;AAAA,IACF;AAAA,IACA,QAAQ;AACN,eAAS;AACT,eAAA;AAAA,IACF;AAAA,IACA,QAAQ,OAAA;AAAA,EAAO;AAEnB;AAOA,gBAAuB,kBACrB,MACA,MAC4B;AAC5B,QAAM,SAAS,KAAK,OAAO,aAAa,EAAA;AACxC,QAAM,SAAS,KAAK,OAAO,aAAa,EAAA;AACxC,MAAI,WAAW,OAAO,KAAA,EAAO,KAAK,CAAC,OAAO,EAAE,MAAM,QAAiB,EAAA,EAAI;AACvE,MAAI,WAAW,OAAO,KAAA,EAAO,KAAK,CAAC,OAAO,EAAE,MAAM,QAAiB,EAAA,EAAI;AACvE,MAAI,WAAW;AACf,MAAI;AACF,eAAS;AACP,YAAM,SAAS,MAAM,QAAQ;AAAA,QAC3B,WAAW,CAAC,UAAU,QAAQ,IAAI,CAAC,QAAQ;AAAA,MAAA;AAE7C,UAAI,OAAO,SAAS,QAAQ;AAC1B,YAAI,OAAO,EAAE,KAAM;AACnB,cAAM,OAAO,EAAE;AACf,mBAAW,OAAO,KAAA,EAAO,KAAK,CAAC,OAAO,EAAE,MAAM,QAAiB,EAAA,EAAI;AAAA,MACrE,WAAW,OAAO,EAAE,MAAM;AACxB,mBAAW;AAAA,MACb,OAAO;AACL,cAAM,OAAO,EAAE;AACf,mBAAW,OAAO,KAAA,EAAO,KAAK,CAAC,OAAO,EAAE,MAAM,QAAiB,EAAA,EAAI;AAAA,MACrE;AAAA,IACF;AAAA,EACF,UAAA;AAKE,UAAM,aAAa,OAAO,SAAS,MAAS;AAC5C,QAAI,WAAY,MAAK,WAAW,MAAM,MAAM;AAAA,IAAC,CAAC;AAC9C,UAAM,aAAa,OAAO,SAAS,MAAS;AAC5C,QAAI,WAAY,MAAK,WAAW,MAAM,MAAM;AAAA,IAAC,CAAC;AAAA,EAChD;AACF;"}