@falkenslab/agent-kit 0.16.1 → 0.18.0

package/dist/core/session.js

@@ -1,3 +1,5 @@
+import { readdir, readFile } from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import { createTranscriptLogger } from "./hooks/transcriptLogger.js";
 import { createStepGate } from "./hooks/stepGate.js";
@@ -8,7 +10,7 @@ import { createFileScopeGate } from "./hooks/fileScopeGate.js";
 import { createPlanGate } from "./hooks/planGate.js";
 import { createHumanApprovalServer } from "./tools/humanApproval.js";
 import { createManualLoginServer } from "./tools/manualLogin.js";
-import { createSaveToSourcesServer } from "./tools/saveToSources.js";
+import { createSaveToSourcesServer, sourcesPromptSection } from "./tools/saveToSources.js";
 import { createTimeServer } from "./tools/time.js";
 import { TODO_TOOL } from "./todos.js";
 import { createModeControl } from "./modeControl.js";
@@ -16,6 +18,7 @@ import { createFileKnowledgeStore } from "./fileKnowledgeStore.js";
 import { createKnowledgeServer } from "./tools/knowledgeTools.js";
 import { allowAnyMcpTool } from "./mcpPermissions.js";
 import { knowledgePluginRoot, knowledgePromptSection } from "./knowledge.js";
+import { AGENT_HELP_SKILL, identityPromptSection, writeAgentHelpPlugin } from "./agentHelp.js";
 import { replyLanguageInstruction } from "./language.js";
 import { chooseLanguage } from "./messages/index.js";
 import { createRunStore } from "./runs.js";
@@ -61,40 +64,57 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
     // The built-in knowledge base (rules in the system prompt + its skills/commands as a plugin) needs
     // somewhere to keep the wiki, so it follows `knowledgeDir`; `spec.knowledgeBase: false` opts out.
     const includeKnowledgeBase = Boolean(config.knowledgeDir) && spec.knowledgeBase !== false;
-    // By default the agent reaches it only through the `knowledge_*` tools, over a store, never
-    // with the file tools (ADR-024); `spec.knowledgeTools: "files"` keeps the file tools on it.
-    const knowledgeViaStore = includeKnowledgeBase && (spec.knowledgeTools ?? "store") === "store";
-    const notesDir = knowledgeViaStore ? undefined : config.knowledgeDir;
+    // The agent reaches it only through the `knowledge_*` tools, over a store, never with the file
+    // tools (ADR-024). Without it (`knowledgeBase: false`), `knowledgeDir` is a folder of the
+    // agent's own notes, kept with the file tools under its own rules.
+    const notesDir = includeKnowledgeBase ? undefined : config.knowledgeDir;
     const extraDirs = config.extraWritableDirs ?? [];
-    // With the store, the file tools are only for the originals (reading) and the extra writable
+    const readableExtras = config.extraReadableDirs ?? [];
+    // With the knowledge base, the file tools are only for the originals (reading) and the extra
     // folders; without either, none.
     const fileTools = !includeFileTools
         ? []
-        : !knowledgeViaStore
+        : !includeKnowledgeBase
             ? ["Read", "Write", "Edit", "Glob", "Grep"]
-            : [...(config.sourcesDir || extraDirs.length ? ["Read", "Glob", "Grep"] : []), ...(extraDirs.length ? ["Write", "Edit"] : [])];
+            : [...(config.sourcesDir || extraDirs.length || readableExtras.length ? ["Read", "Glob", "Grep"] : []), ...(extraDirs.length ? ["Write", "Edit"] : [])];
     // Where Write/Edit may act and Grep may search (see hooks/fileScopeGate.ts): the
     // project's own folders, never the whole cwd — which would include whatever else the
     // project directory holds (the user's config...). `sourcesDir` is searchable but
     // deliberately NOT writable: originals stay as obtained, and the only way to add to it is
     // the `save_to_sources` tool (which never overwrites).
     const writableDirs = [notesDir, ...extraDirs].filter((d) => Boolean(d));
-    const searchableDirs = [notesDir, config.sourcesDir, ...extraDirs].filter((d) => Boolean(d));
+    const searchableDirs = [notesDir, config.sourcesDir, ...extraDirs, ...readableExtras].filter((d) => Boolean(d));
     const readOnlyDirs = config.sourcesDir ? [config.sourcesDir] : [];
     // Skills/commands/plugins are a separate concern from the file tools: an agent that
     // wants a plugin-provided skill/command but has no notes or sources folder shouldn't have
     // to invent one just to get `cwd`/`skills: "all"`/`plugins` wired up. Gated on either
     // signal, not on `pluginRoots` alone, so an agent with file tools keeps getting the SDK's
     // own project-level `.claude/skills`/`.claude/commands` discovery.
