@workerdeck/core 0.13.0 → 0.15.0

package/README.md

@@ -88,26 +88,64 @@ supports — no CLI process, no config directory. `createEngineSession()` assemb
 the capability-scoped tool set, and the executor that runs tool calls.
 
 ```ts
+import variant from '@jitl/quickjs-ng-wasmfile-release-asyncify'
+import { loadEngine } from '@workerdeck/sandbox'
 import { createEngineSession, QuickJsExecutor } from '@workerdeck/core'
 
+// Server-side, the WASM guest is loaded once for the process and shared by every
+// session. The variant package is a peer dependency you install yourself — core
+// does not pick one for you, because the browser build and the server build are
+// different artifacts and only you know which side this is.
+const executor = new QuickJsExecutor({ engine: await loadEngine(variant), defaultTimeoutMs: 15_000 })
+
 const runner = createEngineSession({
   config: { ...createSessionRequest, languageModel: anthropic('claude-sonnet-5') },
-  selectExecutor: () => new QuickJsExecutor({ timeoutMs: 15_000 }),
+  selectExecutor: () => executor,
   capabilities: { webFetch: {} },  // backends, not grants
+  seedVfs: { '/README.md': 'scratch space' },
 })
 ```
 
-Two seams matter here:
+Three seams matter here:
 
 - **Capabilities are grants, wired separately from backends.** `createToolContext` builds the tool
   set from what a profile grants (`fs_*`, `eval_script`, `web_search`, `download`, `web_fetch`,
   `deliver_file`) over what the host actually wired. There is no shell and no host filesystem: the
   files a session sees are an in-memory scratch VFS. Every tool is typed `sandboxed` or
   `authoritative`, and only sandboxed calls may leave the server.
