@falkenslab/agent-kit 0.16.1 → 0.17.0

package/README.md

@@ -38,11 +38,11 @@ A foundation for building AI agents on top of the [Claude Agent SDK](https://www
 
 See [everything he can do](https://falkenslab.github.io/agent-kit/docs/next/examples/captain-whiskers#what-he-can-do), with screenshots.
 
-### teacher-agent
+### miyagi
 
-[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](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; teacher-agent brings what it knows about Moodle and driving the browser.
+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/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/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",

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;

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",

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",

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",

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
@@ -170,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 })),
             }
             : {}),
@@ -259,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/index.d.ts

@@ -6,7 +6,7 @@ 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";

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.1",
+  "version": "0.17.0",
   "description": "Library for building an agent on top of the Claude Agent SDK",
   "author": "Francisco Vargas Ruiz",
   "license": "MIT",