-    const pluginRoots = [...spec.pluginRoots(config), ...(includeKnowledgeBase ? [knowledgePluginRoot(knowledgeViaStore ? "tools" : "files")] : [])];
-    const knowledgeStore = knowledgeViaStore && config.knowledgeDir
-        ? (spec.knowledgeStore?.(config) ?? createFileKnowledgeStore(config.knowledgeDir, { pageTypes: spec.knowledgePageTypes, sourcesDir: config.sourcesDir }))
+    // With an identity, the agent-help skill (agentHelp.ts): written into the run's folder, since
+    // it carries this session's facts and the agent's own guide.
+    const helpPlugin = spec.identity
+        ? await writeAgentHelpPlugin(path.join(runDir, "agent-help"), {
+            mode,
+            switchable: modeControl.switchable,
+            knowledgeBase: includeKnowledgeBase,
+            ...(config.sourcesDir ? { sourcesFolder: `${path.relative(config.projectDir, config.sourcesDir).split(path.sep).join("/")}/` } : {}),
+        }, spec.helpGuide)
+        : undefined;
+    const pluginRoots = [
+        ...spec.pluginRoots(config),
+        ...(includeKnowledgeBase ? [knowledgePluginRoot()] : []),
+        ...(helpPlugin ? [helpPlugin] : []),
+    ];
+    const knowledgeStore = includeKnowledgeBase && config.knowledgeDir
+        ? (spec.knowledgeStore?.(config) ?? createFileKnowledgeStore(config.knowledgeDir, { pageTypes: spec.knowledgePageTypes }))
         : undefined;
     const includeSkillsAndPlugins = includeFileTools || pluginRoots.length > 0;
+    // "plugins": the skills of the plugins loaded, named as the SDK names them.
+    const offeredSkills = spec.skills === "plugins" ? await pluginSkills(pluginRoots) : spec.skills;
     const skillTools = includeSkillsAndPlugins ? ["Skill"] : [];
     // Whatever opt-in subagents `spec` wants for this config, or undefined if none apply.
-    // Either opt-in feature needs the Agent tool (to delegate to a subagent) and Bash (used
-    // only by the subagent itself — see createSubagentBashGate() below, which denies Bash
+    // Subagents need the Agent tool (to delegate to them), and Bash when one of them uses it
+    // (used only by the subagent itself — see createSubagentBashGate() below, which denies Bash
     // to the main agent regardless of which one put it in `tools`) — Bash has to be present
     // in this session's own tools for any subagent to be allowed to use it at all
     // (confirmed empirically the SDK refuses to spawn a subagent whose own tools list names
@@ -106,6 +126,12 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
         ? Object.fromEntries(Object.entries(subagents.agents).map(([name, agent]) => [name, { ...agent, prompt: withReplyLine(agent.prompt) }]))
         : undefined;
     const includeSubagentTools = subagents !== undefined;
+    // Bash only when a subagent can use it: one that lists it, or one without `tools`, which
+    // inherits every session tool. Its definition costs about 1.9k input tokens on every call
+    // (measured), and the main agent can't use it anyway.
+    const subagentTools = includeSubagentTools
+        ? ["Agent", ...(Object.values(subagents.agents).some((agent) => !agent.tools || agent.tools.includes("Bash")) ? ["Bash"] : [])]
+        : [];
     // The exact set of subagent_type values the Agent tool may spawn in this session — see
     // createSubagentTypeGate() below for why this can't just be "whatever's in `agents`
     // below": the SDK's own built-in "general-purpose" type is spawnable regardless of that
@@ -114,10 +140,21 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
     const allowedSubagentTypes = subagents?.allowedSubagentTypes ?? [];
     const transcriptPath = path.join(runDir, "transcript.jsonl");
     const transcriptLogger = createTranscriptLogger(transcriptPath, config.secrets ?? []);
