la-machina-engine 0.3.0 → 0.4.0

package/dist/index.js

@@ -24,23 +24,23 @@ var init_esm_shims = __esm({
 });
 
 // src/orchestrator/types.ts
-import { z as z23 } from "zod";
+import { z as z25 } from "zod";
 var PlanStepSchema, PlanSchema;
 var init_types = __esm({
   "src/orchestrator/types.ts"() {
     "use strict";
     init_esm_shims();
-    PlanStepSchema = z23.object({
-      id: z23.string().min(1),
-      description: z23.string().min(1),
-      action: z23.enum(["research", "implement", "verify", "review", "custom"]),
-      files: z23.array(z23.string()).optional(),
-      spec: z23.string().optional(),
-      dependsOn: z23.array(z23.string()).optional()
+    PlanStepSchema = z25.object({
+      id: z25.string().min(1),
+      description: z25.string().min(1),
+      action: z25.enum(["research", "implement", "verify", "review", "custom"]),
+      files: z25.array(z25.string()).optional(),
+      spec: z25.string().optional(),
+      dependsOn: z25.array(z25.string()).optional()
     });
-    PlanSchema = z23.object({
-      summary: z23.string().min(1),
-      steps: z23.array(PlanStepSchema).min(1)
+    PlanSchema = z25.object({
+      summary: z25.string().min(1),
+      steps: z25.array(PlanStepSchema).min(1)
     });
   }
 });
@@ -1014,6 +1014,42 @@ var LoggingConfigResolved = z.object({
   level: LogLevelEnum,
   sink: LogSinkSchema
 }).strict();
+var ApiHttpMethodEnum = z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]);
+var ApiAuthSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("none") }).strict(),
+  z.object({ type: z.literal("bearer"), tokenRef: z.string().min(1) }).strict(),
+  z.object({
+    type: z.literal("header"),
+    name: z.string().min(1),
+    valueRef: z.string().min(1)
+  }).strict(),
+  z.object({
+    type: z.literal("basic"),
+    userRef: z.string().min(1),
+    passRef: z.string().min(1)
+  }).strict(),
+  z.object({ type: z.literal("custom"), id: z.string().min(1) }).strict()
+]);
+var ApiServiceSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().optional(),
+  baseUrl: z.string().url(),
+  auth: ApiAuthSchema.optional(),
+  // Allow both strings and RegExp values via z.union — RegExp is
+  // serialized as its source when cloned, so we accept both.
+  allowedPaths: z.array(z.union([z.string(), z.instanceof(RegExp)])).optional(),
+  allowedMethods: z.array(ApiHttpMethodEnum).optional(),
+  defaultHeaders: z.record(z.string(), z.string()).optional(),
+  maxBodyBytes: z.number().int().positive().optional()
+}).strict();
+var ApiConfigResolved = z.object({
+  services: z.array(ApiServiceSchema),
+  maxResponseBytes: z.number().int().positive().optional()
+}).strict();
+var RunnerConfigResolved = z.object({
+  url: z.string().url(),
+  secret: z.string().min(1, "runner.secret cannot be empty")
+}).strict();
 var ResolvedConfigSchema = z.object({
   model: ModelConfigResolved,
   storage: StorageConfigResolved,
@@ -1029,7 +1065,9 @@ var ResolvedConfigSchema = z.object({
   permissions: PermissionsConfigResolved,
   compaction: CompactionConfigResolved,
   coordinator: CoordinatorConfigResolved,
-  orchestrator: OrchestratorConfigResolved
+  orchestrator: OrchestratorConfigResolved,
+  runner: RunnerConfigResolved.optional(),
+  api: ApiConfigResolved.optional()
 }).strict();
 var R2ConfigUser = R2ConfigResolved.partial();
 var ModelConfigUser = ModelConfigResolved.partial();
@@ -1070,6 +1108,8 @@ var McpConfigUser = z.object({
   shutdownTimeoutMs: z.number().int().positive().optional()
 }).strict();
 var PermissionsConfigUser = PermissionsConfigResolved.partial();
+var RunnerConfigUser = RunnerConfigResolved;
+var ApiConfigUser = ApiConfigResolved.partial();
 var CompactionConfigUser = CompactionConfigResolved.partial();
 var CoordinatorConfigUser = CoordinatorConfigResolved.partial();
 var OrchestratorConfigUser = OrchestratorConfigResolved.deepPartial();
@@ -1088,7 +1128,9 @@ var UserConfigSchema = z.object({
   permissions: PermissionsConfigUser.optional(),
   compaction: CompactionConfigUser.optional(),
   coordinator: CoordinatorConfigUser.optional(),
-  orchestrator: OrchestratorConfigUser.optional()
+  orchestrator: OrchestratorConfigUser.optional(),
+  runner: RunnerConfigUser.optional(),
+  api: ApiConfigUser.optional()
 }).strict();
 
 // src/config/merge.ts
@@ -1133,10 +1175,36 @@ function deepMerge(base, override) {
   }
   return result;
 }
+var API_RUNTIME_KEYS = ["env", "resolveAuth", "onRequest", "onResponse"];
+function splitApiRuntime(user) {
+  const api = user.api;
+  if (api === void 0) return { stripped: user, runtime: {} };
+  const runtime = {};
+  const schemaSafe = {};
+  for (const [k, v] of Object.entries(api)) {
+    if (API_RUNTIME_KEYS.includes(k)) {
+      runtime[k] = v;
+    } else {
+      schemaSafe[k] = v;
+    }
+  }
+  const clone = { ...user, api: schemaSafe };
+  return { stripped: clone, runtime };
+}
 function mergeConfig(user) {
-  const validatedUser = UserConfigSchema.parse(user);
+  const { stripped, runtime } = splitApiRuntime(user);
+  const validatedUser = UserConfigSchema.parse(stripped);
   const merged = deepMerge(DEFAULTS, validatedUser);
-  return ResolvedConfigSchema.parse(merged);
+  const resolved = ResolvedConfigSchema.parse(merged);
+  if (resolved.api !== void 0 && Object.keys(runtime).length > 0) {
+    const mutableResolved = resolved;
+    mutableResolved.api = {
+      ...resolved.api,
+      ...runtime
+    };
+  } else if (Object.keys(runtime).length > 0) {
+  }
+  return resolved;
 }
 
 // src/engine/engine.ts
@@ -1585,8 +1653,8 @@ function toAISdkMessages(messages) {
           textParts.push({ type: "text", text: block.text });
         }
       }
-      if (textParts.length > 0) out.push({ role: "user", content: textParts });
       if (toolResults.length > 0) out.push({ role: "tool", content: toolResults });
