la-machina-engine 0.7.3 → 0.7.5

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
@@ -1817,7 +1830,11 @@ var AnthropicClient = class {
       messages: request.messages,
       stream: true,
       ...request.system !== void 0 ? { system: request.system } : {},
-      ...request.tools !== void 0 ? { tools: request.tools } : {}
+      ...request.tools !== void 0 ? { tools: request.tools } : {},
+      // Plan 025 — `'required'` maps to Anthropic's `tool_choice: { type: 'any' }`,
+      // which forces the model to call SOME tool but doesn't pin which.
+      // `'auto'` is the SDK default — omit to let it through unchanged.
+      ...request.toolChoice === "required" ? { tool_choice: { type: "any" } } : {}
     };
     const requestOptions = {};
     if (betas.length > 0) {
@@ -1999,6 +2016,9 @@ var AISdkAdapter = class {
       tools,
       ...request.maxTokens !== void 0 ? { maxOutputTokens: request.maxTokens } : {},
       ...request.temperature !== void 0 ? { temperature: request.temperature } : {},
+      // Plan 025 — pass through `'required'` so the AI SDK forwards it
+      // to the provider as that provider's "force tool call" flag.
+      ...request.toolChoice === "required" ? { toolChoice: "required" } : {},
       maxRetries: this.options.maxRetries ?? 2
     });
     for await (const event of result.fullStream) {
@@ -2618,6 +2638,17 @@ function ensureToolResultPairing(messages) {
   return messages;
 }
 
+// src/engine/lastTurnGuard.ts
+init_cjs_shims();
+var LAST_TURN_INSTRUCTION_JSON = "SYSTEM NOTE: This is your final allowed turn. Emit ONLY the JSON object that satisfies the output schema in the system prompt. Do not call any more tools. Do not write any explanation, narration, or markdown \u2014 only the raw JSON.";
+var LAST_TURN_INSTRUCTION_TEXT = "SYSTEM NOTE: This is your final allowed turn. Stop calling tools and deliver your final answer now. The next turn will not happen.";
+function lastTurnInstruction(outputFormat) {
+  return outputFormat === "json" ? LAST_TURN_INSTRUCTION_JSON : LAST_TURN_INSTRUCTION_TEXT;
+}
+function shouldInjectLastTurnInstruction(opts) {
+  return opts.turnCount + 1 === opts.maxTurns;
+}
+
 // src/compact/compactor.ts
 init_cjs_shims();
 
@@ -3007,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,
@@ -3049,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);
     }
@@ -3058,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]",
@@ -3109,15 +3172,37 @@ async function agentLoop(options) {
     const toolCalls = [];
     let stopReason = null;
     let turnUsage = { input: 0, output: 0 };
+    let messagesForApi = messages;
+    if (shouldInjectLastTurnInstruction({
+      turnCount: ctx.getTurnCount(),
+      maxTurns: ctx.getMaxTurns()
+    })) {
+      const instruction = lastTurnInstruction(options.outputFormat);
+      messagesForApi = [
+        ...messages,
+        {
+          role: "user",
+          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(
-      messages
+      messagesForApi
     );
     try {
       for await (const event of client.streamMessage({
         messages: normalizedMessages,
         system,
         tools: anthropicTools,
-        ...escalatedMaxTokens !== void 0 ? { maxTokens: escalatedMaxTokens } : {}
+        ...escalatedMaxTokens !== void 0 ? { maxTokens: escalatedMaxTokens } : {},
+        ...options.toolChoice !== void 0 ? { toolChoice: options.toolChoice } : {}
       })) {
         const handled = consumeEvent(event);
         if (handled.text !== void 0) textBlocks.push(handled.text);
@@ -3141,6 +3226,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(),
@@ -3168,6 +3260,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;
       }
@@ -3319,6 +3419,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, {
@@ -3350,6 +3459,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,
@@ -3376,11 +3494,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."
         );
@@ -3668,6 +3800,9 @@ var RunContext = class {
   getTurnCount() {
     return this.turnCount;
   }
+  getMaxTurns() {
+    return this.maxTurns;
+  }
   getTokensUsed() {
     return this.tokensUsed;
   }
@@ -4692,6 +4827,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();
@@ -9657,6 +9793,227 @@ var TranscriptReader = class {
   }
 };
 
+// src/engine/runToolFilter.ts
+init_cjs_shims();
+function applyRunToolFilter(registry, options) {
+  const stripAll = options.toolChoice === "none" || options.tools !== void 0 && options.tools.length === 0;
+  if (stripAll) {
+    if (options.toolChoice === "required") {
+      throw new EngineError(
+        "ERR_TOOL_CHOICE_CONFLICT",
+        "toolChoice: 'required' is incompatible with an empty tool set (received tools: [] or toolChoice: 'none')."
+      );
+    }
+    for (const tool of registry.list()) {
+      registry.unregister(tool.name);
+    }
+    return;
+  }
+  if (options.tools === void 0) return;
+  const allow = new Set(options.tools);
+  for (const tool of registry.list()) {
+    if (!allow.has(tool.name)) registry.unregister(tool.name);
+  }
+  if (options.toolChoice === "required" && registry.count() === 0) {
+    throw new EngineError(
+      "ERR_TOOL_CHOICE_CONFLICT",
+      "toolChoice: 'required' was requested but no tools matched the per-run allowlist after applying config filters."
+    );
+  }
+}
+
+// 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) {
@@ -10133,6 +10490,38 @@ var Engine = class {
       ...knowledgeRuntime !== void 0 ? { knowledge: knowledgeRuntime } : {},
       ...this.internals.fetch !== void 0 ? { fetch: this.internals.fetch } : {}
     });
+    applyRunToolFilter(registry, options);
+    const inspect = this.buildInspectWriter(storage.workspace, logPath);
+    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,
@@ -10187,7 +10576,17 @@ var Engine = class {
         ...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 } : {}
+        ...offloadConfig !== void 0 ? { toolResultOffload: offloadConfig } : {},
+        // Plan 025 — output mode + tool-choice plumbed down so the
+        // last-turn guard picks the right instruction text and the
+        // model adapter can pass `'required'` to the provider. `'none'`
+        // 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" } : {},
+        // 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 } : {},
@@ -10195,6 +10594,7 @@ var Engine = class {
       });
       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,
@@ -10280,6 +10680,43 @@ var Engine = class {
       ...knowledgeRuntime !== void 0 ? { knowledge: knowledgeRuntime } : {},
       ...this.internals.fetch !== void 0 ? { fetch: this.internals.fetch } : {}
     });
+    const inspect = this.buildInspectWriter(storage.workspace, logPath);
+    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,
@@ -10369,7 +10806,10 @@ ${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 } : {}
+        ...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 } : {},
@@ -10377,6 +10817,7 @@ ${inputJson}
       });
       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,
@@ -11220,7 +11661,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,
@@ -11411,6 +11992,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;
@@ -11450,6 +12036,7 @@ function resolveApiKey(config) {
   EpisodicMemory,
   Hippocampus,
   InlineSkillSource,
+  InspectWriter,
   LocalStorageAdapter,
   MAX_ATTEMPTS,
   McpClient,
@@ -11457,6 +12044,7 @@ function resolveApiKey(config) {
   McpManager,
   McpProtocolError,
   McpTimeoutError,
+  NULL_INSPECT_WRITER,
   NodeBackgroundExecutor,
   NotImplementedError,
   PlanSchema,