-- **`ToolExecutor` decides where code runs.** `QuickJsExecutor` runs it in-process in the
-  [QuickJS guest](https://www.npmjs.com/package/@workerdeck/sandbox); `BrowserBridgeExecutor`
-  ships it to the user's own tab, so client-held documents never reach the server; and
-  `DeferredExecutor` hands the call off to something that will answer later.
+- **Your own tools go in at a stated trust level.** `tools: { name: { tool, trust } }` is the seam
+  for anything that is neither a built-in capability nor MCP. `authoritative` means it runs here
+  with this process's authority and must declare `execute`; `sandboxed` means it rides the executor
+  seam and must *not*. Both contradictions are refused at assembly rather than at runtime, because
+  a sandboxed tool that quietly ran in-process would defeat the only thing sandboxing it was for.
+- **`ToolExecutor` decides where code runs**, and that is a real architectural choice — see below.
+
+### Which executor?
+
+| | `QuickJsExecutor` (in-process) | `BrowserBridgeExecutor` (the tab) | `DeferredExecutor` |
+|---|---|---|---|
+| Runs where | this Node process, WASM guest | the attached client | wherever you send it |
+| Needs a client attached | no | **yes** | no |
+| Data locality | data must reach the server | client-held data never leaves the tab | n/a |
+| Trust | you own both sides | results are **untrusted input** — the sandboxed party answers | depends |
+| Latency | in-process | a WS round trip | unbounded (the session parks) |
+
+The question to ask is **where the data the loop reasons over already lives**:
+
+- In your database or on your disk → in-process. Pushing execution into the tab buys nothing and
+  hands an executor to the party you are sandboxing against.
+- In the user's browser — a document they are editing, a file they dropped, something you would
+  rather not receive at all → the bridge. This is the case it exists for.
+- Somewhere that answers in minutes or hours (a queue, a human, a build) → deferred, and let the
+  session park.
+
+Two constraints that decide it for you regardless: an **unattended job** has no attached client, so
+the bridge is not available to it; and a bridged result is by definition produced by the sandboxed
+party, so nothing authoritative may ever be routed there.
+
+An executor is chosen per *call*, not per session (`selectExecutor` runs at assembly, but a routing
+executor may keep `eval_script` in-process and defer a long-running tool), which is what lets one
+session mix all three.
 
 ## Work that outlives the runner
 
@@ -127,6 +165,36 @@ selectExecutor: () => new DeferredExecutor({
 for you — a `SessionStore` plus `POST /executions/:id/result` — but the mechanism is here, and works
 with no server at all.
 
+## Rules you cannot infer from the types
+
+Things the compiler will not tell you, each of which has cost someone real time:
+
+- **A declared MCP server that never connected is refused, not degraded.** If a profile's
+  `session.mcpServers` names a server and it isn't there, `createEngineSession` throws. The old
+  behaviour — start anyway, minus those tools — produced a session that reported perfectly healthy
+  while the agent apologised its way through every request that needed it. Pass
+  `connectMcpTools(servers, { required: true })` to fail at connect time instead, and hand the
+  resulting connection over as `mcp` (not just `mcp.tools`) so the check is exact.
+- **A stateless MCP server must answer `GET` with 405.** The client opens the SSE stream with a
+  `GET` before it sends anything. Mounted under a framework's default 404, the whole connect fails
+  with an error that names neither the method nor the route.
+- **Never seed the VFS by hand on a restore.** Use `seedVfs`, which is ignored when
+  `config.restore` is set. Building `config.vfs` yourself still works and still wins — and then
+  overwriting the files the parked turn wrote is yours to avoid.
+- **Forward the host's `id`.** `createEngineSession({ id })` is how a session comes back as
+  *itself* across a gateway restart. Dropping it strands every client's route and unread mark, and
+  the rebuild is refused.
+- **`onClose` runs on park as well as close.** Parking releases the same resources; a disposer that
+  assumes the session is over will close an MCP connection the woken session still needs to rebuild.
+- **Authoritative tools are never bridged.** `withMcpTools` marks everything authoritative by
+  construction. If you want a host tool the tab may run, declare it `sandboxed` in `tools` — and
+  then treat its results as untrusted input, because the tab produced them.
+- **Never make a tool's operation depend on a field being absent.** "Create when `id` is missing,
+  overwrite when it is present" is the shape that breaks: models send `""` — and, observed live,
+  `" "` — rather than omitting, and some providers mark every property required so the model
+  *cannot* omit. `z.string().min(1).optional()` does not save it (a space has length 1). Split it
+  into two tools with required arguments, and trim-and-blank-check optional strings inside `run`.
+
 ## Also exported
 
 `InputQueue` (the push-based `AsyncIterable` bridging `sendMessage()` into the SDK's streaming

package/build/index.d.mts

@@ -1,6 +1,6 @@
 import { McpServerStatus, Options, Query, SDKMessage, SDKUserMessage, SessionMessage } from "@anthropic-ai/claude-agent-sdk";
 import { ApiMessage, CreateSessionRequest, EngineCapabilities, McpServerConfigWire, McpServerStatusInfo, MessageAttachment, ModelOption, PermissionMode, PermissionRequest, ProfileEngine, ProfileInfo, SdkSessionSummary, SessionEvent, SessionEventBody, SessionInfo, SessionStatus, ToolCallRequestFrame, ToolExecutionBackend, ToolExecutionOutput } from "@workerdeck/protocol";
-import { LanguageModel, ModelMessage, Tool, ToolSet } from "ai";
+import { LanguageModel, LanguageModel as LanguageModel$1, ModelMessage, Tool, Tool as Tool$1, ToolSet, ToolSet as ToolSet$1 } from "ai";
 import { SandboxEngine, SandboxVfs } from "@workerdeck/sandbox";
 import { Readable, Writable } from "node:stream";
 
@@ -298,11 +298,11 @@ type AiSdkRunnerConfig = Omit<CreateSessionRequest, 'cwd'> & {
   cwd?: string;
   /** AI SDK language model instance (or gateway model id string). Provider
    * resolution from profiles happens host-side; core takes the resolved model. */
-  languageModel: LanguageModel;
+  languageModel: LanguageModel$1;
   /** Tools available to the loop. Tools WITHOUT `execute` halt the loop when
    * called; their calls surface via `pendingToolCalls` and are answered with
    * `resolveToolCall()`, which re-enters the loop by message-state replay. */
-  tools?: ToolSet; /** System prompt (AI SDK v7 `instructions`). */
+  tools?: ToolSet$1; /** System prompt (AI SDK v7 `instructions`). */
   instructions?: string; /** Max loop steps per turn. Default 20. */
   maxSteps?: number;
   /**
@@ -320,7 +320,19 @@ type AiSdkRunnerConfig = Omit<CreateSessionRequest, 'cwd'> & {
     memoryLimitBytes?: number;
   }; /** Which backend the executor represents, for `execution_dispatched` events. */
   executionBackend?: ToolExecutionBackend; /** Swap models mid-session (`set_model`). Unset = setModel() is rejected. */
-  resolveModel?: (modelId: string | undefined) => LanguageModel;
+  resolveModel?: (modelId: string | undefined) => LanguageModel$1;
+  /**
+   * Live MCP status for this session, when the host wired MCP at all. Unlike
+   * the CLI engines — which ask their binary — this engine's MCP is entirely
+   * host-assembled, so the host is the only party that can answer. Unset means
+   * "no MCP here", which reads as an empty list rather than an error: a session
+   * with no servers is a fact, not a missing feature.
+   *
+   * Named apart from the inherited `mcpServers` request field on purpose —
+   * that one is the *wire configuration* a client asked for, this one is what
+   * the host actually connected.
+   */
+  reportMcpServers?: () => Promise<McpServerStatusInfo[] | undefined>;
   /** Called once when the session closes — release per-session resources the
    * host attached (an MCP connection, a watcher). Errors are swallowed. Also
    * runs when the session parks: parking releases the same resources. */
@@ -451,6 +463,15 @@ declare class AiSdkRunner implements Runner {
    * deferred executor). Idempotent by executionId.
    */
   settleExecution(executionId: string, result: ToolExecutionResult): boolean;
+  /**
+   * This session's MCP servers, as the host assembled them.
+   *
+   * Always answers — an empty list when no MCP was wired — because the
+   * alternative (undefined, which the server turns into a 501) says "this
+   * engine cannot tell you", and this engine can: the host that built the
+   * session is the only party who knows, and it has been asked.
+   */
+  mcpServers(): Promise<McpServerStatusInfo[] | undefined>;
   /** Host-facing rename: writes `meta.title`, which `#title()` prefers. Clearing
    * it (undefined) restores the derived title. The engine is never told. */
   setTitle(title: string | undefined): void;
@@ -755,7 +776,7 @@ type ToolDefinition = {
   trust: ToolTrust;
   /** The AI SDK tool. Sandboxed tools are declared WITHOUT `execute` so the loop
    * hands them to the ToolExecutor seam rather than running them inline. */
-  tool: Tool;
+  tool: Tool$1;
 };
 type ToolContextOptions = {
   /** Executor for sandboxed tools. Selected per call by the host (browser bridge
@@ -795,7 +816,7 @@ type ToolContextOptions = {
 /** Everything a session's tools need, plus the tool set to hand the runner. */
 type ToolContext = {
   vfs: SandboxVfs;
-  tools: ToolSet;
+  tools: ToolSet$1;
   definitions: ToolDefinition[]; /** Names the loop must not execute inline (they go through the executor). */
   sandboxedToolNames: string[];
 };
@@ -811,7 +832,36 @@ type ToolContext = {
 declare function createToolContext(options: ToolContextOptions): ToolContext;
 /** Add host-side MCP tools to a context. They are ALWAYS authoritative: they run
  * server-side with server credentials, and must never be handed to a browser. */
-declare function withMcpTools(context: ToolContext, mcpTools: ToolSet): ToolContext;
+declare function withMcpTools(context: ToolContext, mcpTools: ToolSet$1): ToolContext;
+/** A tool the host supplies, with the trust level it is to run at. */
+type HostToolDefinition = {
+  tool: Tool$1;
+  /**
+   * Where this tool may run. `authoritative` tools execute inline in the
+   * gateway and MUST declare `execute`; `sandboxed` ones must NOT, because the
+   * loop hands them to the {@link ToolExecutor} seam instead — which is what
+   * makes them bridgeable to an untrusted tab.
+   */
+  trust: ToolTrust;
+};
+/**
+ * Add host-supplied tools to a context at an explicit trust level.
+ *
+ * The trust level is the whole point of the seam: {@link withMcpTools} can only
+ * produce authoritative tools, so a host tool that *should* be sandboxed — and
+ * therefore executable in the browser tab that asked for it — had no way to be
+ * expressed at all. Here the host says which it is, and the contradictions are
+ * refused rather than silently resolved:
+ *
+ * - a `sandboxed` tool carrying `execute` would run inline in this process with
+ *   the gateway's ambient authority, which is exactly what sandboxing it was
+ *   meant to prevent;
+ * - an `authoritative` tool *without* `execute` would park the turn on a call no
+ *   executor claims, and the session would simply stop.
+ */
+declare function withHostTools(context: ToolContext, hostTools: Record<string, HostToolDefinition>, /** What to call these in error messages ('MCP tool', 'host tool'). */
+
+kind?: string): ToolContext;
 //#endregion
 //#region src/engine.d.ts
 type EngineSessionOptions = {
@@ -822,7 +872,7 @@ type EngineSessionOptions = {
    * this so core never imports a provider SDK and never reads credentials —
    * they come from the operator's environment, exactly like the Claude chain.
    */
-  resolveModel: (profile: ProfileInfo | undefined, config: AiSdkRunnerConfig) => LanguageModel;
+  resolveModel: (profile: ProfileInfo | undefined, config: AiSdkRunnerConfig) => LanguageModel$1;
   /**
    * Executor for sandboxed tools. Return the browser bridge when a client is
    * attached and the server sandbox otherwise; the seam makes them
@@ -849,10 +899,38 @@ type EngineSessionOptions = {
      * Default true — set false to withhold it. */
     deliverFiles?: boolean;
   };
+  /**
+   * A live MCP connection from {@link connectMcpTools} — the preferred way to
+   * hand MCP to a session, and the only one that can fail loudly.
+   *
+   * With this set, the session knows *which servers connected*, so two things
+   * that were previously silent become impossible: a profile naming a server
+   * that never connected refuses to build (see {@link mcpTools} for what that
+   * used to look like), and `runner.mcpServers()` answers `GET
+   * /sessions/:id/mcp` with the real per-server status instead of 501.
+   */
+  mcp?: McpConnection;
   /** Authoritative tools that run server-side with server credentials (MCP).
    * Never bridged to a client. Namespaced `<server>__<tool>` by
-   * {@link connectMcpTools}, which is how a profile grants servers by name. */
-  mcpTools?: ToolSet;
+   * {@link connectMcpTools}, which is how a profile grants servers by name.
+   *
+   * The bare tool set, for a host assembling one itself. Prefer {@link mcp}:
+   * a tool set alone cannot distinguish "this server connected and exposes no
+   * tools" from "this server never connected", so the check here has to be the
+   * cruder one — a declared server contributing no tools is refused. */
+  mcpTools?: ToolSet$1;
+  /**
+   * Extra host tools, each at an explicit trust level (see
+   * {@link withHostTools}). This is the seam for a tool that is neither one of
+   * the built-in capabilities nor MCP — including a **sandboxed** one, which
+   * `mcpTools` cannot express because everything in it is authoritative by
+   * construction.
+   *
+   * A sandboxed tool here rides the same {@link ToolExecutor} seam
+   * `eval_script` does, so it executes wherever `selectExecutor` points — an
+   * in-process QuickJS guest, or the browser tab that asked the question.
+   */
+  tools?: Record<string, HostToolDefinition>;
   /** Extra instructions prepended to the session's system prompt. Overridden by
    * the profile's `session.instructions` when it declares one. */
   instructions?: string;
@@ -860,6 +938,26 @@ type EngineSessionOptions = {
     timeoutMs?: number;
     memoryLimitBytes?: number;
   };
+  /**
+   * Initial scratch-filesystem contents for a **new** session, and the safe way
+   * to seed one: it is ignored outright when `config.restore` is set, because a
+   * rehydrated session brings back the files its parked turn already wrote and
+   * seeding over them destroys exactly the work that was preserved.
+   *
+   * (Hand-building `config.vfs` still works and still wins — but then the
+   * `restore ? undefined : createVfs(...)` dance is yours to get right.)
+   */
+  seedVfs?: Record<string, string>;
+  /**
+   * Build the session under this id rather than minting one.
+   *
+   * Forward the server's `EngineRunnerContext.id` here, always: it is set when
+   * the gateway is rehydrating a session across a restart, and a runner that
+   * ignores it comes back as a *different* session — the rebuild is refused,
+   * and every client's route and unread watermark is stranded. Ignored when
+   * `config.restore` is present, which carries its own id.
+   */
+  id?: string;
 };
 /**
  * Assemble a model-agnostic session: provider model, capability-scoped tools,
@@ -875,7 +973,14 @@ type EngineSessionOptions = {
  */
 declare function createEngineSession(options: EngineSessionOptions): AiSdkRunner;
 type McpConnection = {
-  tools: ToolSet;
+  tools: ToolSet$1;
+  /**
+   * One entry per configured server, connected or not — the truth a session was
+   * assembled against. Handed to {@link createEngineSession} as `mcp`, it is
+   * what `GET /sessions/:id/mcp` answers with and what makes a half-connected
+   * session refuse to build rather than run degraded.
+   */
+  servers: McpServerStatusInfo[];
   close: () => Promise<void>;
 };
 /**
@@ -884,14 +989,29 @@ type McpConnection = {
  * Server-side only, with server credentials: these tools are authoritative and
  * must never be bridged to a browser. `@ai-sdk/mcp` is imported lazily and is an
  * optional dependency — an operator who wires no MCP servers never needs it.
+ *
+ * **A stateless MCP server must answer `GET` with 405.** The client opens the
+ * SSE stream with a `GET` before it sends anything, and a POST-only server
+ * mounted under a framework's default 404 makes the whole connect fail with an
+ * error that names neither the method nor the route. This is the single most
+ * common way an otherwise-correct MCP mount fails.
  */
-declare function connectMcpTools(servers: Record<string, McpServerConfigWire>,
-/** `onError` may fire more than once for a single server: transport-level
- * failures surface through the client's own uncaught-error channel as well as
- * the connect failure. Treat it as a report, not a count. */
-
-options?: {
+declare function connectMcpTools(servers: Record<string, McpServerConfigWire>, options?: {
+  /** `onError` may fire more than once for a single server: transport-level
+   * failures surface through the client's own uncaught-error channel as well as
+   * the connect failure. Treat it as a report, not a count. */
   onError?: (name: string, error: unknown) => void;
+  /**
+   * Reject if any server fails to connect, after closing the ones that did.
+   *
+   * Off by default, which is right for an operator's fleet — one unreachable
+   * server should not take a whole gateway's sessions down. Turn it **on**
+   * when the servers are the app's own: an embedder who mounts one wiki server
+   * and gets a session without it has a session that cannot do its job, and
+   * finding that out at connect time beats finding it out from a transcript
+   * where the agent apologises.
+   */
+  required?: boolean;
 }): Promise<McpConnection>;
 //#endregion
 //#region src/input-queue.d.ts
@@ -969,6 +1089,15 @@ type EngineRunnerRequest = {
   /** Rebuild a parked session instead of starting fresh. Engines that cannot
    * rehydrate throw. */
   restore?: RunnerSnapshot;
+  /**
+   * Adopt this session id instead of minting one. For rehydrating a session
+   * across a gateway restart: the transcript comes back from the *engine's* own
+   * store via `config.resume`, but every client keys its watermarks, unread
+   * counts and routes on the WorkerDeck id, so that id has to survive too
+   * (`SessionInfo.id` is documented as stable across resumes). A `restore`
+   * carries its own id in the snapshot and does not need this.
+   */
+  id?: string;
 };
 /**
  * One engine, as the server consumes it: its capability record, its shipped
@@ -1463,5 +1592,5 @@ declare class JsonRpcStdioConnection {
  */
 declare const providerAdapter: EngineAdapter;
 //#endregion
-export { AiSdkRunner, type AiSdkRunnerConfig, type AiSdkSessionState, type AppServerConnectFn, type AppServerConnectOptions, type AppServerConnection, type AppServerHistoryTurn, type AppServerItem, type AppServerThreadListResponse, type AppServerThreadSummary, type AppServerTokenUsage, type AppServerTurn, type AppServerUserInput, type AttachmentInput, type AttachmentKind, type BridgeAnswer, BrowserBridgeExecutor, type BrowserBridgeExecutorOptions, CLAUDE_CATALOG, CODEX_CATALOG, type ClaudeAuthProbe, type ClaudeAuthStatus, CodexRunner, type CodexRunnerConfig, type DeferredDispatch, DeferredExecutor, type DeferredExecutorOptions, type EngineAdapter, type EngineAvailability, type EngineRunnerRequest, type EngineSessionOptions, type HistoryFn, type HostFetch, InputQueue, JsonRpcError, JsonRpcStdioConnection, type McpConnection, type ModelCatalog, type ParkedExecution, type PendingEntry, type PendingKind, type PendingOutcome, PendingRequestRegistry, type PendingToolCall, type PermissionDecision, type QueryFn, QuickJsExecutor, type QuickJsExecutorOptions, type RegisterOptions, type Runner, type RunnerSnapshot, SUPPORTED_ATTACHMENT_TYPES, type SessionEventListener, SessionRunner, type SessionRunnerConfig, type SettledBy, type ToolCallOutput, type ToolContext, type ToolContextOptions, type ToolDefinition, type ToolExecutionCall, type ToolExecutionDispatch, type ToolExecutionResult, type ToolExecutor, type ToolTrust, type WebFetchDigest, type WebFetchFn, type WebFetchOptions, type WebFetchResult, attachmentContentBlocks, attachmentKind, attachmentRef, checkClaudeAuth, claudeAdapter, codexAdapter, connectAppServer, connectMcpTools, createEngineSession, createToolContext, createWebFetch, getEngineAdapter, htmlToMarkdown, isHostAllowed, isPrivateAddress, listCodexSessions, mcpStatusInfo, modelOptionsFromSdk, normalizeMediaType, normalizeSdkMessage, providerAdapter, resolveBundledClaudeExecutable, resolveBundledCodexExecutable, toApiMessage, toExecutionResult, withMcpTools };
+export { AiSdkRunner, type AiSdkRunnerConfig, type AiSdkSessionState, type AppServerConnectFn, type AppServerConnectOptions, type AppServerConnection, type AppServerHistoryTurn, type AppServerItem, type AppServerThreadListResponse, type AppServerThreadSummary, type AppServerTokenUsage, type AppServerTurn, type AppServerUserInput, type AttachmentInput, type AttachmentKind, type BridgeAnswer, BrowserBridgeExecutor, type BrowserBridgeExecutorOptions, CLAUDE_CATALOG, CODEX_CATALOG, type ClaudeAuthProbe, type ClaudeAuthStatus, CodexRunner, type CodexRunnerConfig, type DeferredDispatch, DeferredExecutor, type DeferredExecutorOptions, type EngineAdapter, type EngineAvailability, type EngineRunnerRequest, type EngineSessionOptions, type HistoryFn, type HostFetch, type HostToolDefinition, InputQueue, JsonRpcError, JsonRpcStdioConnection, type LanguageModel, type McpConnection, type ModelCatalog, type ParkedExecution, type PendingEntry, type PendingKind, type PendingOutcome, PendingRequestRegistry, type PendingToolCall, type PermissionDecision, type QueryFn, QuickJsExecutor, type QuickJsExecutorOptions, type RegisterOptions, type Runner, type RunnerSnapshot, SUPPORTED_ATTACHMENT_TYPES, type SessionEventListener, SessionRunner, type SessionRunnerConfig, type SettledBy, type Tool, type ToolCallOutput, type ToolContext, type ToolContextOptions, type ToolDefinition, type ToolExecutionCall, type ToolExecutionDispatch, type ToolExecutionResult, type ToolExecutor, type ToolSet, type ToolTrust, type WebFetchDigest, type WebFetchFn, type WebFetchOptions, type WebFetchResult, attachmentContentBlocks, attachmentKind, attachmentRef, checkClaudeAuth, claudeAdapter, codexAdapter, connectAppServer, connectMcpTools, createEngineSession, createToolContext, createWebFetch, getEngineAdapter, htmlToMarkdown, isHostAllowed, isPrivateAddress, listCodexSessions, mcpStatusInfo, modelOptionsFromSdk, normalizeMediaType, normalizeSdkMessage, providerAdapter, resolveBundledClaudeExecutable, resolveBundledCodexExecutable, toApiMessage, toExecutionResult, withHostTools, withMcpTools };
 //# sourceMappingURL=index.d.mts.map