@mono-agent/agent-runtime 0.1.0

package/README.md

@@ -0,0 +1,430 @@
+# @mono-agent/agent-runtime
+
+## Category
+
+Category: `runtime`
+
+## Responsibility
+
+Provides the multi-backend agent runtime bridges (Claude SDK, Claude Code CLI, Codex app-server, Pi SDK) with provider session support. This is the runtime layer that `@mono-agent/runtime-adapter` wraps behind runtime contracts, and it enforces optional `@mono-agent/sandbox` policy for runtime-owned tools.
+
+## Public API
+
+- `createRuntime` — runtime factory dispatching to the backend bridges
+- `ai/runtime/model-refs.js` — `parseRuntimeModelReference`, `executionModeIncompatibilityReason`
+- `ai/runtime/registry.js` — `listRuntimeBridges`
+- Provider bridges for `claude` (SDK + CLI), `codex` (app-server), `pi` (Pi SDK), and `opencode`
+- Provider session support: bridges accept `sessionId` in run options and report `provider_session_id`; the runtime exposes `disposeSession` / `disposeAllSessions`
+- Sandbox-aware built-in tools and stdio MCP startup through `@mono-agent/sandbox`
+
+## Dependency Boundary
+
+Depends on external provider SDKs (`@anthropic-ai/claude-agent-sdk`, `@earendil-works/pi-agent-core`, `@earendil-works/pi-ai`, `@modelcontextprotocol/sdk`, `@opencode-ai/sdk`, `zod`) plus `@mono-agent/sandbox` for runtime-owned command preparation and network/path policy checks.
+
+## What This Package Does Not Own
+
+- runtime contracts and backend descriptors (`@mono-agent/runtime-adapter`)
+- Conversation history, context building, or host-side session TTL policy (`@mono-agent/agent-harness`)
+- Host configuration (`@mono-agent/config`, `@mono-agent/agent-host`)
+
+## Verification
+
+```bash
+pnpm --filter @mono-agent/agent-runtime run test
+```
+
+## Overview
+
+Generic agent runtime that supports four backends out of the box:
+
+- **Claude SDK** (`@anthropic-ai/claude-agent-sdk`)
+- **Claude Code CLI** (the `claude` binary)
+- **Pi SDK** (`@earendil-works/pi-agent-core`, used for OpenAI / Codex / Gemini / OpenRouter / Ollama / etc. via Pi providers)
+- **Codex CLI** (the `codex` app-server)
+
+Hosts wire in their own pricing, persistence, credential, and compaction-recording callbacks. The runtime returns raw text + raw structured output; hosts that want a domain-specific contract parse it on their end.
+
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for the package boundary, runtime
+selection flow, lifecycle diagrams, and host responsibilities.
+
+## Install / Usage
+
+```bash
+npm install @mono-agent/agent-runtime
+```
+
+Peer requirements:
+
+- Node.js ≥ 20
+- `claude` CLI on PATH (only for `executionMode: "cli"` with `claude` SDK)
+- `codex` CLI on PATH (only for `executionMode: "cli"` with `codex` SDK; override via the `codexAppServerCommand` option)
+- `ripgrep` on PATH (or supplied via `ripgrepPath`) — required for the `Glob` and `Grep` built-in tools
+
+## Quick start
+
+```js
+import { createRuntime } from "@mono-agent/agent-runtime";
+
+const runtime = createRuntime({
+  // Host integration (all optional)
+  workspace: "/path/to/repo",
+  ripgrepPath: "/usr/bin/rg",
+});
+
+const result = await runtime.run("You are a helpful assistant.", {
+  model: { sdk: "claude", model: "claude-sonnet-4-6" },
+  executionMode: "sdk",
+  messages: [{ role: "user", content: "Read README.md and summarize it." }],
+  cwd: "/path/to/repo",
+  allowedTools: ["Read", "Bash"],
+  maxTurns: 10,
+  onEvent: (event) => console.log(event.type),
+});
+
+console.log(result.text);
+```
+
+## When to reach for this vs. other JS agent runtimes
+
+`@mono-agent/agent-runtime` is purpose-built for **autonomous, long-running agent work** with provider portability and operational resilience as first-class concerns. It is *not* a streaming-chat UI kit. Where each peer fits:
+
+- **Vercel AI SDK** — best when you're building a chat / generative-UI experience inside a React or Next.js app. `useChat`, `useCompletion`, streaming server components, and edge-runtime compatibility are their strengths. Their provider list is curated (Anthropic, OpenAI, Google, etc., via `@ai-sdk/*` packages); there's no Pi gateway, no Claude Code CLI, no Codex CLI app-server, and no per-call provider fallback. If you're rendering a streaming chat into a browser, use them. If you're orchestrating multi-turn autonomous work that must survive a rate-limited primary provider, use us.
+- **Claude Agent SDK** (`@anthropic-ai/claude-agent-sdk`) — first-party Anthropic SDK. Tight integration with Claude features (canUseTool, sub-agents, hooks, MCP). We *wrap* it as one of our four backends and add context compaction, transcript-resume across provider drops, a 22-kind failure taxonomy, a tool-bloat guard with artifact persistence, and a provider fallback router. Reach for the bare Anthropic SDK when you only ever talk to Claude and don't need cross-provider portability or resume.
+- **Mastra** — a workflow engine + memory + RAG stack. Different category: it's the layer *above* a runtime. You can layer Mastra workflows on top of `@mono-agent/agent-runtime` if you want both.
+- **OpenAI Agents SDK** — first-party OpenAI SDK. Same trade-off as the Claude Agent SDK: tight integration with OpenAI, no other providers. Pi providers in our runtime cover OpenAI plus a dozen others through a single API.
+- **LangChain.js** — kitchen sink with deep abstraction stacks. We're deliberately lean; if you want chains, agents, vector stores, and parsers under one umbrella, LangChain is built for that. If you want a focused runtime kernel, use us.
+
+**What we natively bridge (no extra packages):**
+
+- Anthropic Claude via the Claude Agent SDK (`claude` SDK).
+- Anthropic Claude via the `claude` Code CLI binary.
+- OpenAI's Codex via the `codex` app-server CLI.
+- OpenAI, Google Gemini, AWS Bedrock, OpenRouter, xAI, Groq, Mistral, Perplexity, DeepSeek, Ollama, LlamaCPP, GLM, Vercel AI Gateway, GitHub Copilot, Gemini CLI — all through the Pi (`@earendil-works/pi-ai`) provider gateway, which our SDK adapter speaks directly.
+
+**At-a-glance:**
+
+| Need | Use this | Use Vercel AI SDK | Use Claude Agent SDK |
+|---|---|---|---|
+| Streaming chat UI in React/Next | ✗ | ✓ | ✗ |
+| Multi-provider portability | ✓ (4 backends, 15+ providers) | partial | ✗ |
+| CLI providers (claude/codex binaries) | ✓ | ✗ | ✗ |
+| Provider fallback on rate limit / overload | ✓ (`createRouterRuntime`) | ✗ | ✗ |
+| Aggressive context compaction with summarization | ✓ | ✗ | partial |
+| Transcript-tail resume after provider drops | ✓ | ✗ | ✗ |
+| Tool-output bloat guard + artifact persistence | ✓ | ✗ | ✗ |
+| MCP transports out of the box (stdio/SSE/HTTP) | ✓ | partial | ✓ |
+| HITL approval gates with risk tiers | ✓ | ✗ | partial (`canUseTool`) |
+| Multi-subscriber observer with cost/cache metrics | ✓ | partial | partial |
+| Edge-runtime compatibility | ✗ | ✓ | partial |
+
+Honest summary: if the agent runs **without a human watching the screen** for minutes-to-hours and **must survive provider blips**, this is the right tool. If a human is watching a streaming chat, Vercel's SDK is the right tool. Both can coexist in the same app.
+
+## Picking a backend
+
+The runtime picks a backend from `options.model` + `options.executionMode`:
+
+| `model.sdk` | `executionMode` | Backend |
+|---|---|---|
+| `"claude"` | `"sdk"` (or omitted) | Claude SDK |
+| `"claude"` | `"cli"` | `claude` CLI |
+| `"pi"` | any | Pi SDK |
+| `"codex"` | `"cli"` | Codex app-server CLI |
+
+A `model` reference can be the parsed shape `{ sdk, model, provider? }` or a string (`"pi:openai:gpt-5.5"`, `"claude:claude-sonnet-4-6"`, etc.) that you parse with the package's `parseRuntimeModelReference` helper.
+
+## `createRuntime(host)`
+
+Pass host-level integration once at boot. All keys are optional.
+
+```js
+createRuntime({
+  // -- host callbacks --
+  resolveCustomPricing,    // (parsed) => NormalizedPricing | null
+  resolvePiApiKey,         // async (provider) => string | undefined
+  persistArtifact,         // ({ filename, buffer, toolName, toolUseId }) => path | null
+  onCompactionRecorded,    // (compactionRow) => void
+
+  // -- tool runtime context (process-level config for the tool kernel) --
+  workspace,               // primary allowed root for path-based tools
+  repoRoot,                // secondary allowed root
+  ripgrepPath,             // explicit path to `rg`; falls back to vendored binary, then PATH
+  qaOutputDir,             // fallback dir for Playwright MCP filename routing
+  sandboxPolicy,           // optional @mono-agent/sandbox policy for tools and stdio MCP
+
+  // -- observers (multi-subscriber telemetry) --
+  // Optional. Each observer receives every event the runtime emits.
+  // Built-in createMetricsObserver() aggregates cost, cache hit rate, token
+  // counts, tool-call counts, errors, and turn-latency percentiles.
+  observers: [],
+
+  // -- approval gates (HITL) --
+  // Optional. When set, the runtime asks the host before every tool call
+  // whose risk tier is "medium" or "high" (and not session-allowlisted).
+  // See the "Approval gates" section below for the request/response shape.
+  onToolApprovalRequest,           // async (req) => { decision, reason? }
+  toolRiskTiers: { Bash: "high" }, // per-tool tier override (low|medium|high)
+  approvalDefaultRiskTier: "medium",
+  approvalTimeoutMs: 60_000,       // timeout → auto-deny
+  approvalAlwaysAllowTools: [],    // start with these in session allowlist
+
+  // -- host-customisable identity strings (all optional, defaults shown) --
+  runtimeBrand: {
+    schemaPrefix: "agent_runtime", // prefix for snapshot/result schema ids
+    mcpClientName: "agent-runtime", // MCP client name reported to MCP servers
+    mcpClientVersion: "0.1.0",     // MCP client version
+    tempdirPrefix: "agent-runtime-cli-", // mkdtemp prefix for CLI provider scratch dirs
+    providerModelPrefix: "agent",  // id prefix for custom Pi providers
+    doctorCommand: "agent-runtime doctor", // command suggested in tool error messages
+    serviceName: "agent-runtime",  // Codex app-server serviceName
+    clientInfoName: "agent-runtime", // Codex app-server clientInfo.name
+    clientInfoTitle: "Agent Runtime", // Codex app-server clientInfo.title
+  },
+});
+```
+
+`runtimeBrand` lets an external host reskin the package without forking string-by-string.
+
+For Pi OAuth providers such as `openai-codex`, hosts can bind the standard Pi
+auth JSON file with `createPiOAuthApiKeyResolver()`:
+
+```js
+import { createPiOAuthApiKeyResolver, createRuntime } from "@mono-agent/agent-runtime";
+
+const runtime = createRuntime({
+  resolvePiApiKey: createPiOAuthApiKeyResolver({
+    path: `${process.env.HOME}/.pi/agent/auth.json`,
+  }),
+});
+```
+
+The resolver reads provider credentials from the configured file, delegates token
+refresh to `@earendil-works/pi-ai/oauth`, and writes refreshed credentials back
+with `0600` permissions.
+
+Returns:
+
+- `run(systemPrompt, options)` — async, runs one agent turn against the chosen backend.
+- `configureTools(next)` — update the tool runtime context after construction.
+
+### `runtime.run(systemPrompt, options)`
+
+Per-call options (a non-exhaustive selection):
+
+| Option | Type | Notes |
+|---|---|---|
+| `model` | `object \| string` | **Required.** See "Picking a backend". |
+| `executionMode` | `"sdk" \| "cli"` | Default `"sdk"`. |
+| `messages` | `Message[]` | Conversation history. |
+| `cwd` | `string` | Working directory for the agent's tools. |
+| `allowedTools` | `string[]` | Built-in tool allowlist. Default: all. |
+| `disallowedTools` | `string[]` | Block list. |
+| `mcpServers` | `Record<string, McpServerConfig>` | Configured MCP servers (stdio / sse / http). |
+| `sandboxPolicy` | `SandboxPolicy` | Optional fail-closed sandbox policy for built-in tools and stdio MCP process startup. |
+| `maxTurns` | `number` | Hard cap on agent turns. |
+| `outputSchema` | `JSONSchema` | If set, the agent is asked to produce structured JSON matching this schema. The result lands in `result.structuredResult`. |
+| `abortSignal` | `AbortSignal` | Cancel the run. |
+| `liveInput` | `LiveInputQueue` | Stream of in-flight user messages (for human-in-the-loop steering). |
+| `onEvent` | `(event) => void` | Fired for every event the provider emits (assistant text, tool calls/results, runtime warnings, structured output). |
+| `runId` | `string` | Tag this run for downstream callbacks (e.g. `onCompactionRecorded`). |
+| `providerSessionId` | `string` | Resume a prior provider session. |
+| `runArtifactDir` | `string` | Used by some providers as the Playwright MCP filename target. |
+| `piCodexTransport` | `string` | Forwarded to Pi when running OpenAI Codex models. |
+| `codexAppServerCommand` | `string` | Override the Codex CLI binary. |
+| `codexAppServerArgs` | `string[]` | Override the Codex CLI arguments. |
+
+Returns:
+
+```ts
+{
+  text: string,                     // raw assistant text
+  structuredResult?: any,           // JSON returned via outputSchema (if any)
+  structuredResultSource?: string,  // where structuredResult came from
+  events: RuntimeEvent[],           // full event stream (for host-side parsing)
+  usage: {
+    input_tokens, output_tokens,
+    cache_read_tokens, cache_creation_tokens,
+    cost_usd,
+  },
+  durationMs: number,
+  numTurns: number,
+  model: string,
+  effort: string,
+  sdk: "claude" | "pi" | "codex",
+  cancelled: boolean,
+  error: string | null,
+  errorDetails: object | null,
+  failureKind: string | null,
+  providerSessionId: string | null,
+  runtimeWarnings: RuntimeWarning[],
+  diagnostics: object,
+  capabilitiesUsed: {                  // what the backend actually did this call
+    prompt_cache_active: true|false|null,
+    thinking_enabled: true|false|null,
+    structured_output_enforced: boolean,
+    subagent_invoked: true|false|null,
+    mcp_servers_used: string[],
+    native_subagents_used: string[],
+    tool_compaction_applied: boolean,
+    context_compaction_applied: true|false|null,
+  },
+}
+```
+
+`capabilitiesUsed` is the per-call complement to `runtimeCapabilities()`. Tristate fields use `null` to mean "this provider can't tell" — distinct from `false` ("definitely off"). It's also emitted as a `capabilities_resolved` event near the end of the run, so observers can capture it without inspecting the result object.
+
+## Built-in tools
+
+The agent kernel ships with: `Read`, `Write`, `Edit`, `Glob`, `Grep`, `Bash`, `WebFetch`, `WebSearch`. You select via `allowedTools`. Tool implementations honor:
+
+- `cwd` (required for path-based tools)
+- The runtime context's `workspace` / `repoRoot` allow-list (paths outside both, plus `/tmp` and `process.cwd()`, are rejected)
+- Output truncation with optional artifact persistence (`{toolArtifactDir}/tool-output/{runId}/...` when `toolArtifactDir` is configured)
+
+Override or extend the tool surface by passing `mcpServers` for MCP-backed tools.
+
+## Structured output
+
+Pass `options.outputSchema` (a JSON Schema). On Claude SDK / Codex app-server / Pi SDK, the runtime wires the schema into the provider's structured-output API. The matched JSON lands in `result.structuredResult`.
+
+The package does **not** validate `structuredResult` against your schema — it only forwards what the provider produced. Hosts run their own validation (Zod, AJV, etc.).
+
+## Provider fallback router
+
+`createRouterRuntime({ host, chain })` wraps the standard runtime with an ordered chain of model references. On a retryable provider failure (rate limit, overload, network blip — classified via the same taxonomy as `retryableProviderFailureInfo`), it retries the same logical run against the next chain entry, replaying the transcript-tail snapshot of the previous attempt so the next provider continues rather than starts over.
+
+```js
+import { createRouterRuntime } from "@mono-agent/agent-runtime";
+
+const router = createRouterRuntime({
+  host: { /* same shape as createRuntime */ },
+  chain: [
+    { sdk: "claude", model: "claude-opus-4-7" },
+    { sdk: "claude", model: "claude-sonnet-4-6" },
+    { model: { sdk: "pi", provider: "openai", model: "gpt-5.5" }, requires: { structured_output: true } },
+  ],
+});
+
+const result = await router.run("...", { /* same shape as runtime.run */ });
+console.log(result.failoverHistory);
+// [{ model, failureKind, requestId, retryableSubkind }, ...]  one entry per attempt that didn't succeed.
+```
+
+Behaviour:
+
+- Successful run on entry N → returns the result with `failoverHistory` set to attempts 0..N-1.
+- Retryable failure → emits `provider_failover_started`, builds a transcript snapshot, and retries on the next entry.
+- Non-retryable failure (auth, billing, invalid request) → returns immediately with `failoverHistory` containing the one attempt.
+- Cancellation → returns immediately.
+- Chain exhausted → `failureKind: "provider_unavailable_exhausted"`, `failoverHistory` lists every attempt.
+
+Chain entries can require backend capabilities via `requires: { structured_output: true, supports_mcp: true, ... }`; entries that don't satisfy the requirements are skipped (logged in `failoverHistory` as `failureKind: "skipped_capability_mismatch"`).
+
+## Observers & metrics
+
+The runtime emits structured events for everything that happens during a run — assistant messages, tool calls, runtime warnings, cache hits/misses, cost updates, provider request start/end, approval lifecycle. Hosts can subscribe via `host.observers[]` (any number) or the simpler `options.onEvent` callback (one subscriber). Both work simultaneously.
+
+A built-in aggregator covers the common metrics:
+
+```js
+import { createRuntime, createMetricsObserver } from "@mono-agent/agent-runtime";
+
+const metrics = createMetricsObserver();
+const runtime = createRuntime({ observers: [metrics] });
+
+await runtime.run("...", { model: { sdk: "claude", model: "claude-sonnet-4-6" } });
+
+console.log(metrics.snapshot());
+// {
+//   events: { total, byType: { tool_use: 5, assistant: 8, ... } },
+//   tokens: { input, output, cacheReadTokens, cacheCreationTokens },
+//   cost: { cumulativeUsd },
+//   cache: { hits, misses, hitRatio, readTokensFromEvents },
+//   tools: { callsByName: { Bash: 3, Read: 2 }, errorsByName: { ... } },
+//   errors: { total, byKind: { provider_unavailable: 1 } },
+//   turns: { count, latencyMsP50, latencyMsP95 },
+//   approvals: { pending, granted, denied },
+// }
+```
+
+Custom observers implement `{ recordEvent(event), recordMetric(metric)?, flush()? }`. Fan-out is synchronous on the hot path; observers that need to do I/O must buffer internally.
+
+Notable new events emitted by the bridges:
+
+- `provider_request_started` / `_completed` — at the boundary of each LLM call (sdk, model, runtime, timestamp, durationMs).
+- `cache_hit` / `cache_miss` — when the provider reports cached / cache-creation input tokens.
+- `cost_accumulated` — running cost in USD with cumulative token breakdown.
+
+## Approval gates (human-in-the-loop)
+
+Pass `onToolApprovalRequest` to gate tool calls behind a runtime approval. The runtime calls your callback once per tool invocation whose risk tier requires it, and pauses the agent until you respond.
+
+```js
+const runtime = createRuntime({
+  toolRiskTiers: { Bash: "high", Read: "low" },
+  async onToolApprovalRequest(req) {
+    // req = { requestId, toolName, toolUseId, argumentsSummary, riskTier, model }
+    // argumentsSummary is already secret-redacted (API keys, Bearer tokens,
+    // and known JSON fields like "api_key" / "password" stripped).
+    if (req.toolName === "Bash" && req.argumentsSummary.includes("rm -rf")) {
+      return { decision: "deny", reason: "destructive" };
+    }
+    return { decision: "approve" };
+  },
+});
+```
+
+Tiers (configurable per tool):
+
+- **low** — auto-approved; the callback is not called.
+- **medium** (default) — calls the host; if no callback is supplied, auto-approves.
+- **high** — calls the host; if no callback is supplied, fails closed (deny).
+
+Responses:
+
+- `{ decision: "approve" }` — allow this call.
+- `{ decision: "deny", reason? }` — block; the agent receives a tool error.
+- `{ decision: "always" }` — allow + session-allowlist for the run.
+
+Backend coverage: Claude SDK (via `canUseTool`) and Pi SDK (via tool dispatch wrapping). Claude CLI and Codex CLI bridge into their backend's own approval models (`permissionMode` / `approvalPolicy`) — per-call runtime gates aren't available there.
+
+Approval lifecycle is observable via `onEvent`:
+
+- `tool_approval_pending` — emitted before calling the host.
+- `tool_approval_granted` — host approved.
+- `tool_approval_denied` — host denied, timed out, threw, or no callback for a high-risk tool.
+
+## Tool-result bloat handling
+
+`@mono-agent/agent-runtime/agent/tool-bloat.js` enforces a 256 KB default cap per `tool_result`. When a payload exceeds the cap, the kernel:
+
+1. Calls your `persistArtifact({ filename, buffer, toolName, toolUseId })` callback (if you supplied one).
+2. Substitutes a compact text reference in the agent's transcript.
+3. Emits a `runtime_warning` with `warning_kind: "tool_payload_truncated"` and the saved-paths array.
+
+Hosts that don't supply `persistArtifact` get the truncation summary but no on-disk capture.
+
+## Context compaction
+
+`@mono-agent/agent-runtime/agent/compaction.js` provides `createAgentCompactionManager(...)` which the Pi SDK provider invokes automatically. Configure via the agent's settings (`agent_compaction_*` keys). When a compaction completes, the kernel hands a structured row to your `onCompactionRecorded(record)` callback so the host can persist it however it likes.
+
+## Advanced exports
+
+The package exposes its inner pieces via subpath imports:
+
+```js
+import { resolveRuntimeBridge, listRuntimeBridges, runtimeCapabilities } from "@mono-agent/agent-runtime/ai/runtime/registry.js";
+import { generateClaudeResponse } from "@mono-agent/agent-runtime/ai/providers/claude-sdk.js";
+import { createAgentCompactionManager, estimateFirstTurnInput } from "@mono-agent/agent-runtime/agent/compaction.js";
+import { configureToolRuntime, readToolRuntime } from "@mono-agent/agent-runtime/agent/tools/shared/runtime-context.js";
+// ...
+```
+
+These are stable but treated as advanced API. Most consumers should reach for `createRuntime` first.
+
+## Example consumer
+
+See [`examples/echo-agent/`](../../examples/echo-agent/) for a runnable consumer that imports `@mono-agent/agent-runtime`, runs a single Claude SDK turn with the Bash tool, and prints the result.
+
+## License
+
+GPL-3.0-only.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@mono-agent/agent-runtime",
+  "version": "0.1.0",
+  "description": "Agent runtime supporting Claude SDK, Claude CLI, Codex CLI, and PI SDK out of the box",
+  "type": "module",
+  "license": "GPL-3.0-only",
+  "keywords": [
+    "ai",
+    "agents",
+    "runtime",
+    "mono-agent"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./ai": "./src/ai/index.js",
+    "./agent": "./src/agent/index.js",
+    "./ai/*": "./src/ai/*",
+    "./agent/*": "./src/agent/*"
+  },
+  "main": "./src/index.js",
+  "files": [
+    "src/**/*.js",
+    "!src/__tests__/**",
+    "ARCHITECTURE.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.1.0",
+    "@earendil-works/pi-agent-core": "^0.79.1",
+    "@earendil-works/pi-ai": "^0.79.1",
+    "@mono-agent/sandbox": "0.1.0",
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@opencode-ai/sdk": "^1.15.13",
+    "zod": "^4.3.6"
+  },
+  "scripts": {
+    "test": "pnpm --filter @mono-agent/sandbox run build && vitest run --passWithNoTests"
+  }
+}