+    // The person's preferences, by title, for the knowledge base's section (#33).
+    const preferences = knowledgeStore
+        ? (await knowledgeStore.list()).filter((page) => page.type === "preference" && page.status === "active").map(({ id, title }) => ({ id, title }))
+        : [];
+    const promptSections = [
+        spec.buildSystemPrompt(config),
+        ...(spec.identity ? [identityPromptSection(spec.identity)] : []),
+        // The sources' own section, with or without a knowledge base (#30).
+        ...(config.sourcesDir ? [sourcesPromptSection(config.projectDir, config.sourcesDir)] : []),
+        ...(includeKnowledgeBase && config.knowledgeDir
+            ? [knowledgePromptSection({ withSources: Boolean(config.sourcesDir), pageTypes: knowledgeStore?.types(), preferences })]
+            : []),
+    ];
     const sdkOptions = {
-        systemPrompt: withReplyLine(includeKnowledgeBase && config.knowledgeDir
-            ? `${spec.buildSystemPrompt(config)}\n\n${knowledgePromptSection(config.projectDir, config.knowledgeDir, config.sourcesDir, { tools: knowledgeViaStore, pageTypes: knowledgeStore?.types() })}`
-            : spec.buildSystemPrompt(config)),
+        systemPrompt: withReplyLine(promptSections.join("\n\n")),
         // Not the SDK's default (every source): "user" hands the agent the runner's own Claude
         // Code configuration, and its `language` setting outranked the agent's prompt.
         settingSources: spec.settingSources ?? ["project"],
@@ -127,8 +164,16 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
         // whose own memory is the knowledge base. includeGitInstructions: false leaves out the
         // CLI's commit workflow and git context (the runner's git user name among it), which no
         // agent here needs and which pulled replies towards the runner's language (confirmed
-        // empirically, see ADR-018).
-        settings: { autoCompactEnabled: options.autoCompactEnabled ?? true, autoMemoryEnabled: false, includeGitInstructions: false },
+        // empirically, see ADR-018). disableClaudeAiConnectors: true keeps out the claude.ai
+        // connectors of the account the session runs with (Drive, Gmail…), which the CLI fetches
+        // whatever settingSources says (confirmed empirically): the runner's integrations, not the
+        // agent's. An MCP server the agent passes itself is unaffected.
+        settings: {
+            autoCompactEnabled: options.autoCompactEnabled ?? true,
+            autoMemoryEnabled: false,
+            includeGitInstructions: false,
+            disableClaudeAiConnectors: true,
+        },
         // No built-in tools except, if applicable, Read/Write/Edit/Glob/Grep scoped to the
         // project's own folders (fileScopeGate below), and WebFetch/WebSearch
         // with no domain restriction (not conditioned on includeFileTools: it's read-only,
@@ -139,8 +184,8 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
         // so the model ends up looking for SKILL.md files by hand (confirmed empirically).
         // TodoWrite: the SDK's task list for long jobs, in every session (the chats show the list
         // instead of the calls; see todos.ts). Accepted in an explicit list (confirmed empirically).
-        tools: [...fileTools, ...skillTools, "WebFetch", "WebSearch", TODO_TOOL, ...(includeSubagentTools ? ["Agent", "Bash"] : [])],
-        allowedTools: [...fileTools, ...skillTools, "WebFetch", "WebSearch", TODO_TOOL, ...(includeSubagentTools ? ["Agent", "Bash"] : [])],
+        tools: [...fileTools, ...skillTools, "WebFetch", "WebSearch", TODO_TOOL, ...subagentTools],
+        allowedTools: [...fileTools, ...skillTools, "WebFetch", "WebSearch", TODO_TOOL, ...subagentTools],
         // Every mcp__* tool (whatever spec.buildMcpServers() registers, approvals/manualLogin
         // when enabled below, sourceFiles, and any server a project's own .mcp.json
         // declares) is approved generically here rather than listed one by one — see
@@ -170,8 +215,8 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
                 // "skills" acts as a name whitelist, not an addition: "all" enables both the
                 // SDK's own official skills (pdf/docx), the project's own custom ones, and the
                 // plugin-provided built-ins below. A spec's own list gets the knowledge base's
-                // skills added, so it only names its own.
-                skills: skillList(spec.skills, includeKnowledgeBase ? (knowledgeViaStore ? "tools" : "files") : null),
+                // skills and agent-help added, so it only names its own.
+                skills: skillList(offeredSkills, includeKnowledgeBase, Boolean(helpPlugin)),
                 plugins: pluginRoots.map((pluginPath) => ({ type: "local", path: pluginPath, skipMcpDiscovery: true })),
             }
             : {}),
