la-machina-engine 0.7.4 → 0.7.6

package/dist/index.cjs

@@ -841,6 +841,7 @@ __export(index_exports, {
   EpisodicMemory: () => EpisodicMemory,
   Hippocampus: () => Hippocampus,
   InlineSkillSource: () => InlineSkillSource,
+  InspectWriter: () => InspectWriter,
   LocalStorageAdapter: () => LocalStorageAdapter,
   MAX_ATTEMPTS: () => MAX_ATTEMPTS,
   McpClient: () => McpClient,
@@ -848,6 +849,7 @@ __export(index_exports, {
   McpManager: () => McpManager,
   McpProtocolError: () => McpProtocolError,
   McpTimeoutError: () => McpTimeoutError,
+  NULL_INSPECT_WRITER: () => NULL_INSPECT_WRITER,
   NodeBackgroundExecutor: () => NodeBackgroundExecutor,
   NotImplementedError: () => NotImplementedError,
   PlanSchema: () => PlanSchema,
@@ -1022,6 +1024,10 @@ var DEFAULTS = {
     enableRollback: true,
     maxPlanSteps: 20,
     agentMaxTurns: 15
+  },
+  inspect: {
+    enabled: true,
+    redactBaseURL: false
   }
 };
 
@@ -1257,6 +1263,11 @@ var RunnerConfigResolved = import_zod.z.object({
   url: import_zod.z.string().url(),
   secret: import_zod.z.string().min(1, "runner.secret cannot be empty")
 }).strict();
+var InspectConfigResolved = import_zod.z.object({
+  enabled: import_zod.z.boolean(),
+  redactBaseURL: import_zod.z.boolean()
+}).strict();
+var InspectConfigUser = InspectConfigResolved.partial();
 var ResolvedConfigSchema = import_zod.z.object({
   model: ModelConfigResolved,
   storage: StorageConfigResolved,
@@ -1275,7 +1286,8 @@ var ResolvedConfigSchema = import_zod.z.object({
   orchestrator: OrchestratorConfigResolved,
   runner: RunnerConfigResolved.optional(),
   api: ApiConfigResolved.optional(),
-  knowledge: KnowledgeConfigResolved.optional()
+  knowledge: KnowledgeConfigResolved.optional(),
+  inspect: InspectConfigResolved
 }).strict();
 var R2ConfigUser = R2ConfigResolved.partial();
 var ModelConfigUser = ModelConfigResolved.partial();
@@ -1352,7 +1364,8 @@ var UserConfigSchema = import_zod.z.object({
   orchestrator: OrchestratorConfigUser.optional(),
   runner: RunnerConfigUser.optional(),
   api: ApiConfigUser.optional(),
-  knowledge: KnowledgeConfigUser.optional()
+  knowledge: KnowledgeConfigUser.optional(),
+  inspect: InspectConfigUser.optional()
 }).strict();
 
 // src/config/merge.ts
@@ -3025,6 +3038,30 @@ function isSubagentPausedError(err) {
 }
 
 // src/engine/agentLoop.ts
+async function emitInspectTurn(args) {
+  const writer = args.inspect;
+  if (writer === void 0) return;
+  const completedAt = Date.now();
+  const cacheCreate = args.endTokens.cacheCreationInput !== void 0 ? args.endTokens.cacheCreationInput - (args.startTokens.cacheCreationInput ?? 0) : void 0;
+  const cacheRead = args.endTokens.cacheReadInput !== void 0 ? args.endTokens.cacheReadInput - (args.startTokens.cacheReadInput ?? 0) : void 0;
+  const delta = {
+    input: args.endTokens.input - args.startTokens.input,
+    output: args.endTokens.output - args.startTokens.output,
+    ...cacheCreate !== void 0 ? { cacheCreationInput: cacheCreate } : {},
+    ...cacheRead !== void 0 ? { cacheReadInput: cacheRead } : {}
+  };
+  await writer.appendTurn({
+    turn: args.turn,
+    startedAt: args.startedAt,
+    completedAt,
+    durationMs: completedAt - args.startedAt,
+    tokensUsed: delta,
+    stopReason: args.stopReason,
+    toolCallsCount: args.toolCallsCount,
+    ...cacheCreate !== void 0 ? { cacheCreationInput: cacheCreate } : {},
+    ...cacheRead !== void 0 ? { cacheReadInput: cacheRead } : {}
+  });
+}
 var DEFAULT_COMPACTION = {
   strategy: "drop-middle",
   threshold: 0.85,
@@ -3067,6 +3104,8 @@ async function agentLoop(options) {
   };
   for (; ; ) {
     compactedThisTurn = false;
+    const turnStartedAt = Date.now();
+    const turnStartTokens = { ...ctx.getTokensUsed() };
     if (options.runSignal?.aborted === true) {
       return failed(new RunTimeoutError(options.runTimeoutMs ?? 0), transcript);
     }
@@ -3076,6 +3115,12 @@ async function agentLoop(options) {
     if (options.tokenBudget !== void 0) {
       const used = ctx.getTokensUsed();
       if (used.input + used.output >= options.tokenBudget) {
+        await options.inspect?.appendEvent({
+          type: "budget_hit",
+          totalTokens: used.input + used.output,
+          budget: options.tokenBudget,
+          ts: Date.now()
+        });
         return {
           status: "done",
           output: lastAssistantText || "[Token budget exhausted]",
@@ -3120,6 +3165,19 @@ async function agentLoop(options) {
     });
     if (compactResult.compacted) {
       messages = compactResult.messages;
+      const used = ctx.getTokensUsed();
+      const total = used.input + used.output;
+      const ratio = total / contextLimit;
+      const dropped = compactResult.result?.dropped ?? 0;
+      await options.inspect?.appendEvent({
+        type: "compaction_threshold",
+        turn: ctx.getTurnCount(),
+        ratio,
+        threshold: compactionConfig.threshold,
+        strategy: compactResult.result?.strategy ?? compactionConfig.strategy,
+        dropped,
+        ts: Date.now()
+      });
     }
     await fireProgress("streaming");
     const textBlocks = [];
@@ -3132,13 +3190,21 @@ async function agentLoop(options) {
       turnCount: ctx.getTurnCount(),
       maxTurns: ctx.getMaxTurns()
     })) {
+      const instruction = lastTurnInstruction(options.outputFormat);
       messagesForApi = [
         ...messages,
         {
           role: "user",
-          content: [{ type: "text", text: lastTurnInstruction(options.outputFormat) }]
+          content: [{ type: "text", text: instruction }]
         }
       ];
+      await options.inspect?.appendEvent({
+        type: "last_turn_guard",
+        turn: ctx.getTurnCount(),
+        outputFormat: options.outputFormat ?? "text",
+        instruction,
+        ts: Date.now()
+      });
     }
     const normalizedMessages = normalizeMessages(
       messagesForApi
@@ -3173,6 +3239,13 @@ async function agentLoop(options) {
           system
         });
         if (emergency.compacted) {
+          await options.inspect?.appendEvent({
+            type: "compaction_413",
+            turn: ctx.getTurnCount(),
+            droppedMessages: messages.length - emergency.messages.length,
+            strategy: compactionConfig.strategy,
+            ts: Date.now()
+          });
           ctx.rehydrate({
             messages: emergency.messages,
             turnCount: ctx.getTurnCount(),
@@ -3200,6 +3273,14 @@ async function agentLoop(options) {
         }
         const retryAfter = err instanceof RateLimitError && err.retryAfterMs ? err.retryAfterMs : BASE_BACKOFF_MS * Math.pow(2, apiRetryCount - 1);
         const delay = Math.min(retryAfter, 3e4);
+        await options.inspect?.appendEvent({
+          type: "api_retry",
+          turn: ctx.getTurnCount(),
+          status: err instanceof Error && "status" in err ? err.status ?? null : null,
+          attempt: apiRetryCount,
+          delayMs: delay,
+          ts: Date.now()
+        });
         await new Promise((r) => setTimeout(r, delay));
         continue;
       }
@@ -3282,16 +3363,31 @@ async function agentLoop(options) {
       const firstTool = toolCallsToDispatch[0]?.name;
       await fireProgress("tool_dispatch", firstTool);
       const streamExec = new StreamingToolExecutor(executor);
+      let anyConcurrent = false;
       for (const call of toolCallsToDispatch) {
         const tool = options.registry?.get(call.name);
         const safe = tool?.isConcurrencySafe?.(call.input) ?? false;
+        if (safe) anyConcurrent = true;
         streamExec.addTool(call.id, call.name, call.input, safe);
       }
+      await options.inspect?.appendEvent({
+        type: "tool_batch",
+        turn: ctx.getTurnCount(),
+        toolNames: toolCallsToDispatch.map((c) => c.name),
+        concurrent: anyConcurrent && toolCallsToDispatch.length > 1,
+        ts: Date.now()
+      });
       try {
         for await (const { id, result } of streamExec.results()) {
           const missing = result.metadata?.capabilityMissing;
           if (typeof missing === "string") {
             ctx.recordCapabilityMissing(missing);
+            await options.inspect?.appendEvent({
+              type: "capability_stub",
+              turn: ctx.getTurnCount(),
+              toolName: missing,
+              ts: Date.now()
+            });
           }
           const call = toolCallsToDispatch.find((c) => c.id === id);
           let contentForTranscript;
@@ -3351,6 +3447,15 @@ async function agentLoop(options) {
       apiRetryCount = 0;
       consecutive529 = 0;
       await ctx.endTurn();
+      await emitInspectTurn({
+        inspect: options.inspect,
+        turn: ctx.getTurnCount() - 1,
+        startedAt: turnStartedAt,
+        startTokens: turnStartTokens,
+        endTokens: ctx.getTokensUsed(),
+        stopReason,
+        toolCallsCount: toolCallsToDispatch.length
+      });
       await fireProgress("idle");
       if (options.postTurnHooks && options.postTurnHooks.length > 0) {
         await dispatchHooks(options.postTurnHooks, {
@@ -3382,6 +3487,15 @@ async function agentLoop(options) {
       continue;
     }
     await ctx.endTurn();
+    await emitInspectTurn({
+      inspect: options.inspect,
+      turn: ctx.getTurnCount() - 1,
+      startedAt: turnStartedAt,
+      startTokens: turnStartTokens,
+      endTokens: ctx.getTokensUsed(),
+      stopReason,
+      toolCallsCount: 0
+    });
     if (options.postTurnHooks && options.postTurnHooks.length > 0) {
       await dispatchHooks(options.postTurnHooks, {
         runId: ctx.runId,
@@ -3408,11 +3522,25 @@ async function agentLoop(options) {
       if (!maxTokensEscalated) {
         maxTokensEscalated = true;
         escalatedMaxTokens = ESCALATED_MAX_TOKENS;
+        await options.inspect?.appendEvent({
+          type: "recovery_max_tokens",
+          turn: ctx.getTurnCount(),
+          attempt: 0,
+          escalatedTo: ESCALATED_MAX_TOKENS,
+          ts: Date.now()
+        });
         continue;
       }
       if (recoveryCount < MAX_OUTPUT_TOKENS_RECOVERY_LIMIT) {
         recoveryCount++;
         escalatedMaxTokens = void 0;
+        await options.inspect?.appendEvent({
+          type: "recovery_max_tokens",
+          turn: ctx.getTurnCount(),
+          attempt: recoveryCount,
+          escalatedTo: 0,
+          ts: Date.now()
+        });
         await ctx.addUserMessage(
           "Output token limit hit. Resume directly \u2014 no apology, no recap of what you were doing. Pick up mid-thought if that is where the cut happened. Break remaining work into smaller pieces."
         );
@@ -4408,25 +4536,45 @@ If omitted, defaults to "${defaultAgent.name}".`;
         const lastAssistant = [...parentMsgs].reverse().find((m) => m.role === "assistant");
         const assistantContent = lastAssistant ? Array.isArray(lastAssistant.content) ? lastAssistant.content : [] : [];
         const forkedMsgs = buildForkedMessages(taskDescription, assistantContent);
-        const result2 = await runAgent({
-          agentId: spawn2.agentId,
-          description: taskDescription,
-          storage: options.storage,
-          client: options.client,
-          registry: options.childRegistry,
-          parentLogPath: options.parentLogPath,
-          system: options.system,
-          // inherit parent's system prompt
-          maxTurns: options.maxTurns,
-          contextLimit: options.contextLimit,
-          turnTimeoutMs: options.turnTimeoutMs,
-          flushPolicy: options.flushPolicy,
-          idleFlushMs: options.idleFlushMs,
-          // Fork: prepend parent messages + forked messages
-          prependMessages: [...parentMsgs, ...forkedMsgs],
-          ...options.gateBeforeTool !== void 0 ? { gateBeforeTool: options.gateBeforeTool } : {},
-          ...options.toolResultOffload !== void 0 ? { toolResultOffload: options.toolResultOffload } : {}
-        });
+        let result2;
+        try {
+          result2 = await runAgent({
+            agentId: spawn2.agentId,
+            description: taskDescription,
+            storage: options.storage,
+            client: options.client,
+            registry: options.childRegistry,
+            parentLogPath: options.parentLogPath,
+            system: options.system,
+            // inherit parent's system prompt
+            maxTurns: options.maxTurns,
+            contextLimit: options.contextLimit,
+            turnTimeoutMs: options.turnTimeoutMs,
+            flushPolicy: options.flushPolicy,
+            idleFlushMs: options.idleFlushMs,
+            // Fork: prepend parent messages + forked messages
+            prependMessages: [...parentMsgs, ...forkedMsgs],
+            ...options.gateBeforeTool !== void 0 ? { gateBeforeTool: options.gateBeforeTool } : {},
+            ...options.toolResultOffload !== void 0 ? { toolResultOffload: options.toolResultOffload } : {}
+          });
+          await options.inspect?.appendEvent({
+            type: "subagent_spawn_attempt",
+            agentId: spawn2.agentId,
+            subagentType: "fork",
+            success: true,
+            ts: Date.now()
+          });
+        } catch (err) {
+          await options.inspect?.appendEvent({
+            type: "subagent_spawn_attempt",
+            agentId: spawn2.agentId,
+            subagentType: "fork",
+            success: false,
+            error: err instanceof Error ? err.message : String(err),
+            ts: Date.now()
+          });
+          throw err;
+        }
         handlePausedResult(result2, spawn2.agentId, "fork");
         const t2 = result2;
         options.subagentRegistry.setStatus(spawn2.agentId, t2.isError ? "stopped" : "completed");
@@ -4480,7 +4628,7 @@ If omitted, defaults to "${defaultAgent.name}".`;
       const shouldRunAsync = run_in_background === true || options.coordinatorMode === true;
       if (shouldRunAsync) {
         options.subagentRegistry.setBackground(spawn.agentId);
-        const bgPromise = runAgent(runOpts).then((result2) => {
+        const bgPromise = runAgent(runOpts).then(async (result2) => {
           if (result2.kind !== "terminal") {
             options.subagentRegistry.setStatus(spawn.agentId, "stopped");
             options.subagentRegistry.setBackgroundResult(spawn.agentId, {
@@ -4489,6 +4637,14 @@ If omitted, defaults to "${defaultAgent.name}".`;
               isError: true,
               description: taskDescription
             });
+            await options.inspect?.appendEvent({
+              type: "subagent_spawn_attempt",
+              agentId: spawn.agentId,
+              subagentType: typeName ?? "unknown",
+              success: false,
+              error: "background subagent paused (pause not supported for async)",
+              ts: Date.now()
+            });
             return;
           }
           options.subagentRegistry.setStatus(
@@ -4501,7 +4657,15 @@ If omitted, defaults to "${defaultAgent.name}".`;
             isError: result2.isError,
             description: taskDescription
           });
-        }).catch((err) => {
+          await options.inspect?.appendEvent({
+            type: "subagent_spawn_attempt",
+            agentId: spawn.agentId,
+            subagentType: typeName ?? "unknown",
+            success: !result2.isError,
+            ...result2.isError ? { error: "child returned isError" } : {},
+            ts: Date.now()
+          });
+        }).catch(async (err) => {
           options.subagentRegistry.setStatus(spawn.agentId, "stopped");
           options.subagentRegistry.setBackgroundResult(spawn.agentId, {
             agentId: spawn.agentId,
@@ -4509,6 +4673,14 @@ If omitted, defaults to "${defaultAgent.name}".`;
             isError: true,
             description: taskDescription
           });
+          await options.inspect?.appendEvent({
+            type: "subagent_spawn_attempt",
+            agentId: spawn.agentId,
+            subagentType: typeName ?? "unknown",
+            success: false,
+            error: err instanceof Error ? err.message : String(err),
+            ts: Date.now()
+          });
         });
         options.subagentRegistry.setBackgroundPromise(spawn.agentId, bgPromise);
         return {
@@ -4524,7 +4696,27 @@ Use SendMessage with to: '${spawn.agentId}' to communicate with this agent.`,
           }
         };
       }
-      const result = await runAgent(runOpts);
+      let result;
+      try {
+        result = await runAgent(runOpts);
+        await options.inspect?.appendEvent({
+          type: "subagent_spawn_attempt",
+          agentId: spawn.agentId,
+          subagentType: typeName ?? "unknown",
+          success: true,
+          ts: Date.now()
+        });
+      } catch (err) {
+        await options.inspect?.appendEvent({
+          type: "subagent_spawn_attempt",
+          agentId: spawn.agentId,
+          subagentType: typeName ?? "unknown",
+          success: false,
+          error: err instanceof Error ? err.message : String(err),
+          ts: Date.now()
+        });
+        throw err;
+      }
       handlePausedResult(result, spawn.agentId, typeName);
       const t = result;
       options.subagentRegistry.setStatus(spawn.agentId, t.isError ? "stopped" : "completed");
@@ -4727,6 +4919,7 @@ function createSendMessageTool(options) {
 
 // src/engine/engine.ts
 init_contract();
+var import_zod_to_json_schema4 = require("zod-to-json-schema");
 
 // src/tools/fileEdit.ts
 init_cjs_shims();
@@ -6858,7 +7051,7 @@ init_contract();
 function mcpToolName(serverName, toolName) {
   return `mcp__${serverName}__${toolName}`;
 }
-function adaptMcpTool(client, serverName, def) {
+function adaptMcpTool(client, serverName, def, opts) {
   const registeredName = mcpToolName(serverName, def.name);
   return defineTool({
     name: registeredName,
@@ -6868,6 +7061,9 @@ function adaptMcpTool(client, serverName, def) {
     // bypassing Zod-to-JSON-Schema conversion (which would produce `{}`
     // for our `z.unknown()` Zod schema).
     anthropicSchemaOverride: def.inputSchema,
+    // Plan 027 — stdio servers spawn subprocesses; flag so the engine's
+    // capability-stub wrapper can swap them on Workers.
+    ...opts.transport === "stdio" ? { requiresNode: true } : {},
     execute: async (input) => {
       try {
         const result = await client.callTool(def.name, input);
@@ -6911,6 +7107,8 @@ var McpManager = class {
     this.logger = logger;
     this.servers = Object.entries(config.servers).map(([name, serverConfig]) => ({
       name,
+      // Plan 027 — capture transport for the stdio-handoff wiring.
+      transport: serverConfig.type,
       client: new McpClient({
         serverName: name,
         config: serverConfig,
@@ -7050,7 +7248,9 @@ var McpManager = class {
     try {
       await server.client.connect();
       const defs = server.client.listTools();
-      server.tools = defs.map((def) => adaptMcpTool(server.client, server.name, def));
+      server.tools = defs.map(
+        (def) => adaptMcpTool(server.client, server.name, def, { transport: server.transport })
+      );
       server.state = "connected";
       this.pendingConnected.push(server.name);
     } catch (err) {
@@ -9721,6 +9921,198 @@ function applyRunToolFilter(registry, options) {
   }
 }
 
+// src/inspect/writer.ts
+init_cjs_shims();
+var InspectWriter = class {
+  storage;
+  logger;
+  enabled;
+  /** Subdirectory holding all inspect files. Constant per writer. */
+  dir;
+  constructor(opts) {
+    this.storage = opts.storage;
+    if (opts.logger !== void 0) this.logger = opts.logger;
+    this.enabled = opts.enabled;
+    this.dir = `${opts.logPath}/inspect`;
+  }
+  /**
+   * Write the eight start-snapshot files atomically (well, sequentially —
+   * R2 has no multi-object atomic; failures partially-write and the
+   * fail-soft path logs each one).
+   */
+  async writeStartSnapshot(input) {
+    if (!this.enabled) return;
+    await this.safeWrite("system-prompt.txt", input.systemPrompt);
+    await this.safeWriteJson("tools.json", input.tools);
+    await this.safeWriteJson("run-options.json", input.runOptions);
+    await this.safeWriteJson("model-config.json", input.modelConfig);
+    if (input.skills !== void 0) {
+      await this.safeWriteJson("skills.json", input.skills);
+    }
+    if (input.mcpServers !== void 0) {
+      await this.safeWriteJson("mcp-servers.json", input.mcpServers);
+    }
+    if (input.apiServices !== void 0) {
+      await this.safeWriteJson("api-services.json", input.apiServices);
+    }
+    if (input.knowledge !== void 0) {
+      await this.safeWriteJson("knowledge-scope.json", input.knowledge);
+    }
+  }
+  /** Append one event line to events.jsonl. */
+  async appendEvent(event) {
+    if (!this.enabled) return;
+    await this.safeAppend("events.jsonl", JSON.stringify(event) + "\n");
+  }
+  /** Append one row to turns.jsonl. */
+  async appendTurn(row) {
+    if (!this.enabled) return;
+    await this.safeAppend("turns.jsonl", JSON.stringify(row) + "\n");
+  }
+  /** Write the terminal `tools-summary.json` once at run end. */
+  async writeToolsSummary(summary) {
+    if (!this.enabled) return;
+    await this.safeWriteJson("tools-summary.json", summary);
+  }
+  // ---------- private fail-soft helpers ----------
+  async safeWrite(name, content) {
+    try {
+      await this.storage.writeFile(`${this.dir}/${name}`, content);
+    } catch (err) {
+      this.logFailure("writeFile", name, err);
+    }
+  }
+  async safeWriteJson(name, value) {
+    try {
+      await this.storage.writeFile(`${this.dir}/${name}`, JSON.stringify(value, null, 2));
+    } catch (err) {
+      this.logFailure("writeFile (json)", name, err);
+    }
+  }
+  async safeAppend(name, line) {
+    try {
+      await this.storage.appendFile(`${this.dir}/${name}`, line);
+    } catch (err) {
+      this.logFailure("appendFile", name, err);
+    }
+  }
+  logFailure(op, name, err) {
+    if (this.logger === void 0) return;
+    const msg = err instanceof Error ? err.message : String(err);
+    this.logger.warn?.("inspect-writer failed", {
+      op,
+      file: `${this.dir}/${name}`,
+      error: msg
+    });
+  }
+};
+var NULL_INSPECT_WRITER = {
+  writeStartSnapshot: async () => void 0,
+  appendEvent: async () => void 0,
+  appendTurn: async () => void 0,
+  writeToolsSummary: async () => void 0
+};
+
+// src/inspect/scrub.ts
+init_cjs_shims();
+var import_zod_to_json_schema3 = require("zod-to-json-schema");
+function scrubModelConfig(cfg, opts = { redactBaseURL: false }) {
+  const out = {
+    schemaVersion: 1,
+    provider: cfg.provider,
+    modelId: cfg.modelId
+  };
+  if (!opts.redactBaseURL && cfg.baseURL !== void 0) out.baseURL = cfg.baseURL;
+  if (cfg.temperature !== void 0) out.temperature = cfg.temperature;
+  if (cfg.maxTokens !== void 0) out.maxTokens = cfg.maxTokens;
+  if (cfg.maxRetries !== void 0) out.maxRetries = cfg.maxRetries;
+  return out;
+}
+function scrubRunOptions(opts) {
+  const out = {
+    schemaVersion: 1,
+    runId: opts.runId ?? "",
+    nodeId: opts.nodeId,
+    task: opts.task
+  };
+  if (opts.maxTurns !== void 0) out.maxTurns = opts.maxTurns;
+  if (opts.outputFormat !== void 0) out.outputFormat = opts.outputFormat;
+  if (opts.outputSchema !== void 0) out.outputSchema = serializeOutputSchema(opts.outputSchema);
+  if (opts.tools !== void 0) out.tools = [...opts.tools];
+  if (opts.toolChoice !== void 0) out.toolChoice = opts.toolChoice;
+  if (opts.tokenBudget !== void 0) out.tokenBudget = opts.tokenBudget;
+  if (opts.knowledge !== void 0) {
+    const k = {};
+    if (opts.knowledge.folders !== void 0) k.folders = [...opts.knowledge.folders];
+    if (opts.knowledge.external !== void 0) {
+      k.external = opts.knowledge.external.map((e) => {
+        const link = { url: e.url };
+        if (e.description !== void 0) link.description = e.description;
+        return link;
+      });
+    }
+    out.knowledge = k;
+  }
+  if (opts.api !== void 0 && opts.api.services !== void 0) {
+    out.api = {
+      services: opts.api.services.map((s) => {
+        const svc = { name: s.name };
+        if (s.description !== void 0) svc.description = s.description;
+        if (s.baseUrl !== void 0) svc.baseUrl = s.baseUrl;
+        return svc;
+      })
+    };
+  }
+  if (opts.skills !== void 0) {
+    out.skills = opts.skills.map((s) => ({
+      name: s.name,
+      description: s.description ?? "",
+      hasBody: "body" in s && typeof s.body === "string",
+      hasUrl: "url" in s && typeof s.url === "string"
+    }));
+  }
+  if (opts.compaction !== void 0) out.compaction = opts.compaction;
+  if (opts.context !== void 0) out.context = { ...opts.context };
+  return out;
+}
+function serializeOutputSchema(schema) {
+  if (schema === null || typeof schema !== "object") return schema;
+  const candidate = schema;
+  if (candidate._def !== void 0 && typeof candidate.safeParse === "function") {
+    try {
+      return (0, import_zod_to_json_schema3.zodToJsonSchema)(schema, {
+        target: "jsonSchema7",
+        $refStrategy: "none"
+      });
+    } catch {
+      return { error: "failed to serialize Zod schema for inspect" };
+    }
+  }
+  return schema;
+}
+function scrubSkills(skills) {
+  return {
+    schemaVersion: 1,
+    skills: skills.map((s) => ({
+      name: s.name,
+      description: s.description ?? "",
+      hasPages: s.hasPages ?? false
+    }))
+  };
+}
+function scrubApiServices(services) {
+  return {
+    schemaVersion: 1,
+    services: services.map((s) => {
+      const out = { name: s.name };
+      if (s.description !== void 0) out.description = s.description;
+      if (s.baseUrl !== void 0) out.baseUrl = s.baseUrl;
+      if (s.methods !== void 0) out.methods = s.methods.map((m) => m.name);
+      return out;
+    })
+  };
+}
+
 // src/engine/rehydrate.ts
 init_cjs_shims();
 function rebuildMessagesFromEntries(entries) {
@@ -10179,6 +10571,7 @@ var Engine = class {
       systemPrompt += "\n\n" + buildSchemaPrompt(options.outputSchema);
     }
     const gate = this.resolveGate();
+    const inspect = this.buildInspectWriter(storage.workspace, logPath);
     const registry = buildToolRegistry({
       config: this.config,
       storage,
@@ -10190,6 +10583,7 @@ var Engine = class {
       agents,
       mcpTools,
       memory,
+      inspect,
       ...this.config.hooks.propagateGateToSubagents === true && gate !== void 0 ? { subagentGate: gate } : {},
       ...skillSource !== void 0 ? { skillSource } : {},
       ...apiConfig !== void 0 ? { apiConfig } : {},
@@ -10198,6 +10592,36 @@ var Engine = class {
       ...this.internals.fetch !== void 0 ? { fetch: this.internals.fetch } : {}
     });
     applyRunToolFilter(registry, options);
+    await inspect.writeStartSnapshot({
+      systemPrompt,
+      tools: this.snapshotTools(registry, mcpTools),
+      runOptions: scrubRunOptions({ ...options, runId }),
+      modelConfig: scrubModelConfig(
+        {
+          provider: this.config.model.provider,
+          modelId: this.config.model.modelId,
+          ...this.config.model.baseURL !== void 0 ? { baseURL: this.config.model.baseURL } : {},
+          ...this.config.model.temperature !== void 0 ? { temperature: this.config.model.temperature } : {},
+          ...this.config.model.maxTokens !== void 0 ? { maxTokens: this.config.model.maxTokens } : {},
+          ...this.config.model.maxRetries !== void 0 ? { maxRetries: this.config.model.maxRetries } : {}
+        },
+        { redactBaseURL: this.config.inspect.redactBaseURL }
+      ),
+      ...skillList !== void 0 ? { skills: scrubSkills(skillList) } : {},
+      ...mcpTools.length > 0 ? { mcpServers: this.snapshotMcpServers(mcpTools) } : {},
+      ...apiConfig !== void 0 && apiConfig.services.length > 0 ? { apiServices: scrubApiServices(apiConfig.services) } : {},
+      ...knowledgeRuntime !== void 0 ? {
+        knowledge: {
+          schemaVersion: 1,
+          folders: [...knowledgeRuntime.folders],
+          external: knowledgeRuntime.external.map((e) => {
+            const link = { url: e.url };
+            if (e.description !== void 0) link.description = e.description;
+            return link;
+          })
+        }
+      } : {}
+    });
     const writer = new TranscriptWriter({
       storage: storage.workspace,
       logPath,
@@ -10259,14 +10683,24 @@ var Engine = class {
         // is already handled above by stripping the tool list, so the
         // loop only ever sees `'auto'` or `'required'`.
         ...options.outputFormat !== void 0 ? { outputFormat: options.outputFormat } : {},
-        ...options.toolChoice === "required" ? { toolChoice: "required" } : {}
-      });
-      const result = await this.finalizeResult(loopResult, writer, logPath, {
-        ...options.outputFormat !== void 0 ? { outputFormat: options.outputFormat } : {},
-        ...options.outputSchema !== void 0 ? { outputSchema: options.outputSchema } : {}
+        ...options.toolChoice === "required" ? { toolChoice: "required" } : {},
+        // Plan 026 — pass the inspect writer so the loop can append
+        // events / per-turn rows. Disabled-mode writer is a no-op.
+        inspect
       });
+      const result = await this.finalizeResult(
+        loopResult,
+        writer,
+        logPath,
+        {
+          ...options.outputFormat !== void 0 ? { outputFormat: options.outputFormat } : {},
+          ...options.outputSchema !== void 0 ? { outputSchema: options.outputSchema } : {}
+        },
+        inspect
+      );
       this.logRunEnd(log, runId, options.nodeId, result);
       await this.firePostRunHook(runId, options.nodeId, result, ctx, logPath);
+      await this.writeInspectToolsSummary(inspect, storage.workspace, logPath);
       const capabilitiesMissing = ctx.getCapabilitiesMissing();
       return toResponse(result, {
         runId,
@@ -10334,6 +10768,7 @@ var Engine = class {
       systemPrompt += "\n\n" + buildSchemaPrompt(options.outputSchema);
     }
     const gate = this.resolveGate();
+    const inspect = this.buildInspectWriter(storage.workspace, logPath);
     const registry = buildToolRegistry({
       config: this.config,
       storage,
@@ -10345,6 +10780,7 @@ var Engine = class {
       agents,
       mcpTools,
       memory,
+      inspect,
       ...this.config.hooks.propagateGateToSubagents === true && gate !== void 0 ? { subagentGate: gate } : {},
       ...skillSource !== void 0 ? { skillSource } : {},
       ...apiConfig !== void 0 ? { apiConfig } : {},
@@ -10352,6 +10788,42 @@ var Engine = class {
       ...knowledgeRuntime !== void 0 ? { knowledge: knowledgeRuntime } : {},
       ...this.internals.fetch !== void 0 ? { fetch: this.internals.fetch } : {}
     });
+    await inspect.writeStartSnapshot({
+      systemPrompt,
+      tools: this.snapshotTools(registry, mcpTools),
+      runOptions: scrubRunOptions({
+        runId: snapshot.runId,
+        nodeId: snapshot.nodeId,
+        task: "[resumed run \u2014 original task in transcript]",
+        ...options.outputFormat !== void 0 ? { outputFormat: options.outputFormat } : {},
+        ...options.outputSchema !== void 0 ? { outputSchema: options.outputSchema } : {}
+      }),
+      modelConfig: scrubModelConfig(
+        {
+          provider: this.config.model.provider,
+          modelId: this.config.model.modelId,
+          ...this.config.model.baseURL !== void 0 ? { baseURL: this.config.model.baseURL } : {},
+          ...this.config.model.temperature !== void 0 ? { temperature: this.config.model.temperature } : {},
+          ...this.config.model.maxTokens !== void 0 ? { maxTokens: this.config.model.maxTokens } : {},
+          ...this.config.model.maxRetries !== void 0 ? { maxRetries: this.config.model.maxRetries } : {}
+        },
+        { redactBaseURL: this.config.inspect.redactBaseURL }
+      ),
+      ...skillList !== void 0 ? { skills: scrubSkills(skillList) } : {},
+      ...mcpTools.length > 0 ? { mcpServers: this.snapshotMcpServers(mcpTools) } : {},
+      ...apiConfig !== void 0 && apiConfig.services.length > 0 ? { apiServices: scrubApiServices(apiConfig.services) } : {},
+      ...knowledgeRuntime !== void 0 ? {
+        knowledge: {
+          schemaVersion: 1,
+          folders: [...knowledgeRuntime.folders],
+          external: knowledgeRuntime.external.map((e) => {
+            const link = { url: e.url };
+            if (e.description !== void 0) link.description = e.description;
+            return link;
+          })
+        }
+      } : {}
+    });
     const priorState = await loadWriterState(storage.workspace, logPath);
     const writer = new TranscriptWriter({
       storage: storage.workspace,
@@ -10441,14 +10913,24 @@ ${inputJson}
         ...runTimeout.signal !== void 0 ? { runSignal: runTimeout.signal, runTimeoutMs: this.config.execution.runTimeoutMs } : {},
         ...gate !== void 0 ? { gateBeforeTool: gate } : {},
         ..._internal?.handoffToRunner === true ? { handoffToRunner: true } : {},
-        ...offloadConfig !== void 0 ? { toolResultOffload: offloadConfig } : {}
-      });
-      const result = await this.finalizeResult(loopResult, writer, logPath, {
-        ...options.outputFormat !== void 0 ? { outputFormat: options.outputFormat } : {},
-        ...options.outputSchema !== void 0 ? { outputSchema: options.outputSchema } : {}
+        ...offloadConfig !== void 0 ? { toolResultOffload: offloadConfig } : {},
+        // Plan 026 — append resume's events / per-turn rows to the
+        // existing inspect/ logs.
+        inspect
       });
+      const result = await this.finalizeResult(
+        loopResult,
+        writer,
+        logPath,
+        {
+          ...options.outputFormat !== void 0 ? { outputFormat: options.outputFormat } : {},
+          ...options.outputSchema !== void 0 ? { outputSchema: options.outputSchema } : {}
+        },
+        inspect
+      );
       this.logRunEnd(log, snapshot.runId, snapshot.nodeId, result);
       await this.firePostRunHook(snapshot.runId, snapshot.nodeId, result, ctx, logPath);
+      await this.writeInspectToolsSummary(inspect, storage.workspace, logPath);
       const capabilitiesMissing = ctx.getCapabilitiesMissing();
       return toResponse(result, {
         runId: snapshot.runId,
@@ -11096,7 +11578,7 @@ ${inputJson}
     };
     await dispatchHooks(this.config.hooks.postRun, event);
   }
-  async finalizeResult(loopResult, writer, _logPath, jsonOptions) {
+  async finalizeResult(loopResult, writer, _logPath, jsonOptions, inspect) {
     if (loopResult.status === "done") {
       await writer.setStatus("done");
       let data;
@@ -11105,10 +11587,27 @@ ${inputJson}
         if (parsed.ok) {
           if (jsonOptions.outputSchema) {
             const validated = validateOutput(parsed.value, jsonOptions.outputSchema);
-            data = validated.ok ? validated.data : void 0;
+            if (validated.ok) {
+              data = validated.data;
+            } else {
+              await inspect?.appendEvent({
+                type: "json_parse_failure",
+                turn: loopResult.turns,
+                validationError: validated.error,
+                ts: Date.now()
+              });
+              data = void 0;
+            }
           } else {
             data = parsed.value;
           }
+        } else {
+          await inspect?.appendEvent({
+            type: "json_parse_failure",
+            turn: loopResult.turns,
+            parseError: parsed.error ?? "unknown parse error",
+            ts: Date.now()
+          });
         }
       }
       return {
@@ -11292,7 +11791,147 @@ ${inputJson}
       ...this.internals.fetch !== void 0 ? { fetch: this.internals.fetch } : {}
     });
   }
+  // Plan 026 — inspect-bundle helpers ----------------------------
+  buildInspectWriter(storage, logPath) {
+    const inspect = this.config.inspect;
+    return new InspectWriter({
+      storage,
+      logPath,
+      enabled: inspect.enabled
+    });
+  }
+  /**
+   * Snapshot the live ToolRegistry into the inspect-bundle shape.
+   * Tool source is inferred by name: MCP tools have the
+   * `mcp__{server}__{tool}` prefix; everything else is core.
+   */
+  snapshotTools(registry, mcpTools) {
+    const mcpNameSet = new Set(mcpTools.map((t) => t.name));
+    return {
+      schemaVersion: 1,
+      tools: registry.list().map((t) => {
+        const out = {
+          name: t.name,
+          description: t.description ?? "",
+          inputSchema: this.toolInputSchemaToJson(t),
+          source: mcpNameSet.has(t.name) ? "mcp" : "core",
+          ...t.isCapabilityStub === true ? { isCapabilityStub: true } : {}
+        };
+        return out;
+      })
+    };
+  }
+  /** Convert a Zod input schema to JSON Schema for persistence. */
+  toolInputSchemaToJson(t) {
+    const raw = t.inputSchema;
+    if (raw === void 0 || raw === null) return {};
+    const candidate = raw;
+    if (typeof candidate === "object" && candidate._def !== void 0 && typeof candidate.safeParse === "function") {
+      try {
+        const json2 = (0, import_zod_to_json_schema4.zodToJsonSchema)(raw, {
+          target: "jsonSchema7",
+          $refStrategy: "none"
+        });
+        return json2;
+      } catch {
+        return {};
+      }
+    }
+    return raw;
+  }
+  /**
+   * Plan 026 — aggregate `tools-summary.json` from the persisted
+   * transcript shards. Walks meta.json for shard count, reads each
+   * shard, counts every tool_use block by name. Best-effort; the
+   * InspectWriter swallows write failures.
+   */
+  async writeInspectToolsSummary(inspect, storage, logPath) {
+    const counts = /* @__PURE__ */ new Map();
+    let total = 0;
+    try {
+      const metaRaw = await storage.readFile(`${logPath}/meta.json`);
+      if (!metaRaw) return;
+      const meta = JSON.parse(metaRaw);
+      const shardCount = meta.shardCount ?? 0;
+      for (let i = 0; i < shardCount; i++) {
+        const name = `${String(i).padStart(6, "0")}.jsonl`;
+        const text2 = await storage.readFile(`${logPath}/${name}`);
+        if (!text2) continue;
+        for (const line of text2.split("\n")) {
+          if (!line) continue;
+          try {
+            const entry = JSON.parse(line);
+            if (entry.type !== "assistant") continue;
+            const content = entry.message?.content;
+            if (!Array.isArray(content)) continue;
+            for (const block of content) {
+              const b = block;
+              if (b.type === "tool_use" && typeof b.name === "string") {
+                counts.set(b.name, (counts.get(b.name) ?? 0) + 1);
+                total++;
+              }
+            }
+          } catch {
+          }
+        }
+      }
+    } catch {
+      return;
+    }
+    await inspect.writeToolsSummary({
+      schemaVersion: 1,
+      tools: [...counts.entries()].map(([name, callCount]) => ({ name, callCount })).sort((a, b) => b.callCount - a.callCount),
+      totalCalls: total
+    });
+  }
+  /**
+   * Snapshot the resolved MCP servers. Right now `mcpManager.getTools()`
+   * returns the flat tool list; we group them by server-name prefix to
+   * recover which server exposed which tool.
+   */
+  snapshotMcpServers(mcpTools) {
+    const byServer = /* @__PURE__ */ new Map();
+    for (const t of mcpTools) {
+      const m = t.name.match(/^mcp__([^_]+)__(.+)$/);
+      const server = m?.[1] ?? "unknown";
+      const list = byServer.get(server) ?? [];
+      list.push(t.name);
+      byServer.set(server, list);
+    }
+    const declaredMap = this.config.mcp.servers;
+    return {
+      schemaVersion: 1,
+      servers: [...byServer.entries()].map(([name, tools]) => {
+        const declared = declaredMap[name];
+        const out = {
+          name,
+          // If the server isn't in the declared map (synthetic / dynamic),
+          // default to 'http' as a best-effort label.
+          type: declared?.type ?? "http",
+          state: "connected",
+          tools
+        };
+        if (declared !== void 0) {
+          if (declared.type === "stdio") {
+            out.command = declared.command;
+            out.args = [...declared.args];
+          } else {
+            out.url = declared.url;
+            if (declared.headers !== void 0) {
+              out.headers = redactHeadersInline(declared.headers);
+            }
+          }
+        }
+        return out;
+      })
+    };
+  }
 };
+function redactHeadersInline(headers) {
+  const out = {};
+  for (const k of Object.keys(headers)) out[k] = "<redacted>";
+  return out;
+}
 function buildToolRegistry(options) {
   const {
     config,
@@ -11446,7 +12085,10 @@ function buildToolRegistry(options) {
     agents,
     coordinatorMode: isCoordinatorMode(config),
     ...subagentGate !== void 0 ? { gateBeforeTool: subagentGate } : {},
-    ...options.toolResultOffload !== void 0 ? { toolResultOffload: options.toolResultOffload } : {}
+    ...options.toolResultOffload !== void 0 ? { toolResultOffload: options.toolResultOffload } : {},
+    // Plan 026 — Agent tool emits subagent_spawn_attempt to the
+    // parent's events.jsonl on each runAgent call (success and failure).
+    ...options.inspect !== void 0 ? { inspect: options.inspect } : {}
   });
   if (!disabled.has("Agent") && (wantAll || enabled.has("Agent"))) {
     registry.register(agentTool);
@@ -11462,8 +12104,9 @@ function buildToolRegistry(options) {
   for (const tool of mcpTools) {
     if (disabled.has(tool.name)) continue;
     if (wantAll || enabled.has(tool.name)) {
-      registry.register(tool);
-      childRegistry.register(tool);
+      const wrapped = withCapabilityCheck(tool, spawnAvailable);
+      registry.register(wrapped);
+      childRegistry.register(wrapped);
     }
   }
   if (!disabled.has("ToolSearch") && (wantAll || enabled.has("ToolSearch"))) {
@@ -11483,6 +12126,11 @@ init_retry();
 init_snapshot();
 init_synthesize();
 init_types();
+
+// src/inspect/index.ts
+init_cjs_shims();
+
+// src/index.ts
 var ENGINE_VERSION = "0.0.0";
 function initEngine(user = {}) {
   let resolved;
@@ -11522,6 +12170,7 @@ function resolveApiKey(config) {
   EpisodicMemory,
   Hippocampus,
   InlineSkillSource,
+  InspectWriter,
   LocalStorageAdapter,
   MAX_ATTEMPTS,
   McpClient,
@@ -11529,6 +12178,7 @@ function resolveApiKey(config) {
   McpManager,
   McpProtocolError,
   McpTimeoutError,
+  NULL_INSPECT_WRITER,
   NodeBackgroundExecutor,
   NotImplementedError,
   PlanSchema,