@falkenslab/agent-kit 0.16.0 → 0.17.0

package/README.md

@@ -34,13 +34,15 @@ 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)
 
-### teacher-agent
+See [everything he can do](https://falkenslab.github.io/agent-kit/docs/next/examples/captain-whiskers#what-he-can-do), with screenshots.
 
-[teacher-agent](https://github.com/falkenslab/teacher-agent) is a real assistant for Moodle teachers. It signs in with your account in a Chrome window and works as you would: it grades submissions, answers in the forum, creates or reviews content and sums up how the class is going. It asks for your permission before publishing anything students will see, and takes notes about the course to remember everything in the next session.
+### miyagi
 
-Oversight, memory, safety and the chat come from the kit; teacher-agent brings what it knows about Moodle and driving the browser.
+[miyagi](https://github.com/falkenslab/miyagi) is a real assistant for Moodle teachers. It signs in with your account in a Chrome window and works as you would: it grades submissions, answers in the forum, creates or reviews content and sums up how the class is going. It asks for your permission before publishing anything students will see, and takes notes about the course to remember everything in the next session.
+
+Oversight, memory, safety and the chat come from the kit; miyagi brings what it knows about Moodle and driving the browser.
 
 ## Installation
 

package/assets/agent-help/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: agent-help
+description: How to use this agent - its chat's modes, keys and slash commands, resuming an earlier conversation, approvals and questions, the command line, and the agent's own commands and configuration. Load it whenever the person asks how to do something with you, what a key or command does, or what you can do.
+---
+
+# Helping the person use you
+
+Answer from this page only: the chat's part below is the same for every agent built on agent-kit, and the "This session" and "This agent" sections at the end are about you. If something isn't covered here, say you don't know rather than inventing a key, command or option. Answer in the person's language, briefly, with the exact key or command; keys and commands are typed as written here, whatever the language.
+
+## Modes
+
+How much you ask before acting. The current one is in the status bar, below the prompt.
+
+- **interactive**: asks before every single action (each tool call), with the tool and its parameters.
+- **guided**: asks only before something hard to undo or visible to others (publishing, sending); everything else runs on its own.
+- **autonomous**: never asks; there's nobody to ask. A session that starts autonomous stays autonomous.
+- **plan**: only reads and plans, changing nothing, until the plan is approved. The plan comes as a panel: **Run it** (leaves plan mode and carries it out), **Keep planning** (with a comment on what should change) or **Cancel**.
+
+`Shift+Tab` switches to the next mode the session allows (guided, interactive, plan, in a loop). `/plan` turns plan mode on, and off again back to the mode it came from.
+
+## Approvals and questions
+
+- **An approval** shows what is about to happen: **Yes** to go on, **No** to refuse that one action (the agent tries something else), **Stop** to stop it altogether.
+- **A question** with options: `↑`/`↓` and `Enter` to choose, `Space` to mark when several can be chosen, or **Other** to type your own answer. A free question: type the answer and `Enter`, or `Esc` for no answer.
+- **A request for a file**: drag the file onto the terminal (or type its path) and `Enter`, or just `Enter` if you don't have it.
+- **A manual step** (signing in by hand, for an agent that drives a window): do it, then **Done, continue**.
+- In interactive mode every action asks; switching to guided with `Shift+Tab` stops that.
+
+## Keys
+
+- `Enter` sends the message; `\` then `Enter`, or `Ctrl+J`, starts a new line.
+- `Tab` completes a `/command`, or takes the grey suggestion.
+- `↑`/`↓` go through earlier messages; `Ctrl+R` searches them. `↑` on an empty prompt edits the last message still waiting to be sent.
+- `Ctrl+W` deletes a word, `Ctrl+K` to the end of the line, `Ctrl+U` the whole line; `Ctrl+←`/`Ctrl+→` move by word.
+- `@` mentions a file, with completion.
+- `?` on an empty prompt shows the shortcuts.
+- `Esc` interrupts the agent's turn; `Ctrl+C` interrupts it, or leaves at an empty prompt.
+- `Ctrl+O` unfolds (and folds again) the tool calls; the task list of a long job stays on screen while it runs.
+- `PgUp`/`PgDn` or the mouse wheel scroll; `Ctrl+End` goes back to the bottom. In full screen, drag to select and right-click to copy.
+
+Messages typed while the agent works are queued and sent when it finishes.
+
+## Commands
+
+- `/exit` or `/quit`: leave the chat (an agent can name its own exit commands instead).
+- `/copy`: copy the last reply to the clipboard.
+- `/resume`: pick an earlier conversation to go on with (`↑`/`↓`, `Enter`, `Esc` to cancel), where the agent keeps its conversations.
+- `/plan`: plan mode on or off (see Modes).
+
+Typing `/` and `Tab` lists every command, the agent's own included (named `/plugin:command`). An unknown `/command` isn't sent.
+
+## Command line
+
+- `--continue`: start with the latest conversation instead of a new one.
+- `--language=<code>`: the language of the chat and of the replies: `en`, `es`, `fr` or `de`. Without it, the agent's configured one, or the system's.
+
+Some agents use a simpler line-by-line chat that has only part of this (no full screen, no `/copy`).

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

@@ -13,7 +13,7 @@ A source is ingested once, and from then on the knowledge base holds what it tau
 
 ## 2. Read it for real
 
-Read the whole source, not its first page (a long PDF in parts: `list_sources` gives its pages). Its path is `sources/<path>` in the project folder, not in 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.
+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
 

package/dist/core/agentHelp.d.ts

@@ -0,0 +1,30 @@
+import type { AgentIdentity, Mode } from "./agentSpec.js";
+/**
+ * The agent's self-knowledge: who it is (a section of the system prompt) and how it is used
+ * (the `agent-help` skill). The chat's part of the skill is the kit's, the same for every
+ * agent and kept next to the chat's code (`assets/agent-help/SKILL.md`, checked against the
+ * chat's commands and keys by a test); the agent's part is its own guide (`AgentSpec.helpGuide`).
+ */
+/** The plugin the skill is loaded from, as the SDK names its skills ("agent-kit:agent-help"). */
+export declare const AGENT_HELP_SKILL = "agent-kit:agent-help";
+/** Absolute path of the kit's part of the skill, next to `dist/` (or `src/` under tsx). */
+export declare function agentHelpSkillPath(): string;
+/** The "Who you are" section appended to the system prompt: name, version, what it is, the kit's version. */
+export declare function identityPromptSection(identity: AgentIdentity): string;
+/** What the generated skill says about this session. */
+export interface AgentHelpSession {
+    mode: Mode;
+    /** The modes Shift+Tab goes through (`ModeControl.switchable`). */
+    switchable: readonly Mode[];
+    /** The built-in knowledge base is on: its slash commands exist. */
+    knowledgeBase: boolean;
+    /** The sources folder, as shown to the model (e.g. "sources/"). */
+    sourcesFolder?: string;
+}
+/**
+ * Writes the `agent-help` plugin into `dir` (a folder of this run's), with the kit's part of
+ * the skill, this session's facts and the agent's own guide, and returns its root. Generated
+ * rather than shipped as it is: the guide goes inside the skill, so the agent needs no file
+ * tools to read it, and nothing about it reaches the context until the skill is loaded.
+ */
+export declare function writeAgentHelpPlugin(dir: string, session: AgentHelpSession, helpGuide?: string): Promise<string>;

package/dist/core/agentHelp.js

@@ -0,0 +1,55 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { agentKitVersion } from "./version.js";
+/**
+ * The agent's self-knowledge: who it is (a section of the system prompt) and how it is used
+ * (the `agent-help` skill). The chat's part of the skill is the kit's, the same for every
+ * agent and kept next to the chat's code (`assets/agent-help/SKILL.md`, checked against the
+ * chat's commands and keys by a test); the agent's part is its own guide (`AgentSpec.helpGuide`).
+ */
+/** The plugin the skill is loaded from, as the SDK names its skills ("agent-kit:agent-help"). */
+export const AGENT_HELP_SKILL = "agent-kit:agent-help";
+/** Absolute path of the kit's part of the skill, next to `dist/` (or `src/` under tsx). */
+export function agentHelpSkillPath() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "assets", "agent-help", "SKILL.md");
+}
+/** The "Who you are" section appended to the system prompt: name, version, what it is, the kit's version. */
+export function identityPromptSection(identity) {
+    const who = `${identity.name}${identity.version ? ` ${identity.version}` : ""}${identity.description ? `: ${identity.description}` : ""}`;
+    return `## Who you are
+You are ${who}. You are built on agent-kit ${agentKitVersion()}, which provides your chat (its modes, keys and slash commands) and your built-in tools.
+When the person asks how to use you (your modes, keys or commands, resuming an earlier conversation, your configuration, what you can do), load the \`agent-help\` skill and answer from it; don't invent options it doesn't list.`;
+}
+/** The skill's "This session" section. */
+function sessionSection(session) {
+    const lines = [
+        `- This session started in **${session.mode}** mode.`,
+        session.switchable.length > 1
+            ? `- \`Shift+Tab\` goes through: ${session.switchable.join(", ")}.`
+            : "- The mode can't be switched during this session.",
+    ];
+    if (session.knowledgeBase)
+        lines.push("- You keep a knowledge base (your memory across sessions). Its commands: `/knowledge:ingest` (learn the new or changed files of the sources folder), `/knowledge:query <question>` (answer from it), `/knowledge:lint` (check it and fix what's mechanical).");
+    if (session.sourcesFolder)
+        lines.push(`- Originals go in \`${session.sourcesFolder}\`: the person drops files there (or you ask for one, or download it), and you never change them.`);
+    return `## This session\n\n${lines.join("\n")}`;
+}
+/**
+ * Writes the `agent-help` plugin into `dir` (a folder of this run's), with the kit's part of
+ * the skill, this session's facts and the agent's own guide, and returns its root. Generated
+ * rather than shipped as it is: the guide goes inside the skill, so the agent needs no file
+ * tools to read it, and nothing about it reaches the context until the skill is loaded.
+ */
+export async function writeAgentHelpPlugin(dir, session, helpGuide) {
+    const kitPart = (await readFile(agentHelpSkillPath(), "utf8")).trimEnd();
+    const guide = helpGuide ? (await readFile(helpGuide, "utf8")).trim() : "";
+    const agentPart = guide
+        ? `## This agent\n\nThe agent's own guide, for everything about its domain (its commands, configuration, folders):\n\n${guide}`
+        : "## This agent\n\nThis agent has no guide of its own: for its domain, say only what your instructions tell you, and that the rest isn't documented.";
+    await mkdir(path.join(dir, ".claude-plugin"), { recursive: true });
+    await mkdir(path.join(dir, "skills", "agent-help"), { recursive: true });
+    await writeFile(path.join(dir, ".claude-plugin", "plugin.json"), `${JSON.stringify({ name: "agent-kit", description: "How to use this agent: the kit's chat and the agent's own guide." }, null, 2)}\n`);
+    await writeFile(path.join(dir, "skills", "agent-help", "SKILL.md"), `${kitPart}\n\n${sessionSection(session)}\n\n${agentPart}\n`);
+    return dir;
+}

package/dist/core/agentSpec.d.ts

@@ -70,6 +70,18 @@ export interface BaseSessionConfig {
 export interface AgentSpec<TConfig extends BaseSessionConfig> {
     /** The system prompt for this run — everything role/mode/domain-specific lives behind this call. */
     buildSystemPrompt(config: TConfig): string;
+    /**
+     * Who the agent is. With it, the kit tells the model its name, version and what it is, plus
+     * agent-kit's version, and offers the `agent-help` skill, which answers how to use the
+     * agent: the kit's chat (modes, keys, slash commands, resuming) and `helpGuide`. Without
+     * it, neither.
+     */
+    identity?: AgentIdentity;
+    /**
+     * Absolute path of a markdown guide to the agent's own domain (its commands, configuration,
+     * folders), which the `agent-help` skill includes. Only with `identity`.
+     */
+    helpGuide?: string;
     /**
      * MCP servers this agent always registers (e.g. Playwright for a browser-driving
      * agent), on top of the generic ones `buildSessionOptions()` wires up itself when
@@ -192,6 +204,15 @@ export interface AgentSpec<TConfig extends BaseSessionConfig> {
      */
     planMode?: PlanModeSpec<TConfig>;
 }
+/** Who an agent is, as told to its model (`AgentSpec.identity`). */
+export interface AgentIdentity {
+    /** The agent's name, e.g. "padawan". */
+    name: string;
+    /** Its version, e.g. its package's. */
+    version?: string;
+    /** What it is, in one line, e.g. "an agent that takes a Moodle course as a student". */
+    description?: string;
+}
 /** The domain's part of "plan" mode: which files hold the plan and which of its own tools only read. */
 export interface PlanModeSpec<TConfig extends BaseSessionConfig = BaseSessionConfig> {
     /**

package/dist/core/fileKnowledgeStore.js

@@ -163,7 +163,12 @@ export function createFileKnowledgeStore(knowledgeDir, options = {}) {
     async function storedField(key, value, file) {
         if (key !== "file" || !options.sourcesDir || /^[a-z]+:\/\//i.test(value))
             return value;
-        const original = path.resolve(options.sourcesDir, value.replace(/^sources\//, ""));
+        // Relative to the sources folder; a leading "sources/" or the folder's own name is dropped.
+        let relative = value.replace(/\\/g, "/").replace(/^\.\//, "");
+        for (const prefix of ["sources/", `${path.basename(options.sourcesDir)}/`])
+            if (relative.startsWith(prefix))
+                relative = relative.slice(prefix.length);
+        const original = path.resolve(options.sourcesDir, relative);
         if (!(await stat(original).catch(() => null))?.isFile())
             throw new Error(`"${value}" isn't an original in sources/ (list_sources lists them).`);
         return posix(path.relative(path.dirname(file), original));
@@ -321,6 +326,12 @@ export function createFileKnowledgeStore(knowledgeDir, options = {}) {
                 .map(({ id, title, snippet }) => ({ id, title, snippet }));
         },
         index: indexText,
+        async recentLog(limit = 10) {
+            const text = await readFile(path.join(knowledgeDir, "log.md"), "utf8").catch(() => "");
+            // Entries start with "## [date] operation | what"; the newest are at the bottom.
+            const entries = text.split(/\r?\n(?=## )/).filter((entry) => entry.startsWith("## ")).map((entry) => entry.trim());
+            return entries.slice(-limit).reverse();
+        },
         async log(operation, what, pages = []) {
             await mkdir(knowledgeDir, { recursive: true });
             const file = path.join(knowledgeDir, "log.md");
@@ -331,6 +342,7 @@ export function createFileKnowledgeStore(knowledgeDir, options = {}) {
         async check() {
             await writeIndex(); // the one mechanical fix there is: an index.md out of date
             const { pages, byFile } = await pagesByFile();
+            const reservedFiles = new Set([...RESERVED].map((name) => path.normalize(path.join(knowledgeDir, `${name}.md`))));
             const known = new Map(pages.map((p) => [p.id, p]));
             const inbound = new Map();
             const report = { brokenLinks: [], orphans: [], linksToRetired: [], missingOriginals: [] };
@@ -338,11 +350,16 @@ export function createFileKnowledgeStore(knowledgeDir, options = {}) {
                 if (statusOf(page) === "retired")
                     continue;
                 const body = fromFile(page.body, page.file, byFile);
-                // Relative links to .md files that resolve to nothing are broken too.
+                // Relative links to .md files that resolve to nothing are broken too. The overview, the
+                // index and the log aren't pages but are files: a link to one that exists is fine (a
+                // knowledge base written with the file tools links the overview, #22).
                 for (const m of page.body.matchAll(/\]\(([^)\s:]+\.md)(?:#[^)]*)?\)/g)) {
                     const target = path.normalize(path.resolve(path.dirname(page.file), decodeURI(m[1])));
-                    if (!byFile.has(target) && target.startsWith(path.normalize(knowledgeDir)))
-                        report.brokenLinks.push({ page: page.id, target: posix(path.relative(knowledgeDir, target)) });
+                    if (byFile.has(target) || !target.startsWith(path.normalize(knowledgeDir)))
+                        continue;
+                    if (reservedFiles.has(target) && (await stat(target).catch(() => null)))
+                        continue;
+                    report.brokenLinks.push({ page: page.id, target: posix(path.relative(knowledgeDir, target)) });
                 }
                 for (const id of new Set(linkedIds(body))) {
                     const target = known.get(id);

package/dist/core/knowledge.js

@@ -30,7 +30,7 @@ function toolsSection(originals, pageTypes) {
 Your memory across sessions is an interlinked knowledge base of pages that you write and maintain yourself — a wiki, not a pile of notes. A future session only knows what is written there, so anything worth remembering must end up in a page, not just in this turn's reply. You reach it only through the \`knowledge_*\` tools. Write page content in the language you are using with the human.
 
 ### Layers
-${originals ? originalsLine(originals) : ""}- **The knowledge base**: pages identified by type and slug (\`concept/spring-tides\`), plus the \`overview\`, a living synthesis of the whole. Page types: ${pageTypes.map((type) => `\`${type.type}\` (${type.description})`).join("; ")}.
+${originals ? originalsLine(originals) : ""}- **The knowledge base**: pages identified by type and slug (\`concept/spring-tides\`), plus the \`overview\`, a living synthesis of the whole, and the \`log\` of what was done to it (\`knowledge_read\` reads both). Page types: ${pageTypes.map((type) => `\`${type.type}\` (${type.description})`).join("; ")}.
 - **The schema**: these rules plus the \`knowledge-ingest\`, \`knowledge-query\` and \`knowledge-lint\` skills. \`knowledge_create\` without content gives a type's template.
 
 ### Working rules

package/dist/core/knowledgeStore.d.ts

@@ -114,6 +114,11 @@ export interface KnowledgeStore {
     index(): Promise<string>;
     /** Adds an entry to the operation log, dated today. */
     log(operation: string, what: string, pages?: readonly string[]): Promise<void>;
+    /**
+     * The latest entries of the operation log, newest first, as markdown (e.g. "## [2026-10-04]
+     * ingest | …"). Optional: a store without it can't show the log to the agent.
+     */
+    recentLog?(limit?: number): Promise<string[]>;
     /** The mechanical problems. */
     check(): Promise<CheckReport>;
     /** The overview: a living synthesis of the whole knowledge base ("" if none yet). */

package/dist/core/messages/de.js

@@ -5,7 +5,7 @@ export const de = {
     escToInterrupt: "Esc zum Unterbrechen",
     workedFor: (seconds) => `${seconds}s gearbeitet`,
     turns: (count) => `${count} ${plural(count, "Runde", "Runden")}`,
-    tokens: (input, output) => `${input} ein / ${output} aus`,
+    tokens: (input, output, cached) => `${input} ein${cached ? ` (+${cached} Cache)` : ""} / ${output} aus`,
     context: (percent) => `Kontext ${percent}%`,
     mode: (mode) => MODES[mode],
     switchModeKey: "⇧Tab",
@@ -70,12 +70,12 @@ export const de = {
     keepPlanning: "Weiter planen",
     cancelPlan: "Abbrechen",
     planCommentQuestion: "Was soll sich ändern? (Enter zum Überspringen): ",
-    retireLines: (source, why, reason, replacedBy) => [
+    retireLines: (source, why, reason, replacedBy, folder) => [
         `Quelle: ${source}`,
         why === "wrong" ? "Warum: sie ist falsch; ihre Zusammenfassung wird zurückgezogen" : "Warum: sie wird ersetzt; ihre Zusammenfassung wird als ersetzt markiert",
         `Grund: ${reason}`,
         ...(replacedBy ? [`Ersetzt durch: ${replacedBy}`] : []),
-        "Sie wird nach sources/.agent-kit/retired/ verschoben, nicht gelöscht.",
+        `Sie wird nach ${folder}.agent-kit/retired/ verschoben, nicht gelöscht.`,
     ],
     toolPhrases: {
         Read: ["hat {n} Datei gelesen", "hat {n} Dateien gelesen"],
@@ -120,7 +120,7 @@ export const de = {
     labels: {
         askingApproval: (summary) => `Bittet um menschliche Genehmigung: ${summary}`,
         waitingManual: "Wartet auf einen manuellen Eingriff",
-        savingToSources: (destination) => `Speichert eine Datei in sources/${destination}`,
+        savingToSources: (destination) => `Speichert ${destination} in den Quellen`,
         checkingTime: "Datum und Uhrzeit abfragen",
         calculatingDates: "Daten berechnen",
         reading: (file) => `Liest ${file}`,

package/dist/core/messages/en.d.ts

@@ -11,7 +11,8 @@ export interface Messages {
     escToInterrupt: string;
     workedFor(seconds: number): string;
     turns(count: number): string;
-    tokens(input: string, output: string): string;
+    /** The session's input tokens: new ones, and those read again from the cache (if any). */
+    tokens(input: string, output: string, cached?: string): string;
     context(percent: number): string;
     mode(mode: Mode): string;
     switchModeKey: string;
@@ -67,7 +68,7 @@ export interface Messages {
     keepPlanning: string;
     cancelPlan: string;
     planCommentQuestion: string;
-    retireLines(source: string, why: "wrong" | "replaced", reason: string, replacedBy?: string): string[];
+    retireLines(source: string, why: "wrong" | "replaced", reason: string, replacedBy: string | undefined, folder: string): string[];
     toolPhrases: Record<string, ToolPhrase>;
     otherTools: ToolPhrase;
     noOutput: string;

package/dist/core/messages/en.js

@@ -4,7 +4,7 @@ export const en = {
     escToInterrupt: "esc to interrupt",
     workedFor: (seconds) => `Worked for ${seconds}s`,
     turns: (count) => `${count} ${plural(count, "turn", "turns")}`,
-    tokens: (input, output) => `${input} in / ${output} out`,
+    tokens: (input, output, cached) => `${input} in${cached ? ` (+${cached} cached)` : ""} / ${output} out`,
     context: (percent) => `context ${percent}%`,
     mode: (mode) => mode,
     switchModeKey: "shift+tab",
@@ -69,12 +69,12 @@ export const en = {
     keepPlanning: "Keep planning",
     cancelPlan: "Cancel",
     planCommentQuestion: "What should change? (Enter to skip): ",
-    retireLines: (source, why, reason, replacedBy) => [
+    retireLines: (source, why, reason, replacedBy, folder) => [
         `Source: ${source}`,
         why === "wrong" ? "Why: it's wrong; its summary will be retired" : "Why: it's replaced; its summary will be marked superseded",
         `Reason: ${reason}`,
         ...(replacedBy ? [`Replaced by: ${replacedBy}`] : []),
-        "It's moved to sources/.agent-kit/retired/, not deleted.",
+        `It's moved to ${folder}.agent-kit/retired/, not deleted.`,
     ],
     toolPhrases: {
         Read: ["read {n} file", "read {n} files"],
@@ -119,7 +119,7 @@ export const en = {
     labels: {
         askingApproval: (summary) => `Asking for human approval: ${summary}`,
         waitingManual: "Waiting for a human to intervene manually",
-        savingToSources: (destination) => `Saving a file to sources/${destination}`,
+        savingToSources: (destination) => `Saving ${destination} to the sources`,
         checkingTime: "Checking the date and time",
         calculatingDates: "Calculating dates",
         reading: (file) => `Reading ${file}`,

package/dist/core/messages/es.js

@@ -5,7 +5,7 @@ export const es = {
     escToInterrupt: "esc para interrumpir",
     workedFor: (seconds) => `Trabajó ${seconds}s`,
     turns: (count) => `${count} ${plural(count, "turno", "turnos")}`,
-    tokens: (input, output) => `${input} ent. / ${output} sal.`,
+    tokens: (input, output, cached) => `${input} ent.${cached ? ` (+${cached} caché)` : ""} / ${output} sal.`,
     context: (percent) => `contexto ${percent}%`,
     mode: (mode) => MODES[mode],
     switchModeKey: "⇧tab",
@@ -70,12 +70,12 @@ export const es = {
     keepPlanning: "Seguir planificando",
     cancelPlan: "Cancelar",
     planCommentQuestion: "¿Qué debería cambiar? (Enter para omitir): ",
-    retireLines: (source, why, reason, replacedBy) => [
+    retireLines: (source, why, reason, replacedBy, folder) => [
         `Fuente: ${source}`,
         why === "wrong" ? "Motivo: es errónea; su resumen se retirará" : "Motivo: se sustituye; su resumen se marcará como sustituido",
         `Razón: ${reason}`,
         ...(replacedBy ? [`Sustituida por: ${replacedBy}`] : []),
-        "Se mueve a sources/.agent-kit/retired/, no se borra.",
+        `Se mueve a ${folder}.agent-kit/retired/, no se borra.`,
     ],
     toolPhrases: {
         Read: ["leyó {n} fichero", "leyó {n} ficheros"],
@@ -120,7 +120,7 @@ export const es = {
     labels: {
         askingApproval: (summary) => `Pidiendo aprobación humana: ${summary}`,
         waitingManual: "Esperando a que una persona intervenga a mano",
-        savingToSources: (destination) => `Guardando un fichero en sources/${destination}`,
+        savingToSources: (destination) => `Guardando ${destination} en las fuentes`,
         checkingTime: "Consultando la fecha y la hora",
         calculatingDates: "Calculando fechas",
         reading: (file) => `Leyendo ${file}`,

package/dist/core/messages/fr.js

@@ -5,7 +5,7 @@ export const fr = {
     escToInterrupt: "échap pour interrompre",
     workedFor: (seconds) => `A travaillé ${seconds}s`,
     turns: (count) => `${count} ${plural(count, "tour", "tours")}`,
-    tokens: (input, output) => `${input} entr. / ${output} sort.`,
+    tokens: (input, output, cached) => `${input} entr.${cached ? ` (+${cached} cache)` : ""} / ${output} sort.`,
     context: (percent) => `contexte ${percent}%`,
     mode: (mode) => MODES[mode],
     switchModeKey: "⇧tab",
@@ -70,12 +70,12 @@ export const fr = {
     keepPlanning: "Continuer à planifier",
     cancelPlan: "Annuler",
     planCommentQuestion: "Que faut-il changer ? (Entrée pour passer) : ",
-    retireLines: (source, why, reason, replacedBy) => [
+    retireLines: (source, why, reason, replacedBy, folder) => [
         `Source : ${source}`,
         why === "wrong" ? "Motif : elle est erronée ; son résumé sera retiré" : "Motif : elle est remplacée ; son résumé sera marqué comme remplacé",
         `Raison : ${reason}`,
         ...(replacedBy ? [`Remplacée par : ${replacedBy}`] : []),
-        "Elle est déplacée dans sources/.agent-kit/retired/, pas supprimée.",
+        `Elle est déplacée dans ${folder}.agent-kit/retired/, pas supprimée.`,
     ],
     toolPhrases: {
         Read: ["a lu {n} fichier", "a lu {n} fichiers"],
@@ -120,7 +120,7 @@ export const fr = {
     labels: {
         askingApproval: (summary) => `Demande d'approbation humaine : ${summary}`,
         waitingManual: "En attente d'une intervention manuelle",
-        savingToSources: (destination) => `Enregistrement d'un fichier dans sources/${destination}`,
+        savingToSources: (destination) => `Enregistrement de ${destination} dans les sources`,
         checkingTime: "Consultation de la date et de l'heure",
         calculatingDates: "Calcul de dates",
         reading: (file) => `Lecture de ${file}`,

package/dist/core/runner.d.ts

@@ -97,6 +97,11 @@ export type AgentEvent =
 export interface SessionUsage {
     /** Input tokens, cache reads and writes included, across every model the session used. */
     inputTokens: number;
+    /**
+     * The part of `inputTokens` read from the cache: the context sent again on every call. It
+     * grows with each call while the context barely does, so the chat shows it apart.
+     */
+    cacheReadTokens?: number;
     outputTokens: number;
     /** An estimate, not a billing statement. */
     costUsd: number;

package/dist/core/runner.js

@@ -90,6 +90,7 @@ export function runQuery(prompt, options) {
                 const models = Object.values(message.modelUsage ?? {});
                 const usage = {
                     inputTokens: models.reduce((sum, m) => sum + m.inputTokens + m.cacheReadInputTokens + m.cacheCreationInputTokens, 0),
+                    cacheReadTokens: models.reduce((sum, m) => sum + m.cacheReadInputTokens, 0),
                     outputTokens: models.reduce((sum, m) => sum + m.outputTokens, 0),
                     costUsd: message.total_cost_usd,
                 };

package/dist/core/session.js

@@ -16,6 +16,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";
@@ -86,15 +87,29 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
     // 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")] : [])];
+    // 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(knowledgeViaStore ? "tools" : "files")] : []),
+        ...(helpPlugin ? [helpPlugin] : []),
+    ];
     const knowledgeStore = knowledgeViaStore && config.knowledgeDir
         ? (spec.knowledgeStore?.(config) ?? createFileKnowledgeStore(config.knowledgeDir, { pageTypes: spec.knowledgePageTypes, sourcesDir: config.sourcesDir }))
         : undefined;
     const includeSkillsAndPlugins = includeFileTools || pluginRoots.length > 0;
     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 +121,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 +135,15 @@ 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 ?? []);
+    const promptSections = [
+        spec.buildSystemPrompt(config),
+        ...(spec.identity ? [identityPromptSection(spec.identity)] : []),
+        ...(includeKnowledgeBase && config.knowledgeDir
+            ? [knowledgePromptSection(config.projectDir, config.knowledgeDir, config.sourcesDir, { tools: knowledgeViaStore, pageTypes: knowledgeStore?.types() })]
+            : []),
+    ];
     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"],
@@ -139,8 +165,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
@@ -148,6 +174,11 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
         // name isn't known ahead of time.
         canUseTool: allowAnyMcpTool,
         disallowedTools: spec.disallowedTools ?? [],
+        // TodoWrite (todos.ts) only exists with CLAUDE_CODE_ENABLE_TASKS=0: by default the CLI
+        // offers its TaskCreate/TaskUpdate/TaskList/TaskGet tools instead, and drops TodoWrite from
+        // the session even when `tools` names it (confirmed empirically). `env` replaces the
+        // subprocess environment, so the rest is passed on as it is.
+        env: { ...process.env, CLAUDE_CODE_ENABLE_TASKS: "0" },
         // Real text streaming instead of silently waiting for the turn's complete message —
         // see the caller's message loop.
         includePartialMessages: true,
@@ -165,8 +196,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(spec.skills, includeKnowledgeBase ? (knowledgeViaStore ? "tools" : "files") : null, Boolean(helpPlugin)),
                 plugins: pluginRoots.map((pluginPath) => ({ type: "local", path: pluginPath, skipMcpDiscovery: true })),
             }
             : {}),
@@ -254,10 +285,10 @@ 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) {
+function skillList(skills, knowledgeVariant, agentHelp) {
     if (skills === undefined || skills === "all")
         return "all";
-    return knowledgeVariant ? [...new Set([...skills, ...KNOWLEDGE_SKILLS[knowledgeVariant]])] : skills;
+    return [...new Set([...skills, ...(knowledgeVariant ? KNOWLEDGE_SKILLS[knowledgeVariant] : []), ...(agentHelp ? [AGENT_HELP_SKILL] : [])])];
 }
 /**
  * User message queue backed by a single long-lived generator, for any multi-turn

package/dist/core/tools/knowledgeTools.js

@@ -22,6 +22,7 @@ async function attempt(work) {
     }
 }
 const OVERVIEW = "overview";
+const LOG = "log";
 /** The `knowledge` MCP server over `store`. */
 export function createKnowledgeServer(store, options) {
     const typeNames = store.types().map((t) => t.type);
@@ -49,9 +50,15 @@ export function createKnowledgeServer(store, options) {
         const hits = await store.search(args.query, args.limit ?? 10);
         return hits.length ? hits.map((hit) => `- ${hit.id} — ${hit.title}: ${hit.snippet}`).join("\n") : "No page matches.";
     }), { annotations: { readOnlyHint: true } });
-    const read = tool("knowledge_read", 'A page by its id ("concept/bowline"), or "overview": its fields, its content (links to other pages as ids) and the pages that link to it.', { page: z.string().describe('The page id, or "overview"') }, async (args) => attempt(async () => {
+    const read = tool("knowledge_read", 'A page by its id ("concept/bowline"): its fields, its content (links to other pages as ids) and the pages that link to it. Or "overview" (the living synthesis of the whole knowledge base), or "log" (the latest entries of the operation log, newest first: what was done to the knowledge base, and when).', { page: z.string().describe('The page id, "overview" or "log"') }, async (args) => attempt(async () => {
         if (args.page === OVERVIEW)
             return (await store.overview()) || "There's no overview yet: write it with knowledge_rewrite (page \"overview\").";
+        if (args.page === LOG) {
+            if (!store.recentLog)
+                return "This knowledge base's store can't show its log.";
+            const entries = await store.recentLog(10);
+            return entries.length ? entries.join("\n\n") : "The log is empty: nothing has been logged yet.";
+        }
         const page = await store.read(args.page);
         if (!page)
             throw new Error(`There's no page "${args.page}". knowledge_search or knowledge_index finds the right one.`);

package/dist/core/tools/saveToSources.js

@@ -46,8 +46,6 @@ const DEFAULT_DESCRIPTION = "Copy a file from this run's own folder (e.g. someth
     "downloading a document you're about to study in depth, so later sessions have it too.";
 /** The most `download_to_sources` and `request_file` copy in. */
 export const MAX_SOURCE_BYTES = 50 * 1024 * 1024;
-const ok = (text) => ({ content: [{ type: "text", text }] });
-const fail = (text) => ({ content: [{ type: "text", text }], isError: true });
 const message = (error) => (error instanceof Error ? error.message : String(error));
 function added(result, extra = "") {
     return result.duplicateOf
@@ -116,6 +114,20 @@ export async function downloadToFile(url, file, maxBytes) {
 export function createSaveToSourcesServer(runDir, sourcesDir, description = DEFAULT_DESCRIPTION, options = {}) {
     const projectDir = options.projectDir ?? path.dirname(sourcesDir);
     const maxBytes = options.maxBytes ?? MAX_SOURCE_BYTES;
+    // The texts say "sources/"; the model reads the folder's real name (e.g. "treasure/"),
+    // since it reads and searches the originals by that path. Paths it gives may start with
+    // either.
+    const folder = `${path.relative(projectDir, sourcesDir).split(path.sep).join("/") || "."}/`;
+    const named = (text) => text.replaceAll("sources/", folder);
+    const inFolder = (relative) => {
+        const clean = relative.replace(/\\/g, "/").replace(/^\.\//, "");
+        for (const prefix of [folder, "sources/"])
+            if (clean.startsWith(prefix))
+                return clean.slice(prefix.length);
+        return clean;
+    };
+    const ok = (text) => ({ content: [{ type: "text", text: named(text) }] });
+    const fail = (text) => ({ content: [{ type: "text", text: named(text) }], isError: true });
     const replaces = z.string().optional().describe("For a new version: the original it replaces, relative to sources/ (kept, never overwritten)");
     const saveToSources = tool("save_to_sources", description, {
         source: z.string().describe("Path to the file, relative to this run's own folder - not a URL"),
@@ -131,7 +143,7 @@ export function createSaveToSourcesServer(runDir, sourcesDir, description = DEFA
         }
         try {
             const relative = path.relative(runDir, resolvedSource).split(path.sep).join("/");
-            return ok(added(await addSource(sourcesDir, resolvedSource, args.destination, { kind: "run", from: relative }, { replaces: args.replaces })));
+            return ok(added(await addSource(sourcesDir, resolvedSource, inFolder(args.destination), { kind: "run", from: relative }, { replaces: args.replaces && inFolder(args.replaces) })));
         }
         catch (error) {
             return fail(message(error));
@@ -150,7 +162,7 @@ export function createSaveToSourcesServer(runDir, sourcesDir, description = DEFA
         from: z.number().int().positive().optional().describe("First slide (PPTX)"),
         to: z.number().int().positive().optional().describe("Last slide (PPTX)"),
     }, async (args) => {
-        const file = resolveWithin(sourcesDir, args.source);
+        const file = resolveWithin(sourcesDir, inFolder(args.source));
         if (!file || !(await stat(file).catch(() => null))?.isFile())
             return fail(`"${args.source}" isn't an original in sources/ (list_sources lists them).`);
         if (!EXTRACTABLE.has(path.extname(file).slice(1).toLowerCase()))
@@ -171,7 +183,7 @@ export function createSaveToSourcesServer(runDir, sourcesDir, description = DEFA
         try {
             const type = await downloadToFile(args.url, temp, maxBytes);
             const name = decodeURIComponent(new URL(args.url).pathname.split("/").filter(Boolean).pop() ?? "download");
-            const result = await addSource(sourcesDir, temp, args.destination, { kind: "url", from: args.url }, { replaces: args.replaces, name });
+            const result = await addSource(sourcesDir, temp, inFolder(args.destination), { kind: "url", from: args.url }, { replaces: args.replaces && inFolder(args.replaces), name });
             let extra = "";
             if (!result.duplicateOf && /html/i.test(type)) {
                 const html = await readFile(temp, "utf8");
@@ -217,7 +229,7 @@ export function createSaveToSourcesServer(runDir, sourcesDir, description = DEFA
         if (info.size > maxBytes)
             return fail(`"${answer}" is ${info.size} bytes, over the ${maxBytes}-byte limit.`);
         try {
-            return ok(added(await addSource(sourcesDir, file, args.destination ?? path.basename(file), { kind: "person", from: path.basename(file) }, { replaces: args.replaces })));
+            return ok(added(await addSource(sourcesDir, file, args.destination ? inFolder(args.destination) : path.basename(file), { kind: "person", from: path.basename(file) }, { replaces: args.replaces && inFolder(args.replaces) })));
         }
         catch (error) {
             return fail(message(error));
@@ -229,11 +241,11 @@ export function createSaveToSourcesServer(runDir, sourcesDir, description = DEFA
         reason: z.string().describe("Why, in one sentence, in the person's language"),
         replacedBy: z.string().optional().describe('For "replaced": the original that replaces it, relative to sources/'),
     }, async (args) => {
-        const answer = await askForDecision(runDir, { title: t().retireTitle, lines: t().retireLines(args.source, args.why, args.reason, args.replacedBy) });
+        const answer = await askForDecision(runDir, { title: t().retireTitle, lines: t().retireLines(inFolder(args.source), args.why, args.reason, args.replacedBy && inFolder(args.replacedBy), folder) });
         if (answer !== "" && answer !== "y" && answer !== "yes")
             return ok(answer === "q" ? "The person stopped: don't retire it, and stop what you were doing." : "The person said no: the original stays.");
         try {
-            const result = await retireSource(sourcesDir, options.knowledgeDir, projectDir, args.source, args.why, args.reason, args.replacedBy);
+            const result = await retireSource(sourcesDir, options.knowledgeDir, projectDir, inFolder(args.source), args.why, args.reason, args.replacedBy && inFolder(args.replacedBy));
             const pages = result.summaries.map((s) => `${s.page} marked ${s.marked}${s.supersededBy ? ` (see ${s.supersededBy})` : ""}`);
             return ok([
                 `Retired: moved to sources/${result.movedTo}.`,
@@ -245,9 +257,11 @@ export function createSaveToSourcesServer(runDir, sourcesDir, description = DEFA
             return fail(message(error));
         }
     });
-    return createSdkMcpServer({
-        name: "sourceFiles",
-        version: "1.0.0",
-        tools: [saveToSources, listSourcesTool, extractTextTool, downloadToSources, ...(options.interactive ? [requestFile, retire] : [])],
-    });
+    // The descriptions (the tool's and its parameters') with the folder's real name too.
+    const tools = [saveToSources, listSourcesTool, extractTextTool, downloadToSources, ...(options.interactive ? [requestFile, retire] : [])].map((definition) => ({
+        ...definition,
+        description: named(definition.description),
+        inputSchema: Object.fromEntries(Object.entries(definition.inputSchema).map(([key, schema]) => [key, schema.description ? schema.describe(named(schema.description)) : schema])),
+    }));
+    return createSdkMcpServer({ name: "sourceFiles", version: "1.0.0", tools: tools });
 }

package/dist/core/version.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The version of agent-kit in use, read from its own `package.json` (next to `dist/`, or
+ * `src/` under tsx), e.g. to show it in an agent's header or log.
+ */
+export declare function agentKitVersion(): string;

package/dist/core/version.js

@@ -0,0 +1,12 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+let cached;
+/**
+ * The version of agent-kit in use, read from its own `package.json` (next to `dist/`, or
+ * `src/` under tsx), e.g. to show it in an agent's header or log.
+ */
+export function agentKitVersion() {
+    cached ??= JSON.parse(readFileSync(path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json"), "utf8")).version;
+    return cached;
+}

package/dist/index.d.ts

@@ -6,10 +6,11 @@ export { createPromptLoader } from "./core/promptTemplate.js";
 export { resolveClaudeAuth, type ClaudeAuthConfig } from "./core/claudeAuth.js";
 export { ensureClaudeAuth } from "./tui/claudeAuth.js";
 export { createFriendlyToolLabel, truncate, truncatePath, type ToolDescriber, } from "./core/toolLabels.js";
-export type { Mode, BaseSessionConfig, AgentSpec, PlanModeSpec } from "./core/agentSpec.js";
+export type { Mode, BaseSessionConfig, AgentSpec, AgentIdentity, PlanModeSpec } from "./core/agentSpec.js";
 export { buildSessionOptions, createInputQueue, createDeferred, createModeControl, togglePlanMode, type ModeControl } from "./core/session.js";
 export { runQuery, type AgentEvent, type AgentRun, type SessionUsage, type ContextUsage } from "./core/runner.js";
 export { knowledgePluginRoot, knowledgePromptSection } from "./core/knowledge.js";
+export { agentKitVersion } from "./core/version.js";
 export { BUILT_IN_PAGE_TYPES, isSlug, parseId, linkedIds, type KnowledgeStore, type PageType, type KnowledgePage, type PageInfo, type SearchHit, type CheckReport, type FieldChanges, type NewPage, } from "./core/knowledgeStore.js";
 export { createFileKnowledgeStore, type FileKnowledgeStoreOptions } from "./core/fileKnowledgeStore.js";
 export { createKnowledgeServer, type KnowledgeToolsOptions } from "./core/tools/knowledgeTools.js";

package/dist/index.js

@@ -11,6 +11,7 @@ export { createFriendlyToolLabel, truncate, truncatePath, } from "./core/toolLab
 export { buildSessionOptions, createInputQueue, createDeferred, createModeControl, togglePlanMode } from "./core/session.js";
 export { runQuery } from "./core/runner.js";
 export { knowledgePluginRoot, knowledgePromptSection } from "./core/knowledge.js";
+export { agentKitVersion } from "./core/version.js";
 export { BUILT_IN_PAGE_TYPES, isSlug, parseId, linkedIds, } from "./core/knowledgeStore.js";
 export { createFileKnowledgeStore } from "./core/fileKnowledgeStore.js";
 export { createKnowledgeServer } from "./core/tools/knowledgeTools.js";

package/dist/tui/ink/SessionView.d.ts

@@ -19,6 +19,7 @@ export declare function previewLines(lines: readonly string[], terminalRows: num
 export declare function statusText(mode: Mode | undefined, turns: number, usage: SessionUsage | null, extra?: {
     contextPercent?: number | null;
     modeSwitchable?: boolean;
+    width?: number;
 }): string;
 export interface SessionViewProps {
     model: SessionModel;

package/dist/tui/ink/SessionView.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import wrapAnsi from "wrap-ansi";
+import stringWidth from "string-width";
 import { useEffect, useReducer, useRef, useState, useSyncExternalStore } from "react";
 import { Box, measureElement, Static, Text, useInput, useStdout } from "ink";
 import { MultiSelect, Select, TextInput } from "@inkjs/ui";
@@ -86,13 +87,24 @@ function formatTokens(count) {
     return count >= 1000 ? `${(count / 1000).toFixed(1)}k` : String(count);
 }
 export function statusText(mode, turns, usage, extra = {}) {
-    const parts = [
+    const text = (withCached) => statusParts(mode, turns, usage, extra, withCached).join(" · ");
+    const full = text(true);
+    // The cached part goes first when the terminal is too narrow for it.
+    return extra.width !== undefined && stringWidth(full) > extra.width ? text(false) : full;
+}
+function statusParts(mode, turns, usage, extra, withCached) {
+    return [
         ...(mode ? [`⏵⏵ ${t().mode(mode)}${extra.modeSwitchable ? ` (${t().switchModeKey})` : ""}`] : []),
         t().turns(turns),
-        ...(usage ? [t().tokens(formatTokens(usage.inputTokens), formatTokens(usage.outputTokens))] : []),
+        // The new input apart from what was read again from the cache: the total grows with every
+        // call (each one sends the whole context again), which looked like the context growing.
+        ...(usage
+            ? [
+                t().tokens(formatTokens(usage.inputTokens - (usage.cacheReadTokens ?? 0)), formatTokens(usage.outputTokens), withCached && usage.cacheReadTokens ? formatTokens(usage.cacheReadTokens) : undefined),
+            ]
+            : []),
         ...(extra.contextPercent != null ? [t().context(Math.round(extra.contextPercent))] : []),
     ];
-    return parts.join(" · ");
 }
 // No emoji-capable characters: Windows Terminal draws ✳ (U+2733) as a green emoji.
 const WORKING_GLYPHS = ["·", "✢", "✱", "✶", "✻", "✽", "✻", "✶", "✱", "✢"];
@@ -110,7 +122,8 @@ function Working({ label, startedAt, width }) {
 /** Line in progress, checkpoint panel or spinner, the input, and the status bar. */
 function LiveArea({ session, checkpoint, renderApproval, mode, width, statusExtra, modeSwitchable, reservedRows, children }) {
     // The mode in the spinner's color; the rest dim.
-    const plain = statusText(mode, session.turns, session.usage, { contextPercent: session.contextPercent, modeSwitchable }) + (statusExtra ? ` · ${statusExtra}` : "");
+    const extraText = statusExtra ? ` · ${statusExtra}` : "";
+    const plain = statusText(mode, session.turns, session.usage, { contextPercent: session.contextPercent, modeSwitchable, width: width - stringWidth(extraText) }) + extraText;
     const cut = mode ? plain.indexOf(" · ") : -1;
     const status = cut > 0 ? ui.working(plain.slice(0, cut)) + ui.dim(plain.slice(cut)) : ui.dim(plain);
     return (_jsxs(Box, { flexDirection: "column", flexShrink: 0, width: width, marginTop: session.liveGap ? 1 : 0, children: [stripAnsi(session.live) ? _jsx(Text, { children: session.live }) : null, checkpoint ? (_jsx(CheckpointPanel, { checkpoint: checkpoint, renderApproval: renderApproval, reservedRows: reservedRows, width: width })) : session.busy ? (

package/dist/tui/ink/runChatInk.d.ts

@@ -74,6 +74,13 @@ export interface InkChatOptions extends ChatTuiOptions {
      */
     firstPromptSuggestion?: string;
 }
+/** The chat's own commands, never sent to the model (the agent-help skill lists them; a test keeps both in step). */
+export declare const DEFAULT_EXIT_COMMANDS: readonly string[];
+export declare const LOCAL_COMMANDS: {
+    readonly copy: "/copy";
+    readonly resume: "/resume";
+    readonly plan: "/plan";
+};
 /** A choice asked in place of the prompt (the /resume list). */
 export interface ChatPicker {
     title: string;

package/dist/tui/ink/runChatInk.js

@@ -27,7 +27,9 @@ import { createTerminalStatus, focusFromReport } from "./terminalStatus.js";
 import { listProjectFiles } from "./fileMentions.js";
 import { headerLines } from "./header.js";
 const DEFAULT_PROMPT_LABEL = "\n> ";
-const DEFAULT_EXIT_COMMANDS = ["/exit", "/quit"];
+/** The chat's own commands, never sent to the model (the agent-help skill lists them; a test keeps both in step). */
+export const DEFAULT_EXIT_COMMANDS = ["/exit", "/quit"];
+export const LOCAL_COMMANDS = { copy: "/copy", resume: "/resume", plan: "/plan" };
 const DEFAULT_HISTORY_LIMIT = 100;
 // The prompt's frame: a border and one column of padding on each side.
 const PROMPT_FRAME_COLUMNS = 4;
@@ -382,19 +384,19 @@ export async function runChatInk(options, tuiOptions = {}) {
             if (exitCommands.has(line.toLowerCase()))
                 break;
             // A local command, never sent to the model: the last reply to the clipboard (OSC 52).
-            if (status && line.toLowerCase() === "/copy") {
+            if (status && line.toLowerCase() === LOCAL_COMMANDS.copy) {
                 const reply = model.lastReply();
                 if (reply)
                     stdout.write(clipboardSequence(reply));
                 model.writeLine(ui.dim(reply ? t().copiedReply(reply.length) : t().nothingToCopy));
                 continue;
             }
-            if (runsDir && line.toLowerCase() === "/resume") {
+            if (runsDir && line.toLowerCase() === LOCAL_COMMANDS.resume) {
                 await resume();
                 continue;
             }
             // A local command too: into plan mode, or back to the mode it was entered from.
-            if (line.toLowerCase() === "/plan") {
+            if (line.toLowerCase() === LOCAL_COMMANDS.plan) {
                 const control = modeControl();
                 const next = control ? togglePlanMode(control) : null;
                 if (next)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falkenslab/agent-kit",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Library for building an agent on top of the Claude Agent SDK",
   "author": "Francisco Vargas Ruiz",
   "license": "MIT",