@@ -187,7 +232,6 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
             ...(config.sourcesDir
                 ? {
                     sourceFiles: createSaveToSourcesServer(runDir, config.sourcesDir, spec.saveToSourcesDescription, {
-                        knowledgeDir: config.knowledgeDir,
                         projectDir: config.projectDir,
                         interactive: mode !== "autonomous",
                     }),
@@ -196,13 +240,7 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
             // The knowledge base's own tools, over its store (tools/knowledgeTools.ts, ADR-024).
             ...(knowledgeStore
                 ? {
-                    knowledge: createKnowledgeServer(knowledgeStore, {
-                        runDir,
-                        interactive: mode !== "autonomous",
-                        sourcesDir: config.sourcesDir,
-                        projectDir: config.projectDir,
-                        knowledgeDir: config.knowledgeDir,
-                    }),
+                    knowledge: createKnowledgeServer(knowledgeStore, { runDir, interactive: mode !== "autonomous" }),
                 }
                 : {}),
             // The date and date arithmetic, in every session and mode: only reads (tools/time.ts).
@@ -217,8 +255,16 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
                                     writableDirs,
                                     searchableDirs,
                                     readOnlyDirs,
-                                    deniedPaths: config.deniedPaths ?? [],
-                                    ...(knowledgeViaStore && config.knowledgeDir ? { toolOnlyDirs: [{ dir: config.knowledgeDir, instead: "the knowledge_* tools" }] } : {}),
+                                    // The SDK's own credentials, whatever the agent denies.
+                                    deniedPaths: [...(config.deniedPaths ?? []), path.join(claudeConfigDir(), ".credentials.json")],
+                                    // Read and Glob only in the agent's folders, plus what only the kit knows it
+                                    // needs: the run folder, the plugins, the project's .claude/ (when loaded) and
+                                    // the SDK's large tool results. Never the rest of the disk (~/.ssh, other
+                                    // projects' .env...), which an agent reading untrusted content could be talked into.
+                                    readableDirs: searchableDirs,
+                                    alsoReadable: [runDir, ...pluginRoots, ...((spec.settingSources ?? ["project"]).includes("project") ? [path.join(config.projectDir, ".claude")] : [])],
+                                    toolResultsRoot: claudeProjectDir(config.projectDir),
+                                    ...(includeKnowledgeBase && config.knowledgeDir ? { toolOnlyDirs: [{ dir: config.knowledgeDir, instead: "the knowledge_* tools" }] } : {}),
                                 }),
                             ] }]
                     : []),
@@ -254,15 +300,50 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
     return { options: sdkOptions, transcriptLogger, transcriptPath, modeControl, language, ...(knowledgeStore ? { knowledgeStore } : {}) };
 }
 export { createModeControl, togglePlanMode } from "./modeControl.js";
