@falkenslab/agent-kit 0.15.0 → 0.16.1

package/README.md

@@ -34,7 +34,9 @@ A foundation for building AI agents on top of the [Claude Agent SDK](https://www
 
 [Captain Whiskers](./examples/captain-whiskers) is a toy agent to see the kit in action: a retired pirate cat who tells jokes in the terminal, in your language. It starts full screen with its logo and has a small crew of subagents: one looks for new jokes on the web, another rates them before they're told, and a third tells the time with a tool of the captain's own. It lets you try the different levels of oversight and is the best starting point for an agent of your own. Its README explains how to run it.
 
-![Captain Whiskers in Windows Terminal: its logo at the top, the conversation in the middle and the framed prompt at the bottom, with a suggestion for the next message](docs/assets/captain-whiskers.png)
+![Captain Whiskers in Windows Terminal: his logo with the mode and the agent-kit version at the top, his crew at work in the middle, a task list under the spinner, and the framed prompt and status bar at the bottom](docs/assets/captain-whiskers.png)
+
+See [everything he can do](https://falkenslab.github.io/agent-kit/docs/next/examples/captain-whiskers#what-he-can-do), with screenshots.
 
 ### teacher-agent
 

package/assets/knowledge-plugin/.claude-plugin/plugin.json

@@ -1,4 +1,4 @@
 {
   "name": "knowledge",
-  "description": "Built-in knowledge base workflows (an LLM wiki): page templates, ingesting sources, querying the knowledge base and health-checking it."
+  "description": "Built-in knowledge base workflows (an LLM wiki) over the kit's knowledge_* tools: ingesting sources, querying the knowledge base and health-checking it."
 }

package/assets/knowledge-plugin/commands/ingest.md

@@ -4,4 +4,4 @@ description: Ingest material into the knowledge base right now - the files or to
 
 Apply the `knowledge-ingest` skill right now to: $ARGUMENTS
 
-If nothing is given above, find every file in the sources folder that has no summary page in the knowledge base yet (check `index.md` and `summaries/`) and ingest them all. When you're done, summarize which pages you created and updated, and anything you couldn't read.
+If nothing is given above, ingest every original `list_sources` reports as new, and update the summaries of the ones it reports as changed. When you're done, summarize which pages you created and updated, and anything you couldn't read.

package/assets/knowledge-plugin/commands/lint.md

@@ -2,4 +2,4 @@
 description: Health-check the knowledge base right now - broken links, orphans, duplicates, contradictions, gaps
 ---
 
-Apply the `knowledge-lint` skill right now over the whole knowledge base. Fix what's mechanical (links, index, missing back-links) and report the rest: what needs the human's decision, and the gaps worth filling next.
+Apply the `knowledge-lint` skill right now over the whole knowledge base. Fix what's mechanical (broken links, orphans, links to retired pages) and report the rest: what needs the human's decision, and the gaps worth filling next.

package/assets/knowledge-plugin/skills/knowledge-ingest/SKILL.md

@@ -1,42 +1,36 @@
 ---
 name: knowledge-ingest
-description: Ingest one source into the knowledge base - a file in sources/, a document, a page - creating its summary page, creating or updating the concept and entity pages it touches, linking everything both ways, and updating index.md and log.md.
+description: Ingest one source into the knowledge base - an original in sources/, a document, a page - creating its summary page, creating or updating the concept and entity pages it touches, and logging it.
 ---
 
 # Ingesting a source into the knowledge base
 
-A source is ingested once, and from then on the knowledge base holds what it taught: later sessions read the pages, not the original again. Ingesting is not summarizing a file in isolation - its value is in how it connects to what the knowledge base already knows. Load the `knowledge-pages` skill first for the page templates.
+A source is ingested once, and from then on the knowledge base holds what it taught: later sessions read the pages, not the original again. Its value is in how it connects to what the knowledge base already knows. Work only through the `knowledge_*` tools; links between pages are ids, `[Bowline](concept/bowline)`, and the index and backlinks are kept for you.
 
 ## 1. Check it isn't already ingested
 
-Look for it in `index.md` (Summaries) or `Grep` its file name or URL inside the knowledge base. If it already has a page:
-- unchanged source: nothing to do;
-- the source changed or the page is thin: update that page instead of creating another.
+`list_sources` gives each original's status and summary pages: *new* needs ingesting; *ingested* has a page; *changed* changed after its ingest (update its summary). For a document from elsewhere, `knowledge_search` its title or URL.
 
 ## 2. Read it for real
 
-Read the whole source, not its first page. If it exists only outside the sources folder (a downloaded document, a remote file), save it with `save_to_sources` first, so the original is kept as obtained.
+Read the whole source, not its first page (a long PDF in parts: `list_sources` gives its pages). Its path is the sources folder's (named in the system prompt) plus the path `list_sources` gives, from the project folder, not from this skill's folder. `Read` reads PDFs and images; `extract_text` reads DOCX, PPTX (with its speaker notes) and XLSX. If it exists only outside the sources folder, keep the original first: `download_to_sources` for a URL (a web page is kept as markdown too: read that one), `save_to_sources` for a file in the run's folder, `request_file` to ask the person for one.
 
 ## 3. Write the summary page
 
-Create `summaries/<slug>.md` with the template: summary, key points (literal wording where exactness matters), frontmatter `file`/`url` pointing to the original.
+`knowledge_create` with type `summary` (call it once without content to get the template), and the field `file` (the original, relative to sources/) or `url`. Key points quote literally where exactness matters. Create the new concept and entity pages it feeds in the same call (`also`): they can link to each other.
 
 ## 4. Update concepts and entities
 
-For every concept or entity the source explains or relies on:
-- no page yet: create it;
-- page exists: add what is new (a better definition, an example, a nuance, a fact) with `Edit`, and link the summary under "Sources".
+For every concept or entity the source explains or relies on, `knowledge_search` it first (under other names and aliases too: a duplicate page is worse than none):
+- no page yet: create it, with the summary (`also`) or on its own;
+- page exists: add what is new (a better definition, an example, a nuance) with `knowledge_edit`, and link the summary under its sources.
 
-Check first whether it exists under another name (`Grep` the knowledge base for the term and look at `aliases`): a duplicate page is worse than none.
+If the source contradicts a page, record both versions with attribution in both pages; don't overwrite.
 
-## 5. Link both ways and look for conflicts
+## 5. Close
 
-Every link you added from page A to page B needs its counterpart in B. If the source contradicts an existing page, record both versions with attribution in both pages - don't overwrite.
+`knowledge_log` with operation `ingest`, the source's title and the pages created and updated. Rewrite the `overview` (`knowledge_rewrite`) only if the source changes the big picture. When ingesting several sources in a row, log once at the end.
 
-## 6. Close
+## An original that was wrong or replaced
 
-- `index.md`: new pages, and one-line descriptions that changed.
-- `log.md`: `## [date] ingest | <source title>` with the pages created and updated.
-- `overview.md`: only if the source changes the big picture.
-
-When ingesting several sources in a row, do steps 1-5 for each and close once at the end.
+`retire_source` (the person approves it) moves it aside and marks its summary retired (wrong) or superseded (replaced). Then `knowledge_check` lists the passages that cite it: after a wrong one, correct or remove what it taught (`knowledge_edit`, or `knowledge_retire` for a page that was only about it); after a replaced one, ingest the new original and re-ground those passages on it.

package/assets/knowledge-plugin/skills/knowledge-lint/SKILL.md

@@ -1,26 +1,30 @@
 ---
 name: knowledge-lint
-description: Health-check the knowledge base - broken links, pages missing from index.md, orphan pages, one-way links, duplicated concepts, mentioned-but-missing concepts, contradictions, gaps - fix what's mechanical and report the rest.
+description: Health-check the knowledge base - broken links, orphan pages, links to retired pages, missing or changed originals, duplicated concepts, mentioned-but-missing concepts, contradictions, gaps - fix what's mechanical and report the rest.
 ---
 
 # Linting the knowledge base
 
-A knowledge base maintained across sessions drifts: links break, pages go unlisted, the same concept appears under two names. Lint it when asked and after a large ingest. Load `knowledge-pages` first for the templates.
+A knowledge base maintained across sessions drifts. Lint it when asked and after a large ingest.
 
-## Checks
+## 1. The mechanical checks, in one call
 
-Use `Glob` to list pages and `Grep` (always with `path` inside the knowledge base) to find links, instead of reading every page in full.
+`knowledge_check` returns broken links, orphan pages, links to retired pages, summaries whose original is gone, originals that are new, changed or missing, and the passages that cite a retired original. The index and backlinks are kept by the store: there's nothing to fix there.
 
-1. **Broken links**: a relative link whose target file doesn't exist. Fix it if the right target is obvious (a typo, a page under a close name); otherwise report it.
-2. **Index**: every page is listed in `index.md` and every entry there points to an existing page. Fix it.
-3. **Orphans**: pages nothing links to (`Grep` for the file name). Link them from where they belong, or report why they don't belong anywhere.
-4. **One-way links**: a summary that feeds a concept which doesn't list it back... Add the missing side.
-5. **Duplicates**: two pages for the same idea under different names. Merge the content into one, mark the other as superseded (never delete it) and repoint links.
-6. **Missing pages**: terms that several pages treat as concepts or entities but have no page. Create them if the material is there; otherwise list them.
-7. **Contradictions**: claims that disagree across pages without being recorded as such. Record both sides, attributed.
-8. **Provenance**: claims with no traceable source. Add the link, or mark them as unsourced.
-9. **Gaps**: files in the sources folder with no summary page yet, concepts mentioned but never explained by any source. Report them - they are what to ingest or find next.
+- **Broken links**: fix them with `knowledge_edit` when the right target is obvious (a typo, a page under a close name: `knowledge_search`); otherwise report them.
+- **Orphans**: link them from the pages where they belong, or report why they don't belong anywhere.
+- **Links to retired pages, passages citing a retired original**: correct or re-ground them.
+- **New or changed originals**: report them as what to ingest or update next (or do it, if asked).
+
+## 2. The checks that need judgement
+
+Use `knowledge_index` and `knowledge_search`; read only the pages a check needs.
+
+- **Duplicates**: two pages for the same idea under different names. Merge the content into one with `knowledge_edit`, `knowledge_supersede` the other (never delete it) and repoint links.
+- **Missing pages**: terms that several pages treat as concepts or entities but have no page. Create them if the material is there; otherwise list them.
+- **Contradictions**: claims that disagree across pages without being recorded as such. Record both sides, attributed.
+- **Provenance**: claims with no traceable source. Add the link, or mark them as unsourced.
 
 ## Close
 
-Append `## [date] lint | <summary>` to `log.md` listing what was fixed. Then report to the human: what you fixed, and what needs their decision or more material. Don't make judgement calls silently - merging pages that are only similar, or choosing between contradictory sources, goes in the report.
+`knowledge_log` with operation `lint` and what was fixed. Then report to the person: what you fixed, and what needs their decision or more material. Don't make judgement calls silently: merging pages that are only similar, or choosing between contradictory sources, goes in the report.

package/assets/knowledge-plugin/skills/knowledge-query/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: knowledge-query
-description: Answer a question from the knowledge base - find the relevant pages through the index, read them, answer with links to them, and file the answer back as a synthesis page when it is worth keeping.
+description: Answer a question from the knowledge base - find the relevant pages, read them, answer citing them, and file the answer back as a synthesis page when it is worth keeping.
 ---
 
 # Querying the knowledge base
 
 The knowledge base exists so a question doesn't start from zero. Answer from it first; go back to the originals or the web only for what it doesn't hold.
 
-1. **Start from the index.** Read `index.md`, pick the pages that can matter, read those (not the whole knowledge base). `Grep` inside the knowledge base for terms and aliases the index doesn't reveal.
-2. **Answer from the pages**, linking each one you drew on. Say what comes from the knowledge base, what comes from an original in the sources folder (read it if the knowledge base is thin or contradictory) and what comes from outside (label it as such).
+1. **Find the pages.** `knowledge_search` the question's terms (and their synonyms), or `knowledge_index` for the catalog; `knowledge_read` only the pages that matter.
+2. **Answer from the pages**, citing each one you drew on. Say what comes from the knowledge base, what from an original in the sources folder (read it if the knowledge base is thin or contradictory) and what from outside (label it as such).
 3. **Say what is missing.** If the knowledge base can't answer part of the question, say so and name the source that would fill it, instead of filling the gap from memory silently.
-4. **File it back.** If the answer is a comparison, an analysis or a report that will be asked again, save it as `syntheses/<slug>.md` (template in `knowledge-pages`) with links to its inputs, add it to `index.md`, and log it: `## [date] query | <question>`. A quick factual answer needs no page.
-5. **Feed the knowledge base.** If answering revealed a concept or fact that has no page, or a contradiction, fix that in the knowledge base too and log it.
+4. **File it back.** If the answer is a comparison, an analysis or a report that will be asked again, `knowledge_create` a `synthesis` page with links to its inputs, and `knowledge_log` it (operation `query`). A quick factual answer needs no page.
+5. **Feed the knowledge base.** If answering revealed a concept with no page, or a contradiction, fix that too and log it.

package/assets/knowledge-plugin-files/.claude-plugin/plugin.json

@@ -0,0 +1,4 @@
+{
+  "name": "knowledge",
+  "description": "Built-in knowledge base workflows (an LLM wiki): page templates, ingesting sources, querying the knowledge base and health-checking it."
+}

package/assets/knowledge-plugin-files/commands/ingest.md

@@ -0,0 +1,7 @@
+---
+description: Ingest material into the knowledge base right now - the files or topic given, or everything in sources/ not ingested yet
+---
+
+Apply the `knowledge-ingest` skill right now to: $ARGUMENTS
+
+If nothing is given above, ingest every original `list_sources` reports as new, and update the summaries of the ones it reports as changed. When you're done, summarize which pages you created and updated, and anything you couldn't read.

package/assets/knowledge-plugin-files/commands/lint.md

@@ -0,0 +1,5 @@
+---
+description: Health-check the knowledge base right now - broken links, orphans, duplicates, contradictions, gaps
+---
+
+Apply the `knowledge-lint` skill right now over the whole knowledge base. Fix what's mechanical (links, index, missing back-links) and report the rest: what needs the human's decision, and the gaps worth filling next.

package/assets/knowledge-plugin-files/commands/query.md

@@ -0,0 +1,5 @@
+---
+description: Answer a question from the knowledge base, and file the answer back if it is worth keeping
+---
+
+Apply the `knowledge-query` skill right now to answer: $ARGUMENTS

package/assets/knowledge-plugin-files/skills/knowledge-ingest/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: knowledge-ingest
+description: Ingest one source into the knowledge base - a file in sources/, a document, a page - creating its summary page, creating or updating the concept and entity pages it touches, linking everything both ways, and updating index.md and log.md.
+---
+
+# Ingesting a source into the knowledge base
+
+A source is ingested once, and from then on the knowledge base holds what it taught: later sessions read the pages, not the original again. Ingesting is not summarizing a file in isolation - its value is in how it connects to what the knowledge base already knows. Load the `knowledge-pages` skill first for the page templates.
+
+## 1. Check it isn't already ingested
+
+`list_sources` gives each original's status and summary pages: *new* needs ingesting; *ingested* has a page; *changed* changed after its ingest. For a document from elsewhere, look for it in `index.md` (Summaries) or `Grep` its URL inside the knowledge base. If it already has a page:
+- unchanged source: nothing to do;
+- the source changed or the page is thin: update that page instead of creating another.
+
+## 2. Read it for real
+
+Read the whole source, not its first page (a long PDF in parts: `list_sources` gives its pages). If it exists only outside the sources folder, keep the original first: `download_to_sources` for a URL (a web page is kept as markdown too: read that one), `save_to_sources` for a file in the run's folder, `request_file` to ask the person for one. `Read` reads PDFs and images; read DOCX, PPTX (with its speaker notes) and XLSX with `extract_text`.
+
+## 3. Write the summary page
+
+Create `summaries/<slug>.md` with the template: summary, key points (literal wording where exactness matters), frontmatter `file`/`url` pointing to the original.
+
+## 4. Update concepts and entities
+
+For every concept or entity the source explains or relies on:
+- no page yet: create it;
+- page exists: add what is new (a better definition, an example, a nuance, a fact) with `Edit`, and link the summary under "Sources".
+
+Check first whether it exists under another name (`Grep` the knowledge base for the term and look at `aliases`): a duplicate page is worse than none.
+
+## 5. Link both ways and look for conflicts
+
+Every link you added from page A to page B needs its counterpart in B. If the source contradicts an existing page, record both versions with attribution in both pages - don't overwrite.
+
+## 6. Close
+
+- `index.md`: new pages, and one-line descriptions that changed.
+- `log.md`: `## [date] ingest | <source title>` with the pages created and updated.
+- `overview.md`: only if the source changes the big picture.
+
+When ingesting several sources in a row, do steps 1-5 for each and close once at the end.
+
+## An original that was wrong or replaced
+
+`retire_source` (the person approves it) moves it aside and marks its summary retired (wrong) or superseded (replaced by a better one). Then update `index.md`, and fix the pages that cite it (`Grep` its file name): after a wrong one, correct or remove what it taught; after a replaced one, ingest the new original and re-ground those passages on it.

package/assets/knowledge-plugin-files/skills/knowledge-lint/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: knowledge-lint
+description: Health-check the knowledge base - broken links, pages missing from index.md, orphan pages, one-way links, duplicated concepts, mentioned-but-missing concepts, contradictions, gaps - fix what's mechanical and report the rest.
+---
+
+# Linting the knowledge base
+
+A knowledge base maintained across sessions drifts: links break, pages go unlisted, the same concept appears under two names. Lint it when asked and after a large ingest. Load `knowledge-pages` first for the templates.
+
+## Checks
+
+Use `Glob` to list pages and `Grep` (always with `path` inside the knowledge base) to find links, instead of reading every page in full.
+
+1. **Broken links**: a relative link whose target file doesn't exist. Fix it if the right target is obvious (a typo, a page under a close name); otherwise report it.
+2. **Index**: every page is listed in `index.md` and every entry there points to an existing page. Fix it.
+3. **Orphans**: pages nothing links to (`Grep` for the file name). Link them from where they belong, or report why they don't belong anywhere.
+4. **One-way links**: a summary that feeds a concept which doesn't list it back... Add the missing side.
+5. **Duplicates**: two pages for the same idea under different names. Merge the content into one, mark the other as superseded (never delete it) and repoint links.
+6. **Missing pages**: terms that several pages treat as concepts or entities but have no page. Create them if the material is there; otherwise list them.
+7. **Contradictions**: claims that disagree across pages without being recorded as such. Record both sides, attributed.
+8. **Provenance**: claims with no traceable source. Add the link, or mark them as unsourced.
+9. **Gaps**: originals `list_sources` reports as new (no summary yet), changed (their summary may be stale) or missing (deleted by hand: their summaries point nowhere), and concepts mentioned but never explained by any source. Report them - they are what to ingest, update or find next.
+
+## Close
+
+Append `## [date] lint | <summary>` to `log.md` listing what was fixed. Then report to the human: what you fixed, and what needs their decision or more material. Don't make judgement calls silently - merging pages that are only similar, or choosing between contradictory sources, goes in the report.

package/assets/knowledge-plugin-files/skills/knowledge-query/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: knowledge-query
+description: Answer a question from the knowledge base - find the relevant pages through the index, read them, answer with links to them, and file the answer back as a synthesis page when it is worth keeping.
+---
+
+# Querying the knowledge base
+
+The knowledge base exists so a question doesn't start from zero. Answer from it first; go back to the originals or the web only for what it doesn't hold.
+
+1. **Start from the index.** Read `index.md`, pick the pages that can matter, read those (not the whole knowledge base). `Grep` inside the knowledge base for terms and aliases the index doesn't reveal.
+2. **Answer from the pages**, linking each one you drew on. Say what comes from the knowledge base, what comes from an original in the sources folder (read it if the knowledge base is thin or contradictory) and what comes from outside (label it as such).
+3. **Say what is missing.** If the knowledge base can't answer part of the question, say so and name the source that would fill it, instead of filling the gap from memory silently.
+4. **File it back.** If the answer is a comparison, an analysis or a report that will be asked again, save it as `syntheses/<slug>.md` (template in `knowledge-pages`) with links to its inputs, add it to `index.md`, and log it: `## [date] query | <question>`. A quick factual answer needs no page.
+5. **Feed the knowledge base.** If answering revealed a concept or fact that has no page, or a contradiction, fix that in the knowledge base too and log it.

package/dist/core/agentSpec.d.ts

@@ -1,4 +1,5 @@
 import type { AgentDefinition as SdkSubagentDefinition, McpServerConfig, SettingSource } from "@anthropic-ai/claude-agent-sdk";
+import type { KnowledgeStore, PageType } from "./knowledgeStore.js";
 /**
  * The human-supervision spectrum every agent built on this kit shares, independent of
  * domain: "interactive" pauses before every single action, "guided" only pauses before a
@@ -49,6 +50,11 @@ export interface BaseSessionConfig {
      * language (see language.ts). Pass the same value to the chat, wizard or progress view.
      */
     language?: string;
+    /**
+     * The time zone the date and time tools answer in (`current_time`, `date_math`), an IANA
+     * name such as "Europe/Madrid"; the system's if not given.
+     */
+    timeZone?: string;
 }
 /**
  * Everything actually *about the domain* that `buildSessionOptions()` needs but doesn't
@@ -104,12 +110,31 @@ export interface AgentSpec<TConfig extends BaseSessionConfig> {
     /**
      * The built-in knowledge base (see knowledge.ts): when `config.knowledgeDir` is set, the kit
      * appends its "Knowledge base" rules to the system prompt and loads its plugin (skills
-     * knowledge-pages/knowledge-ingest/knowledge-query/knowledge-lint, commands /knowledge:ingest, /knowledge:query,
-     * /knowledge:lint), so the agent maintains its notes as an interlinked wiki. On by default;
+     * knowledge-ingest/knowledge-query/knowledge-lint, commands /knowledge:ingest, /knowledge:query,
+     * /knowledge:lint), so the agent maintains its notes as an interlinked wiki, through the
+     * `knowledge_*` tools by default (see `knowledgeTools`). On by default;
      * set `false` for an agent that writes its own rules for `knowledgeDir` (or wants plain
      * notes) — `knowledgePromptSection()`/`knowledgePluginRoot()` are exported to reuse the pieces.
      */
     knowledgeBase?: boolean;
+    /**
+     * How the agent reaches the built-in knowledge base: `"store"` (the default), only through
+     * the kit's `knowledge_*` tools over a `KnowledgeStore`, never with the file tools, so the
+     * storage can change and the wiki's rules are kept by code (ADR-024); `"files"`, with the
+     * file tools on `knowledgeDir` and the rules in the prompt, as before.
+     */
+    knowledgeTools?: "store" | "files";
+    /**
+     * The agent's own page types for the built-in knowledge base, besides the kit's four
+     * (summary, concept, entity, synthesis): each with its folder (`""` for the root), index
+     * section, description (told to the model) and template.
+     */
+    knowledgePageTypes?: PageType[];
+    /**
+     * The knowledge base's store, instead of the kit's over markdown files in `knowledgeDir`
+     * (e.g. a database or a vector store implementing `KnowledgeStore`).
+     */
+    knowledgeStore?(config: TConfig): KnowledgeStore;
     /**
      * Whether the kit tells the agent (and each subagent) to reply in the resolved language
      * (`config.language`, `--language`, the system's), following the human if they write in

package/dist/core/extractText.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Word, PowerPoint and Excel originals as markdown: the SDK's `Read` refuses DOCX and PPTX
+ * (confirmed empirically), and course material is often both. The libraries are optional
+ * peer dependencies of the kit (`mammoth` for DOCX, `fflate` to open PPTX and XLSX, which
+ * are zips of XML); without them the caller is told what to install.
+ */
+export declare const EXTRACTABLE: Set<string>;
+export declare class MissingLibraryError extends Error {
+    readonly library: string;
+    constructor(library: string, options?: ErrorOptions);
+}
+/** An original's text as markdown; `from`/`to` pick slides of a deck. */
+export declare function extractText(file: string, from?: number, to?: number): Promise<string>;

package/dist/core/extractText.js

@@ -0,0 +1,147 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+/**
+ * Word, PowerPoint and Excel originals as markdown: the SDK's `Read` refuses DOCX and PPTX
+ * (confirmed empirically), and course material is often both. The libraries are optional
+ * peer dependencies of the kit (`mammoth` for DOCX, `fflate` to open PPTX and XLSX, which
+ * are zips of XML); without them the caller is told what to install.
+ */
+export const EXTRACTABLE = new Set(["docx", "pptx", "xlsx"]);
+/** The most rows of a sheet written out; the rest are counted. */
+const MAX_SHEET_ROWS = 200;
+export class MissingLibraryError extends Error {
+    library;
+    constructor(library, options) {
+        super(`Reading this format needs the optional "${library}" library: npm install ${library}`, options);
+        this.library = library;
+    }
+}
+async function load(library) {
+    try {
+        return (await import(library));
+    }
+    catch (error) {
+        throw new MissingLibraryError(library, { cause: error });
+    }
+}
+const decode = (xml) => xml
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&#(\d+);/g, (_, code) => String.fromCodePoint(Number(code)))
+    .replace(/&amp;/g, "&");
+/** The paragraphs of a DrawingML text body (slides and notes): each `<a:p>` its runs' `<a:t>` text. */
+function paragraphs(xml) {
+    return [...xml.matchAll(/<a:p\b[\s\S]*?<\/a:p>/g)]
+        .map((p) => [...p[0].matchAll(/<a:t>([\s\S]*?)<\/a:t>/g)].map((t) => decode(t[1])).join(""))
+        .map((text) => text.trim())
+        .filter(Boolean);
+}
+const text = (files, name) => (files[name] ? new TextDecoder().decode(files[name]) : undefined);
+async function unzip(file) {
+    const { unzipSync } = await load("fflate");
+    return unzipSync(new Uint8Array(await readFile(file)));
+}
+/** A slide deck: a section per slide (its title, text and speaker notes), from slide `from` to `to` (1-based). */
+async function pptx(file, from, to) {
+    const files = await unzip(file);
+    const slides = Object.keys(files)
+        .map((name) => /^ppt\/slides\/slide(\d+)\.xml$/.exec(name))
+        .filter((m) => Boolean(m))
+        .map((m) => Number(m[1]))
+        .sort((a, b) => a - b);
+    const first = Math.max(1, from ?? 1);
+    const last = Math.min(slides.length, to ?? slides.length);
+    const parts = [`# ${path.basename(file)}`, `${slides.length} slides${first > 1 || last < slides.length ? `; slides ${first} to ${last}` : ""}.`];
+    let images = 0;
+    for (const n of slides.slice(first - 1, last)) {
+        const xml = text(files, `ppt/slides/slide${n}.xml`) ?? "";
+        images += (xml.match(/<p:pic\b/g) ?? []).length;
+        const [title, ...body] = paragraphs(xml);
+        parts.push(`## Slide ${n}${title ? `: ${title}` : ""}`);
+        if (body.length)
+            parts.push(body.map((line) => `- ${line}`).join("\n"));
+        // A slide's notes are linked from its relationships; their slide-number placeholder is left out.
+        const rels = text(files, `ppt/slides/_rels/slide${n}.xml.rels`) ?? "";
+        const notesTarget = /Target="\.\.\/notesSlides\/(notesSlide\d+\.xml)"/.exec(rels)?.[1];
+        const notes = notesTarget ? paragraphs(text(files, `ppt/notesSlides/${notesTarget}`) ?? "").filter((line) => !/^\d+$/.test(line)) : [];
+        if (notes.length)
+            parts.push(`Speaker notes:\n${notes.map((line) => `> ${line}`).join("\n")}`);
+    }
+    if (images)
+        parts.push(`(${images} images left out.)`);
+    return `${parts.join("\n\n")}\n`;
+}
+/** The column index of a cell reference ("C7" → 2). */
+function columnOf(ref) {
+    let index = 0;
+    for (const letter of /^[A-Z]+/.exec(ref)?.[0] ?? "A")
+        index = index * 26 + letter.charCodeAt(0) - 64;
+    return index - 1;
+}
+const cell = (value) => value.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+/** A workbook: a markdown table per sheet, capped in rows. */
+async function xlsx(file) {
+    const files = await unzip(file);
+    const shared = [...(text(files, "xl/sharedStrings.xml") ?? "").matchAll(/<si>([\s\S]*?)<\/si>/g)].map((si) => [...si[1].matchAll(/<t[^>]*>([\s\S]*?)<\/t>/g)].map((t) => decode(t[1])).join(""));
+    const workbook = text(files, "xl/workbook.xml") ?? "";
+    const names = [...workbook.matchAll(/<sheet\b[^>]*name="([^"]*)"/g)].map((m) => decode(m[1]));
+    const sheets = Object.keys(files)
+        .map((name) => /^xl\/worksheets\/sheet(\d+)\.xml$/.exec(name))
+        .filter((m) => Boolean(m))
+        .map((m) => Number(m[1]))
+        .sort((a, b) => a - b);
+    const parts = [`# ${path.basename(file)}`];
+    for (const n of sheets) {
+        const xml = text(files, `xl/worksheets/sheet${n}.xml`) ?? "";
+        const rows = [...xml.matchAll(/<row\b[\s\S]*?<\/row>/g)].map((row) => {
+            const values = [];
+            for (const c of row[0].matchAll(/<c\b([^>]*?)(?:\/>|>([\s\S]*?)<\/c>)/g)) {
+                const attrs = c[1];
+                const ref = /r="([A-Z]+\d+)"/.exec(attrs)?.[1] ?? "";
+                const type = /t="(\w+)"/.exec(attrs)?.[1];
+                const raw = /<v>([\s\S]*?)<\/v>/.exec(c[2] ?? "")?.[1] ?? /<t[^>]*>([\s\S]*?)<\/t>/.exec(c[2] ?? "")?.[1] ?? "";
+                const value = type === "s" ? (shared[Number(raw)] ?? "") : decode(raw);
+                values[ref ? columnOf(ref) : values.length] = value;
+            }
+            return Array.from(values, (v) => cell(v ?? ""));
+        });
+        const filled = rows.filter((row) => row.some(Boolean));
+        parts.push(`## ${names[n - 1] ?? `Sheet ${n}`}`);
+        if (!filled.length) {
+            parts.push("(empty)");
+            continue;
+        }
+        const width = Math.max(...filled.map((row) => row.length));
+        const pad = (row) => `| ${Array.from({ length: width }, (_, i) => row[i] ?? "").join(" | ")} |`;
+        const shown = filled.slice(0, MAX_SHEET_ROWS);
+        parts.push([pad(shown[0]), `|${" --- |".repeat(width)}`, ...shown.slice(1).map(pad)].join("\n"));
+        if (filled.length > MAX_SHEET_ROWS)
+            parts.push(`(${filled.length - MAX_SHEET_ROWS} more rows.)`);
+    }
+    return `${parts.join("\n\n")}\n`;
+}
+/** A Word document: headings, paragraphs, lists and tables. */
+async function docx(file) {
+    const mammoth = await load("mammoth");
+    const { value: html } = await mammoth.convertToHtml({ path: file });
+    const images = (html.match(/<img\b/g) ?? []).length;
+    // Markdown with turndown (also optional); plain text without it.
+    const turndown = await load("turndown").catch(() => null);
+    const body = turndown
+        ? new turndown.default({ headingStyle: "atx" }).turndown(html.replace(/<img\b[^>]*>/g, ""))
+        : decode(html.replace(/<\/(p|h\d|li|tr)>/g, "\n").replace(/<[^>]+>/g, "")).trim();
+    return `# ${path.basename(file)}\n\n${body}\n${images ? `\n(${images} images left out.)\n` : ""}`;
+}
+/** An original's text as markdown; `from`/`to` pick slides of a deck. */
+export async function extractText(file, from, to) {
+    const type = path.extname(file).slice(1).toLowerCase();
+    if (type === "docx")
+        return docx(file);
+    if (type === "pptx")
+        return pptx(file, from, to);
+    if (type === "xlsx")
+        return xlsx(file);
+    throw new Error(`extract_text reads DOCX, PPTX and XLSX; for "${path.basename(file)}" use Read (PDFs, images, text).`);
+}

package/dist/core/fileKnowledgeStore.d.ts

@@ -0,0 +1,10 @@
+import { type KnowledgeStore, type PageType } from "./knowledgeStore.js";
+/** Options of `createFileKnowledgeStore()`. */
+export interface FileKnowledgeStoreOptions {
+    /** The agent's own page types, besides the kit's four. */
+    pageTypes?: readonly PageType[];
+    /** The sources folder: a summary's `file` field is given relative to it. */
+    sourcesDir?: string;
+}
+/** A `KnowledgeStore` over the markdown files of `knowledgeDir`. */
+export declare function createFileKnowledgeStore(knowledgeDir: string, options?: FileKnowledgeStoreOptions): KnowledgeStore;