package/src/agent/allowlists.js

@@ -0,0 +1,49 @@
+export const ALLOWLIST_MODE_ALL = "all";
+export const ALLOWLIST_MODE_CUSTOM = "custom";
+
+export function normalizeList(value) {
+  return Array.isArray(value)
+    ? [...new Set(value.filter((entry) => typeof entry === "string" && entry.trim()).map((entry) => entry.trim()))]
+    : [];
+}
+
+export function normalizeAllowlistMode(value) {
+  if (value === ALLOWLIST_MODE_ALL || value === ALLOWLIST_MODE_CUSTOM) return value;
+  throw new Error('allowlist mode must be "all" or "custom"');
+}
+
+export function storedAllowlistMode(value) {
+  return value === ALLOWLIST_MODE_CUSTOM ? ALLOWLIST_MODE_CUSTOM : ALLOWLIST_MODE_ALL;
+}
+
+export function parseStoredAllowlist(value) {
+  try {
+    return normalizeList(JSON.parse(value || "[]"));
+  } catch {
+    return [];
+  }
+}
+
+export function inferAllowlistMode({ mode, list, fallback = ALLOWLIST_MODE_ALL } = {}) {
+  if (mode !== undefined) return normalizeAllowlistMode(mode);
+  return normalizeList(list).length > 0
+    ? ALLOWLIST_MODE_CUSTOM
+    : storedAllowlistMode(fallback);
+}
+
+export function resolveAllowlist({ mode, allowlist, all, getName = (item) => item }) {
+  const normalizedMode = storedAllowlistMode(mode);
+  if (normalizedMode === ALLOWLIST_MODE_ALL) return [...all];
+  const allowed = new Set(normalizeList(allowlist));
+  return all.filter((item) => allowed.has(getName(item)));
+}
+
+export function resolveAllowlistMap({ mode, allowlist, all }) {
+  const normalizedMode = storedAllowlistMode(mode);
+  if (normalizedMode === ALLOWLIST_MODE_ALL) return { ...all };
+  const out = {};
+  for (const name of normalizeList(allowlist)) {
+    if (all[name]) out[name] = all[name];
+  }
+  return out;
+}