-/** The knowledge plugin's skills, as the SDK names a plugin's skills ("plugin:skill"): the tools variant has no page templates skill (knowledge_create gives them). */
-const KNOWLEDGE_SKILLS = {
-    tools: ["knowledge-ingest", "knowledge-query", "knowledge-lint"].map((skill) => `knowledge:${skill}`),
-    files: ["knowledge-pages", "knowledge-ingest", "knowledge-query", "knowledge-lint"].map((skill) => `knowledge:${skill}`),
-};
-function skillList(skills, knowledgeVariant) {
+/** The Claude Code configuration folder the SDK's CLI uses: `CLAUDE_CONFIG_DIR`, or `~/.claude`. */
+function claudeConfigDir() {
+    return process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
+}
+/**
+ * The CLI's folder for a project, where it keeps each session's transcript and large tool
+ * results (`<session>/tool-results/`): the project's path with every character but letters
+ * and digits as "-" (confirmed empirically).
+ */
+export function claudeProjectDir(projectDir) {
+    return path.join(claudeConfigDir(), "projects", path.resolve(projectDir).replace(/[^a-zA-Z0-9]/g, "-"));
+}
+/** The knowledge plugin's skills, as the SDK names a plugin's skills ("plugin:skill"). */
+const KNOWLEDGE_SKILLS = ["knowledge-ingest", "knowledge-query", "knowledge-lint"].map((skill) => `knowledge:${skill}`);
+/**
+ * The skills of the plugins in `roots`, as the SDK names them: `<plugin>:<folder>`, the
+ * plugin's name from its `.claude-plugin/plugin.json` and the skill's folder under `skills/`,
+ * whatever its frontmatter's `name` says (confirmed empirically).
+ */
+export async function pluginSkills(roots) {
+    const names = [];
+    for (const root of roots) {
+        let plugin;
+        try {
+            plugin = JSON.parse(await readFile(path.join(root, ".claude-plugin", "plugin.json"), "utf8")).name;
+        }
+        catch {
+            continue; // not a plugin the SDK would load
+        }
+        if (!plugin)
+            continue;
+        const folders = await readdir(path.join(root, "skills"), { withFileTypes: true }).catch(() => []);
+        for (const folder of folders.filter((entry) => entry.isDirectory())) {
+            const hasSkill = await readFile(path.join(root, "skills", folder.name, "SKILL.md")).then(() => true, () => false);
+            if (hasSkill)
+                names.push(`${plugin}:${folder.name}`);
+        }
+    }
+    return names;
+}
+function skillList(skills, knowledgeBase, agentHelp) {
     if (skills === undefined || skills === "all")
         return "all";
-    return knowledgeVariant ? [...new Set([...skills, ...KNOWLEDGE_SKILLS[knowledgeVariant]])] : skills;
+    return [...new Set([...skills, ...(knowledgeBase ? KNOWLEDGE_SKILLS : []), ...(agentHelp ? [AGENT_HELP_SKILL] : [])])];
 }
 /**
  * User message queue backed by a single long-lived generator, for any multi-turn

package/dist/core/sources.d.ts

@@ -1,10 +1,11 @@
 /**
  * The sources folder's bookkeeping: originals stay files (ADR-024), and the kit keeps a
  * manifest next to them (`.agent-kit/sources.json`, inside `sourcesDir`, where the agent's
- * file tools can't write) with each original's hash, size and provenance, the version it
- * replaces, and the hash it had when a summary page first pointed to it. From that it tells
- * new, ingested, changed and missing originals apart, refuses duplicates, and retires an
- * original into `.agent-kit/retired/` instead of deleting it.
+ * file tools can't write) with each original's hash, size, provenance, the version it replaces
+ * and when its content last changed. From that it refuses duplicates, tells present, missing
+ * and retired originals apart, and retires an original into `.agent-kit/retired/` instead of
+ * deleting it. It knows nothing of the knowledge base: each owns its data, and the model
+ * connects them through their tools (#30). Hashes never leave it.
  */
 export declare const KIT_DIR = ".agent-kit";
 /** Where an original came from. */
@@ -33,8 +34,8 @@ export interface SourceEntry {
     replaces?: string;
     /** The page this one was generated from (a web page's markdown, from its HTML). */
     derivedFrom?: string;
-    /** The hash when a summary page first pointed to it: a different hash now means it changed after its ingest. */
-    ingestedHash?: string;
+    /** When its content last changed (ISO 8601): when it was added, or when its hash last differed. Not when it was only touched. */
+    changedAt: string;
 }
 export interface RetiredSource {
     path: string;
@@ -50,18 +51,23 @@ export interface SourceManifest {
     files: Record<string, SourceEntry>;
     retired: RetiredSource[];
 }
-export type SourceStatus = "new" | "ingested" | "changed" | "missing" | "present";
+/** Present in the folder; missing (in the manifest, deleted by hand); or retired with `retire_source`. */
+export type SourceStatus = "present" | "missing" | "retired";
 export interface SourceListing {
     path: string;
     status: SourceStatus;
     type: string;
+    /** When its content last changed (ISO 8601), to compare with when something was built from it. */
+    changedAt?: string;
     size?: number;
     pages?: number;
     slides?: number;
     origin?: SourceOrigin;
     replaces?: string;
-    /** The summary pages that point to it (paths relative to the project). */
-    summaries: string[];
+    /** For a retired one: when, why, and what replaced it. */
+    retiredAt?: string;
+    why?: "wrong" | "replaced";
+    replacedBy?: string;
 }
 export declare function hashFile(file: string): Promise<string>;
 /** Resolves `candidate` against `base`; the absolute path only if it stays inside it. */
@@ -70,18 +76,15 @@ export declare function loadManifest(sourcesDir: string): Promise<SourceManifest
 export declare function saveManifest(sourcesDir: string, manifest: SourceManifest): Promise<void>;
 /** Every original under `sourcesDir` (paths relative to it), leaving out hidden files and folders (the kit's own among them). */
 export declare function scanSources(sourcesDir: string): Promise<string[]>;
-/** The summary pages (knowledge base layout: `summaries/*.md`) by the absolute path of the original their frontmatter `file:` points to. */
-export declare function summariesByOriginal(knowledgeDir: string): Promise<Map<string, string[]>>;
 /** Pages of a PDF, read from its page tree without a parser; undefined when it can't tell (e.g. compressed object streams). */
 export declare function pdfPageCount(bytes: Buffer): number | undefined;
 /** Slides of a PPTX, from the file names in the zip (stored uncompressed). */
 export declare function pptxSlideCount(bytes: Buffer): number | undefined;
 /**
- * Every original with its status, recording in the manifest the ones copied in by hand and,
- * the first time a summary page points to one, its hash at ingest. Without a knowledge
- * folder there's no ingest to compare with: originals are "present".
+ * Every original with its status and when its content last changed, recording in the manifest
+ * the ones copied in by hand; then the missing ones and the retired ones.
  */
-export declare function listSources(sourcesDir: string, knowledgeDir: string | undefined, projectDir: string): Promise<SourceListing[]>;
+export declare function listSources(sourcesDir: string): Promise<SourceListing[]>;
 export interface AddedSource {
     /** Where it is, relative to `sourcesDir`. */
     path: string;
@@ -99,24 +102,14 @@ export declare function addSource(sourcesDir: string, file: string, destination:
     derivedFrom?: string;
     name?: string;
 }): Promise<AddedSource>;
-/** What retiring an original did to its summary pages (paths relative to the project). */
+/** Where a retired original went. */
 export interface RetireResult {
+    /** Relative to `sourcesDir`. */
     movedTo: string;
-    summaries: {
-        page: string;
-        marked: "retired" | "superseded";
-        supersededBy?: string;
-    }[];
 }
 /**
- * Moves an original to `.agent-kit/retired/` (never deleted: the person empties that folder)
- * and records why. Its summary pages are marked: retired if the original was wrong (what it
- * taught was wrong), superseded if it was replaced, pointing to the replacement's summary
- * when there is one.
- */
-export declare function retireSource(sourcesDir: string, knowledgeDir: string | undefined, projectDir: string, source: string, why: "wrong" | "replaced", reason: string, replacedBy?: string): Promise<RetireResult>;
-/**
- * Records `source` (relative to `sourcesDir`) as ingested now, with its current hash: a
- * summary page was just written from it, so "changed" means changed after this.
+ * Moves an original to `.agent-kit/retired/` (never deleted: the person empties that folder) and
+ * records why. What was built from it (summary pages) is the knowledge base's to update: the
+ * model does it with its tools.
  */
-export declare function recordIngest(sourcesDir: string, source: string): Promise<void>;
+export declare function retireSource(sourcesDir: string, source: string, why: "wrong" | "replaced", reason: string, replacedBy?: string): Promise<RetireResult>;

package/dist/core/sources.js

@@ -5,10 +5,11 @@ import path from "node:path";
 /**
  * The sources folder's bookkeeping: originals stay files (ADR-024), and the kit keeps a
  * manifest next to them (`.agent-kit/sources.json`, inside `sourcesDir`, where the agent's
- * file tools can't write) with each original's hash, size and provenance, the version it
- * replaces, and the hash it had when a summary page first pointed to it. From that it tells
- * new, ingested, changed and missing originals apart, refuses duplicates, and retires an
- * original into `.agent-kit/retired/` instead of deleting it.
+ * file tools can't write) with each original's hash, size, provenance, the version it replaces
+ * and when its content last changed. From that it refuses duplicates, tells present, missing
+ * and retired originals apart, and retires an original into `.agent-kit/retired/` instead of
+ * deleting it. It knows nothing of the knowledge base: each owns its data, and the model
+ * connects them through their tools (#30). Hashes never leave it.
  */
 export const KIT_DIR = ".agent-kit";
 const MANIFEST = "sources.json";
@@ -70,41 +71,20 @@ export async function scanSources(sourcesDir) {
     await walk(sourcesDir);
     return found.sort();
 }
-/** An entry for `file`, reusing the recorded hash when its size and modification time haven't changed. */
+/**
+ * An entry for `file`, reusing the recorded hash when its size and modification time haven't
+ * changed; `changedAt` moves only when the content (its hash) did. Entries from before
+ * `changedAt` existed take their `addedAt`.
+ */
 async function freshEntry(file, known, origin) {
     const info = await stat(file);
-    if (known && known.size === info.size && known.mtimeMs === info.mtimeMs)
-        return known;
-    return { ...(known ?? { addedAt: now(), origin }), hash: await hashFile(file), size: info.size, mtimeMs: info.mtimeMs };
-}
-/** The original a frontmatter `file:` value points to (a relative path or a markdown link), resolved from the page's folder. */
-function linkedFile(value, pageDir) {
-    const link = /\]\(([^)]+)\)/.exec(value)?.[1] ?? value.trim().replace(/^["']|["']$/g, "");
-    if (!link || /^[a-z]+:\/\//i.test(link))
-        return undefined;
-    return path.resolve(pageDir, decodeURI(link));
-}
-/** The summary pages (knowledge base layout: `summaries/*.md`) by the absolute path of the original their frontmatter `file:` points to. */
-export async function summariesByOriginal(knowledgeDir) {
-    const byOriginal = new Map();
-    const dir = path.join(knowledgeDir, "summaries");
-    let names;
-    try {
-        names = await readdir(dir);
-    }
-    catch {
-        return byOriginal;
-    }
-    for (const name of names.filter((n) => n.endsWith(".md"))) {
-        const page = path.join(dir, name);
-        const text = await readFile(page, "utf8");
-        const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text)?.[1] ?? "";
-        const value = /^file:\s*(.+)$/m.exec(frontmatter)?.[1];
-        const original = value ? linkedFile(value, dir) : undefined;
-        if (original)
-            byOriginal.set(path.normalize(original), [...(byOriginal.get(path.normalize(original)) ?? []), page]);
-    }
-    return byOriginal;
+    const previous = known ? { ...known, changedAt: known.changedAt ?? known.addedAt } : undefined;
+    if (previous && previous.size === info.size && previous.mtimeMs === info.mtimeMs)
+        return previous;
+    const hash = await hashFile(file);
+    const stamp = now();
+    const base = previous ?? { addedAt: stamp, origin, changedAt: stamp };
+    return { ...base, hash, size: info.size, mtimeMs: info.mtimeMs, changedAt: previous && previous.hash === hash ? previous.changedAt : stamp };
 }
 /** Pages of a PDF, read from its page tree without a parser; undefined when it can't tell (e.g. compressed object streams). */
 export function pdfPageCount(bytes) {
@@ -124,31 +104,19 @@ export function pptxSlideCount(bytes) {
 }
 const typeOf = (file) => path.extname(file).slice(1).toLowerCase() || "file";
 /**
- * Every original with its status, recording in the manifest the ones copied in by hand and,
- * the first time a summary page points to one, its hash at ingest. Without a knowledge
- * folder there's no ingest to compare with: originals are "present".
+ * Every original with its status and when its content last changed, recording in the manifest
+ * the ones copied in by hand; then the missing ones and the retired ones.
  */
-export function listSources(sourcesDir, knowledgeDir, projectDir) {
-    return serialized(sourcesDir, () => listSourcesNow(sourcesDir, knowledgeDir, projectDir));
+export function listSources(sourcesDir) {
+    return serialized(sourcesDir, () => listSourcesNow(sourcesDir));
 }
-async function listSourcesNow(sourcesDir, knowledgeDir, projectDir) {
+async function listSourcesNow(sourcesDir) {
     const manifest = await loadManifest(sourcesDir);
-    const summaries = knowledgeDir ? await summariesByOriginal(knowledgeDir) : new Map();
     const files = await scanSources(sourcesDir);
     const listing = [];
     for (const rel of files) {
         const full = path.join(sourcesDir, rel);
         const entry = await freshEntry(full, manifest.files[rel], { kind: "manual" });
-        const pagesOf = summaries.get(path.normalize(full)) ?? [];
-        let status = "present";
-        if (knowledgeDir) {
-            if (pagesOf.length === 0)
-                status = "new";
-            else {
-                entry.ingestedHash ??= entry.hash;
-                status = entry.ingestedHash === entry.hash ? "ingested" : "changed";
-            }
-        }
         manifest.files[rel] = entry;
         const type = typeOf(rel);
         const counts = type === "pdf" || type === "pptx"
@@ -156,18 +124,28 @@ async function listSourcesNow(sourcesDir, knowledgeDir, projectDir) {
             : {};
         listing.push({
             path: rel,
-            status,
+            status: "present",
             type,
+            changedAt: entry.changedAt,
             size: entry.size,
             ...counts,
             origin: entry.origin,
             ...(entry.replaces ? { replaces: entry.replaces } : {}),
-            summaries: pagesOf.map((page) => posix(path.relative(projectDir, page))),
         });
     }
     for (const [rel, entry] of Object.entries(manifest.files)) {
         if (!files.includes(rel))
-            listing.push({ path: rel, status: "missing", type: typeOf(rel), origin: entry.origin, summaries: [] });
+            listing.push({ path: rel, status: "missing", type: typeOf(rel), origin: entry.origin });
+    }
+    for (const retired of manifest.retired) {
+        listing.push({
+            path: retired.path,
+            status: "retired",
+            type: typeOf(retired.path),
+            retiredAt: retired.retiredAt,
+            why: retired.why,
+            ...(retired.replacedBy ? { replacedBy: retired.replacedBy } : {}),
+        });
     }
     await saveManifest(sourcesDir, manifest);
     return listing;
@@ -219,11 +197,13 @@ async function addSourceNow(sourcesDir, file, destination, origin, extra) {
     }
     const rel = posix(path.relative(sourcesDir, target));
     const info = await stat(target);
+    const stamp = now();
     manifest.files[rel] = {
         hash,
         size: info.size,
         mtimeMs: info.mtimeMs,
-        addedAt: now(),
+        addedAt: stamp,
+        changedAt: stamp,
         origin,
         ...(extra.replaces ? { replaces: posix(path.relative(sourcesDir, resolveWithin(sourcesDir, extra.replaces))) } : {}),
         ...(extra.derivedFrom ? { derivedFrom: extra.derivedFrom } : {}),
@@ -231,26 +211,15 @@ async function addSourceNow(sourcesDir, file, destination, origin, extra) {
     await saveManifest(sourcesDir, manifest);
     return { path: rel };
 }
-/** Adds frontmatter fields and a notice under the frontmatter of a markdown page. */
-async function markPage(page, fields, notice) {
-    const text = await readFile(page, "utf8");
-    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text);
-    const lines = Object.entries(fields).map(([key, value]) => `${key}: ${value}`);
-    const updated = match
-        ? `---\n${match[1].split(/\r?\n/).filter((line) => !Object.keys(fields).some((key) => line.startsWith(`${key}:`))).concat(lines).join("\n")}\n---\n\n> ${notice}\n\n${text.slice(match[0].length).replace(/^\s+/, "")}`
-        : `---\n${lines.join("\n")}\n---\n\n> ${notice}\n\n${text}`;
-    await writeFile(page, updated);
-}
 /**
- * Moves an original to `.agent-kit/retired/` (never deleted: the person empties that folder)
- * and records why. Its summary pages are marked: retired if the original was wrong (what it
- * taught was wrong), superseded if it was replaced, pointing to the replacement's summary
- * when there is one.
+ * Moves an original to `.agent-kit/retired/` (never deleted: the person empties that folder) and
+ * records why. What was built from it (summary pages) is the knowledge base's to update: the
+ * model does it with its tools.
  */
-export function retireSource(sourcesDir, knowledgeDir, projectDir, source, why, reason, replacedBy) {
-    return serialized(sourcesDir, () => retireSourceNow(sourcesDir, knowledgeDir, projectDir, source, why, reason, replacedBy));
+export function retireSource(sourcesDir, source, why, reason, replacedBy) {
+    return serialized(sourcesDir, () => retireSourceNow(sourcesDir, source, why, reason, replacedBy));
 }
-async function retireSourceNow(sourcesDir, knowledgeDir, projectDir, source, why, reason, replacedBy) {
+async function retireSourceNow(sourcesDir, source, why, reason, replacedBy) {
     const full = resolveWithin(sourcesDir, source);
     if (!full || !(await stat(full).catch(() => null))?.isFile())
         throw new Error(`"${source}" isn't an original in sources/.`);
@@ -260,7 +229,6 @@ async function retireSourceNow(sourcesDir, knowledgeDir, projectDir, source, why
     const replacement = replacedBy ? resolveWithin(sourcesDir, replacedBy) : undefined;
     if (replacedBy && (!replacement || !(await stat(replacement).catch(() => null))))
         throw new Error(`"${replacedBy}" isn't an original in sources/.`);
-    const summaries = knowledgeDir ? await summariesByOriginal(knowledgeDir) : new Map();
     const manifest = await loadManifest(sourcesDir);
     const stamp = now();
     const movedTo = posix(path.join(KIT_DIR, RETIRED_DIR, `${stamp.replace(/[:.]/g, "-")}-${path.basename(rel)}`));
@@ -277,36 +245,5 @@ async function retireSourceNow(sourcesDir, knowledgeDir, projectDir, source, why
     });
     delete manifest.files[rel];
     await saveManifest(sourcesDir, manifest);
-    const date = stamp.slice(0, 10);
-    const replacementSummary = replacement ? summaries.get(path.normalize(replacement))?.[0] : undefined;
-    const result = { movedTo, summaries: [] };
-    for (const page of summaries.get(path.normalize(full)) ?? []) {
-        if (why === "wrong") {
-            await markPage(page, { status: "retired", retired: date }, `Retired on ${date}: its original was wrong (${reason}). Don't rely on what it says.`);
-            result.summaries.push({ page: posix(path.relative(projectDir, page)), marked: "retired" });
-        }
-        else {
-            const link = replacementSummary ? posix(path.relative(path.dirname(page), replacementSummary)) : undefined;
-            await markPage(page, { status: "superseded", superseded: date, ...(link ? { superseded_by: link } : {}) }, `Superseded on ${date}: its original was replaced (${reason})${link ? `; see [the new summary](${link})` : ""}.`);
-            result.summaries.push({ page: posix(path.relative(projectDir, page)), marked: "superseded", ...(replacementSummary ? { supersededBy: posix(path.relative(projectDir, replacementSummary)) } : {}) });
-        }
-    }
-    return result;
-}
-/**
- * Records `source` (relative to `sourcesDir`) as ingested now, with its current hash: a
- * summary page was just written from it, so "changed" means changed after this.
- */
-export function recordIngest(sourcesDir, source) {
-    return serialized(sourcesDir, async () => {
-        const full = resolveWithin(sourcesDir, source);
-        if (!full || !(await stat(full).catch(() => null))?.isFile())
-            return;
-        const rel = posix(path.relative(sourcesDir, full));
-        const manifest = await loadManifest(sourcesDir);
-        const entry = await freshEntry(full, manifest.files[rel], { kind: "manual" });
-        entry.ingestedHash = entry.hash;
-        manifest.files[rel] = entry;
-        await saveManifest(sourcesDir, manifest);
-    });
+    return { movedTo };
 }