+      if (textParts.length > 0) out.push({ role: "user", content: textParts });
     } else if (role === "assistant") {
       if (typeof content === "string") {
         out.push({ role: "assistant", content });
@@ -1784,6 +1852,68 @@ function hasProcessLifecycle() {
   return typeof process !== "undefined" && typeof process.on === "function" && typeof process.removeListener === "function" && detectRuntime() === "node";
 }
 
+// src/tools/capabilityStub.ts
+init_esm_shims();
+import { z as z2 } from "zod";
+
+// src/tools/contract.ts
+init_esm_shims();
+function defineTool(tool) {
+  return tool;
+}
+var ToolRegistry = class {
+  tools = /* @__PURE__ */ new Map();
+  register(tool) {
+    if (typeof tool.name !== "string" || tool.name.length === 0) {
+      throw new Error("ToolRegistry: tool.name must be a non-empty string");
+    }
+    if (this.tools.has(tool.name)) {
+      throw new Error(`ToolRegistry: "${tool.name}" is already registered`);
+    }
+    this.tools.set(tool.name, tool);
+  }
+  registerAll(tools) {
+    for (const tool of tools) this.register(tool);
+  }
+  unregister(name) {
+    this.tools.delete(name);
+  }
+  get(name) {
+    return this.tools.get(name);
+  }
+  has(name) {
+    return this.tools.has(name);
+  }
+  list() {
+    return Array.from(this.tools.values());
+  }
+  count() {
+    return this.tools.size;
+  }
+};
+
+// src/tools/capabilityStub.ts
+var anyInput = z2.unknown();
+function capabilityStub(original) {
+  return defineTool({
+    name: original.name,
+    description: original.description,
+    inputSchema: anyInput,
+    isCapabilityStub: true,
+    execute: async () => ({
+      isError: true,
+      content: `Tool "${original.name}" requires Node runtime and cannot execute in this environment. To use this tool, run async via engine.start() with config.runner configured so the run can hand off to a Node runner. See README \xA7"Runner contract" for setup.`,
+      metadata: { capabilityMissing: original.name }
+    })
+  });
+}
+function withCapabilityCheck(tool, spawnAvailable) {
+  if (tool.requiresNode === true && !spawnAvailable) {
+    return capabilityStub(tool);
+  }
+  return tool;
+}
+
 // src/subagent/registry.ts
 init_esm_shims();
 
@@ -1966,7 +2096,7 @@ var SubagentRegistry = class _SubagentRegistry {
 
 // src/tools/agent.ts
 init_esm_shims();
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 
 // src/subagent/runner.ts
 init_esm_shims();
@@ -1977,48 +2107,49 @@ import { zodToJsonSchema } from "zod-to-json-schema";
 
 // src/transcript/snapshot.ts
 init_esm_shims();
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 var SNAPSHOT_FILENAME = "snapshot.json";
-var TokenUsageSchema = z2.object({
-  input: z2.number().int().nonnegative(),
-  output: z2.number().int().nonnegative(),
-  cacheCreationInput: z2.number().int().nonnegative().optional(),
-  cacheReadInput: z2.number().int().nonnegative().optional()
+var TokenUsageSchema = z3.object({
+  input: z3.number().int().nonnegative(),
+  output: z3.number().int().nonnegative(),
+  cacheCreationInput: z3.number().int().nonnegative().optional(),
+  cacheReadInput: z3.number().int().nonnegative().optional()
 }).strict();
-var PendingToolCallSchema = z2.object({
-  toolName: z2.string().min(1),
-  toolUseId: z2.string().min(1),
-  input: z2.unknown(),
-  calledAt: z2.string().datetime({ offset: true })
+var PendingToolCallSchema = z3.object({
+  toolName: z3.string().min(1),
+  toolUseId: z3.string().min(1),
+  input: z3.unknown(),
+  calledAt: z3.string().datetime({ offset: true })
 }).strict();
-var PendingSubagentSchema = z2.lazy(
-  () => z2.object({
-    subagentType: z2.string().min(1),
-    parentToolUseId: z2.string().min(1),
+var PendingSubagentSchema = z3.lazy(
+  () => z3.object({
+    subagentType: z3.string().min(1),
+    parentToolUseId: z3.string().min(1),
     childSnapshot: RunSnapshotSchema
   }).strict()
 );
-var RunSnapshotSchema = z2.lazy(
-  () => z2.object({
-    version: z2.literal(1),
-    status: z2.literal("paused"),
-    runId: z2.string().min(1),
-    nodeId: z2.string().min(1),
-    pausedAt: z2.string().datetime({ offset: true }),
-    pauseReason: z2.enum([
+var RunSnapshotSchema = z3.lazy(
+  () => z3.object({
+    version: z3.literal(1),
+    status: z3.literal("paused"),
+    runId: z3.string().min(1),
+    nodeId: z3.string().min(1),
+    pausedAt: z3.string().datetime({ offset: true }),
+    pauseReason: z3.enum([
       "gate_required",
       "subagent_gate_required",
+      "handoff_to_runner",
       "max_turns",
       "explicit",
       "timeout"
     ]),
-    messageCount: z2.number().int().nonnegative(),
-    lastShardIndex: z2.number().int().nonnegative(),
-    lastMessageUuid: z2.string().uuid(),
+    messageCount: z3.number().int().nonnegative(),
+    lastShardIndex: z3.number().int().nonnegative(),
+    lastMessageUuid: z3.string().uuid(),
     pendingToolCall: PendingToolCallSchema.optional(),
     pendingSubagent: PendingSubagentSchema.optional(),
     tokensUsedSoFar: TokenUsageSchema,
-    turnsUsed: z2.number().int().nonnegative()
+    turnsUsed: z3.number().int().nonnegative()
   }).strict()
 );
 function snapshotPath(logPath) {
@@ -2746,6 +2877,27 @@ async function agentLoop(options) {
           }
         }
       }
+      if (options.handoffToRunner === true) {
+        for (const call of toolCallsToDispatch) {
+          const tool = options.registry?.get(call.name);
+          if (tool?.isCapabilityStub === true) {
+            const paused = await pauseHere({
+              ctx,
+              transcript,
+              reason: "handoff_to_runner",
+              pendingToolCall: {
+                toolName: call.name,
+                toolUseId: call.id,
+                input: call.input,
+                calledAt: (/* @__PURE__ */ new Date()).toISOString()
+              },
+              storage: options.storage,
+              subagentRegistry: options.subagentRegistry
+            });
+            return paused;
+          }
+        }
+      }
       const firstTool = toolCallsToDispatch[0]?.name;
       await fireProgress("tool_dispatch", firstTool);
       const streamExec = new StreamingToolExecutor(executor);
@@ -2756,6 +2908,10 @@ async function agentLoop(options) {
       }
       try {
         for await (const { id, result } of streamExec.results()) {
+          const missing = result.metadata?.capabilityMissing;
+          if (typeof missing === "string") {
+            ctx.recordCapabilityMissing(missing);
+          }
           await ctx.addToolResult(id, truncateToolResult(result.content), result.isError === true);
         }
       } catch (err) {
@@ -3014,6 +3170,12 @@ var RunContext = class {
   turnCount = 0;
   tokensUsed = { input: 0, output: 0 };
   lastUuid = null;
+  /**
+   * Plan 019 — names of tools whose capability-stub returned an
+   * `isError` result during this run. Aggregated and surfaced on the
+   * response's `meta.capabilitiesMissing` (deduped, insertion-ordered).
+   */
+  capabilitiesMissing = /* @__PURE__ */ new Set();
   constructor(options) {
     this.runId = options.runId;
     this.nodeId = options.nodeId;
@@ -3054,6 +3216,42 @@ var RunContext = class {
       this.episodes.logTurn(this.turnCount, "assistant", summary);
     }
   }
+  /**
+   * Inject a tool_result + a follow-up text block as a SINGLE user
+   * message. Used by the resume() synthetic-release path when a
+   * paused run is resumed without an explicit `gateAnswer`: we need
+   * to both satisfy the tool_use↔tool_result pairing AND give the
+   * model a retry instruction, in the same user turn.
+   *
+   * Splitting this into `addToolResult(...) + addUserMessage(...)`
+   * produces two consecutive user messages, which the AI SDK's
+   * openai-compatible adapter rejects with
+   * `MissingToolResultsError`. Combining them into one user message
+   * is the portable shape that works on every provider we support.
+   *
+   * Writes a single `user` transcript entry carrying the mixed
+   * content, so `rebuildMessagesFromEntries` reconstructs the same
+   * single-message shape on resume.
+   */
+  async addMixedUserMessage(blocks) {
+    this.messages.push({ role: "user", content: blocks });
+    await this.writeEntry({
+      type: "user",
+      uuid: this.nextUuid(),
+      parentUuid: this.lastUuid,
+      ts: this.now(),
+      message: { role: "user", content: blocks }
+    });
+    const summary = blocks.map((b) => {
+      const x = b;
+      if (x.type === "text") return x.text ?? "";
+      if (x.type === "tool_result") {
+        return typeof x.content === "string" ? x.content : JSON.stringify(x.content);
+      }
+      return "";
+    }).filter((s) => s.length > 0).join("\n");
+    this.episodes?.logTurn(this.turnCount, "user", summary);
+  }
   /**
    * Append a tool result to the conversation. The Anthropic Messages
    * API requires tool_result blocks to be wrapped in a user message,
@@ -3099,6 +3297,14 @@ var RunContext = class {
   getTokensUsed() {
     return this.tokensUsed;
   }
+  /** Plan 019 — record that a capability-stubbed tool fired during this run. */
+  recordCapabilityMissing(toolName) {
+    this.capabilitiesMissing.add(toolName);
+  }
+  /** Plan 019 — capability-stubbed tool names observed this run (deduped). */
+  getCapabilitiesMissing() {
+    return [...this.capabilitiesMissing];
+  }
   shouldContinue() {
     return this.turnCount < this.maxTurns;
   }
@@ -3272,9 +3478,9 @@ init_esm_shims();
 
 // src/transcript/entries.ts
 init_esm_shims();
-import { z as z3 } from "zod";
-var UuidSchema = z3.string().uuid();
-var IsoTsSchema = z3.string().datetime({ offset: true });
+import { z as z4 } from "zod";
+var UuidSchema = z4.string().uuid();
+var IsoTsSchema = z4.string().datetime({ offset: true });
 var TimelineBase = {
   uuid: UuidSchema,
   parentUuid: UuidSchema.nullable(),
@@ -3284,55 +3490,55 @@ var SessionBase = {
   uuid: UuidSchema,
   ts: IsoTsSchema
 };
-var MessageSchema = z3.object({
-  role: z3.enum(["user", "assistant"]),
-  content: z3.array(z3.unknown())
+var MessageSchema = z4.object({
+  role: z4.enum(["user", "assistant"]),
+  content: z4.array(z4.unknown())
 }).strict();
-var UserEntrySchema = z3.object({
-  type: z3.literal("user"),
+var UserEntrySchema = z4.object({
+  type: z4.literal("user"),
   ...TimelineBase,
   message: MessageSchema
 }).strict();
-var AssistantEntrySchema = z3.object({
-  type: z3.literal("assistant"),
+var AssistantEntrySchema = z4.object({
+  type: z4.literal("assistant"),
   ...TimelineBase,
   message: MessageSchema
 }).strict();
-var ToolResultEntrySchema = z3.object({
-  type: z3.literal("tool_result"),
+var ToolResultEntrySchema = z4.object({
+  type: z4.literal("tool_result"),
   ...TimelineBase,
-  toolUseId: z3.string().min(1),
-  content: z3.unknown(),
-  isError: z3.boolean().optional()
+  toolUseId: z4.string().min(1),
+  content: z4.unknown(),
+  isError: z4.boolean().optional()
 }).strict();
-var SubagentSpawnEntrySchema = z3.object({
-  type: z3.literal("subagent_spawn"),
+var SubagentSpawnEntrySchema = z4.object({
+  type: z4.literal("subagent_spawn"),
   ...TimelineBase,
-  agentId: z3.string().min(1),
-  agentType: z3.string().min(1)
+  agentId: z4.string().min(1),
+  agentType: z4.string().min(1)
 }).strict();
-var SubagentDoneEntrySchema = z3.object({
-  type: z3.literal("subagent_done"),
+var SubagentDoneEntrySchema = z4.object({
+  type: z4.literal("subagent_done"),
   ...TimelineBase,
-  agentId: z3.string().min(1),
-  output: z3.string()
+  agentId: z4.string().min(1),
+  output: z4.string()
 }).strict();
-var MetaEntrySchema = z3.object({
-  type: z3.literal("meta"),
+var MetaEntrySchema = z4.object({
+  type: z4.literal("meta"),
   ...SessionBase,
-  key: z3.string().min(1),
-  value: z3.unknown()
+  key: z4.string().min(1),
+  value: z4.unknown()
 }).strict();
-var ErrorEntrySchema = z3.object({
-  type: z3.literal("error"),
+var ErrorEntrySchema = z4.object({
+  type: z4.literal("error"),
   ...SessionBase,
-  error: z3.object({
-    code: z3.string().min(1),
-    message: z3.string(),
-    stack: z3.string().optional()
+  error: z4.object({
+    code: z4.string().min(1),
+    message: z4.string(),
+    stack: z4.string().optional()
   }).strict()
 }).strict();
-var EntrySchema = z3.discriminatedUnion("type", [
+var EntrySchema = z4.discriminatedUnion("type", [
   UserEntrySchema,
   AssistantEntrySchema,
   ToolResultEntrySchema,
@@ -3364,16 +3570,16 @@ function parseEntryLine(line) {
 
 // src/transcript/meta.ts
 init_esm_shims();
-import { z as z4 } from "zod";
-var TranscriptMetaSchema = z4.object({
-  version: z4.literal(1),
-  status: z4.enum(["pending", "running", "paused", "done", "failed"]),
-  startedAt: z4.string().datetime({ offset: true }),
-  updatedAt: z4.string().datetime({ offset: true }),
-  turnCount: z4.number().int().nonnegative(),
-  messageCount: z4.number().int().nonnegative(),
-  lastShardIndex: z4.number().int().nonnegative().nullable(),
-  shardCount: z4.number().int().nonnegative()
+import { z as z5 } from "zod";
+var TranscriptMetaSchema = z5.object({
+  version: z5.literal(1),
+  status: z5.enum(["pending", "running", "paused", "done", "failed"]),
+  startedAt: z5.string().datetime({ offset: true }),
+  updatedAt: z5.string().datetime({ offset: true }),
+  turnCount: z5.number().int().nonnegative(),
+  messageCount: z5.number().int().nonnegative(),
+  lastShardIndex: z5.number().int().nonnegative().nullable(),
+  shardCount: z5.number().int().nonnegative()
 }).strict();
 var META_FILENAME = "meta.json";
 function metaPath(logPath) {
@@ -3721,47 +3927,11 @@ Output format:
 Directive: ${directive}`;
 }
 
-// src/tools/contract.ts
-init_esm_shims();
-function defineTool(tool) {
-  return tool;
-}
-var ToolRegistry = class {
-  tools = /* @__PURE__ */ new Map();
-  register(tool) {
-    if (typeof tool.name !== "string" || tool.name.length === 0) {
-      throw new Error("ToolRegistry: tool.name must be a non-empty string");
-    }
-    if (this.tools.has(tool.name)) {
-      throw new Error(`ToolRegistry: "${tool.name}" is already registered`);
-    }
-    this.tools.set(tool.name, tool);
-  }
-  registerAll(tools) {
-    for (const tool of tools) this.register(tool);
-  }
-  unregister(name) {
-    this.tools.delete(name);
-  }
-  get(name) {
-    return this.tools.get(name);
-  }
-  has(name) {
-    return this.tools.has(name);
-  }
-  list() {
-    return Array.from(this.tools.values());
-  }
-  count() {
-    return this.tools.size;
-  }
-};
-
 // src/tools/agent.ts
-var inputSchema = z5.object({
-  description: z5.string().min(1),
-  subagent_type: z5.string().optional(),
-  run_in_background: z5.boolean().optional()
+var inputSchema = z6.object({
+  description: z6.string().min(1),
+  subagent_type: z6.string().optional(),
+  run_in_background: z6.boolean().optional()
 });
 function createAgentTool(options) {
   if (options.agents.length === 0) {
@@ -3966,7 +4136,7 @@ function handlePausedResult(result, agentId, subagentType) {
 
 // src/tools/bash.ts
 init_esm_shims();
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 var _spawn = null;
 async function getSpawn() {
   if (_spawn === null) {
@@ -3978,15 +4148,16 @@ async function getSpawn() {
 var MAX_OUTPUT_BYTES = 512 * 1024;
 var SIGKILL_GRACE_MS = 500;
 var BLOCKED_DEVICE_PATHS = /\b(\/dev\/zero|\/dev\/random|\/dev\/urandom|\/proc\/kcore|\/dev\/sda|\/dev\/mem)\b/;
-var inputSchema2 = z6.object({
-  command: z6.string().min(1),
-  cwd: z6.string().min(1).optional()
+var inputSchema2 = z7.object({
+  command: z7.string().min(1),
+  cwd: z7.string().min(1).optional()
 });
 function createBashTool() {
   return defineTool({
     name: "Bash",
     description: "Execute a shell command via /bin/sh -c. Returns combined stdout+stderr and the exit code.",
     inputSchema: inputSchema2,
+    requiresNode: true,
     execute: async ({ command, cwd }, ctx) => {
       if (BLOCKED_DEVICE_PATHS.test(command)) {
         return {
@@ -4066,10 +4237,10 @@ function createBashTool() {
 
 // src/tools/sendMessage.ts
 init_esm_shims();
-import { z as z7 } from "zod";
-var inputSchema3 = z7.object({
-  to: z7.string().min(1).describe("Agent name (subagent_type) or agentId to send the message to."),
-  message: z7.string().min(1).describe("Message content to deliver to the target agent.")
+import { z as z8 } from "zod";
+var inputSchema3 = z8.object({
+  to: z8.string().min(1).describe("Agent name (subagent_type) or agentId to send the message to."),
+  message: z8.string().min(1).describe("Message content to deliver to the target agent.")
 });
 function createSendMessageTool(options) {
   return defineTool({
@@ -4120,12 +4291,12 @@ function createSendMessageTool(options) {
 
 // src/tools/fileEdit.ts
 init_esm_shims();
-import { z as z8 } from "zod";
-var inputSchema4 = z8.object({
-  path: z8.string().min(1),
-  old_string: z8.string().min(1),
-  new_string: z8.string(),
-  replace_all: z8.boolean().optional()
+import { z as z9 } from "zod";
+var inputSchema4 = z9.object({
+  path: z9.string().min(1),
+  old_string: z9.string().min(1),
+  new_string: z9.string(),
+  replace_all: z9.boolean().optional()
 });
 function createFileEditTool(storage) {
   return defineTool({
@@ -4209,13 +4380,13 @@ function normalizeQuotes(s) {
 
 // src/tools/fileRead.ts
 init_esm_shims();
-import { z as z9 } from "zod";
-var inputSchema5 = z9.object({
-  path: z9.string().min(1),
-  offset: z9.number().int().positive().optional(),
-  limit: z9.number().int().positive().optional(),
+import { z as z10 } from "zod";
+var inputSchema5 = z10.object({
+  path: z10.string().min(1),
+  offset: z10.number().int().positive().optional(),
+  limit: z10.number().int().positive().optional(),
   /** PDF page range, e.g. "1-5", "3", "10-20". Max 20 pages per request. */
-  pages: z9.string().optional()
+  pages: z10.string().optional()
 });
 var IMAGE_EXTENSIONS = /* @__PURE__ */ new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".svg"]);
 var PDF_EXTENSION = ".pdf";
@@ -4383,7 +4554,7 @@ async function readImage(storage, filePath, ext) {
     ".svg": "image/svg+xml"
   };
   const mimeType = mimeMap[ext] ?? "application/octet-stream";
-  const base64 = buffer.toString("base64");
+  const base642 = buffer.toString("base64");
   return {
     content: `[Image: ${filePath} (${mimeType}, ${(buffer.length / 1024).toFixed(1)}KB)]
 
@@ -4392,17 +4563,17 @@ Base64 data is included in the metadata for visual analysis.`,
       format: "image",
       mimeType,
       bytes: buffer.length,
-      base64
+      base64: base642
     }
   };
 }
 
 // src/tools/fileWrite.ts
 init_esm_shims();
-import { z as z10 } from "zod";
-var inputSchema6 = z10.object({
-  path: z10.string().min(1),
-  content: z10.string()
+import { z as z11 } from "zod";
+var inputSchema6 = z11.object({
+  path: z11.string().min(1),
+  content: z11.string()
 });
 function createFileWriteTool(storageOrOptions) {
   const opts = "readFile" in storageOrOptions ? { storage: storageOrOptions } : storageOrOptions;
@@ -4441,7 +4612,7 @@ function createFileWriteTool(storageOrOptions) {
 // src/tools/glob.ts
 init_esm_shims();
 import picomatch from "picomatch";
-import { z as z11 } from "zod";
+import { z as z12 } from "zod";
 
 // src/tools/walkAdapter.ts
 init_esm_shims();
@@ -4478,9 +4649,9 @@ async function* walkAdapter(adapter, startPath, options = {}) {
 }
 
 // src/tools/glob.ts
-var inputSchema7 = z11.object({
-  pattern: z11.string().min(1),
-  path: z11.string().optional()
+var inputSchema7 = z12.object({
+  pattern: z12.string().min(1),
+  path: z12.string().optional()
 });
 var MAX_RESULTS = 1e3;
 function createGlobTool(storage) {
@@ -4533,22 +4704,22 @@ function createGlobTool(storage) {
 // src/tools/grep.ts
 init_esm_shims();
 import picomatch2 from "picomatch";
-import { z as z12 } from "zod";
-var inputSchema8 = z12.object({
-  pattern: z12.string().min(1),
-  path: z12.string().optional(),
-  glob: z12.string().optional(),
-  type: z12.string().optional(),
-  output_mode: z12.enum(["content", "files_with_matches", "count"]).optional(),
-  "-i": z12.boolean().optional(),
-  "-n": z12.boolean().optional(),
-  "-A": z12.number().int().nonnegative().optional(),
-  "-B": z12.number().int().nonnegative().optional(),
-  "-C": z12.number().int().nonnegative().optional(),
-  context: z12.number().int().nonnegative().optional(),
-  multiline: z12.boolean().optional(),
-  head_limit: z12.number().int().nonnegative().optional(),
-  offset: z12.number().int().nonnegative().optional()
+import { z as z13 } from "zod";
+var inputSchema8 = z13.object({
+  pattern: z13.string().min(1),
+  path: z13.string().optional(),
+  glob: z13.string().optional(),
+  type: z13.string().optional(),
+  output_mode: z13.enum(["content", "files_with_matches", "count"]).optional(),
+  "-i": z13.boolean().optional(),
+  "-n": z13.boolean().optional(),
+  "-A": z13.number().int().nonnegative().optional(),
+  "-B": z13.number().int().nonnegative().optional(),
+  "-C": z13.number().int().nonnegative().optional(),
+  context: z13.number().int().nonnegative().optional(),
+  multiline: z13.boolean().optional(),
+  head_limit: z13.number().int().nonnegative().optional(),
+  offset: z13.number().int().nonnegative().optional()
 });
 var MAX_FILES_SCANNED = 5e3;
 var MAX_MATCHES_PER_FILE = 100;
@@ -4772,10 +4943,10 @@ function formatJsResults(results, mode, limit) {
 
 // src/tools/webFetch.ts
 init_esm_shims();
-import { z as z13 } from "zod";
-var inputSchema9 = z13.object({
-  url: z13.string().url(),
-  prompt: z13.string().optional()
+import { z as z14 } from "zod";
+var inputSchema9 = z14.object({
+  url: z14.string().url(),
+  prompt: z14.string().optional()
 });
 var MAX_OUTPUT_BYTES2 = 256 * 1024;
 function createWebFetchTool(options = {}) {
@@ -4904,10 +5075,10 @@ function normalizePath(p) {
 
 // src/tools/webSearch.ts
 init_esm_shims();
-import { z as z14 } from "zod";
-var inputSchema10 = z14.object({
-  query: z14.string().min(2),
-  max_results: z14.number().int().positive().optional()
+import { z as z15 } from "zod";
+var inputSchema10 = z15.object({
+  query: z15.string().min(2),
+  max_results: z15.number().int().positive().optional()
 });
 function createWebSearchTool() {
   return defineTool({
@@ -4964,10 +5135,10 @@ function htmlToText2(html) {
 
 // src/tools/sleep.ts
 init_esm_shims();
-import { z as z15 } from "zod";
-var inputSchema11 = z15.object({
-  durationMs: z15.number().int().nonnegative().max(3e5),
-  reason: z15.string().optional()
+import { z as z16 } from "zod";
+var inputSchema11 = z16.object({
+  durationMs: z16.number().int().nonnegative().max(3e5),
+  reason: z16.string().optional()
 });
 function createSleepTool() {
   return defineTool({
@@ -5007,10 +5178,10 @@ function createSleepTool() {
 
 // src/tools/toolSearch.ts
 init_esm_shims();
-import { z as z16 } from "zod";
-var inputSchema12 = z16.object({
-  query: z16.string().min(1),
-  max_results: z16.number().int().positive().optional()
+import { z as z17 } from "zod";
+var inputSchema12 = z17.object({
+  query: z17.string().min(1),
+  max_results: z17.number().int().positive().optional()
 });
 function createToolSearchTool(registry) {
   return defineTool({
@@ -5053,11 +5224,11 @@ ${lines.join("\n")}`,
 
 // src/tools/memorize.ts
 init_esm_shims();
-import { z as z17 } from "zod";
-var inputSchema13 = z17.object({
-  text: z17.string().min(1),
-  kind: z17.enum(["rule", "lesson"]).default("lesson"),
-  topic: z17.string().optional()
+import { z as z18 } from "zod";
+var inputSchema13 = z18.object({
+  text: z18.string().min(1),
+  kind: z18.enum(["rule", "lesson"]).default("lesson"),
+  topic: z18.string().optional()
 });
 function createMemorizeTool(memory) {
   return defineTool({
@@ -5089,11 +5260,11 @@ function createMemorizeTool(memory) {
 
 // src/tools/recall.ts
 init_esm_shims();
-import { z as z18 } from "zod";
-var inputSchema14 = z18.object({
-  query: z18.string().min(1),
-  scope: z18.enum(["identity", "rules", "lessons", "all"]).default("all"),
-  topic: z18.string().optional()
+import { z as z19 } from "zod";
+var inputSchema14 = z19.object({
+  query: z19.string().min(1),
+  scope: z19.enum(["identity", "rules", "lessons", "all"]).default("all"),
+  topic: z19.string().optional()
 });
 function createRecallTool(memory) {
   return defineTool({
@@ -5148,13 +5319,13 @@ ${content}`,
 
 // src/tools/notebookEdit.ts
 init_esm_shims();
-import { z as z19 } from "zod";
-var inputSchema15 = z19.object({
-  notebook_path: z19.string().min(1),
-  edit_mode: z19.enum(["replace", "insert", "delete"]).default("replace"),
-  cell_index: z19.number().int().nonnegative(),
-  new_source: z19.string().optional(),
-  cell_type: z19.enum(["code", "markdown"]).optional()
+import { z as z20 } from "zod";
+var inputSchema15 = z20.object({
+  notebook_path: z20.string().min(1),
+  edit_mode: z20.enum(["replace", "insert", "delete"]).default("replace"),
+  cell_index: z20.number().int().nonnegative(),
+  new_source: z20.string().optional(),
+  cell_type: z20.enum(["code", "markdown"]).optional()
 });
 function createNotebookEditTool(storage) {
   return defineTool({
@@ -5309,12 +5480,12 @@ var TaskStore = class {
 
 // src/tools/tasks/tools.ts
 init_esm_shims();
-import { z as z20 } from "zod";
-var TaskStatusEnum = z20.enum(["pending", "in_progress", "completed", "deleted"]);
-var createSchema = z20.object({
-  subject: z20.string().min(1),
-  description: z20.string().default(""),
-  metadata: z20.record(z20.unknown()).optional()
+import { z as z21 } from "zod";
+var TaskStatusEnum = z21.enum(["pending", "in_progress", "completed", "deleted"]);
+var createSchema = z21.object({
+  subject: z21.string().min(1),
+  description: z21.string().default(""),
+  metadata: z21.record(z21.unknown()).optional()
 });
 function createTaskCreateTool(store) {
   return defineTool({
@@ -5330,8 +5501,8 @@ function createTaskCreateTool(store) {
     }
   });
 }
-var getSchema = z20.object({
-  taskId: z20.string().min(1)
+var getSchema = z21.object({
+  taskId: z21.string().min(1)
 });
 function createTaskGetTool(store) {
   return defineTool({
@@ -5352,7 +5523,7 @@ ${task.description}`,
     }
   });
 }
-var listSchema = z20.object({
+var listSchema = z21.object({
   status: TaskStatusEnum.optional()
 });
 function createTaskListTool(store) {
@@ -5378,12 +5549,12 @@ ${lines.join("\n")}`,
     }
   });
 }
-var updateSchema = z20.object({
-  taskId: z20.string().min(1),
-  subject: z20.string().min(1).optional(),
+var updateSchema = z21.object({
+  taskId: z21.string().min(1),
+  subject: z21.string().min(1).optional(),
   status: TaskStatusEnum.optional(),
-  description: z20.string().optional(),
-  metadata: z20.record(z20.unknown()).optional()
+  description: z21.string().optional(),
+  metadata: z21.record(z21.unknown()).optional()
 });
 function createTaskUpdateTool(store) {
   return defineTool({
@@ -6232,7 +6403,7 @@ function wrapFetchWithHeadersProvider(baseFetch, headersProvider, staticHeaders)
 
 // src/mcp/toolAdapter.ts
 init_esm_shims();
-import { z as z21 } from "zod";
+import { z as z22 } from "zod";
 function mcpToolName(serverName, toolName) {
   return `mcp__${serverName}__${toolName}`;
 }
@@ -6241,7 +6412,7 @@ function adaptMcpTool(client, serverName, def) {
   return defineTool({
     name: registeredName,
     description: def.description.length > 0 ? def.description : `MCP tool ${serverName}/${def.name}`,
-    inputSchema: z21.unknown(),
+    inputSchema: z22.unknown(),
     // Pass the MCP server's JSON Schema through to Anthropic verbatim,
     // bypassing Zod-to-JSON-Schema conversion (which would produce `{}`
     // for our `z.unknown()` Zod schema).
@@ -7350,11 +7521,11 @@ ${issues.join("\n")}` };
 
 // src/skills/skillPage.ts
 init_esm_shims();
-import { z as z22 } from "zod";
+import { z as z23 } from "zod";
 var SAFE_NAME3 = /^[a-zA-Z0-9_-]+$/;
-var inputSchema16 = z22.object({
-  skill: z22.string().min(1),
-  page: z22.string().min(1).optional()
+var inputSchema16 = z23.object({
+  skill: z23.string().min(1),
+  page: z23.string().min(1).optional()
 });
 function createSkillPageTool(options) {
   return defineTool({
@@ -7410,6 +7581,203 @@ The skill "${skill}" has no pages.`;
   });
 }
 
+// src/tools/apiCall.ts
+init_esm_shims();
+import { z as z24 } from "zod";
+var ALL_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+var DEFAULT_MAX_BODY_BYTES = 256 * 1024;
+var DEFAULT_MAX_RESPONSE_BYTES = 100 * 1024;
+function createApiCallTool(opts) {
+  if (opts.services.length === 0) {
+    throw new Error("createApiCallTool: services list must be non-empty");
+  }
+  const services = /* @__PURE__ */ new Map();
+  for (const svc of opts.services) {
+    if (services.has(svc.name)) {
+      throw new Error(`createApiCallTool: duplicate service name "${svc.name}"`);
+    }
+    services.set(svc.name, svc);
+  }
+  const serviceNames = [...services.keys()];
+  for (const svc of opts.services) {
+    if (svc.auth?.type === "custom" && opts.resolveAuth === void 0) {
+      throw new Error(
+        `createApiCallTool: service "${svc.name}" uses custom auth (id: ${svc.auth.id}) but no resolveAuth was supplied`
+      );
+    }
+  }
+  const fetchFn = opts.fetch ?? globalThis.fetch.bind(globalThis);
+  const maxResponseBytes = opts.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+  const inputSchema17 = z24.object({
+    service: z24.enum(serviceNames),
+    method: z24.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]),
+    path: z24.string().regex(/^\//, "path must start with /"),
+    query: z24.record(z24.string(), z24.string()).optional(),
+    body: z24.unknown().optional(),
+    headers: z24.record(z24.string(), z24.string()).optional()
+  });
+  const description = opts.toolDescription ?? `Call a configured external API. Services: ${serviceNames.join(", ")}. Auth is injected automatically \u2014 do not pass credentials via headers.`;
+  return defineTool({
+    name: opts.toolName ?? "ApiCall",
+    description,
+    inputSchema: inputSchema17,
+    execute: async (input) => {
+      const svc = services.get(input.service);
+      if (!svc) {
+        return errResult(`ERR_API_UNKNOWN_SERVICE: ${input.service}`);
+      }
+      const allowedMethods = svc.allowedMethods ?? ALL_METHODS;
+      if (!allowedMethods.includes(input.method)) {
+        return errResult(
+          `ERR_API_METHOD_NOT_ALLOWED: ${input.method} not permitted for service ${svc.name}`
+        );
+      }
+      if (!pathAllowed(input.path, svc.allowedPaths)) {
+        return errResult(`ERR_API_PATH_NOT_ALLOWED: ${input.path} for service ${svc.name}`);
+      }
+      let bodyText;
+      if (input.body !== void 0) {
+        bodyText = JSON.stringify(input.body);
+        const cap = svc.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+        if (byteLength(bodyText) > cap) {
+          return errResult(`ERR_API_BODY_TOO_LARGE: exceeds ${cap} bytes`);
+        }
+      }
+      let authHeaders;
+      try {
+        authHeaders = await resolveAuth({
+          auth: svc.auth ?? { type: "none" },
+          env: opts.env,
+          resolver: opts.resolveAuth,
+          ctx: { serviceName: svc.name, method: input.method, path: input.path }
+        });
+      } catch (err) {
+        const raw2 = err instanceof Error ? err.message : String(err);
+        const truncated = raw2.length > 200 ? raw2.slice(0, 200) + "\u2026" : raw2;
+        return errResult(`ERR_API_RESOLVER_FAILED: ${truncated}`);
+      }
+      const userHeaders = sanitizeHeaders(input.headers ?? {}, authHeaders);
+      const url = buildUrl(svc.baseUrl, input.path, input.query);
+      await invokeHook(opts.onRequest, {
+        service: svc.name,
+        method: input.method,
+        path: input.path
+      });
+      const started = Date.now();
+      let res;
+      try {
+        res = await fetchFn(url, {
+          method: input.method,
+          headers: {
+            "Content-Type": "application/json",
+            ...svc.defaultHeaders ?? {},
+            ...userHeaders,
+            ...authHeaders
+            // wins last — model cannot override
+          },
+          ...bodyText !== void 0 ? { body: bodyText } : {}
+        });
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return errResult(`network error: ${msg}`);
+      }
+      const raw = await res.text();
+      const content = raw.length > maxResponseBytes ? raw.slice(0, maxResponseBytes) + "\n\u2026[TRUNCATED]" : raw;
+      await invokeHook(opts.onResponse, {
+        service: svc.name,
+        method: input.method,
+        path: input.path,
+        status: res.status,
+        latencyMs: Date.now() - started,
+        bytesIn: raw.length
+      });
+      return {
+        content,
+        isError: !res.ok,
+        metadata: { status: res.status, service: svc.name }
+      };
+    }
+  });
+}
+function errResult(msg) {
+  return { content: msg, isError: true };
+}
+function pathAllowed(path2, allowed) {
+  if (!allowed || allowed.length === 0) return true;
+  for (const a of allowed) {
+    if (typeof a === "string") {
+      if (path2.startsWith(a)) return true;
+    } else if (a.test(path2)) {
+      return true;
+    }
+  }
+  return false;
+}
+function byteLength(s) {
+  return new TextEncoder().encode(s).byteLength;
+}
+function buildUrl(baseUrl, path2, query) {
+  const base = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+  const url = new URL(base + path2);
+  for (const [k, v] of Object.entries(query ?? {})) {
+    url.searchParams.set(k, v);
+  }
+  return url.toString();
+}
+function sanitizeHeaders(user, auth) {
+  const banned = new Set(Object.keys(auth).map((k) => k.toLowerCase()));
+  const out = {};
+  for (const [k, v] of Object.entries(user)) {
+    if (banned.has(k.toLowerCase())) continue;
+    out[k] = v;
+  }
+  return out;
+}
+async function resolveAuth(args) {
+  const { auth, env, resolver, ctx } = args;
+  switch (auth.type) {
+    case "none":
+      return {};
+    case "bearer": {
+      const token = envLookup(env, auth.tokenRef);
+      return { Authorization: `Bearer ${token}` };
+    }
+    case "header": {
+      const value = envLookup(env, auth.valueRef);
+      return { [auth.name]: value };
+    }
+    case "basic": {
+      const u = envLookup(env, auth.userRef);
+      const p = envLookup(env, auth.passRef);
+      return { Authorization: `Basic ${base64(`${u}:${p}`)}` };
+    }
+    case "custom":
+      if (resolver === void 0) {
+        throw new Error(`custom auth id "${auth.id}" requires resolveAuth`);
+      }
+      return resolver(auth, ctx);
+  }
+}
+function envLookup(env, ref) {
+  if (env === void 0 || env[ref] === void 0) {
+    throw new Error(`ERR_API_ENV_MISSING: ${ref}`);
+  }
+  return env[ref];
+}
+function base64(input) {
+  if (typeof globalThis.btoa === "function") {
+    return globalThis.btoa(input);
+  }
+  return Buffer.from(input, "utf8").toString("base64");
+}
+async function invokeHook(hook, event) {
+  if (hook === void 0) return;
+  try {
+    await hook(event);
+  } catch {
+  }
+}
+
 // src/skills/storageSkillSource.ts
 init_esm_shims();
 var SAFE_NAME4 = /^[a-zA-Z0-9_-]+$/;
@@ -8192,6 +8560,7 @@ function rebuildMessagesFromEntries(entries) {
 init_esm_shims();
 function toResponse(result, extra) {
   const timestamp = Date.now();
+  const capsField = extra.capabilitiesMissing !== void 0 && extra.capabilitiesMissing.length > 0 ? { capabilitiesMissing: extra.capabilitiesMissing } : {};
   if (result.status === "done") {
     return {
       runId: extra.runId,
@@ -8203,7 +8572,8 @@ function toResponse(result, extra) {
         tokensUsed: result.tokensUsed,
         durationMs: extra.durationMs,
         output: result.output,
-        ...extra.logPath !== void 0 ? { transcript: { path: extra.logPath, lastShardIndex: 0 } } : {}
+        ...extra.logPath !== void 0 ? { transcript: { path: extra.logPath, lastShardIndex: 0 } } : {},
+        ...capsField
       },
       errors: [],
       timestamp
@@ -8222,7 +8592,8 @@ function toResponse(result, extra) {
         snapshot: result.snapshot,
         ...result.snapshot.pendingToolCall !== void 0 ? { pendingToolCall: result.snapshot.pendingToolCall } : {},
         pauseReason: result.reason,
-        ...extra.logPath !== void 0 ? { transcript: { path: extra.logPath, lastShardIndex: result.snapshot.lastShardIndex } } : {}
+        ...extra.logPath !== void 0 ? { transcript: { path: extra.logPath, lastShardIndex: result.snapshot.lastShardIndex } } : {},
+        ...capsField
       },
       errors: [],
       timestamp
@@ -8556,7 +8927,15 @@ var Engine = class {
     this.mcpManager = new McpManager(config.mcp, createLogger(config.logging), { samplingHandler });
     this.permissionPolicy = buildPermissionPolicy(config.permissions);
   }
-  async run(options) {
+  /**
+   * Run a task synchronously to completion. The `_internal` parameter is
+   * reserved for the engine's own async wrappers (`start`, `resumeAsync`)
+   * to request runner handoff (Plan 019) — external callers must leave
+   * it unset. Sync callers never hand off; if they hit a Node-only tool
+   * on a restricted runtime, the capability stub returns an error and
+   * the model adapts.
+   */
+  async run(options, _internal) {
     const startTime = Date.now();
     const runId = options.runId ?? `run_${randomUUID()}`;
     const log = createLogger(this.config.logging);
@@ -8579,6 +8958,7 @@ var Engine = class {
     const coordinatorBase = isCoordinatorMode(this.config) ? getCoordinatorBasePrompt() : void 0;
     const skillSource = this.resolveSkillSource(options.skills, storage);
     const skillList = skillSource !== void 0 ? await skillSource.list() : void 0;
+    const apiConfig = this.resolveApiConfig(options.api);
     let systemPrompt = await buildSystemPrompt({
       ...coordinatorBase !== void 0 ? { base: coordinatorBase } : {},
       memory,
@@ -8609,7 +8989,9 @@ var Engine = class {
       mcpTools,
       memory,
       ...this.config.hooks.propagateGateToSubagents === true && gate !== void 0 ? { subagentGate: gate } : {},
-      ...skillSource !== void 0 ? { skillSource } : {}
+      ...skillSource !== void 0 ? { skillSource } : {},
+      ...apiConfig !== void 0 ? { apiConfig } : {},
+      ...this.internals.fetch !== void 0 ? { fetch: this.internals.fetch } : {}
     });
     const writer = new TranscriptWriter({
       storage: storage.workspace,
@@ -8663,7 +9045,8 @@ var Engine = class {
         onProgress: this.buildHeartbeat(storage, runId, options.nodeId),
         ...options.tokenBudget !== void 0 ? { tokenBudget: options.tokenBudget } : {},
         ...runTimeout.signal !== void 0 ? { runSignal: runTimeout.signal, runTimeoutMs: this.config.execution.runTimeoutMs } : {},
-        ...gate !== void 0 ? { gateBeforeTool: gate } : {}
+        ...gate !== void 0 ? { gateBeforeTool: gate } : {},
+        ..._internal?.handoffToRunner === true ? { handoffToRunner: true } : {}
       });
       const result = await this.finalizeResult(loopResult, writer, logPath, {
         ...options.outputFormat !== void 0 ? { outputFormat: options.outputFormat } : {},
@@ -8671,18 +9054,20 @@ var Engine = class {
       });
       this.logRunEnd(log, runId, options.nodeId, result);
       await this.firePostRunHook(runId, options.nodeId, result, ctx, logPath);
+      const capabilitiesMissing = ctx.getCapabilitiesMissing();
       return toResponse(result, {
         runId,
         nodeId: options.nodeId,
         durationMs: Date.now() - startTime,
-        logPath
+        logPath,
+        ...capabilitiesMissing.length > 0 ? { capabilitiesMissing } : {}
       });
     } finally {
       runTimeout.clear();
       await writer.close();
     }
   }
-  async resume(options) {
+  async resume(options, _internal) {
     const startTime = Date.now();
     const log = createLogger(this.config.logging);
     const storage = await this.buildStorage();
@@ -8715,6 +9100,7 @@ var Engine = class {
     const coordinatorBase = isCoordinatorMode(this.config) ? getCoordinatorBasePrompt() : void 0;
     const skillSource = this.resolveSkillSource(options.skills, storage);
     const skillList = skillSource !== void 0 ? await skillSource.list() : void 0;
+    const apiConfig = this.resolveApiConfig(options.api);
     let systemPrompt = await buildSystemPrompt({
       ...coordinatorBase !== void 0 ? { base: coordinatorBase } : {},
       memory,
@@ -8745,7 +9131,9 @@ var Engine = class {
       mcpTools,
       memory,
       ...this.config.hooks.propagateGateToSubagents === true && gate !== void 0 ? { subagentGate: gate } : {},
-      ...skillSource !== void 0 ? { skillSource } : {}
+      ...skillSource !== void 0 ? { skillSource } : {},
+      ...apiConfig !== void 0 ? { apiConfig } : {},
+      ...this.internals.fetch !== void 0 ? { fetch: this.internals.fetch } : {}
     });
     const priorState = await loadWriterState(storage.workspace, logPath);
     const writer = new TranscriptWriter({
@@ -8799,18 +9187,21 @@ var Engine = class {
           const answer = typeof options.gateAnswer === "string" ? options.gateAnswer : JSON.stringify(options.gateAnswer);
           await ctx.addToolResult(pending.toolUseId, answer, false);
         } else {
-          await ctx.addToolResult(
-            pending.toolUseId,
-            `APPROVAL_GATE_RELEASED: the prior ${pending.toolName} call was paused for human approval and has now been approved. Retry is required.`,
-            false
-          );
           const inputJson = JSON.stringify(pending.input ?? {}, null, 2);
-          await ctx.addUserMessage(
-            `The human has approved the paused ${pending.toolName} tool call. You MUST now re-issue the EXACT same tool call to complete the work \u2014 do not change the arguments, do not answer in text, do not declare the task done. Approved arguments (copy verbatim):
+          await ctx.addMixedUserMessage([
+            {
+              type: "tool_result",
+              tool_use_id: pending.toolUseId,
+              content: `APPROVAL_GATE_RELEASED: the prior ${pending.toolName} call was paused for human approval and has now been approved. Retry is required.`
+            },
+            {
+              type: "text",
+              text: `The human has approved the paused ${pending.toolName} tool call. You MUST now re-issue the EXACT same tool call to complete the work \u2014 do not change the arguments, do not answer in text, do not declare the task done. Approved arguments (copy verbatim):
 \`\`\`json
 ${inputJson}
 \`\`\``
-          );
+            }
+          ]);
         }
       }
       await writer.setStatus("running");
@@ -8831,7 +9222,8 @@ ${inputJson}
         stopHooks: this.config.hooks.stopHooks,
         onProgress: this.buildHeartbeat(storage, snapshot.runId, snapshot.nodeId),
         ...runTimeout.signal !== void 0 ? { runSignal: runTimeout.signal, runTimeoutMs: this.config.execution.runTimeoutMs } : {},
-        ...gate !== void 0 ? { gateBeforeTool: gate } : {}
+        ...gate !== void 0 ? { gateBeforeTool: gate } : {},
+        ..._internal?.handoffToRunner === true ? { handoffToRunner: true } : {}
       });
       const result = await this.finalizeResult(loopResult, writer, logPath, {
         ...options.outputFormat !== void 0 ? { outputFormat: options.outputFormat } : {},
@@ -8839,11 +9231,13 @@ ${inputJson}
       });
       this.logRunEnd(log, snapshot.runId, snapshot.nodeId, result);
       await this.firePostRunHook(snapshot.runId, snapshot.nodeId, result, ctx, logPath);
+      const capabilitiesMissing = ctx.getCapabilitiesMissing();
       return toResponse(result, {
         runId: snapshot.runId,
         nodeId: snapshot.nodeId,
         durationMs: Date.now() - startTime,
-        logPath
+        logPath,
+        ...capabilitiesMissing.length > 0 ? { capabilitiesMissing } : {}
       });
     } finally {
       runTimeout.clear();
@@ -8913,13 +9307,15 @@ ${inputJson}
     } : void 0;
     const initial = RunStateManager.initial(runId, options.nodeId, webhook);
     await stateManager.write(initial);
+    const handoffEnabled = this.config.runner !== void 0;
     this.backgroundExecutor.schedule(runId, async (signal) => {
       await stateManager.update(runId, options.nodeId, { status: "running" });
       try {
-        const response = await this.run({ ...options, runId });
+        const response = await this.run({ ...options, runId }, { handoffToRunner: handoffEnabled });
         if (signal.aborted) return;
-        await stateManager.finalize(runId, options.nodeId, response);
-        await this.maybeFireWebhook(stateManager, runId, options.nodeId, response);
+        const postHandoff = await this.maybeHandoffToRunner(runId, options.nodeId, response);
+        await stateManager.finalize(runId, options.nodeId, postHandoff);
+        await this.maybeFireWebhook(stateManager, runId, options.nodeId, postHandoff);
       } catch (err) {
         if (signal.aborted) return;
         const errorMsg = err instanceof Error ? err.message : String(err);
@@ -8967,12 +9363,14 @@ ${inputJson}
     } : { ...RunStateManager.initial(options.runId, nodeId, webhook), status: "running" };
     await stateManager.write(next);
     const resumeNodeId = nodeId;
+    const handoffEnabled = this.config.runner !== void 0;
     this.backgroundExecutor.schedule(options.runId, async (signal) => {
       try {
-        const response = await this.resume(options);
+        const response = await this.resume(options, { handoffToRunner: handoffEnabled });
         if (signal.aborted) return;
-        await stateManager.finalize(options.runId, resumeNodeId, response);
-        await this.maybeFireWebhook(stateManager, options.runId, resumeNodeId, response);
+        const postHandoff = await this.maybeHandoffToRunner(options.runId, resumeNodeId, response);
+        await stateManager.finalize(options.runId, resumeNodeId, postHandoff);
+        await this.maybeFireWebhook(stateManager, options.runId, resumeNodeId, postHandoff);
       } catch (err) {
         if (signal.aborted) return;
         const errorMsg = err instanceof Error ? err.message : String(err);
@@ -9161,6 +9559,68 @@ ${inputJson}
     }
     return orphaned;
   }
+  // ---------- runner handoff (Plan 019) ----------
+  /**
+   * When the response indicates the run paused for runner handoff, POST
+   * `{ runId }` to the configured runner URL. On success, return the
+   * response unchanged — state stays `paused` and the runner will flip
+   * it to `done` (or `failed`) on its side. On POST failure, convert
+   * the response to `failed` with `ERR_RUNNER_UNREACHABLE` so the
+   * caller sees a terminal state instead of a silent hang.
+   *
+   * Called only from `start()` / `resumeAsync()`. Sync `run()` never
+   * produces a `handoff_to_runner` pause (see `_internal.handoffToRunner`).
+   */
+  async maybeHandoffToRunner(runId, nodeId, response) {
+    if (response.status !== "paused") return response;
+    if (response.meta.pauseReason !== "handoff_to_runner") return response;
+    const runner = this.config.runner;
+    if (runner === void 0) {
+      return response;
+    }
+    const fetchFn = this.internals.fetch ?? globalThis.fetch.bind(globalThis);
+    try {
+      const res = await fetchFn(runner.url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${runner.secret}`
+        },
+        body: JSON.stringify({ runId })
+      });
+      if (!res.ok) {
+        return {
+          runId,
+          status: "failed",
+          data: null,
+          meta: { nodeId },
+          errors: [
+            {
+              code: "ERR_RUNNER_UNREACHABLE",
+              message: `Runner returned HTTP ${res.status}`
+            }
+          ],
+          timestamp: Date.now()
+        };
+      }
+      return response;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return {
+        runId,
+        status: "failed",
+        data: null,
+        meta: { nodeId },
+        errors: [
+          {
+            code: "ERR_RUNNER_UNREACHABLE",
+            message: `Runner handoff failed: ${msg}`
+          }
+        ],
+        timestamp: Date.now()
+      };
+    }
+  }
   // ---------- webhook helpers ----------
   async maybeFireWebhook(stateManager, runId, nodeId, response) {
     const state = await stateManager.read(runId, nodeId);
@@ -9304,6 +9764,11 @@ ${inputJson}
       if (disabled.has(name)) continue;
       if (wantAll || enabled.has(name)) names.add(name);
     }
+    if ((this.config.api?.services.length ?? 0) > 0) {
+      if (!disabled.has("ApiCall") && (wantAll || enabled.has("ApiCall"))) {
+        names.add("ApiCall");
+      }
+    }
     for (const tool of this.config.tools.custom) {
       names.add(tool.name);
     }
@@ -9460,6 +9925,34 @@ ${inputJson}
     }
     return void 0;
   }
+  /**
+   * Plan 020 — resolve the effective ApiCall config for a run.
+   *
+   * Precedence (each field independently):
+   *   RunOptions.api.X > config.api.X
+   *
+   * If neither side provides any services, returns undefined so the
+   * tool isn't registered at all. Env + resolveAuth + hooks flow
+   * through untouched — they never hit the Zod schema.
+   */
+  resolveApiConfig(override) {
+    const base = this.config.api;
+    if (override === void 0 && base === void 0) return void 0;
+    const services = override?.services ?? base?.services;
+    if (services === void 0 || services.length === 0) return void 0;
+    const env = override?.env ?? base?.env;
+    const resolveAuth2 = override?.resolveAuth ?? base?.resolveAuth;
+    const onRequest = override?.onRequest ?? base?.onRequest;
+    const onResponse = override?.onResponse ?? base?.onResponse;
+    return {
+      services,
+      ...env !== void 0 ? { env } : {},
+      ...resolveAuth2 !== void 0 ? { resolveAuth: resolveAuth2 } : {},
+      ...onRequest !== void 0 ? { onRequest } : {},
+      ...onResponse !== void 0 ? { onResponse } : {},
+      ...base?.maxResponseBytes !== void 0 ? { maxResponseBytes: base.maxResponseBytes } : {}
+    };
+  }
   /**
    * Build a throttled heartbeat callback for agentLoop's `onProgress` hook.
    *
@@ -9554,8 +10047,8 @@ function buildToolRegistry(options) {
   const fileTracker = new FileTracker();
   const spawnAvailable = canSpawnProcesses();
   const candidates = [
-    // Bash — requires child_process.spawn (Node.js only).
-    ...spawnAvailable ? [{ name: "Bash", tool: createBashTool() }] : [],
+    // Bash — requires child_process.spawn. Stubbed on Workers.
+    { name: "Bash", tool: withCapabilityCheck(createBashTool(), spawnAvailable) },
     {
       name: "Read",
       tool: createFileReadTool({ storage: storage.workspace, tracker: fileTracker })
@@ -9601,6 +10094,21 @@ function buildToolRegistry(options) {
       childRegistry.register(skillTool);
     }
   }
+  if (options.apiConfig !== void 0 && options.apiConfig.services.length > 0) {
+    if (!disabled.has("ApiCall") && (wantAll || enabled.has("ApiCall"))) {
+      const apiTool = createApiCallTool({
+        services: options.apiConfig.services,
+        ...options.fetch !== void 0 ? { fetch: options.fetch } : {},
+        ...options.apiConfig.env !== void 0 ? { env: options.apiConfig.env } : {},
+        ...options.apiConfig.resolveAuth !== void 0 ? { resolveAuth: options.apiConfig.resolveAuth } : {},
+        ...options.apiConfig.onRequest !== void 0 ? { onRequest: options.apiConfig.onRequest } : {},
+        ...options.apiConfig.onResponse !== void 0 ? { onResponse: options.apiConfig.onResponse } : {},
+        ...options.apiConfig.maxResponseBytes !== void 0 ? { maxResponseBytes: options.apiConfig.maxResponseBytes } : {}
+      });
+      registry.register(apiTool);
+      childRegistry.register(apiTool);
+    }
+  }
   const agentTool = createAgentTool({
     storage: storage.workspace,
     client,
@@ -9722,6 +10230,8 @@ export {
   buildSystemPrompt,
   buildWorkerAgent,
   canSpawnProcesses,
+  capabilityStub,
+  createApiCallTool,
   createLogger,
   createModelAdapter,
   createSendMessageTool,
@@ -9753,6 +10263,7 @@ export {
   synthesizeSpec,
   toResponse,
   tryParseJSON,
-  validateOutput
+  validateOutput,
+  withCapabilityCheck
 };
 //# sourceMappingURL=index.js.map