la-machina-engine 0.6.0 → 0.7.0

package/dist/index.cjs

@@ -127,34 +127,34 @@ var init_fetchData = __esm({
 });
 
 // src/orchestrator/types.ts
-var import_zod26, PlanStepSchema, PlanSchema;
+var import_zod28, PlanStepSchema, PlanSchema;
 var init_types = __esm({
   "src/orchestrator/types.ts"() {
     "use strict";
     init_cjs_shims();
-    import_zod26 = require("zod");
-    PlanStepSchema = import_zod26.z.object({
-      id: import_zod26.z.string().min(1),
-      description: import_zod26.z.string().min(1),
-      action: import_zod26.z.enum(["research", "implement", "verify", "review", "custom"]),
-      files: import_zod26.z.array(import_zod26.z.string()).optional(),
-      spec: import_zod26.z.string().optional(),
-      dependsOn: import_zod26.z.array(import_zod26.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_zod26.z.object({
-      summary: import_zod26.z.string().min(1),
-      steps: import_zod26.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;
   }
@@ -164,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);
       }
     }
   }
@@ -869,6 +869,7 @@ __export(index_exports, {
   WebhookDispatcher: () => WebhookDispatcher,
   adaptMcpTool: () => adaptMcpTool,
   buildForkedMessages: () => buildForkedMessages,
+  buildKnowledgeIndex: () => buildKnowledgeIndex,
   buildPermissionPolicy: () => buildPermissionPolicy,
   buildSchemaPrompt: () => buildSchemaPrompt,
   buildSystemPrompt: () => buildSystemPrompt,
@@ -879,6 +880,8 @@ __export(index_exports, {
   createFetchDataTool: () => createFetchDataTool,
   createLogger: () => createLogger,
   createModelAdapter: () => createModelAdapter,
+  createReadKnowledgeTool: () => createReadKnowledgeTool,
+  createSearchKnowledgeTool: () => createSearchKnowledgeTool,
   createSendMessageTool: () => createSendMessageTool,
   createSkillPageTool: () => createSkillPageTool,
   createSmartMemory: () => createSmartMemory,
@@ -888,6 +891,7 @@ __export(index_exports, {
   detectRuntime: () => detectRuntime,
   getCoordinatorBasePrompt: () => getCoordinatorBasePrompt,
   getCoordinatorSystemPrompt: () => getCoordinatorSystemPrompt,
+  getExtractor: () => getExtractor,
   hasProcessLifecycle: () => hasProcessLifecycle,
   initEngine: () => initEngine,
   isCoordinatorMode: () => isCoordinatorMode,
@@ -910,7 +914,8 @@ __export(index_exports, {
   toResponse: () => toResponse,
   tryParseJSON: () => tryParseJSON2,
   validateOutput: () => validateOutput,
-  withCapabilityCheck: () => withCapabilityCheck
+  withCapabilityCheck: () => withCapabilityCheck,
+  writeKnowledgeIndex: () => writeKnowledgeIndex
 });
 module.exports = __toCommonJS(index_exports);
 init_cjs_shims();
@@ -1243,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")
@@ -1264,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();
@@ -1275,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()
@@ -1339,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
@@ -1431,9 +1444,21 @@ function splitOffloadRuntime(user) {
   };
   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: afterOffload, summarizer } = splitOffloadRuntime(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);
@@ -2429,8 +2454,8 @@ function compactPreview(value) {
   }
   return str;
 }
-function tryParseJSON(text) {
-  const trimmed = text.replace(/^\uFEFF/, "").trim();
+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 };
@@ -2514,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, "");
@@ -3163,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({
@@ -3403,11 +3428,11 @@ function toAnthropicTool(tool) {
     target: "jsonSchema7",
     $refStrategy: "none"
   });
-  const { $schema: _schema, ...inputSchema18 } = schema;
+  const { $schema: _schema, ...inputSchema20 } = schema;
   return {
     name: tool.name,
     description: tool.description,
-    input_schema: inputSchema18
+    input_schema: inputSchema20
   };
 }
 function partitionToolCalls(calls, registry) {
@@ -3542,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",
@@ -3552,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 });
@@ -5405,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: {
@@ -5422,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 {
@@ -5503,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}":
 
@@ -5523,8 +5548,8 @@ ${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
@@ -5632,7 +5657,7 @@ function createMemorizeTool(memory) {
     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: inputSchema14,
-    execute: async ({ text, kind, topic }) => {
+    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.`,
@@ -5640,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 }
       };
     }
@@ -6325,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;
     }
@@ -6402,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");
@@ -6691,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 inputSchema18 = obj.inputSchema !== null && typeof obj.inputSchema === "object" && !Array.isArray(obj.inputSchema) ? obj.inputSchema : { type: "object", properties: {} };
-    out.push({ name, description, inputSchema: inputSchema18 });
+    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;
 }
@@ -7343,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;
@@ -7384,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) {
@@ -7404,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);
       }
     }
@@ -7460,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";
   }
 };
 
@@ -7497,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;
@@ -7869,8 +7894,8 @@ function buildSchemaPrompt(schema) {
   }
   return lines.join("\n");
 }
-function tryParseJSON2(text) {
-  const trimmed = text.trim();
+function tryParseJSON2(text2) {
+  const trimmed = text2.trim();
   try {
     return { ok: true, value: JSON.parse(trimmed) };
   } catch {
@@ -7998,7 +8023,7 @@ function createApiCallTool(opts) {
   }
   const fetchFn = opts.fetch ?? globalThis.fetch.bind(globalThis);
   const maxResponseBytes = opts.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
-  const inputSchema18 = import_zod25.z.object({
+  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 /"),
@@ -8010,7 +8035,7 @@ function createApiCallTool(opts) {
   return defineTool({
     name: opts.toolName ?? "ApiCall",
     description,
-    inputSchema: inputSchema18,
+    inputSchema: inputSchema20,
     execute: async (input) => {
       const svc = services.get(input.service);
       if (!svc) {
@@ -8171,6 +8196,569 @@ 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_-]+$/;
@@ -8310,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;
@@ -8784,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
@@ -9329,6 +9930,7 @@ var Engine = class {
     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,
@@ -9362,6 +9964,7 @@ var Engine = class {
       ...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({
@@ -9474,6 +10077,7 @@ var Engine = class {
     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,
@@ -9507,6 +10111,7 @@ var Engine = class {
       ...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);
@@ -10149,6 +10754,14 @@ ${inputJson}
         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);
     }
@@ -10340,6 +10953,36 @@ ${inputJson}
       ...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;
@@ -10402,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, {
@@ -10523,6 +11168,30 @@ function buildToolRegistry(options) {
       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,
@@ -10570,6 +11239,153 @@ function buildToolRegistry(options) {
 // 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();
 init_retry();
@@ -10643,6 +11459,7 @@ function resolveApiKey(config) {
   WebhookDispatcher,
   adaptMcpTool,
   buildForkedMessages,
+  buildKnowledgeIndex,
   buildPermissionPolicy,
   buildSchemaPrompt,
   buildSystemPrompt,
@@ -10653,6 +11470,8 @@ function resolveApiKey(config) {
   createFetchDataTool,
   createLogger,
   createModelAdapter,
+  createReadKnowledgeTool,
+  createSearchKnowledgeTool,
   createSendMessageTool,
   createSkillPageTool,
   createSmartMemory,
@@ -10662,6 +11481,7 @@ function resolveApiKey(config) {
   detectRuntime,
   getCoordinatorBasePrompt,
   getCoordinatorSystemPrompt,
+  getExtractor,
   hasProcessLifecycle,
   initEngine,
   isCoordinatorMode,
@@ -10684,6 +11504,7 @@ function resolveApiKey(config) {
   toResponse,
   tryParseJSON,
   validateOutput,
-  withCapabilityCheck
+  withCapabilityCheck,
+  writeKnowledgeIndex
 });
 //# sourceMappingURL=index.cjs.map