la-machina-engine 0.5.0 → 0.7.0

package/dist/index.cjs

@@ -37,35 +37,124 @@ var init_cjs_shims = __esm({
   }
 });
 
+// src/tools/contract.ts
+function defineTool(tool) {
+  return tool;
+}
+var ToolRegistry;
+var init_contract = __esm({
+  "src/tools/contract.ts"() {
+    "use strict";
+    init_cjs_shims();
+    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/fetchData.ts
+var fetchData_exports = {};
+__export(fetchData_exports, {
+  createFetchDataTool: () => createFetchDataTool
+});
+function createFetchDataTool(opts) {
+  return defineTool({
+    name: "FetchData",
+    description: "Fetch the full content of a tool result that was offloaded because it was too large for the main context. Pass the `ref` token from the summarized tool_result message (the text that looked like 'Use FetchData with ref=\"...\"'). Returns the raw bytes of the original tool output.",
+    inputSchema,
+    execute: async ({ ref }) => {
+      if (!SAFE_REF.test(ref)) {
+        return {
+          content: `ERR_OFFLOAD_INVALID_REF: ref "${ref}" contains unsafe characters`,
+          isError: true
+        };
+      }
+      const path = `${opts.logPath}/toolResults/${ref}.json`;
+      const raw = await opts.storage.readFile(path);
+      if (raw === null) {
+        return {
+          content: `ERR_OFFLOAD_REF_NOT_FOUND: no data found for ref "${ref}"`,
+          isError: true
+        };
+      }
+      return {
+        content: raw,
+        isError: false,
+        metadata: { ref, bytes: raw.length }
+      };
+    }
+  });
+}
+var import_zod6, SAFE_REF, inputSchema;
+var init_fetchData = __esm({
+  "src/tools/fetchData.ts"() {
+    "use strict";
+    init_cjs_shims();
+    import_zod6 = require("zod");
+    init_contract();
+    SAFE_REF = /^[a-zA-Z0-9_-]+$/;
+    inputSchema = import_zod6.z.object({
+      ref: import_zod6.z.string().min(1)
+    });
+  }
+});
+
 // src/orchestrator/types.ts
-var import_zod25, PlanStepSchema, PlanSchema;
+var import_zod28, PlanStepSchema, PlanSchema;
 var init_types = __esm({
   "src/orchestrator/types.ts"() {
     "use strict";
     init_cjs_shims();
-    import_zod25 = require("zod");
-    PlanStepSchema = import_zod25.z.object({
-      id: import_zod25.z.string().min(1),
-      description: import_zod25.z.string().min(1),
-      action: import_zod25.z.enum(["research", "implement", "verify", "review", "custom"]),
-      files: import_zod25.z.array(import_zod25.z.string()).optional(),
-      spec: import_zod25.z.string().optional(),
-      dependsOn: import_zod25.z.array(import_zod25.z.string()).optional()
+    import_zod28 = require("zod");
+    PlanStepSchema = import_zod28.z.object({
+      id: import_zod28.z.string().min(1),
+      description: import_zod28.z.string().min(1),
+      action: import_zod28.z.enum(["research", "implement", "verify", "review", "custom"]),
+      files: import_zod28.z.array(import_zod28.z.string()).optional(),
+      spec: import_zod28.z.string().optional(),
+      dependsOn: import_zod28.z.array(import_zod28.z.string()).optional()
     });
-    PlanSchema = import_zod25.z.object({
-      summary: import_zod25.z.string().min(1),
-      steps: import_zod25.z.array(PlanStepSchema).min(1)
+    PlanSchema = import_zod28.z.object({
+      summary: import_zod28.z.string().min(1),
+      steps: import_zod28.z.array(PlanStepSchema).min(1)
     });
   }
 });
 
 // src/orchestrator/planParser.ts
 function parsePlan(raw, maxSteps) {
-  const json = extractJson(raw);
-  if (json === null) return null;
+  const json2 = extractJson(raw);
+  if (json2 === null) return null;
   let parsed;
   try {
-    parsed = JSON.parse(json);
+    parsed = JSON.parse(json2);
   } catch {
     return null;
   }
@@ -75,23 +164,23 @@ function parsePlan(raw, maxSteps) {
   if (plan.steps.length > maxSteps) return null;
   return plan;
 }
-function extractJson(text) {
-  const fenceMatch = text.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
+function extractJson(text2) {
+  const fenceMatch = text2.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
   if (fenceMatch?.[1]) {
     const inner = fenceMatch[1].trim();
     if (inner.startsWith("{")) return inner;
   }
   let start = -1;
   let depth = 0;
-  for (let i = 0; i < text.length; i++) {
-    const c = text[i];
+  for (let i = 0; i < text2.length; i++) {
+    const c = text2[i];
     if (c === "{") {
       if (depth === 0) start = i;
       depth++;
     } else if (c === "}") {
       depth--;
       if (depth === 0 && start !== -1) {
-        return text.slice(start, i + 1);
+        return text2.slice(start, i + 1);
       }
     }
   }
@@ -780,6 +869,7 @@ __export(index_exports, {
   WebhookDispatcher: () => WebhookDispatcher,
   adaptMcpTool: () => adaptMcpTool,
   buildForkedMessages: () => buildForkedMessages,
+  buildKnowledgeIndex: () => buildKnowledgeIndex,
   buildPermissionPolicy: () => buildPermissionPolicy,
   buildSchemaPrompt: () => buildSchemaPrompt,
   buildSystemPrompt: () => buildSystemPrompt,
@@ -787,16 +877,21 @@ __export(index_exports, {
   canSpawnProcesses: () => canSpawnProcesses,
   capabilityStub: () => capabilityStub,
   createApiCallTool: () => createApiCallTool,
+  createFetchDataTool: () => createFetchDataTool,
   createLogger: () => createLogger,
   createModelAdapter: () => createModelAdapter,
+  createReadKnowledgeTool: () => createReadKnowledgeTool,
+  createSearchKnowledgeTool: () => createSearchKnowledgeTool,
   createSendMessageTool: () => createSendMessageTool,
   createSkillPageTool: () => createSkillPageTool,
   createSmartMemory: () => createSmartMemory,
   defaultSamplingHandler: () => defaultSamplingHandler,
+  defaultToolResultSummarizer: () => defaultToolResultSummarizer,
   defineTool: () => defineTool,
   detectRuntime: () => detectRuntime,
   getCoordinatorBasePrompt: () => getCoordinatorBasePrompt,
   getCoordinatorSystemPrompt: () => getCoordinatorSystemPrompt,
+  getExtractor: () => getExtractor,
   hasProcessLifecycle: () => hasProcessLifecycle,
   initEngine: () => initEngine,
   isCoordinatorMode: () => isCoordinatorMode,
@@ -817,9 +912,10 @@ __export(index_exports, {
   snapshotFiles: () => snapshotFiles,
   synthesizeSpec: () => synthesizeSpec,
   toResponse: () => toResponse,
-  tryParseJSON: () => tryParseJSON,
+  tryParseJSON: () => tryParseJSON2,
   validateOutput: () => validateOutput,
-  withCapabilityCheck: () => withCapabilityCheck
+  withCapabilityCheck: () => withCapabilityCheck,
+  writeKnowledgeIndex: () => writeKnowledgeIndex
 });
 module.exports = __toCommonJS(index_exports);
 init_cjs_shims();
@@ -1071,13 +1167,19 @@ var McpConfigResolved = import_zod.z.object({
   shutdownTimeoutMs: import_zod.z.number().int().positive()
 }).strict();
 var CompactionStrategyEnum = import_zod.z.enum(["drop-middle", "summarize", "session-memory", "auto"]);
+var ToolResultOffloadConfigResolved = import_zod.z.object({
+  enabled: import_zod.z.boolean(),
+  thresholdBytes: import_zod.z.number().int().positive(),
+  maxPreviewChars: import_zod.z.number().int().positive()
+}).strict();
 var CompactionConfigResolved = import_zod.z.object({
   strategy: CompactionStrategyEnum,
   threshold: import_zod.z.number().min(0).max(1),
   keepLast: import_zod.z.number().int().positive(),
   summaryMaxTokens: import_zod.z.number().int().positive(),
   microcompact: import_zod.z.boolean(),
-  microcompactAgeMs: import_zod.z.number().int().nonnegative()
+  microcompactAgeMs: import_zod.z.number().int().nonnegative(),
+  toolResultOffload: ToolResultOffloadConfigResolved.optional()
 }).strict();
 var CoordinatorConfigResolved = import_zod.z.object({
   enabled: import_zod.z.boolean(),
@@ -1146,6 +1248,11 @@ var ApiConfigResolved = import_zod.z.object({
   services: import_zod.z.array(ApiServiceSchema),
   maxResponseBytes: import_zod.z.number().int().positive().optional()
 }).strict();
+var KnowledgeConfigResolved = import_zod.z.object({
+  enabled: import_zod.z.boolean(),
+  maxSearchResults: import_zod.z.number().int().positive(),
+  maxReadBytes: import_zod.z.number().int().positive()
+}).strict();
 var RunnerConfigResolved = import_zod.z.object({
   url: import_zod.z.string().url(),
   secret: import_zod.z.string().min(1, "runner.secret cannot be empty")
@@ -1167,7 +1274,8 @@ var ResolvedConfigSchema = import_zod.z.object({
   coordinator: CoordinatorConfigResolved,
   orchestrator: OrchestratorConfigResolved,
   runner: RunnerConfigResolved.optional(),
-  api: ApiConfigResolved.optional()
+  api: ApiConfigResolved.optional(),
+  knowledge: KnowledgeConfigResolved.optional()
 }).strict();
 var R2ConfigUser = R2ConfigResolved.partial();
 var ModelConfigUser = ModelConfigResolved.partial();
@@ -1178,6 +1286,7 @@ var StorageConfigUser = import_zod.z.object({
   r2: R2ConfigUser.optional(),
   r2Binding: R2BucketBindingShape.optional()
 }).strict();
+var KnowledgeConfigUser = KnowledgeConfigResolved.partial();
 var MemoryConfigUser = import_zod.z.object({
   mode: MemoryModeEnum.optional(),
   scope: MemoryScopeUserEnum.optional()
@@ -1213,7 +1322,16 @@ var McpConfigUser = import_zod.z.object({
 var PermissionsConfigUser = PermissionsConfigResolved.partial();
 var RunnerConfigUser = RunnerConfigResolved;
 var ApiConfigUser = ApiConfigResolved.partial();
-var CompactionConfigUser = CompactionConfigResolved.partial();
+var ToolResultOffloadConfigUser = ToolResultOffloadConfigResolved.partial();
+var CompactionConfigUser = import_zod.z.object({
+  strategy: CompactionStrategyEnum.optional(),
+  threshold: import_zod.z.number().min(0).max(1).optional(),
+  keepLast: import_zod.z.number().int().positive().optional(),
+  summaryMaxTokens: import_zod.z.number().int().positive().optional(),
+  microcompact: import_zod.z.boolean().optional(),
+  microcompactAgeMs: import_zod.z.number().int().nonnegative().optional(),
+  toolResultOffload: ToolResultOffloadConfigUser.optional()
+}).strict();
 var CoordinatorConfigUser = CoordinatorConfigResolved.partial();
 var OrchestratorConfigUser = OrchestratorConfigResolved.deepPartial();
 var UserConfigSchema = import_zod.z.object({
@@ -1233,7 +1351,8 @@ var UserConfigSchema = import_zod.z.object({
   coordinator: CoordinatorConfigUser.optional(),
   orchestrator: OrchestratorConfigUser.optional(),
   runner: RunnerConfigUser.optional(),
-  api: ApiConfigUser.optional()
+  api: ApiConfigUser.optional(),
+  knowledge: KnowledgeConfigUser.optional()
 }).strict();
 
 // src/config/merge.ts
@@ -1306,9 +1425,41 @@ function coerceDeprecatedMemoryScope(user) {
     memory: { ...memory, scope: "workspace" }
   };
 }
+var OFFLOAD_DEFAULTS = { thresholdBytes: 2048, maxPreviewChars: 500 };
+function splitOffloadRuntime(user) {
+  const block = user.compaction?.toolResultOffload;
+  if (block === void 0) return { stripped: user };
+  const { summarizer, ...schemaSafe } = block;
+  const filled = {
+    enabled: schemaSafe.enabled ?? false,
+    thresholdBytes: schemaSafe.thresholdBytes ?? OFFLOAD_DEFAULTS.thresholdBytes,
+    maxPreviewChars: schemaSafe.maxPreviewChars ?? OFFLOAD_DEFAULTS.maxPreviewChars
+  };
+  const clone = {
+    ...user,
+    compaction: {
+      ...user.compaction ?? {},
+      toolResultOffload: filled
+    }
+  };
+  return { stripped: clone, summarizer };
+}
+var KNOWLEDGE_DEFAULTS = { maxSearchResults: 5, maxReadBytes: 1e4 };
+function fillKnowledgeDefaults(user) {
+  const block = user.knowledge;
+  if (block === void 0) return user;
+  const filled = {
+    enabled: block.enabled ?? false,
+    maxSearchResults: block.maxSearchResults ?? KNOWLEDGE_DEFAULTS.maxSearchResults,
+    maxReadBytes: block.maxReadBytes ?? KNOWLEDGE_DEFAULTS.maxReadBytes
+  };
+  return { ...user, knowledge: filled };
+}
 function mergeConfig(user) {
   const withCoercedScope = coerceDeprecatedMemoryScope(user);
-  const { stripped, runtime } = splitApiRuntime(withCoercedScope);
+  const withKnowledge = fillKnowledgeDefaults(withCoercedScope);
+  const { stripped: afterOffload, summarizer } = splitOffloadRuntime(withKnowledge);
+  const { stripped, runtime } = splitApiRuntime(afterOffload);
   const validatedUser = UserConfigSchema.parse(stripped);
   const merged = deepMerge(DEFAULTS, validatedUser);
   const resolved = ResolvedConfigSchema.parse(merged);
@@ -1320,6 +1471,13 @@ function mergeConfig(user) {
     };
   } else if (Object.keys(runtime).length > 0) {
   }
+  if (summarizer !== void 0 && resolved.compaction.toolResultOffload !== void 0) {
+    const mutable = resolved.compaction;
+    mutable.toolResultOffload = {
+      ...resolved.compaction.toolResultOffload,
+      summarizer
+    };
+  }
   return resolved;
 }
 
@@ -1966,44 +2124,7 @@ function hasProcessLifecycle() {
 // src/tools/capabilityStub.ts
 init_cjs_shims();
 var import_zod2 = require("zod");
-
-// src/tools/contract.ts
-init_cjs_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
+init_contract();
 var anyInput = import_zod2.z.unknown();
 function capabilityStub(original) {
   return defineTool({
@@ -2207,7 +2328,7 @@ var SubagentRegistry = class _SubagentRegistry {
 
 // src/tools/agent.ts
 init_cjs_shims();
-var import_zod6 = require("zod");
+var import_zod7 = require("zod");
 
 // src/subagent/runner.ts
 init_cjs_shims();
@@ -2271,6 +2392,131 @@ async function writeSnapshot(storage, logPath, snapshot) {
   await storage.writeFile(snapshotPath(logPath), JSON.stringify(validated, null, 2));
 }
 
+// src/engine/toolResultOffload.ts
+init_cjs_shims();
+
+// src/engine/toolResultSummarizer.ts
+init_cjs_shims();
+var MAX_ITEM_PREVIEW_CHARS = 150;
+var MAX_TOP_LEVEL_KEYS = 8;
+var defaultToolResultSummarizer = (ctx) => {
+  return summarize(ctx);
+};
+function summarize(ctx) {
+  const { toolName, rawContent, rawBytes, ref, maxPreviewChars } = ctx;
+  const parsed = tryParseJSON(rawContent);
+  if (parsed.ok) {
+    if (Array.isArray(parsed.value)) {
+      return summarizeArray(toolName, parsed.value, ref, rawBytes);
+    }
+    if (parsed.value !== null && typeof parsed.value === "object") {
+      return summarizeObject(toolName, parsed.value, ref, rawBytes);
+    }
+  }
+  const preview = rawContent.slice(0, maxPreviewChars);
+  const truncated = rawContent.length > maxPreviewChars ? "\u2026" : "";
+  return `[${toolName}] ${formatBytes(rawBytes)} offloaded.
+` + (preview.length > 0 ? `Preview: ${preview}${truncated}
+` : "") + `Use FetchData with ref="${ref}" to read the full content.`;
+}
+function summarizeArray(toolName, arr, ref, bytes) {
+  const count = arr.length;
+  const firstHint = arr.length > 0 ? compactPreview(arr[0]) : "";
+  const hintLine = firstHint ? `First item preview: ${firstHint}
+` : "";
+  return `[${toolName}] Array of ${count} item${count === 1 ? "" : "s"} (${formatBytes(bytes)}).
+` + hintLine + `Use FetchData with ref="${ref}" to read the full array.`;
+}
+function summarizeObject(toolName, obj, ref, bytes) {
+  const keys = Object.keys(obj);
+  const shown = keys.slice(0, MAX_TOP_LEVEL_KEYS);
+  const overflow = keys.length > MAX_TOP_LEVEL_KEYS ? ` (+${keys.length - shown.length} more)` : "";
+  const parts = shown.map((k) => `${k}=${compactPreview(obj[k])}`).join(", ");
+  return `[${toolName}] Object (${formatBytes(bytes)}). Keys: ${parts}${overflow}
+Use FetchData with ref="${ref}" to read the full object.`;
+}
+function compactPreview(value) {
+  let str;
+  if (value === null) {
+    str = "null";
+  } else if (typeof value === "string") {
+    str = JSON.stringify(value);
+  } else if (Array.isArray(value)) {
+    str = `[${value.length} item${value.length === 1 ? "" : "s"}]`;
+  } else if (typeof value === "object") {
+    const keys = Object.keys(value);
+    str = `{${keys.slice(0, 3).join(", ")}${keys.length > 3 ? ", \u2026" : ""}}`;
+  } else {
+    str = String(value);
+  }
+  if (str.length > MAX_ITEM_PREVIEW_CHARS) {
+    return str.slice(0, MAX_ITEM_PREVIEW_CHARS) + "\u2026";
+  }
+  return str;
+}
+function tryParseJSON(text2) {
+  const trimmed = text2.replace(/^\uFEFF/, "").trim();
+  if (trimmed.length === 0) return { ok: false };
+  const first = trimmed[0];
+  if (first !== "{" && first !== "[" && first !== '"') return { ok: false };
+  try {
+    return { ok: true, value: JSON.parse(trimmed) };
+  } catch {
+    return { ok: false };
+  }
+}
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+// src/engine/toolResultOffload.ts
+async function maybeOffloadToolResult(input) {
+  const {
+    offloadConfig,
+    storage,
+    logPath,
+    toolUseId,
+    toolName,
+    toolInput,
+    rawContent,
+    rawIsError
+  } = input;
+  if (offloadConfig === void 0 || offloadConfig.enabled !== true) {
+    return rawContent;
+  }
+  if (rawIsError) {
+    return rawContent;
+  }
+  if (toolName === "FetchData") {
+    return rawContent;
+  }
+  const rawBytes = byteLength(rawContent);
+  if (rawBytes <= offloadConfig.thresholdBytes) {
+    return rawContent;
+  }
+  const path = `${logPath}/toolResults/${toolUseId}.json`;
+  await storage.writeFile(path, rawContent);
+  const summarizer = offloadConfig.summarizer ?? defaultToolResultSummarizer;
+  const summary = await summarizer({
+    toolName,
+    toolInput,
+    rawContent,
+    rawBytes,
+    ref: toolUseId,
+    maxPreviewChars: offloadConfig.maxPreviewChars
+  });
+  if (!summary.includes(toolUseId)) {
+    return `${summary}
+[offloaded \u2014 ref=${toolUseId}, use FetchData to read the full content]`;
+  }
+  return summary;
+}
+function byteLength(s) {
+  return new TextEncoder().encode(s).byteLength;
+}
+
 // src/hooks/dispatch.ts
 init_cjs_shims();
 async function dispatchHooks(hooks, event) {
@@ -2293,8 +2539,8 @@ var INTERNAL_BLOCK_PATTERNS = [
   /<git_signature>[\s\S]*?<\/git_signature>/g,
   /<caller>[\s\S]*?<\/caller>/g
 ];
-function stripInternalBlocks(text) {
-  let result = text;
+function stripInternalBlocks(text2) {
+  let result = text2;
   for (const pattern of INTERNAL_BLOCK_PATTERNS) {
     pattern.lastIndex = 0;
     result = result.replace(pattern, "");
@@ -2942,8 +3188,8 @@ async function agentLoop(options) {
         assistantContent.push({ type: "thinking", thinking });
       }
     }
-    for (const text of textBlocks) {
-      if (text.length > 0) assistantContent.push({ type: "text", text });
+    for (const text2 of textBlocks) {
+      if (text2.length > 0) assistantContent.push({ type: "text", text: text2 });
     }
     for (const tc of toolCalls) {
       assistantContent.push({
@@ -3023,7 +3269,32 @@ async function agentLoop(options) {
           if (typeof missing === "string") {
             ctx.recordCapabilityMissing(missing);
           }
-          await ctx.addToolResult(id, truncateToolResult(result.content), result.isError === true);
+          const call = toolCallsToDispatch.find((c) => c.id === id);
+          let contentForTranscript;
+          if (options.toolResultOffload !== void 0 && options.storage !== void 0) {
+            try {
+              contentForTranscript = await maybeOffloadToolResult({
+                offloadConfig: options.toolResultOffload,
+                storage: options.storage,
+                logPath: options.offloadLogPath ?? transcript.path,
+                toolUseId: id,
+                toolName: call?.name ?? "unknown",
+                toolInput: call?.input,
+                rawContent: result.content,
+                rawIsError: result.isError === true
+              });
+            } catch (err) {
+              const msg = err instanceof Error ? err.message : String(err);
+              contentForTranscript = `[tool-result offload failed: ${msg}] ${result.content.slice(0, 500)}`;
+            }
+          } else {
+            contentForTranscript = result.content;
+          }
+          await ctx.addToolResult(
+            id,
+            truncateToolResult(contentForTranscript),
+            result.isError === true
+          );
         }
       } catch (err) {
         if (err instanceof SubagentPausedError) {
@@ -3157,11 +3428,11 @@ function toAnthropicTool(tool) {
     target: "jsonSchema7",
     $refStrategy: "none"
   });
-  const { $schema: _schema, ...inputSchema17 } = schema;
+  const { $schema: _schema, ...inputSchema20 } = schema;
   return {
     name: tool.name,
     description: tool.description,
-    input_schema: inputSchema17
+    input_schema: inputSchema20
   };
 }
 function partitionToolCalls(calls, registry) {
@@ -3296,8 +3567,8 @@ var RunContext = class {
     this.episodes = options.episodes ?? null;
   }
   // ---------- message mutators ----------
-  async addUserMessage(text) {
-    const content = [{ type: "text", text }];
+  async addUserMessage(text2) {
+    const content = [{ type: "text", text: text2 }];
     this.messages.push({ role: "user", content });
     await this.writeEntry({
       type: "user",
@@ -3306,7 +3577,7 @@ var RunContext = class {
       ts: this.now(),
       message: { role: "user", content }
     });
-    this.episodes?.logTurn(this.turnCount, "user", text);
+    this.episodes?.logTurn(this.turnCount, "user", text2);
   }
   async addAssistantMessage(content) {
     this.messages.push({ role: "assistant", content });
@@ -3871,6 +4142,19 @@ async function loadWriterState(storage, logPath) {
 // src/subagent/runner.ts
 async function runAgent(options) {
   const childLogPath = `${options.parentLogPath}/subagents/${options.agentId}`;
+  let restorePrevFetchData = null;
+  if (options.toolResultOffload !== void 0 && options.toolResultOffload.enabled) {
+    const { createFetchDataTool: createFetchDataTool2 } = await Promise.resolve().then(() => (init_fetchData(), fetchData_exports));
+    const existing = options.registry.get("FetchData");
+    options.registry.unregister("FetchData");
+    options.registry.register(
+      createFetchDataTool2({ storage: options.storage, logPath: childLogPath })
+    );
+    restorePrevFetchData = () => {
+      options.registry.unregister("FetchData");
+      if (existing !== void 0) options.registry.register(existing);
+    };
+  }
   const writer = new TranscriptWriter({
     storage: options.storage,
     logPath: childLogPath,
@@ -3911,7 +4195,15 @@ async function runAgent(options) {
       // Propagate parent's gate + storage into the child loop when set.
       // Without `storage`, a gate denial would fail the child instead of
       // pausing it, so both must travel together.
-      ...options.gateBeforeTool !== void 0 ? { gateBeforeTool: options.gateBeforeTool, storage: options.storage } : {}
+      ...options.gateBeforeTool !== void 0 ? { gateBeforeTool: options.gateBeforeTool, storage: options.storage } : {},
+      // Plan 021 — the child needs its own storage + offload config
+      // so its own large tool results get offloaded into
+      // `childLogPath/toolResults/...`, not the parent's folder.
+      ...options.toolResultOffload !== void 0 ? {
+        storage: options.storage,
+        toolResultOffload: options.toolResultOffload,
+        offloadLogPath: childLogPath
+      } : {}
     });
     if (result.status === "done") {
       await writer.setStatus("done");
@@ -3967,6 +4259,7 @@ async function runAgent(options) {
     } catch {
     }
     await writer.close();
+    restorePrevFetchData?.();
   }
 }
 
@@ -4039,10 +4332,11 @@ Directive: ${directive}`;
 }
 
 // src/tools/agent.ts
-var inputSchema = import_zod6.z.object({
-  description: import_zod6.z.string().min(1),
-  subagent_type: import_zod6.z.string().optional(),
-  run_in_background: import_zod6.z.boolean().optional()
+init_contract();
+var inputSchema2 = import_zod7.z.object({
+  description: import_zod7.z.string().min(1),
+  subagent_type: import_zod7.z.string().optional(),
+  run_in_background: import_zod7.z.boolean().optional()
 });
 function createAgentTool(options) {
   if (options.agents.length === 0) {
@@ -4062,7 +4356,7 @@ If omitted, defaults to "${defaultAgent.name}".`;
   return defineTool({
     name: "Agent",
     description,
-    inputSchema,
+    inputSchema: inputSchema2,
     isConcurrencySafe: (input) => {
       const typed = input;
       const typeName = typed?.subagent_type ?? defaultAgent.name;
@@ -4103,7 +4397,8 @@ If omitted, defaults to "${defaultAgent.name}".`;
           idleFlushMs: options.idleFlushMs,
           // Fork: prepend parent messages + forked messages
           prependMessages: [...parentMsgs, ...forkedMsgs],
-          ...options.gateBeforeTool !== void 0 ? { gateBeforeTool: options.gateBeforeTool } : {}
+          ...options.gateBeforeTool !== void 0 ? { gateBeforeTool: options.gateBeforeTool } : {},
+          ...options.toolResultOffload !== void 0 ? { toolResultOffload: options.toolResultOffload } : {}
         });
         handlePausedResult(result2, spawn2.agentId, "fork");
         const t2 = result2;
@@ -4152,7 +4447,8 @@ If omitted, defaults to "${defaultAgent.name}".`;
         turnTimeoutMs: options.turnTimeoutMs,
         flushPolicy: options.flushPolicy,
         idleFlushMs: options.idleFlushMs,
-        ...options.gateBeforeTool !== void 0 ? { gateBeforeTool: options.gateBeforeTool } : {}
+        ...options.gateBeforeTool !== void 0 ? { gateBeforeTool: options.gateBeforeTool } : {},
+        ...options.toolResultOffload !== void 0 ? { toolResultOffload: options.toolResultOffload } : {}
       };
       const shouldRunAsync = run_in_background === true || options.coordinatorMode === true;
       if (shouldRunAsync) {
@@ -4247,7 +4543,8 @@ function handlePausedResult(result, agentId, subagentType) {
 
 // src/tools/bash.ts
 init_cjs_shims();
-var import_zod7 = require("zod");
+var import_zod8 = require("zod");
+init_contract();
 var _spawn = null;
 async function getSpawn() {
   if (_spawn === null) {
@@ -4259,15 +4556,15 @@ 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 = import_zod7.z.object({
-  command: import_zod7.z.string().min(1),
-  cwd: import_zod7.z.string().min(1).optional()
+var inputSchema3 = import_zod8.z.object({
+  command: import_zod8.z.string().min(1),
+  cwd: import_zod8.z.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,
+    inputSchema: inputSchema3,
     requiresNode: true,
     execute: async ({ command, cwd }, ctx) => {
       if (BLOCKED_DEVICE_PATHS.test(command)) {
@@ -4348,16 +4645,17 @@ function createBashTool() {
 
 // src/tools/sendMessage.ts
 init_cjs_shims();
-var import_zod8 = require("zod");
-var inputSchema3 = import_zod8.z.object({
-  to: import_zod8.z.string().min(1).describe("Agent name (subagent_type) or agentId to send the message to."),
-  message: import_zod8.z.string().min(1).describe("Message content to deliver to the target agent.")
+var import_zod9 = require("zod");
+init_contract();
+var inputSchema4 = import_zod9.z.object({
+  to: import_zod9.z.string().min(1).describe("Agent name (subagent_type) or agentId to send the message to."),
+  message: import_zod9.z.string().min(1).describe("Message content to deliver to the target agent.")
 });
 function createSendMessageTool(options) {
   return defineTool({
     name: "SendMessage",
     description: "Send a text message to a running subagent by name or agentId. The message is queued and delivered at the start of the agent's next turn. Use this to redirect, provide additional context, or coordinate with agents you spawned.",
-    inputSchema: inputSchema3,
+    inputSchema: inputSchema4,
     execute: async ({ to, message }) => {
       const { registry } = options;
       let agentId = registry.findByName(to);
@@ -4400,20 +4698,24 @@ function createSendMessageTool(options) {
   });
 }
 
+// src/engine/engine.ts
+init_contract();
+
 // src/tools/fileEdit.ts
 init_cjs_shims();
-var import_zod9 = require("zod");
-var inputSchema4 = import_zod9.z.object({
-  path: import_zod9.z.string().min(1),
-  old_string: import_zod9.z.string().min(1),
-  new_string: import_zod9.z.string(),
-  replace_all: import_zod9.z.boolean().optional()
+var import_zod10 = require("zod");
+init_contract();
+var inputSchema5 = import_zod10.z.object({
+  path: import_zod10.z.string().min(1),
+  old_string: import_zod10.z.string().min(1),
+  new_string: import_zod10.z.string(),
+  replace_all: import_zod10.z.boolean().optional()
 });
 function createFileEditTool(storage) {
   return defineTool({
     name: "Edit",
     description: "Replace old_string with new_string in a file. By default old_string must be unique; set replace_all to replace every occurrence.",
-    inputSchema: inputSchema4,
+    inputSchema: inputSchema5,
     execute: async ({ path, old_string, new_string, replace_all }) => {
       if (old_string === new_string) {
         return {
@@ -4491,13 +4793,14 @@ function normalizeQuotes(s) {
 
 // src/tools/fileRead.ts
 init_cjs_shims();
-var import_zod10 = require("zod");
-var inputSchema5 = import_zod10.z.object({
-  path: import_zod10.z.string().min(1),
-  offset: import_zod10.z.number().int().positive().optional(),
-  limit: import_zod10.z.number().int().positive().optional(),
+var import_zod11 = require("zod");
+init_contract();
+var inputSchema6 = import_zod11.z.object({
+  path: import_zod11.z.string().min(1),
+  offset: import_zod11.z.number().int().positive().optional(),
+  limit: import_zod11.z.number().int().positive().optional(),
   /** PDF page range, e.g. "1-5", "3", "10-20". Max 20 pages per request. */
-  pages: import_zod10.z.string().optional()
+  pages: import_zod11.z.string().optional()
 });
 var IMAGE_EXTENSIONS = /* @__PURE__ */ new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".svg"]);
 var PDF_EXTENSION = ".pdf";
@@ -4516,7 +4819,7 @@ function createFileReadTool(storageOrOptions) {
   return defineTool({
     name: "Read",
     description: "Read a file from the workspace. Text files return cat -n style line numbers. PDF files extract text per page (use pages param). Image files return base64 for visual analysis.",
-    inputSchema: inputSchema5,
+    inputSchema: inputSchema6,
     isConcurrencySafe: () => true,
     execute: async ({ path, offset, limit, pages }) => {
       const ext = extname(path);
@@ -4681,10 +4984,11 @@ Base64 data is included in the metadata for visual analysis.`,
 
 // src/tools/fileWrite.ts
 init_cjs_shims();
-var import_zod11 = require("zod");
-var inputSchema6 = import_zod11.z.object({
-  path: import_zod11.z.string().min(1),
-  content: import_zod11.z.string()
+var import_zod12 = require("zod");
+init_contract();
+var inputSchema7 = import_zod12.z.object({
+  path: import_zod12.z.string().min(1),
+  content: import_zod12.z.string()
 });
 function createFileWriteTool(storageOrOptions) {
   const opts = "readFile" in storageOrOptions ? { storage: storageOrOptions } : storageOrOptions;
@@ -4692,7 +4996,7 @@ function createFileWriteTool(storageOrOptions) {
   return defineTool({
     name: "Write",
     description: "Write a file to the workspace. Creates parents and overwrites existing files.",
-    inputSchema: inputSchema6,
+    inputSchema: inputSchema7,
     execute: async ({ path, content }) => {
       if (tracker !== void 0) {
         const exists = await storage.exists(path);
@@ -4723,7 +5027,8 @@ function createFileWriteTool(storageOrOptions) {
 // src/tools/glob.ts
 init_cjs_shims();
 var import_picomatch = __toESM(require("picomatch"), 1);
-var import_zod12 = require("zod");
+var import_zod13 = require("zod");
+init_contract();
 
 // src/tools/walkAdapter.ts
 init_cjs_shims();
@@ -4760,16 +5065,16 @@ async function* walkAdapter(adapter, startPath, options = {}) {
 }
 
 // src/tools/glob.ts
-var inputSchema7 = import_zod12.z.object({
-  pattern: import_zod12.z.string().min(1),
-  path: import_zod12.z.string().optional()
+var inputSchema8 = import_zod13.z.object({
+  pattern: import_zod13.z.string().min(1),
+  path: import_zod13.z.string().optional()
 });
 var MAX_RESULTS = 1e3;
 function createGlobTool(storage) {
   return defineTool({
     name: "Glob",
     description: "Find files by glob pattern. Supports *, **, ?, [abc], {a,b}. Returns paths sorted by mtime descending.",
-    inputSchema: inputSchema7,
+    inputSchema: inputSchema8,
     isConcurrencySafe: () => true,
     execute: async ({ pattern, path: searchPath }) => {
       const startPath = searchPath ?? "";
@@ -4815,22 +5120,23 @@ function createGlobTool(storage) {
 // src/tools/grep.ts
 init_cjs_shims();
 var import_picomatch2 = __toESM(require("picomatch"), 1);
-var import_zod13 = require("zod");
-var inputSchema8 = import_zod13.z.object({
-  pattern: import_zod13.z.string().min(1),
-  path: import_zod13.z.string().optional(),
-  glob: import_zod13.z.string().optional(),
-  type: import_zod13.z.string().optional(),
-  output_mode: import_zod13.z.enum(["content", "files_with_matches", "count"]).optional(),
-  "-i": import_zod13.z.boolean().optional(),
-  "-n": import_zod13.z.boolean().optional(),
-  "-A": import_zod13.z.number().int().nonnegative().optional(),
-  "-B": import_zod13.z.number().int().nonnegative().optional(),
-  "-C": import_zod13.z.number().int().nonnegative().optional(),
-  context: import_zod13.z.number().int().nonnegative().optional(),
-  multiline: import_zod13.z.boolean().optional(),
-  head_limit: import_zod13.z.number().int().nonnegative().optional(),
-  offset: import_zod13.z.number().int().nonnegative().optional()
+var import_zod14 = require("zod");
+init_contract();
+var inputSchema9 = import_zod14.z.object({
+  pattern: import_zod14.z.string().min(1),
+  path: import_zod14.z.string().optional(),
+  glob: import_zod14.z.string().optional(),
+  type: import_zod14.z.string().optional(),
+  output_mode: import_zod14.z.enum(["content", "files_with_matches", "count"]).optional(),
+  "-i": import_zod14.z.boolean().optional(),
+  "-n": import_zod14.z.boolean().optional(),
+  "-A": import_zod14.z.number().int().nonnegative().optional(),
+  "-B": import_zod14.z.number().int().nonnegative().optional(),
+  "-C": import_zod14.z.number().int().nonnegative().optional(),
+  context: import_zod14.z.number().int().nonnegative().optional(),
+  multiline: import_zod14.z.boolean().optional(),
+  head_limit: import_zod14.z.number().int().nonnegative().optional(),
+  offset: import_zod14.z.number().int().nonnegative().optional()
 });
 var MAX_FILES_SCANNED = 5e3;
 var MAX_MATCHES_PER_FILE = 100;
@@ -4876,7 +5182,7 @@ function createGrepTool(storage) {
   return defineTool({
     name: "Grep",
     description: "Search for a regex pattern across files. Supports ripgrep when available (context lines, multiline, type filters, pagination). Falls back to JS RegExp scanner.",
-    inputSchema: inputSchema8,
+    inputSchema: inputSchema9,
     isConcurrencySafe: () => true,
     execute: async (input, ctx) => {
       if (rgAvailable && input.path !== void 0) {
@@ -5054,10 +5360,11 @@ function formatJsResults(results, mode, limit) {
 
 // src/tools/webFetch.ts
 init_cjs_shims();
-var import_zod14 = require("zod");
-var inputSchema9 = import_zod14.z.object({
-  url: import_zod14.z.string().url(),
-  prompt: import_zod14.z.string().optional()
+var import_zod15 = require("zod");
+init_contract();
+var inputSchema10 = import_zod15.z.object({
+  url: import_zod15.z.string().url(),
+  prompt: import_zod15.z.string().optional()
 });
 var MAX_OUTPUT_BYTES2 = 256 * 1024;
 function createWebFetchTool(options = {}) {
@@ -5065,7 +5372,7 @@ function createWebFetchTool(options = {}) {
   return defineTool({
     name: "WebFetch",
     description: "Fetch a URL and return its content as plain text. HTML is stripped to its readable text.",
-    inputSchema: inputSchema9,
+    inputSchema: inputSchema10,
     isConcurrencySafe: () => true,
     execute: async ({ url }, ctx) => {
       let response;
@@ -5123,8 +5430,8 @@ Make a new WebFetch request with the redirect URL if you want to follow it.`,
           isError: true
         };
       }
-      const text = isHtml(contentType) ? htmlToText(raw) : raw;
-      const { content, truncated } = truncate(text, MAX_OUTPUT_BYTES2);
+      const text2 = isHtml(contentType) ? htmlToText(raw) : raw;
+      const { content, truncated } = truncate(text2, MAX_OUTPUT_BYTES2);
       return {
         content,
         metadata: {
@@ -5140,24 +5447,24 @@ Make a new WebFetch request with the redirect URL if you want to follow it.`,
 function isHtml(contentType) {
   return contentType.toLowerCase().includes("html");
 }
-function htmlToText(html) {
-  return html.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, "").replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, "").replace(/<[^>]+>/g, " ").replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/[ \t]+/g, " ").replace(/\n[ \t]+/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+function htmlToText(html2) {
+  return html2.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, "").replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, "").replace(/<[^>]+>/g, " ").replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/[ \t]+/g, " ").replace(/\n[ \t]+/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
 }
-function truncate(text, maxBytes) {
-  if (Buffer.byteLength(text, "utf8") <= maxBytes) {
-    return { content: text, truncated: false };
+function truncate(text2, maxBytes) {
+  if (Buffer.byteLength(text2, "utf8") <= maxBytes) {
+    return { content: text2, truncated: false };
   }
   let lo = 0;
-  let hi = text.length;
+  let hi = text2.length;
   while (lo < hi) {
     const mid = lo + hi + 1 >>> 1;
-    if (Buffer.byteLength(text.slice(0, mid), "utf8") <= maxBytes) {
+    if (Buffer.byteLength(text2.slice(0, mid), "utf8") <= maxBytes) {
       lo = mid;
     } else {
       hi = mid - 1;
     }
   }
-  return { content: text.slice(0, lo) + "\n... (truncated)", truncated: true };
+  return { content: text2.slice(0, lo) + "\n... (truncated)", truncated: true };
 }
 async function safeText(response) {
   try {
@@ -5186,16 +5493,17 @@ function normalizePath(p) {
 
 // src/tools/webSearch.ts
 init_cjs_shims();
-var import_zod15 = require("zod");
-var inputSchema10 = import_zod15.z.object({
-  query: import_zod15.z.string().min(2),
-  max_results: import_zod15.z.number().int().positive().optional()
+var import_zod16 = require("zod");
+init_contract();
+var inputSchema11 = import_zod16.z.object({
+  query: import_zod16.z.string().min(2),
+  max_results: import_zod16.z.number().int().positive().optional()
 });
 function createWebSearchTool() {
   return defineTool({
     name: "WebSearch",
     description: "Search the web for information. Returns search result snippets. Use when you need current information not available in local files.",
-    inputSchema: inputSchema10,
+    inputSchema: inputSchema11,
     isConcurrencySafe: () => true,
     execute: async ({ query }) => {
       const encoded = encodeURIComponent(query);
@@ -5220,17 +5528,17 @@ function createWebSearchTool() {
           isError: true
         };
       }
-      let html;
+      let html2;
       try {
-        html = await response.text();
+        html2 = await response.text();
       } catch (err) {
         return {
           content: `Failed to read search response: ${err.message}`,
           isError: true
         };
       }
-      const text = htmlToText2(html);
-      const trimmed = text.slice(0, 8e3);
+      const text2 = htmlToText2(html2);
+      const trimmed = text2.slice(0, 8e3);
       return {
         content: `Search results for "${query}":
 
@@ -5240,22 +5548,23 @@ ${trimmed}`,
     }
   });
 }
-function htmlToText2(html) {
-  return html.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, "").replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, "").replace(/<[^>]+>/g, " ").replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/[ \t]+/g, " ").replace(/\n[ \t]+/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+function htmlToText2(html2) {
+  return html2.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, "").replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, "").replace(/<[^>]+>/g, " ").replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/[ \t]+/g, " ").replace(/\n[ \t]+/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
 }
 
 // src/tools/sleep.ts
 init_cjs_shims();
-var import_zod16 = require("zod");
-var inputSchema11 = import_zod16.z.object({
-  durationMs: import_zod16.z.number().int().nonnegative().max(3e5),
-  reason: import_zod16.z.string().optional()
+var import_zod17 = require("zod");
+init_contract();
+var inputSchema12 = import_zod17.z.object({
+  durationMs: import_zod17.z.number().int().nonnegative().max(3e5),
+  reason: import_zod17.z.string().optional()
 });
 function createSleepTool() {
   return defineTool({
     name: "Sleep",
     description: "Pause execution for the given number of milliseconds (max 300000 = 5 minutes). Use when you need to wait for an external process or rate limit.",
-    inputSchema: inputSchema11,
+    inputSchema: inputSchema12,
     isConcurrencySafe: () => true,
     execute: async ({ durationMs, reason }, ctx) => {
       if (durationMs === 0) {
@@ -5289,16 +5598,17 @@ function createSleepTool() {
 
 // src/tools/toolSearch.ts
 init_cjs_shims();
-var import_zod17 = require("zod");
-var inputSchema12 = import_zod17.z.object({
-  query: import_zod17.z.string().min(1),
-  max_results: import_zod17.z.number().int().positive().optional()
+var import_zod18 = require("zod");
+init_contract();
+var inputSchema13 = import_zod18.z.object({
+  query: import_zod18.z.string().min(1),
+  max_results: import_zod18.z.number().int().positive().optional()
 });
 function createToolSearchTool(registry) {
   return defineTool({
     name: "ToolSearch",
     description: "Search the available tools by keyword. Returns matching tool names and descriptions. Use when you want to discover what tools are available for a task.",
-    inputSchema: inputSchema12,
+    inputSchema: inputSchema13,
     isConcurrencySafe: () => true,
     execute: async ({ query, max_results }) => {
       const limit = max_results ?? 10;
@@ -5335,18 +5645,19 @@ ${lines.join("\n")}`,
 
 // src/tools/memorize.ts
 init_cjs_shims();
-var import_zod18 = require("zod");
-var inputSchema13 = import_zod18.z.object({
-  text: import_zod18.z.string().min(1),
-  kind: import_zod18.z.enum(["rule", "lesson"]).default("lesson"),
-  topic: import_zod18.z.string().optional()
+var import_zod19 = require("zod");
+init_contract();
+var inputSchema14 = import_zod19.z.object({
+  text: import_zod19.z.string().min(1),
+  kind: import_zod19.z.enum(["rule", "lesson"]).default("lesson"),
+  topic: import_zod19.z.string().optional()
 });
 function createMemorizeTool(memory) {
   return defineTool({
     name: "Memorize",
     description: 'Save a fact, rule, or lesson to persistent memory. Memories survive across runs and are included in the system prompt of future runs. Use "rule" for behavioral constraints (always/never do X). Use "lesson" for learnings and observations.',
-    inputSchema: inputSchema13,
-    execute: async ({ text, kind, topic }) => {
+    inputSchema: inputSchema14,
+    execute: async ({ text: text2, kind, topic }) => {
       if (memory.mode === "off" || memory.mode === "read-only") {
         return {
           content: `Cannot memorize: memory mode is "${memory.mode}". Set config.memory.mode to "read-write" to enable.`,
@@ -5354,15 +5665,15 @@ function createMemorizeTool(memory) {
         };
       }
       if (kind === "rule") {
-        await memory.encodeRule(text, "always");
+        await memory.encodeRule(text2, "always");
         return {
-          content: `Memorized rule: "${text.slice(0, 80)}${text.length > 80 ? "\u2026" : ""}"`,
+          content: `Memorized rule: "${text2.slice(0, 80)}${text2.length > 80 ? "\u2026" : ""}"`,
           metadata: { kind: "rule" }
         };
       }
-      await memory.encodeLesson(text, topic);
+      await memory.encodeLesson(text2, topic);
       return {
-        content: `Memorized lesson: "${text.slice(0, 80)}${text.length > 80 ? "\u2026" : ""}"${topic ? ` (topic: ${topic})` : ""}`,
+        content: `Memorized lesson: "${text2.slice(0, 80)}${text2.length > 80 ? "\u2026" : ""}"${topic ? ` (topic: ${topic})` : ""}`,
         metadata: { kind: "lesson", topic }
       };
     }
@@ -5371,17 +5682,18 @@ function createMemorizeTool(memory) {
 
 // src/tools/recall.ts
 init_cjs_shims();
-var import_zod19 = require("zod");
-var inputSchema14 = import_zod19.z.object({
-  query: import_zod19.z.string().min(1),
-  scope: import_zod19.z.enum(["identity", "rules", "lessons", "all"]).default("all"),
-  topic: import_zod19.z.string().optional()
+var import_zod20 = require("zod");
+init_contract();
+var inputSchema15 = import_zod20.z.object({
+  query: import_zod20.z.string().min(1),
+  scope: import_zod20.z.enum(["identity", "rules", "lessons", "all"]).default("all"),
+  topic: import_zod20.z.string().optional()
 });
 function createRecallTool(memory) {
   return defineTool({
     name: "Recall",
     description: "Search persistent memory for previously saved facts, rules, and lessons. Use when you need to recall information from prior runs or check what rules/lessons are stored.",
-    inputSchema: inputSchema14,
+    inputSchema: inputSchema15,
     isConcurrencySafe: () => true,
     execute: async ({ query, scope, topic }) => {
       if (memory.mode === "off") {
@@ -5430,19 +5742,20 @@ ${content}`,
 
 // src/tools/notebookEdit.ts
 init_cjs_shims();
-var import_zod20 = require("zod");
-var inputSchema15 = import_zod20.z.object({
-  notebook_path: import_zod20.z.string().min(1),
-  edit_mode: import_zod20.z.enum(["replace", "insert", "delete"]).default("replace"),
-  cell_index: import_zod20.z.number().int().nonnegative(),
-  new_source: import_zod20.z.string().optional(),
-  cell_type: import_zod20.z.enum(["code", "markdown"]).optional()
+var import_zod21 = require("zod");
+init_contract();
+var inputSchema16 = import_zod21.z.object({
+  notebook_path: import_zod21.z.string().min(1),
+  edit_mode: import_zod21.z.enum(["replace", "insert", "delete"]).default("replace"),
+  cell_index: import_zod21.z.number().int().nonnegative(),
+  new_source: import_zod21.z.string().optional(),
+  cell_type: import_zod21.z.enum(["code", "markdown"]).optional()
 });
 function createNotebookEditTool(storage) {
   return defineTool({
     name: "NotebookEdit",
     description: "Edit a Jupyter notebook (.ipynb) by inserting, replacing, or deleting cells. Specify the cell_index (0-based) and the operation.",
-    inputSchema: inputSchema15,
+    inputSchema: inputSchema16,
     execute: async ({
       notebook_path,
       edit_mode,
@@ -5591,12 +5904,13 @@ var TaskStore = class {
 
 // src/tools/tasks/tools.ts
 init_cjs_shims();
-var import_zod21 = require("zod");
-var TaskStatusEnum = import_zod21.z.enum(["pending", "in_progress", "completed", "deleted"]);
-var createSchema = import_zod21.z.object({
-  subject: import_zod21.z.string().min(1),
-  description: import_zod21.z.string().default(""),
-  metadata: import_zod21.z.record(import_zod21.z.unknown()).optional()
+var import_zod22 = require("zod");
+init_contract();
+var TaskStatusEnum = import_zod22.z.enum(["pending", "in_progress", "completed", "deleted"]);
+var createSchema = import_zod22.z.object({
+  subject: import_zod22.z.string().min(1),
+  description: import_zod22.z.string().default(""),
+  metadata: import_zod22.z.record(import_zod22.z.unknown()).optional()
 });
 function createTaskCreateTool(store) {
   return defineTool({
@@ -5612,8 +5926,8 @@ function createTaskCreateTool(store) {
     }
   });
 }
-var getSchema = import_zod21.z.object({
-  taskId: import_zod21.z.string().min(1)
+var getSchema = import_zod22.z.object({
+  taskId: import_zod22.z.string().min(1)
 });
 function createTaskGetTool(store) {
   return defineTool({
@@ -5634,7 +5948,7 @@ ${task.description}`,
     }
   });
 }
-var listSchema = import_zod21.z.object({
+var listSchema = import_zod22.z.object({
   status: TaskStatusEnum.optional()
 });
 function createTaskListTool(store) {
@@ -5660,12 +5974,12 @@ ${lines.join("\n")}`,
     }
   });
 }
-var updateSchema = import_zod21.z.object({
-  taskId: import_zod21.z.string().min(1),
-  subject: import_zod21.z.string().min(1).optional(),
+var updateSchema = import_zod22.z.object({
+  taskId: import_zod22.z.string().min(1),
+  subject: import_zod22.z.string().min(1).optional(),
   status: TaskStatusEnum.optional(),
-  description: import_zod21.z.string().optional(),
-  metadata: import_zod21.z.record(import_zod21.z.unknown()).optional()
+  description: import_zod22.z.string().optional(),
+  metadata: import_zod22.z.record(import_zod22.z.unknown()).optional()
 });
 function createTaskUpdateTool(store) {
   return defineTool({
@@ -6036,17 +6350,17 @@ var BindingHttpTransport = class {
     }
     if (response.status === 202 || response.status === 204) return;
     if (!response.ok) {
-      const text = await safeText2(response);
+      const text2 = await safeText2(response);
       const err = new Error(
-        `BindingHttpTransport: HTTP ${String(response.status)} ${response.statusText}${text ? ` \u2014 ${text}` : ""}`
+        `BindingHttpTransport: HTTP ${String(response.status)} ${response.statusText}${text2 ? ` \u2014 ${text2}` : ""}`
       );
       this.onerror?.(err);
       throw err;
     }
     const contentType = response.headers.get("Content-Type") ?? "";
     if (!contentType.includes("application/json")) {
-      const text = await response.text();
-      const parsed2 = parseSseFrames(text);
+      const text2 = await response.text();
+      const parsed2 = parseSseFrames(text2);
       for (const msg of parsed2) this.onmessage?.(msg);
       return;
     }
@@ -6113,9 +6427,9 @@ async function safeText2(r) {
     return "";
   }
 }
-function parseSseFrames(text) {
+function parseSseFrames(text2) {
   const out = [];
-  for (const block of text.split(/\r?\n\r?\n/)) {
+  for (const block of text2.split(/\r?\n\r?\n/)) {
     const lines = block.split(/\r?\n/).filter((l) => l.startsWith("data:"));
     if (lines.length === 0) continue;
     const raw = lines.map((l) => l.slice(5).trimStart()).join("\n");
@@ -6402,8 +6716,8 @@ function normalizeToolList(response, serverName) {
     const name = typeof obj.name === "string" ? obj.name : null;
     if (name === null) continue;
     const description = typeof obj.description === "string" ? obj.description : "";
-    const inputSchema17 = obj.inputSchema !== null && typeof obj.inputSchema === "object" && !Array.isArray(obj.inputSchema) ? obj.inputSchema : { type: "object", properties: {} };
-    out.push({ name, description, inputSchema: inputSchema17 });
+    const inputSchema20 = obj.inputSchema !== null && typeof obj.inputSchema === "object" && !Array.isArray(obj.inputSchema) ? obj.inputSchema : { type: "object", properties: {} };
+    out.push({ name, description, inputSchema: inputSchema20 });
   }
   return out;
 }
@@ -6512,7 +6826,8 @@ function wrapFetchWithHeadersProvider(baseFetch, headersProvider, staticHeaders)
 
 // src/mcp/toolAdapter.ts
 init_cjs_shims();
-var import_zod22 = require("zod");
+var import_zod23 = require("zod");
+init_contract();
 function mcpToolName(serverName, toolName) {
   return `mcp__${serverName}__${toolName}`;
 }
@@ -6521,7 +6836,7 @@ function adaptMcpTool(client, serverName, def) {
   return defineTool({
     name: registeredName,
     description: def.description.length > 0 ? def.description : `MCP tool ${serverName}/${def.name}`,
-    inputSchema: import_zod22.z.unknown(),
+    inputSchema: import_zod23.z.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).
@@ -7053,15 +7368,15 @@ var Hippocampus = class _Hippocampus {
     return (content ?? "").trim();
   }
   // ---------- encode (write) ----------
-  async encodeRule(text, kind, confidence = "medium", source = "llm") {
+  async encodeRule(text2, kind, confidence = "medium", source = "llm") {
     const ts = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
     const metadata = `<!-- confidence:${confidence} source:${source} ts:${ts} -->`;
-    const entry = `- ${text} ${metadata}
+    const entry = `- ${text2} ${metadata}
 `;
     const sectionHeader = `## ${kind.charAt(0).toUpperCase()}${kind.slice(1)}`;
     let content = await this.storage.readFile(this.rulesPath);
     if (content === null) content = RULES_SKELETON;
-    if (_Hippocampus.extractEntryTexts(content).has(text)) return;
+    if (_Hippocampus.extractEntryTexts(content).has(text2)) return;
     const lines = content.split(/(?<=\n)/);
     const out = [];
     let inserted = false;
@@ -7094,17 +7409,17 @@ ${entry}`);
     }
     await this.storage.writeFile(this.rulesPath, out.join(""));
   }
-  async encodeLesson(text, topic = "", source = "llm") {
+  async encodeLesson(text2, topic = "", source = "llm") {
     const ts = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
     const topicTag = topic ? ` topic:${topic}` : "";
     const sourceTag = source !== "llm" ? ` source:${source}` : "";
-    const entry = `- ${text} <!--${topicTag}${sourceTag} ts:${ts} -->
+    const entry = `- ${text2} <!--${topicTag}${sourceTag} ts:${ts} -->
 `;
     const existing = await this.storage.readFile(this.lessonsPath);
     if (existing === null) {
       await this.storage.writeFile(this.lessonsPath, `# Lessons
 ${entry}`);
-    } else if (!_Hippocampus.extractEntryTexts(existing).has(text)) {
+    } else if (!_Hippocampus.extractEntryTexts(existing).has(text2)) {
       await this.storage.appendFile(this.lessonsPath, entry);
     }
     if (topic) {
@@ -7114,7 +7429,7 @@ ${entry}`);
       if (topicContent === null) {
         await this.storage.writeFile(topicPath, `# ${topic}
 ${entry}`);
-      } else if (!_Hippocampus.extractEntryTexts(topicContent).has(text)) {
+      } else if (!_Hippocampus.extractEntryTexts(topicContent).has(text2)) {
         await this.storage.appendFile(topicPath, entry);
       }
     }
@@ -7170,12 +7485,12 @@ ${entries.map((e) => `- ${e}`).join("\n")}
   }
   /** Sanitize a topic name into a safe file slug. */
   static sanitizeSlug(name) {
-    let text = name.toLowerCase().trim();
-    text = text.replace(/[^a-z0-9\s_-]/g, "");
-    text = text.replace(/\s+/g, "-");
-    text = text.replace(/-+/g, "-");
-    text = text.replace(/^-|-$/g, "");
-    return text.length > 0 ? text : "general";
+    let text2 = name.toLowerCase().trim();
+    text2 = text2.replace(/[^a-z0-9\s_-]/g, "");
+    text2 = text2.replace(/\s+/g, "-");
+    text2 = text2.replace(/-+/g, "-");
+    text2 = text2.replace(/^-|-$/g, "");
+    return text2.length > 0 ? text2 : "general";
   }
 };
 
@@ -7207,13 +7522,13 @@ function createSmartMemory(options) {
       if (!readsEnabled) return "";
       return hippocampus.recallTopic(slug);
     },
-    async encodeRule(text, kind, confidence, source) {
+    async encodeRule(text2, kind, confidence, source) {
       if (!writesEnabled) return;
-      await hippocampus.encodeRule(text, kind, confidence, source);
+      await hippocampus.encodeRule(text2, kind, confidence, source);
     },
-    async encodeLesson(text, topic, source) {
+    async encodeLesson(text2, topic, source) {
       if (!writesEnabled) return;
-      await hippocampus.encodeLesson(text, topic, source);
+      await hippocampus.encodeLesson(text2, topic, source);
     },
     async rewriteIdentity(entries) {
       if (!writesEnabled) return;
@@ -7579,8 +7894,8 @@ function buildSchemaPrompt(schema) {
   }
   return lines.join("\n");
 }
-function tryParseJSON(text) {
-  const trimmed = text.trim();
+function tryParseJSON2(text2) {
+  const trimmed = text2.trim();
   try {
     return { ok: true, value: JSON.parse(trimmed) };
   } catch {
@@ -7619,17 +7934,18 @@ ${issues.join("\n")}` };
 
 // src/skills/skillPage.ts
 init_cjs_shims();
-var import_zod23 = require("zod");
+var import_zod24 = require("zod");
+init_contract();
 var SAFE_NAME3 = /^[a-zA-Z0-9_-]+$/;
-var inputSchema16 = import_zod23.z.object({
-  skill: import_zod23.z.string().min(1),
-  page: import_zod23.z.string().min(1).optional()
+var inputSchema17 = import_zod24.z.object({
+  skill: import_zod24.z.string().min(1),
+  page: import_zod24.z.string().min(1).optional()
 });
 function createSkillPageTool(options) {
   return defineTool({
     name: "SkillPage",
     description: "Load a skill. Pass `skill` alone to read the main SKILL.md; pass both `skill` and `page` to read a supplemental page. Skill names appear in the system prompt skill index.",
-    inputSchema: inputSchema16,
+    inputSchema: inputSchema17,
     execute: async ({ skill, page }) => {
       if (!SAFE_NAME3.test(skill)) {
         return {
@@ -7681,7 +7997,8 @@ The skill "${skill}" has no pages.`;
 
 // src/tools/apiCall.ts
 init_cjs_shims();
-var import_zod24 = require("zod");
+var import_zod25 = require("zod");
+init_contract();
 var ALL_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
 var DEFAULT_MAX_BODY_BYTES = 256 * 1024;
 var DEFAULT_MAX_RESPONSE_BYTES = 100 * 1024;
@@ -7706,19 +8023,19 @@ function createApiCallTool(opts) {
   }
   const fetchFn = opts.fetch ?? globalThis.fetch.bind(globalThis);
   const maxResponseBytes = opts.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
-  const inputSchema17 = import_zod24.z.object({
-    service: import_zod24.z.enum(serviceNames),
-    method: import_zod24.z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]),
-    path: import_zod24.z.string().regex(/^\//, "path must start with /"),
-    query: import_zod24.z.record(import_zod24.z.string(), import_zod24.z.string()).optional(),
-    body: import_zod24.z.unknown().optional(),
-    headers: import_zod24.z.record(import_zod24.z.string(), import_zod24.z.string()).optional()
+  const inputSchema20 = import_zod25.z.object({
+    service: import_zod25.z.enum(serviceNames),
+    method: import_zod25.z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]),
+    path: import_zod25.z.string().regex(/^\//, "path must start with /"),
+    query: import_zod25.z.record(import_zod25.z.string(), import_zod25.z.string()).optional(),
+    body: import_zod25.z.unknown().optional(),
+    headers: import_zod25.z.record(import_zod25.z.string(), import_zod25.z.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,
+    inputSchema: inputSchema20,
     execute: async (input) => {
       const svc = services.get(input.service);
       if (!svc) {
@@ -7737,7 +8054,7 @@ function createApiCallTool(opts) {
       if (input.body !== void 0) {
         bodyText = JSON.stringify(input.body);
         const cap = svc.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
-        if (byteLength(bodyText) > cap) {
+        if (byteLength2(bodyText) > cap) {
           return errResult(`ERR_API_BODY_TOO_LARGE: exceeds ${cap} bytes`);
         }
       }
@@ -7811,7 +8128,7 @@ function pathAllowed(path, allowed) {
   }
   return false;
 }
-function byteLength(s) {
+function byteLength2(s) {
   return new TextEncoder().encode(s).byteLength;
 }
 function buildUrl(baseUrl, path, query) {
@@ -7876,6 +8193,572 @@ async function invokeHook(hook, event) {
   }
 }
 
+// src/engine/engine.ts
+init_fetchData();
+
+// src/tools/searchKnowledge.ts
+init_cjs_shims();
+var import_zod26 = require("zod");
+init_contract();
+
+// src/knowledge/scope.ts
+init_cjs_shims();
+var SAFE_PATH_RE = /^[a-zA-Z0-9_\-./]+$/;
+function parseFolderRef(raw) {
+  if (typeof raw !== "string" || raw.length === 0) {
+    throw new Error(`invalid knowledge folder ref: empty`);
+  }
+  if (raw.startsWith("/")) {
+    throw new Error(`invalid knowledge folder ref: absolute paths not allowed ("${raw}")`);
+  }
+  const trimmed = raw.replace(/\/+$/g, "");
+  if (trimmed.length === 0) {
+    throw new Error(`invalid knowledge folder ref: "${raw}"`);
+  }
+  if (!SAFE_PATH_RE.test(trimmed)) {
+    throw new Error(`invalid knowledge folder ref: unsafe characters in "${raw}"`);
+  }
+  if (trimmed.split("/").some((seg) => seg === ".." || seg === "." || seg === "")) {
+    throw new Error(`invalid knowledge folder ref: traversal in "${raw}"`);
+  }
+  const segs = trimmed.split("/");
+  const base = segs[0];
+  const subPath = segs.slice(1).join("/");
+  return { path: trimmed, base, subPath };
+}
+function relPathInScope(folder, relPath) {
+  if (folder.subPath === "") return true;
+  return relPath === folder.subPath || relPath.startsWith(`${folder.subPath}/`);
+}
+function parseKnowledgeRef(raw) {
+  if (typeof raw !== "string" || raw.length === 0) {
+    throw new Error("invalid knowledge ref: empty");
+  }
+  if (raw.startsWith("ext:")) {
+    const name = raw.slice("ext:".length);
+    if (!/^[a-zA-Z0-9_-]+$/.test(name) || name.length === 0) {
+      throw new Error(`invalid knowledge ref: external name "${name}" has unsafe characters`);
+    }
+    return { kind: "ext", target: name };
+  }
+  if (raw.startsWith("/")) {
+    throw new Error(`invalid knowledge ref: absolute paths not allowed ("${raw}")`);
+  }
+  const hashAt = raw.indexOf("#");
+  const filePath = hashAt === -1 ? raw : raw.slice(0, hashAt);
+  const section = hashAt === -1 ? void 0 : raw.slice(hashAt + 1);
+  if (!SAFE_PATH_RE.test(filePath)) {
+    throw new Error(`invalid knowledge ref: unsafe characters in "${filePath}"`);
+  }
+  if (filePath.split("/").some((seg) => seg === ".." || seg === "." || seg === "")) {
+    throw new Error(`invalid knowledge ref: traversal in "${filePath}"`);
+  }
+  if (section !== void 0) {
+    if (section.length > 0 && !/^[a-zA-Z0-9_-]+$/.test(section)) {
+      throw new Error(`invalid knowledge ref: unsafe characters in section "${section}"`);
+    }
+    return { kind: "section", target: filePath, section };
+  }
+  return { kind: "file", target: filePath };
+}
+function refInScope(folders, filePath) {
+  return folders.some((f) => {
+    if (filePath === f.base || filePath.startsWith(`${f.base}/`)) {
+      const relInBase = filePath === f.base ? "" : filePath.slice(f.base.length + 1);
+      return relPathInScope(f, relInBase);
+    }
+    return false;
+  });
+}
+
+// src/knowledge/tokenize.ts
+init_cjs_shims();
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "the",
+  "and",
+  "of",
+  "to",
+  "a",
+  "in",
+  "is",
+  "it",
+  "you",
+  "that",
+  "was",
+  "for",
+  "on",
+  "are",
+  "with",
+  "as",
+  "this",
+  "by",
+  "from",
+  "or",
+  "but",
+  "not",
+  "all",
+  "an",
+  "has",
+  "have",
+  "had",
+  "will",
+  "can",
+  "do",
+  "did",
+  "be",
+  "been",
+  "being",
+  "your",
+  "our",
+  "their",
+  "his",
+  "her",
+  "my",
+  "we",
+  "they",
+  "them",
+  "than",
+  "so",
+  "if",
+  "at",
+  "no",
+  "yes",
+  "me",
+  "us",
+  "i",
+  "he",
+  "she"
+]);
+function tokenize(text2) {
+  if (typeof text2 !== "string" || text2.length === 0) return [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const raw of text2.toLowerCase().split(/[\W_]+/)) {
+    if (raw.length < 2) continue;
+    if (STOP_WORDS.has(raw)) continue;
+    seen.add(raw);
+  }
+  return [...seen].sort();
+}
+function scoreOverlap(sectionWords, queryTokens) {
+  const set = sectionWords instanceof Set ? sectionWords : new Set(sectionWords);
+  let n = 0;
+  for (const t of queryTokens) if (set.has(t)) n++;
+  return n;
+}
+
+// src/tools/searchKnowledge.ts
+var DEFAULT_MAX_RESULTS = 5;
+var inputSchema18 = import_zod26.z.object({
+  query: import_zod26.z.string().min(1),
+  maxResults: import_zod26.z.number().int().positive().optional()
+});
+function createSearchKnowledgeTool(opts) {
+  const scoped = opts.folders.map(parseFolderRef);
+  const indexCache = /* @__PURE__ */ new Map();
+  const cap = opts.maxSearchResults ?? DEFAULT_MAX_RESULTS;
+  const externals = opts.external;
+  return defineTool({
+    name: "SearchKnowledge",
+    description: "Search the agent's knowledge base. Returns up to K ranked snippets matching the query (across all configured knowledge folders + any attached external file links). Each result carries a `ref` you can pass back to the `ReadKnowledge` tool to load the full content of that section or file.",
+    inputSchema: inputSchema18,
+    execute: async ({ query, maxResults }) => {
+      const limit = Math.min(maxResults ?? cap, cap);
+      const queryTokens = tokenize(query);
+      if (queryTokens.length === 0) {
+        return { content: "no searchable tokens in query", isError: false };
+      }
+      const sectionHits = [];
+      const seenBases = /* @__PURE__ */ new Set();
+      for (const folder of scoped) {
+        if (!seenBases.has(folder.base)) {
+          seenBases.add(folder.base);
+        }
+      }
+      for (const baseName of seenBases) {
+        const idx = await loadIndex(opts.adapter, baseName, indexCache);
+        if (idx === null) continue;
+        for (const section of idx.sections) {
+          const eligible = scoped.some(
+            (f) => f.base === baseName && relPathInScope(f, section.relPath)
+          );
+          if (!eligible) continue;
+          const score = scoreOverlap(section.words, queryTokens);
+          if (score > 0) sectionHits.push({ section, base: baseName, score });
+        }
+      }
+      const externalHits = [];
+      for (const link of externals) {
+        const score = scoreOverlap(tokenize(link.description), queryTokens);
+        if (score > 0) externalHits.push({ link, score });
+      }
+      const all = [
+        ...sectionHits.map((h) => ({
+          kind: "knowledge",
+          score: h.score,
+          render: () => `[knowledge] ${h.base}/${h.section.relPath} \xA7"${h.section.heading || "(lead-in)"}"
+  ${truncatePreview(h.section.preview)}
+  ref: ${h.base}/${h.section.slug}`
+        })),
+        ...externalHits.map((h) => ({
+          kind: "external",
+          score: h.score,
+          render: () => `[external] ${h.link.name} (${h.link.format})
+  ${h.link.description}
+  ref: ext:${h.link.name}`
+        }))
+      ];
+      if (all.length === 0) {
+        return { content: `no knowledge matches for "${query}"`, isError: false };
+      }
+      all.sort((a, b) => b.score - a.score);
+      const top = all.slice(0, limit);
+      const body = top.map((h, i) => `${i + 1}. ${h.render()}`).join("\n\n");
+      return {
+        content: `Found ${top.length} knowledge match${top.length === 1 ? "" : "es"} (of ${all.length} ranked):
+
+${body}`,
+        isError: false,
+        metadata: { hits: all.length, returned: top.length }
+      };
+    }
+  });
+}
+function truncatePreview(s) {
+  if (s.length <= 200) return s;
+  return s.slice(0, 200) + "\u2026";
+}
+async function loadIndex(adapter, base, cache) {
+  const cached2 = cache.get(base);
+  if (cached2 !== void 0) return cached2;
+  let raw;
+  try {
+    raw = await adapter.readFile(`${base}/_index.json`);
+  } catch {
+    return null;
+  }
+  if (raw === null) return null;
+  try {
+    const parsed = JSON.parse(raw);
+    cache.set(base, parsed);
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+// src/tools/readKnowledge.ts
+init_cjs_shims();
+var import_zod27 = require("zod");
+init_contract();
+
+// src/knowledge/extractors.ts
+init_cjs_shims();
+var CSV_MAX_ROWS = 100;
+var HTML_TAG_RE = /<[^>]+>/g;
+var HTML_ENTITIES = {
+  "&amp;": "&",
+  "&lt;": "<",
+  "&gt;": ">",
+  "&quot;": '"',
+  "&#39;": "'",
+  "&nbsp;": " "
+};
+function decodeHtmlEntities(s) {
+  return s.replace(/&(amp|lt|gt|quot|#39|nbsp);/g, (m) => HTML_ENTITIES[m] ?? m);
+}
+var text = {
+  format: "txt",
+  requiresNode: false,
+  extract: async (raw) => raw
+};
+var md = {
+  format: "md",
+  requiresNode: false,
+  extract: async (raw) => raw
+};
+var json = {
+  format: "json",
+  requiresNode: false,
+  extract: async (raw) => {
+    try {
+      return JSON.stringify(JSON.parse(raw), null, 2);
+    } catch {
+      return raw;
+    }
+  }
+};
+var csv = {
+  format: "csv",
+  requiresNode: false,
+  extract: async (raw) => {
+    const lines = raw.split(/\r?\n/).filter((l) => l.length > 0);
+    if (lines.length === 0) return "";
+    if (lines.length <= CSV_MAX_ROWS + 1) return lines.join("\n");
+    const head = lines.slice(0, CSV_MAX_ROWS + 1);
+    const remaining = lines.length - head.length;
+    return `${head.join("\n")}
+\u2026[${remaining.toLocaleString()} more row${remaining === 1 ? "" : "s"} truncated]`;
+  }
+};
+var html = {
+  format: "html",
+  requiresNode: false,
+  extract: async (raw) => {
+    const stripped = raw.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, "").replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, "").replace(HTML_TAG_RE, " ");
+    return decodeHtmlEntities(stripped).replace(/\s+/g, " ").trim();
+  }
+};
+var pdf = {
+  format: "pdf",
+  requiresNode: true,
+  extract: async (raw) => {
+    let pdfParse;
+    try {
+      const mod = await import("pdf-parse");
+      pdfParse = mod.default ?? mod;
+    } catch {
+      throw new Error(
+        "ERR_KNOWLEDGE_FORMAT_UNSUPPORTED: pdf-parse is not installed. Run `npm install pdf-parse` to enable PDF extraction."
+      );
+    }
+    const buf = Buffer.from(raw, "binary");
+    const result = await pdfParse(buf);
+    return result.text;
+  }
+};
+var docx = {
+  format: "docx",
+  requiresNode: true,
+  extract: async (raw) => {
+    let mammoth;
+    try {
+      mammoth = await import("mammoth");
+    } catch {
+      throw new Error(
+        "ERR_KNOWLEDGE_FORMAT_UNSUPPORTED: mammoth is not installed. Run `npm install mammoth` to enable DOCX extraction."
+      );
+    }
+    const buf = Buffer.from(raw, "binary");
+    const result = await mammoth.extractRawText({ buffer: buf });
+    return result.value;
+  }
+};
+var EXTRACTORS = {
+  md,
+  txt: text,
+  json,
+  csv,
+  html,
+  pdf,
+  docx
+};
+function getExtractor(format) {
+  const e = EXTRACTORS[format];
+  if (e === void 0) throw new Error(`ERR_KNOWLEDGE_FORMAT_UNSUPPORTED: ${format}`);
+  return e;
+}
+
+// src/tools/readKnowledge.ts
+var DEFAULT_MAX_READ_BYTES = 1e4;
+var inputSchema19 = import_zod27.z.object({
+  ref: import_zod27.z.string().min(1)
+});
+function createReadKnowledgeTool(opts) {
+  const scoped = opts.folders.map(parseFolderRef);
+  const indexCache = /* @__PURE__ */ new Map();
+  const fileCache = /* @__PURE__ */ new Map();
+  const cap = opts.maxReadBytes ?? DEFAULT_MAX_READ_BYTES;
+  const externalsByName = new Map(opts.external.map((e) => [e.name, e]));
+  const fetchFn = opts.fetch ?? globalThis.fetch.bind(globalThis);
+  return defineTool({
+    name: "ReadKnowledge",
+    description: "Load the full content of a knowledge ref returned by SearchKnowledge. Use the `ref` value verbatim from the search results \u2014 section refs return one section, file refs return the whole file (with format-specific extraction for non-markdown formats), and `ext:{name}` refs fetch a pre-registered external file.",
+    inputSchema: inputSchema19,
+    execute: async ({ ref }) => {
+      let parsed;
+      try {
+        parsed = parseKnowledgeRef(ref);
+      } catch (err) {
+        return {
+          content: `ERR_KNOWLEDGE_REF_INVALID: ${err instanceof Error ? err.message : String(err)}`,
+          isError: true
+        };
+      }
+      if (parsed.kind === "ext") {
+        return readExternal(parsed.target, externalsByName, fetchFn, cap);
+      }
+      if (!refInScope(scoped, parsed.target)) {
+        return {
+          content: `ERR_KNOWLEDGE_FOLDER_NOT_ALLOWED: ref "${parsed.target}" is outside the run's allowed folders`,
+          isError: true
+        };
+      }
+      const base = parsed.target.split("/")[0];
+      const relPath = parsed.target.slice(base.length + 1);
+      if (parsed.kind === "section") {
+        const idx = await loadIndex2(opts.adapter, base, indexCache);
+        if (idx === null) {
+          return {
+            content: `ERR_KNOWLEDGE_INDEX_MISSING: no _index.json for base "${base}"`,
+            isError: true
+          };
+        }
+        const sectionSlug = parsed.section ?? "";
+        const section = idx.sections.find(
+          (s) => s.relPath === relPath && extractAnchor(s.slug) === sectionSlug
+        );
+        if (section === void 0) {
+          return {
+            content: `ERR_KNOWLEDGE_REF_NOT_FOUND: section ${parsed.target}#${sectionSlug} not in index for "${base}"`,
+            isError: true
+          };
+        }
+        const fullContent = await readFile(opts.adapter, parsed.target, fileCache);
+        if (fullContent === null) {
+          return {
+            content: `ERR_KNOWLEDGE_REF_NOT_FOUND: file ${parsed.target} not found in storage`,
+            isError: true
+          };
+        }
+        const sliced = sliceLines(fullContent, section.startLine, section.endLine);
+        return wrapResult(`[knowledge] ${parsed.target}#${sectionSlug}`, sliced, cap);
+      }
+      const fmt = inferFormat(parsed.target);
+      if (fmt === null) {
+        return {
+          content: `ERR_KNOWLEDGE_FORMAT_UNSUPPORTED: cannot infer format for "${parsed.target}"`,
+          isError: true
+        };
+      }
+      const raw = await readFile(opts.adapter, parsed.target, fileCache);
+      if (raw === null) {
+        return {
+          content: `ERR_KNOWLEDGE_REF_NOT_FOUND: file ${parsed.target} not found in storage`,
+          isError: true
+        };
+      }
+      let extracted;
+      try {
+        extracted = await getExtractor(fmt).extract(raw);
+      } catch (err) {
+        return {
+          content: `ERR_KNOWLEDGE_EXTRACTOR_FAILED: ${err instanceof Error ? err.message : String(err)}`,
+          isError: true
+        };
+      }
+      return wrapResult(`[knowledge] ${parsed.target} (${fmt})`, extracted, cap);
+    }
+  });
+}
+async function readExternal(name, registry, fetchFn, cap) {
+  const link = registry.get(name);
+  if (link === void 0) {
+    return {
+      content: `ERR_KNOWLEDGE_REF_NOT_FOUND: no external link named "${name}"`,
+      isError: true
+    };
+  }
+  let res;
+  try {
+    res = await fetchFn(link.url, {
+      headers: link.headers ?? {}
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      content: `ERR_KNOWLEDGE_NETWORK: ${msg.slice(0, 200)}`,
+      isError: true
+    };
+  }
+  if (!res.ok) {
+    return {
+      content: `ERR_KNOWLEDGE_NETWORK: HTTP ${res.status} fetching ext:${name}`,
+      isError: true
+    };
+  }
+  const raw = await res.text();
+  let extracted;
+  try {
+    extracted = await getExtractor(link.format).extract(raw);
+  } catch (err) {
+    return {
+      content: `ERR_KNOWLEDGE_EXTRACTOR_FAILED: ${err instanceof Error ? err.message : String(err)}`,
+      isError: true
+    };
+  }
+  return wrapResult(`[external] ${name} (${link.format})`, extracted, cap);
+}
+function wrapResult(header, body, cap) {
+  let payload = body;
+  if (body.length > cap) {
+    payload = body.slice(0, cap) + `
+\u2026[+${body.length - cap} more chars truncated]`;
+  }
+  return {
+    content: `${header}
+
+${payload}`,
+    isError: false,
+    metadata: { bytes: body.length }
+  };
+}
+async function loadIndex2(adapter, base, cache) {
+  const cached2 = cache.get(base);
+  if (cached2 !== void 0) return cached2;
+  let raw;
+  try {
+    raw = await adapter.readFile(`${base}/_index.json`);
+  } catch {
+    return null;
+  }
+  if (raw === null) return null;
+  try {
+    const idx = JSON.parse(raw);
+    cache.set(base, idx);
+    return idx;
+  } catch {
+    return null;
+  }
+}
+async function readFile(adapter, path, cache) {
+  const cached2 = cache.get(path);
+  if (cached2 !== void 0) return cached2;
+  const content = await adapter.readFile(path).catch(() => null);
+  if (content === null) return null;
+  cache.set(path, content);
+  return content;
+}
+function sliceLines(content, start, end) {
+  const lines = content.split(/\r?\n/);
+  return lines.slice(start - 1, end).join("\n");
+}
+function extractAnchor(slug) {
+  const i = slug.indexOf("#");
+  return i === -1 ? "" : slug.slice(i + 1);
+}
+function inferFormat(filePath) {
+  const ext = (filePath.split(".").pop() ?? "").toLowerCase();
+  switch (ext) {
+    case "md":
+    case "markdown":
+      return "md";
+    case "txt":
+      return "txt";
+    case "json":
+      return "json";
+    case "csv":
+      return "csv";
+    case "html":
+    case "htm":
+      return "html";
+    case "pdf":
+      return "pdf";
+    case "docx":
+      return "docx";
+  }
+  return null;
+}
+
 // src/skills/storageSkillSource.ts
 init_cjs_shims();
 var SAFE_NAME4 = /^[a-zA-Z0-9_-]+$/;
@@ -8015,9 +8898,9 @@ var InlineSkillSource = class {
         `InlineSkillSource: fetch ${url} \u2192 HTTP ${String(response.status)} ${response.statusText}`
       );
     }
-    const text = await response.text();
-    this.cache.set(cacheKey, text);
-    return text;
+    const text2 = await response.text();
+    this.cache.set(cacheKey, text2);
+    return text2;
   }
   assertUrlAllowed(url) {
     const hosts = this.allowedHosts;
@@ -8489,47 +9372,60 @@ var R2BindingStorageAdapter = class {
 // src/storage/factory.ts
 var ENGINE_DATA_FOLDER = ".claude";
 var WORKSPACES_FOLDER = "workspaces";
-async function createEngineStorage(config) {
+var KNOWLEDGE_FOLDER = "knowledge";
+async function createEngineStorage(config, options = {}) {
   switch (config.provider) {
     case "local":
-      return createLocalStorage(config);
+      return createLocalStorage(config, options);
     case "r2":
-      return createR2Storage(config);
+      return createR2Storage(config, options);
     case "r2-binding":
-      return createR2BindingStorage(config);
+      return createR2BindingStorage(config, options);
   }
 }
-async function createLocalStorage(config) {
+async function createLocalStorage(config, options) {
   const path = await import("path");
-  const workspaceRoot = path.join(
-    config.rootPath,
-    WORKSPACES_FOLDER,
-    config.workspaceId,
-    ENGINE_DATA_FOLDER
-  );
-  return {
-    workspace: new LocalStorageAdapter(workspaceRoot)
-  };
+  const tenantRoot = path.join(config.rootPath, WORKSPACES_FOLDER, config.workspaceId);
+  const workspaceRoot = path.join(tenantRoot, ENGINE_DATA_FOLDER);
+  const out = { workspace: new LocalStorageAdapter(workspaceRoot) };
+  if (options.withKnowledge) {
+    const knowledgeRoot = path.join(tenantRoot, KNOWLEDGE_FOLDER);
+    return { ...out, knowledge: new LocalStorageAdapter(knowledgeRoot) };
+  }
+  return out;
 }
-function createR2Storage(config) {
+function createR2Storage(config, options) {
   if (!config.r2) {
     throw new StorageError('storage.r2 is required when storage.provider === "r2"');
   }
   const rootPrefix = config.rootPath.replace(/^\/+|\/+$/g, "");
-  const workspacePrefix = `${rootPrefix}/${WORKSPACES_FOLDER}/${config.workspaceId}/${ENGINE_DATA_FOLDER}`;
-  return {
-    workspace: new R2StorageAdapter(config.r2, workspacePrefix)
-  };
+  const tenantPrefix = `${rootPrefix}/${WORKSPACES_FOLDER}/${config.workspaceId}`;
+  const workspacePrefix = `${tenantPrefix}/${ENGINE_DATA_FOLDER}`;
+  const out = { workspace: new R2StorageAdapter(config.r2, workspacePrefix) };
+  if (options.withKnowledge) {
+    const knowledgePrefix = `${tenantPrefix}/${KNOWLEDGE_FOLDER}`;
+    return { ...out, knowledge: new R2StorageAdapter(config.r2, knowledgePrefix) };
+  }
+  return out;
 }
-function createR2BindingStorage(config) {
+function createR2BindingStorage(config, options) {
   if (!config.r2Binding) {
     throw new StorageError('storage.r2Binding is required when storage.provider === "r2-binding"');
   }
   const rootPrefix = config.rootPath.replace(/^\/+|\/+$/g, "");
-  const workspacePrefix = `${rootPrefix}/${WORKSPACES_FOLDER}/${config.workspaceId}/${ENGINE_DATA_FOLDER}`;
-  return {
+  const tenantPrefix = `${rootPrefix}/${WORKSPACES_FOLDER}/${config.workspaceId}`;
+  const workspacePrefix = `${tenantPrefix}/${ENGINE_DATA_FOLDER}`;
+  const out = {
     workspace: new R2BindingStorageAdapter(config.r2Binding, workspacePrefix)
   };
+  if (options.withKnowledge) {
+    const knowledgePrefix = `${tenantPrefix}/${KNOWLEDGE_FOLDER}`;
+    return {
+      ...out,
+      knowledge: new R2BindingStorageAdapter(config.r2Binding, knowledgePrefix)
+    };
+  }
+  return out;
 }
 
 // src/transcript/reader.ts
@@ -9033,6 +9929,8 @@ var Engine = class {
     const skillSource = this.resolveSkillSource(options.skills, storage);
     const skillList = skillSource !== void 0 ? await skillSource.list() : void 0;
     const apiConfig = this.resolveApiConfig(options.api);
+    const offloadConfig = this.resolveOffloadConfig(options.compaction?.toolResultOffload);
+    const knowledgeRuntime = this.resolveKnowledgeRuntime(options.knowledge, storage);
     let systemPrompt = await buildSystemPrompt({
       ...coordinatorBase !== void 0 ? { base: coordinatorBase } : {},
       memory,
@@ -9065,6 +9963,8 @@ var Engine = class {
       ...this.config.hooks.propagateGateToSubagents === true && gate !== void 0 ? { subagentGate: gate } : {},
       ...skillSource !== void 0 ? { skillSource } : {},
       ...apiConfig !== void 0 ? { apiConfig } : {},
+      ...offloadConfig !== void 0 ? { toolResultOffload: offloadConfig } : {},
+      ...knowledgeRuntime !== void 0 ? { knowledge: knowledgeRuntime } : {},
       ...this.internals.fetch !== void 0 ? { fetch: this.internals.fetch } : {}
     });
     const writer = new TranscriptWriter({
@@ -9120,7 +10020,8 @@ var Engine = class {
         ...options.tokenBudget !== void 0 ? { tokenBudget: options.tokenBudget } : {},
         ...runTimeout.signal !== void 0 ? { runSignal: runTimeout.signal, runTimeoutMs: this.config.execution.runTimeoutMs } : {},
         ...gate !== void 0 ? { gateBeforeTool: gate } : {},
-        ..._internal?.handoffToRunner === true ? { handoffToRunner: true } : {}
+        ..._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 } : {},
@@ -9175,6 +10076,8 @@ var Engine = class {
     const skillSource = this.resolveSkillSource(options.skills, storage);
     const skillList = skillSource !== void 0 ? await skillSource.list() : void 0;
     const apiConfig = this.resolveApiConfig(options.api);
+    const offloadConfig = this.resolveOffloadConfig(options.compaction?.toolResultOffload);
+    const knowledgeRuntime = this.resolveKnowledgeRuntime(options.knowledge, storage);
     let systemPrompt = await buildSystemPrompt({
       ...coordinatorBase !== void 0 ? { base: coordinatorBase } : {},
       memory,
@@ -9207,6 +10110,8 @@ var Engine = class {
       ...this.config.hooks.propagateGateToSubagents === true && gate !== void 0 ? { subagentGate: gate } : {},
       ...skillSource !== void 0 ? { skillSource } : {},
       ...apiConfig !== void 0 ? { apiConfig } : {},
+      ...offloadConfig !== void 0 ? { toolResultOffload: offloadConfig } : {},
+      ...knowledgeRuntime !== void 0 ? { knowledge: knowledgeRuntime } : {},
       ...this.internals.fetch !== void 0 ? { fetch: this.internals.fetch } : {}
     });
     const priorState = await loadWriterState(storage.workspace, logPath);
@@ -9297,7 +10202,8 @@ ${inputJson}
         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 } : {},
-        ..._internal?.handoffToRunner === true ? { handoffToRunner: true } : {}
+        ..._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 } : {},
@@ -9843,6 +10749,19 @@ ${inputJson}
         names.add("ApiCall");
       }
     }
+    if (this.config.compaction.toolResultOffload?.enabled === true) {
+      if (!disabled.has("FetchData") && (wantAll || enabled.has("FetchData"))) {
+        names.add("FetchData");
+      }
+    }
+    if (this.config.knowledge?.enabled === true) {
+      if (!disabled.has("SearchKnowledge") && (wantAll || enabled.has("SearchKnowledge"))) {
+        names.add("SearchKnowledge");
+      }
+      if (!disabled.has("ReadKnowledge") && (wantAll || enabled.has("ReadKnowledge"))) {
+        names.add("ReadKnowledge");
+      }
+    }
     for (const tool of this.config.tools.custom) {
       names.add(tool.name);
     }
@@ -9944,7 +10863,7 @@ ${inputJson}
       await writer.setStatus("done");
       let data;
       if (jsonOptions?.outputFormat === "json") {
-        const parsed = tryParseJSON(loopResult.output);
+        const parsed = tryParseJSON2(loopResult.output);
         if (parsed.ok) {
           if (jsonOptions.outputSchema) {
             const validated = validateOutput(parsed.value, jsonOptions.outputSchema);
@@ -10009,6 +10928,61 @@ ${inputJson}
    * tool isn't registered at all. Env + resolveAuth + hooks flow
    * through untouched — they never hit the Zod schema.
    */
+  /**
+   * Plan 021 — resolve the effective tool-result offload config.
+   *
+   * Precedence (each field independently):
+   *   RunOptions.compaction.toolResultOffload.X >
+   *     config.compaction.toolResultOffload.X
+   *
+   * When neither side enables offload, returns undefined and no
+   * `FetchData` tool is registered.
+   */
+  resolveOffloadConfig(override) {
+    const base = this.config.compaction.toolResultOffload;
+    if (override === void 0 && base === void 0) return void 0;
+    const enabled = override?.enabled ?? base?.enabled ?? false;
+    if (!enabled) return void 0;
+    const thresholdBytes = override?.thresholdBytes ?? base?.thresholdBytes ?? 2048;
+    const maxPreviewChars = override?.maxPreviewChars ?? base?.maxPreviewChars ?? 500;
+    const summarizer = override?.summarizer ?? base?.summarizer;
+    return {
+      enabled: true,
+      thresholdBytes,
+      maxPreviewChars,
+      ...summarizer !== void 0 ? { summarizer } : {}
+    };
+  }
+  /**
+   * Plan 023 — resolve the effective runtime knowledge bundle for a
+   * single run.
+   *
+   * Engine-level config (`config.knowledge`) carries the capability
+   * flag + scalar caps. The actual folders + external links are
+   * RUNTIME-only, supplied via `RunOptions.knowledge`. Returning
+   * `undefined` means "don't register the knowledge tools" — callers
+   * skip the bundle entirely.
+   *
+   * Three gates must all pass:
+   *   1. `config.knowledge.enabled === true` (engine opt-in)
+   *   2. `storage.knowledge !== undefined` (adapter was built)
+   *   3. There IS something to look at — at least one folder OR
+   *      one external link supplied for this run.
+   */
+  resolveKnowledgeRuntime(override, storage) {
+    if (this.config.knowledge?.enabled !== true) return void 0;
+    if (storage.knowledge === void 0) return void 0;
+    const folders = override?.folders ?? [];
+    const external = override?.external ?? [];
+    if (folders.length === 0 && external.length === 0) return void 0;
+    return {
+      adapter: storage.knowledge,
+      folders,
+      external,
+      maxSearchResults: this.config.knowledge.maxSearchResults,
+      maxReadBytes: this.config.knowledge.maxReadBytes
+    };
+  }
   resolveApiConfig(override) {
     const base = this.config.api;
     if (override === void 0 && base === void 0) return void 0;
@@ -10071,7 +11045,9 @@ ${inputJson}
     if (this.internals.buildStorage !== void 0) {
       return this.internals.buildStorage();
     }
-    return createEngineStorage(this.config.storage);
+    return createEngineStorage(this.config.storage, {
+      withKnowledge: this.config.knowledge?.enabled === true
+    });
   }
   buildClient() {
     return createModelAdapter(this.config.model, {
@@ -10183,6 +11159,39 @@ function buildToolRegistry(options) {
       childRegistry.register(apiTool);
     }
   }
+  if (options.toolResultOffload?.enabled === true) {
+    if (!disabled.has("FetchData") && (wantAll || enabled.has("FetchData"))) {
+      const fetchDataTool = createFetchDataTool({
+        storage: storage.workspace,
+        logPath: options.parentLogPath
+      });
+      registry.register(fetchDataTool);
+    }
+  }
+  if (options.knowledge !== void 0) {
+    const k = options.knowledge;
+    if (!disabled.has("SearchKnowledge") && (wantAll || enabled.has("SearchKnowledge"))) {
+      const searchTool = createSearchKnowledgeTool({
+        adapter: k.adapter,
+        folders: k.folders,
+        external: k.external,
+        maxSearchResults: k.maxSearchResults
+      });
+      registry.register(searchTool);
+      childRegistry.register(searchTool);
+    }
+    if (!disabled.has("ReadKnowledge") && (wantAll || enabled.has("ReadKnowledge"))) {
+      const readTool = createReadKnowledgeTool({
+        adapter: k.adapter,
+        folders: k.folders,
+        external: k.external,
+        maxReadBytes: k.maxReadBytes,
+        ...options.fetch !== void 0 ? { fetch: options.fetch } : {}
+      });
+      registry.register(readTool);
+      childRegistry.register(readTool);
+    }
+  }
   const agentTool = createAgentTool({
     storage: storage.workspace,
     client,
@@ -10198,7 +11207,8 @@ function buildToolRegistry(options) {
     idleFlushMs: config.transcript.idleFlushMs,
     agents,
     coordinatorMode: isCoordinatorMode(config),
-    ...subagentGate !== void 0 ? { gateBeforeTool: subagentGate } : {}
+    ...subagentGate !== void 0 ? { gateBeforeTool: subagentGate } : {},
+    ...options.toolResultOffload !== void 0 ? { toolResultOffload: options.toolResultOffload } : {}
   });
   if (!disabled.has("Agent") && (wantAll || enabled.has("Agent"))) {
     registry.register(agentTool);
@@ -10226,6 +11236,155 @@ function buildToolRegistry(options) {
   return registry;
 }
 
+// src/index.ts
+init_contract();
+init_fetchData();
+
+// src/knowledge/indexer.ts
+init_cjs_shims();
+var HEADING_RE = /^(#{1,6})[ \t]+(.+?)\s*$/;
+var WIKI_LINK_RE = /\[\[([^\]|#]+)(?:[#|][^\]]*)?\]\]/g;
+var FORMAT_BY_EXT = {
+  md: "md",
+  markdown: "md",
+  txt: "txt",
+  json: "json",
+  csv: "csv",
+  html: "html",
+  htm: "html",
+  pdf: "pdf",
+  docx: "docx"
+};
+var PREVIEW_CHARS = 200;
+async function buildKnowledgeIndex(options) {
+  const { adapter, base } = options;
+  const safeBase = base.replace(/^\/+|\/+$/g, "");
+  if (safeBase.length === 0 || safeBase.includes("..")) {
+    throw new Error(`buildKnowledgeIndex: invalid base "${base}"`);
+  }
+  const files = await listFilesRecursive(adapter, safeBase);
+  const sections = [];
+  const filesMeta = {};
+  for (const fileRel of files) {
+    if (fileRel === "_index.json") continue;
+    const fullPath = `${safeBase}/${fileRel}`;
+    const ext = (fileRel.split(".").pop() ?? "").toLowerCase();
+    const format = FORMAT_BY_EXT[ext];
+    if (format === void 0) continue;
+    const raw = await adapter.readFile(fullPath);
+    if (raw === null) continue;
+    const sizeBytes = byteLength3(raw);
+    const meta = { format, size: sizeBytes };
+    if (format === "md" || format === "txt") {
+      const fileSections = splitSections(raw, fileRel);
+      sections.push(...fileSections);
+      const wikiLinks = extractWikiLinks(raw);
+      if (wikiLinks.length > 0) meta.wikiLinks = wikiLinks;
+    }
+    filesMeta[fileRel] = meta;
+  }
+  return {
+    schema: "v1",
+    base: safeBase,
+    builtAt: options.nowIso ?? (/* @__PURE__ */ new Date()).toISOString(),
+    fileCount: Object.keys(filesMeta).length,
+    sections,
+    files: filesMeta
+  };
+}
+async function writeKnowledgeIndex(options) {
+  const index = await buildKnowledgeIndex(options);
+  await options.adapter.writeFile(`${index.base}/_index.json`, JSON.stringify(index, null, 2));
+  return index;
+}
+async function listFilesRecursive(adapter, dir) {
+  const out = [];
+  const stack = [""];
+  while (stack.length > 0) {
+    const sub = stack.pop();
+    const fullDir = sub === "" ? dir : `${dir}/${sub}`;
+    let entries = [];
+    try {
+      entries = await adapter.listDir(fullDir);
+    } catch {
+      continue;
+    }
+    for (const name of entries) {
+      const childRel = sub === "" ? name : `${sub}/${name}`;
+      const childFull = `${dir}/${childRel}`;
+      const isDir = await adapter.isDirectory(childFull).catch(() => false);
+      if (isDir) {
+        stack.push(childRel);
+      } else {
+        out.push(childRel);
+      }
+    }
+  }
+  return out.sort();
+}
+function splitSections(content, relPath) {
+  const lines = content.split(/\r?\n/);
+  const out = [];
+  const heads = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const m = HEADING_RE.exec(line);
+    if (m) heads.push({ line: i + 1, depth: m[1].length, heading: m[2].trim() });
+  }
+  const leadInEndLine = heads.length > 0 ? heads[0].line - 1 : lines.length;
+  const leadInBody = lines.slice(0, leadInEndLine).join("\n").trim();
+  if (leadInBody.length > 0) {
+    out.push({
+      relPath,
+      heading: "",
+      slug: `${relPath}#`,
+      depth: 0,
+      words: tokenize(leadInBody),
+      preview: makePreview(leadInBody),
+      startLine: 1,
+      endLine: leadInEndLine
+    });
+  }
+  for (let i = 0; i < heads.length; i++) {
+    const h = heads[i];
+    const startLine = h.line;
+    const endLine = i + 1 < heads.length ? heads[i + 1].line - 1 : lines.length;
+    const body = lines.slice(startLine - 1, endLine).join("\n");
+    out.push({
+      relPath,
+      heading: h.heading,
+      slug: `${relPath}#${slugify(h.heading)}`,
+      depth: h.depth,
+      words: tokenize(body),
+      preview: makePreview(body),
+      startLine,
+      endLine
+    });
+  }
+  return out;
+}
+function makePreview(body) {
+  const trimmed = body.replace(/^#{1,6}\s+.+$\r?\n?/m, "").trim();
+  if (trimmed.length <= PREVIEW_CHARS) return trimmed;
+  return trimmed.slice(0, PREVIEW_CHARS) + "\u2026";
+}
+function slugify(text2) {
+  return text2.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function extractWikiLinks(text2) {
+  const seen = /* @__PURE__ */ new Set();
+  let m;
+  WIKI_LINK_RE.lastIndex = 0;
+  while ((m = WIKI_LINK_RE.exec(text2)) !== null) {
+    const target = m[1].trim();
+    if (target.length > 0) seen.add(target);
+  }
+  return [...seen].sort();
+}
+function byteLength3(s) {
+  return new TextEncoder().encode(s).byteLength;
+}
+
 // src/index.ts
 init_orchestrate();
 init_planParser();
@@ -10300,6 +11459,7 @@ function resolveApiKey(config) {
   WebhookDispatcher,
   adaptMcpTool,
   buildForkedMessages,
+  buildKnowledgeIndex,
   buildPermissionPolicy,
   buildSchemaPrompt,
   buildSystemPrompt,
@@ -10307,16 +11467,21 @@ function resolveApiKey(config) {
   canSpawnProcesses,
   capabilityStub,
   createApiCallTool,
+  createFetchDataTool,
   createLogger,
   createModelAdapter,
+  createReadKnowledgeTool,
+  createSearchKnowledgeTool,
   createSendMessageTool,
   createSkillPageTool,
   createSmartMemory,
   defaultSamplingHandler,
+  defaultToolResultSummarizer,
   defineTool,
   detectRuntime,
   getCoordinatorBasePrompt,
   getCoordinatorSystemPrompt,
+  getExtractor,
   hasProcessLifecycle,
   initEngine,
   isCoordinatorMode,
@@ -10339,6 +11504,7 @@ function resolveApiKey(config) {
   toResponse,
   tryParseJSON,
   validateOutput,
-  withCapabilityCheck
+  withCapabilityCheck,
+  writeKnowledgeIndex
 });
 //# sourceMappingURL=index.cjs.map