@falkenslab/agent-kit 0.18.0 → 0.20.0

package/dist/core/messages/fr.js

@@ -22,6 +22,18 @@ export const fr = {
     resumeHint: "↑/↓ choisir · Entrée reprendre · Échap annuler",
     resumeQuestion: "Numéro de la conversation à reprendre (Entrée pour annuler) : ",
     noEarlierRuns: "(aucune conversation précédente à reprendre)",
+    commandResume: "Choisir une conversation précédente pour la reprendre",
+    commandPlan: "Passer en mode plan, ou revenir",
+    commandExtensions: "Ce qui tourne, ce qui est éteint et pourquoi ; en activer ou désactiver une",
+    extensionsRunning: (names) => `En service : ${names}`,
+    extensionsNone: "(aucune extension)",
+    extensionOff: (name, reason) => `${name} est désactivée : ${reason}`,
+    extensionsInstalled: "Installées :",
+    extensionSwitched: (name, enabled) => `(${name} ${enabled ? "activée" : "désactivée"}, dans cette même session)`,
+    extensionToggled: (name, enabled) => `(${name} ${enabled ? "activée" : "désactivée"} : la session se rouvre, avec la même conversation)`,
+    extensionNotInstalled: (name) => `(${name} n'est pas installée : /extensions les liste)`,
+    extensionsUsage: "(usage : /extensions, /extensions enable <nom>, /extensions disable <nom>)",
+    extensionsCantReopen: "(ce chat ne peut pas rouvrir sa session : activez-la ou désactivez-la depuis le terminal, puis recommencez)",
     currentRun: "(celle-ci)",
     resumed: (date) => `(conversation du ${date} reprise)`,
     suggestionKey: "tab",
@@ -91,22 +103,6 @@ export const fr = {
         Task: ["a lancé {n} sous-agent", "a lancé {n} sous-agents"],
         mcp__time__current_time: ["a consulté l'heure", "a consulté l'heure {n} fois"],
         mcp__time__date_math: ["a calculé des dates", "a calculé des dates {n} fois"],
-        mcp__sourceFiles__list_sources: ["a examiné les sources", "a examiné les sources {n} fois"],
-        mcp__sourceFiles__extract_text: ["a lu {n} document", "a lu {n} documents"],
-        mcp__sourceFiles__save_to_sources: ["a enregistré {n} source", "a enregistré {n} sources"],
-        mcp__sourceFiles__download_to_sources: ["a téléchargé {n} source", "a téléchargé {n} sources"],
-        mcp__sourceFiles__request_file: ["a demandé {n} fichier", "a demandé {n} fichiers"],
-        mcp__sourceFiles__retire_source: ["a retiré {n} source", "a retiré {n} sources"],
-        mcp__knowledge__knowledge_index: ["a lu l'index", "a lu l'index {n} fois"],
-        mcp__knowledge__knowledge_search: ["a cherché dans la base", "a cherché dans la base {n} fois"],
-        mcp__knowledge__knowledge_read: ["a lu {n} page", "a lu {n} pages"],
-        mcp__knowledge__knowledge_create: ["a créé {n} page", "a créé {n} pages"],
-        mcp__knowledge__knowledge_edit: ["a modifié {n} page", "a modifié {n} pages"],
-        mcp__knowledge__knowledge_rewrite: ["a réécrit {n} page", "a réécrit {n} pages"],
-        mcp__knowledge__knowledge_supersede: ["a remplacé {n} page", "a remplacé {n} pages"],
-        mcp__knowledge__knowledge_retire: ["a retiré {n} page", "a retiré {n} pages"],
-        mcp__knowledge__knowledge_log: ["a mis à jour le journal", "a mis à jour le journal {n} fois"],
-        mcp__knowledge__knowledge_check: ["a vérifié la base", "a vérifié la base {n} fois"],
         mcp__approvals__ask_human: ["a posé {n} question", "a posé {n} questions"],
         mcp__approvals__present_plan: ["a présenté le plan", "a présenté le plan {n} fois"],
     },
@@ -120,7 +116,6 @@ export const fr = {
     labels: {
         askingApproval: (summary) => `Demande d'approbation humaine : ${summary}`,
         waitingManual: "En attente d'une intervention manuelle",
-        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}`,
@@ -139,21 +134,6 @@ export const fr = {
         applyingSkill: (skill) => `Application de la skill "${skill}"`,
         aSkill: "une skill",
         updatingTasks: "Mise à jour de la liste des tâches",
-        listingSources: "Examen des sources",
-        extractingText: (source) => `Lecture de ${source}`,
-        downloading: (url) => `Téléchargement de ${url} dans les sources`,
-        requestingFile: (description) => `Demande d'un fichier : ${description}`,
-        retiringSource: (source) => `Retrait de la source ${source}`,
-        knowledgeIndex: "Lecture de l'index de la base de connaissances",
-        knowledgeSearch: (query) => `Recherche de "${query}" dans la base de connaissances`,
-        knowledgeRead: (page) => `Lecture de ${page}`,
-        knowledgeCreate: (page) => `Création de ${page}`,
-        knowledgeEdit: (page) => `Modification de ${page}`,
-        knowledgeRewrite: (page) => `Réécriture de ${page}`,
-        knowledgeSupersede: (page) => `${page} marquée comme remplacée`,
-        knowledgeRetire: (page) => `Retrait de ${page}`,
-        knowledgeLog: "Mise à jour du journal de la base de connaissances",
-        knowledgeCheck: "Vérification de la base de connaissances",
         askingHuman: (question) => `Question : ${question}`,
         presentingPlan: "Présentation du plan",
     },

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

@@ -17,6 +17,12 @@ export declare function getLanguage(): Language;
  * once per process.
  */
 export declare function chooseLanguage(option?: string): Language;
+/**
+ * Switches the kit's language on purpose, e.g. the person picked another in a chat (#47): from
+ * then on it wins over `--language` and `config.language`, until switched again. The session
+ * says so to the model when it opens next (the controller's `setLanguage()` reopens it).
+ */
+export declare function switchLanguage(language: Language): void;
 /** Warnings about unsupported language codes not shown yet (English, one line each). */
 export declare function takeLanguageWarnings(): string[];
 /** The kit's texts in the current language. */

package/dist/core/messages/index.js

@@ -23,6 +23,8 @@ export function withEnglishFallback(own) {
 let current = "en";
 let messages = en;
 let chosen = false;
+// A language switched to on purpose (switchLanguage()): kept over --language and options.
+let switched = false;
 let pendingWarnings = [];
 const warned = new Set();
 /** Sets the language of the kit's texts directly (a host that resolved it itself, tests). */
@@ -43,7 +45,7 @@ export function getLanguage() {
  * once per process.
  */
 export function chooseLanguage(option) {
-    if (chosen && option === undefined)
+    if (switched || (chosen && option === undefined))
         return current;
     const resolved = detectLanguage(option);
     for (const warning of resolved.warnings) {
@@ -55,6 +57,15 @@ export function chooseLanguage(option) {
     setLanguage(resolved.language);
     return current;
 }
+/**
+ * Switches the kit's language on purpose, e.g. the person picked another in a chat (#47): from
+ * then on it wins over `--language` and `config.language`, until switched again. The session
+ * says so to the model when it opens next (the controller's `setLanguage()` reopens it).
+ */
+export function switchLanguage(language) {
+    setLanguage(language);
+    switched = true;
+}
 /** Warnings about unsupported language codes not shown yet (English, one line each). */
 export function takeLanguageWarnings() {
     const taken = pendingWarnings;

package/dist/core/packaged.d.ts

@@ -0,0 +1,10 @@
+/** A path inside `…/app.asar/…`, as the unpacked copy next to it (`…/app.asar.unpacked/…`); any other path as it is. */
+export declare function outsideArchive(file: string): string;
+/**
+ * The SDK's CLI binary unpacked next to the archive, when the kit runs packaged: the SDK would
+ * resolve it inside `app.asar`, where it can't be executed, and its first turn would hang with
+ * no error (confirmed empirically). Looked up as the SDK does (`@anthropic-ai/claude-agent-sdk-
+ * <platform>-<arch>`, either libc on Linux), with `resolve` replaceable for tests. `undefined`
+ * when not packaged, or when the build didn't unpack it: then the SDK finds its own.
+ */
+export declare function unpackedClaudeExecutable(resolve?: (request: string) => string, platform?: NodeJS.Platform, arch?: string): string | undefined;

package/dist/core/packaged.js

@@ -0,0 +1,38 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+/**
+ * Running packaged in an archive (Electron's `app.asar`, ADR-026, #42). Electron reads files
+ * inside the archive for its own process, but another process can't: not the Claude Code CLI
+ * reading a plugin, not the binary itself. So every path the kit hands to another process goes
+ * through `outsideArchive()`, which points it at the copy the build unpacked (`asarUnpack`).
+ */
+const ARCHIVE = /([\\/])app\.asar([\\/])/;
+/** A path inside `…/app.asar/…`, as the unpacked copy next to it (`…/app.asar.unpacked/…`); any other path as it is. */
+export function outsideArchive(file) {
+    return file.replace(ARCHIVE, "$1app.asar.unpacked$2");
+}
+/**
+ * The SDK's CLI binary unpacked next to the archive, when the kit runs packaged: the SDK would
+ * resolve it inside `app.asar`, where it can't be executed, and its first turn would hang with
+ * no error (confirmed empirically). Looked up as the SDK does (`@anthropic-ai/claude-agent-sdk-
+ * <platform>-<arch>`, either libc on Linux), with `resolve` replaceable for tests. `undefined`
+ * when not packaged, or when the build didn't unpack it: then the SDK finds its own.
+ */
+export function unpackedClaudeExecutable(resolve = createRequire(import.meta.url).resolve, platform = process.platform, arch = process.arch) {
+    const packages = platform === "linux" ? [`linux-${arch}`, `linux-${arch}-musl`] : [`${platform}-${arch}`];
+    for (const suffix of packages) {
+        let file;
+        try {
+            file = resolve(`@anthropic-ai/claude-agent-sdk-${suffix}/claude${platform === "win32" ? ".exe" : ""}`);
+        }
+        catch {
+            continue;
+        }
+        if (!ARCHIVE.test(file))
+            return undefined;
+        const unpacked = outsideArchive(file);
+        if (existsSync(unpacked))
+            return unpacked;
+    }
+    return undefined;
+}

package/dist/core/pluginAgents.d.ts

@@ -0,0 +1,20 @@
+import type { AgentDefinition } from "@anthropic-ai/claude-agent-sdk";
+/**
+ * A plugin's subagents (`agents/<file>.md`, ADR-025), read so the session registers them as it
+ * does an agent's own from `buildSubagents()`: in the type gate's allow-list, in the `Agent` and
+ * `Bash` decision, and with the reply-language line. The SDK loads them itself as
+ * `<plugin>:<name>`, the name from the frontmatter, not the file (confirmed empirically); a
+ * definition under that same key in `options.agents` replaces the plugin's (also confirmed), which
+ * is how the kit adds the line.
+ */
+/** A markdown file's frontmatter: `key: value`, with `[a, b]`, `a, b` or a YAML list for lists. */
+export declare function frontmatter(text: string): {
+    fields: Record<string, string | string[]>;
+    body: string;
+};
+/**
+ * The subagents of the plugins in `roots`, by the name the SDK gives them (`<plugin>:<name>`):
+ * `description` and the body as the prompt, `tools` (none listed: it inherits the session's),
+ * `model` and `maxTurns` when given.
+ */
+export declare function pluginAgents(roots: readonly string[]): Promise<Record<string, AgentDefinition>>;

package/dist/core/pluginAgents.js

@@ -0,0 +1,76 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+/**
+ * A plugin's subagents (`agents/<file>.md`, ADR-025), read so the session registers them as it
+ * does an agent's own from `buildSubagents()`: in the type gate's allow-list, in the `Agent` and
+ * `Bash` decision, and with the reply-language line. The SDK loads them itself as
+ * `<plugin>:<name>`, the name from the frontmatter, not the file (confirmed empirically); a
+ * definition under that same key in `options.agents` replaces the plugin's (also confirmed), which
+ * is how the kit adds the line.
+ */
+/** A markdown file's frontmatter: `key: value`, with `[a, b]`, `a, b` or a YAML list for lists. */
+export function frontmatter(text) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text);
+    if (!match)
+        return { fields: {}, body: text };
+    const fields = {};
+    const lines = match[1].split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const kv = /^([A-Za-z_][\w-]*):\s*(.*)$/.exec(lines[i]);
+        if (!kv)
+            continue;
+        const [, key, raw] = kv;
+        if (raw === "") {
+            const items = [];
+            while (i + 1 < lines.length && /^\s+-\s/.test(lines[i + 1]))
+                items.push(lines[++i].replace(/^\s+-\s*/, ""));
+            fields[key] = items.map(unquote);
+        }
+        else if (/^\[.*\]$/.test(raw)) {
+            fields[key] = raw.slice(1, -1).split(",").map(unquote).filter(Boolean);
+        }
+        else {
+            fields[key] = unquote(raw);
+        }
+    }
+    return { fields, body: text.slice(match[0].length).trim() };
+}
+const unquote = (value) => value.trim().replace(/^["']|["']$/g, "");
+/** A field as a list: a list as is, `a, b` split on commas. */
+function list(value) {
+    if (value === undefined)
+        return undefined;
+    return Array.isArray(value) ? value : value.split(",").map(unquote).filter(Boolean);
+}
+/**
+ * The subagents of the plugins in `roots`, by the name the SDK gives them (`<plugin>:<name>`):
+ * `description` and the body as the prompt, `tools` (none listed: it inherits the session's),
+ * `model` and `maxTurns` when given.
+ */
+export async function pluginAgents(roots) {
+    const agents = {};
+    for (const root of roots) {
+        let plugin;
+        try {
+            plugin = JSON.parse(await readFile(path.join(root, ".claude-plugin", "plugin.json"), "utf8")).name;
+        }
+        catch {
+            continue;
+        }
+        const files = await readdir(path.join(root, "agents")).catch(() => []);
+        for (const file of files.filter((name) => name.endsWith(".md"))) {
+            const { fields, body } = frontmatter(await readFile(path.join(root, "agents", file), "utf8"));
+            const name = typeof fields.name === "string" && fields.name ? fields.name : file.replace(/\.md$/, "");
+            const tools = list(fields.tools);
+            const maxTurns = typeof fields.maxTurns === "string" ? Number(fields.maxTurns) : undefined;
+            agents[`${plugin}:${name}`] = {
+                description: typeof fields.description === "string" ? fields.description : "",
+                prompt: body,
+                ...(tools ? { tools } : {}),
+                ...(typeof fields.model === "string" ? { model: fields.model } : {}),
+                ...(maxTurns && Number.isFinite(maxTurns) ? { maxTurns } : {}),
+            };
+        }
+    }
+    return agents;
+}

package/dist/core/pluginDownloads.d.ts

@@ -0,0 +1,14 @@
+/** The regular files of a tar archive, by path (ustar, with pax and GNU long names). */
+export declare function untar(tar: Uint8Array): Map<string, Uint8Array>;
+/** The highest of `versions` that `wanted` asks for: an exact version, or a range (`^`, `~`, comparators, `*`). */
+export declare function pickVersion(versions: readonly string[], wanted: string): string | undefined;
+/** An npm package into a new temporary folder: `{ dir, version }`. */
+export declare function fetchNpmPlugin(name: string, wanted?: string, registry?: string): Promise<{
+    dir: string;
+    version: string;
+}>;
+/** A zip archive into a new temporary folder; the plugin is its root, or its only folder. */
+export declare function fetchArchivePlugin(url: string, sha256?: string): Promise<{
+    dir: string;
+    root: string;
+}>;

package/dist/core/pluginDownloads.js

@@ -0,0 +1,141 @@
+import { createHash } from "node:crypto";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { inKitRange } from "./externalExtensions.js";
+async function fflate() {
+    try {
+        return (await import("fflate"));
+    }
+    catch (error) {
+        throw new Error('Installing from an npm or archive source needs the optional "fflate" library: npm install fflate', { cause: error });
+    }
+}
+async function download(url) {
+    if (!url.startsWith("https://"))
+        throw new Error(`Only https downloads: ${url}.`);
+    const response = await fetch(url);
+    if (!response.ok)
+        throw new Error(`${url} answered ${response.status}.`);
+    return new Uint8Array(await response.arrayBuffer());
+}
+/** Files into `dir`, each at its relative path; one that would land outside it is refused. */
+async function writeFiles(dir, files) {
+    const root = path.resolve(dir);
+    for (const [name, data] of files) {
+        const target = path.resolve(root, name);
+        if (!target.startsWith(`${root}${path.sep}`) || name.split(/[\\/]/).includes(".."))
+            throw new Error(`The download has a file outside its folder: ${name}.`);
+        await mkdir(path.dirname(target), { recursive: true });
+        await writeFile(target, data);
+    }
+}
+/** The regular files of a tar archive, by path (ustar, with pax and GNU long names). */
+export function untar(tar) {
+    const files = new Map();
+    const text = (from, length) => new TextDecoder().decode(tar.subarray(from, from + length)).replace(/\0.*$/s, "");
+    let offset = 0;
+    let longName;
+    while (offset + 512 <= tar.length) {
+        const name = text(offset, 100);
+        if (!name)
+            break; // the two empty blocks at the end
+        const size = parseInt(text(offset + 124, 12).trim() || "0", 8);
+        const type = text(offset + 156, 1);
+        const prefix = text(offset + 345, 155);
+        const body = tar.subarray(offset + 512, offset + 512 + size);
+        if (type === "x") {
+            longName = /(?:^|\n)\d+ path=([^\n]*)\n/.exec(new TextDecoder().decode(body))?.[1] ?? longName;
+        }
+        else if (type === "L") {
+            longName = new TextDecoder().decode(body).replace(/\0.*$/s, "");
+        }
+        else {
+            if (type === "0" || type === "" || type === "7")
+                files.set(longName ?? (prefix ? `${prefix}/${name}` : name), body);
+            longName = undefined;
+        }
+        offset += 512 + Math.ceil(size / 512) * 512;
+    }
+    return files;
+}
+/** The highest of `versions` that `wanted` asks for: an exact version, or a range (`^`, `~`, comparators, `*`). */
+export function pickVersion(versions, wanted) {
+    const range = wanted.trim();
+    if (versions.includes(range))
+        return range;
+    const comparators = range.split(/\s+/).flatMap((part) => {
+        if (part === "*" || part === "x" || part === "")
+            return [];
+        const caret = /^\^(\d+)\.(\d+)\.(\d+)$/.exec(part);
+        if (caret) {
+            const [major, minor, patch] = caret.slice(1).map(Number);
+            const upper = major > 0 ? `${major + 1}.0.0` : minor > 0 ? `0.${minor + 1}.0` : `0.0.${patch + 1}`;
+            return [`>=${major}.${minor}.${patch}`, `<${upper}`];
+        }
+        const tilde = /^~(\d+)\.(\d+)\.(\d+)$/.exec(part);
+        if (tilde)
+            return [`>=${tilde[1]}.${tilde[2]}.${tilde[3]}`, `<${tilde[1]}.${Number(tilde[2]) + 1}.0`];
+        return [part];
+    });
+    const stable = versions.filter((version) => /^\d+\.\d+\.\d+$/.test(version));
+    const matching = stable.filter((version) => !comparators.length || inKitRange(version, comparators.join(" ")));
+    const order = (version) => version.split(".").map(Number);
+    return matching.sort((a, b) => {
+        const [x, y] = [order(a), order(b)];
+        for (let i = 0; i < 3; i++)
+            if (x[i] !== y[i])
+                return x[i] - y[i];
+        return 0;
+    }).at(-1);
+}
+/** An npm package into a new temporary folder: `{ dir, version }`. */
+export async function fetchNpmPlugin(name, wanted = "latest", registry = "https://registry.npmjs.org") {
+    if (!/^(@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*$/i.test(name))
+        throw new Error(`"${name}" isn't an npm package name.`);
+    const response = await fetch(`${registry.replace(/\/+$/, "")}/${name.replace("/", "%2f")}`, { headers: { accept: "application/json" } });
+    if (!response.ok)
+        throw new Error(`The registry has no package ${name} (${response.status}).`);
+    const metadata = (await response.json());
+    const version = metadata["dist-tags"]?.[wanted] ?? pickVersion(Object.keys(metadata.versions ?? {}), wanted);
+    const dist = version ? metadata.versions?.[version]?.dist : undefined;
+    if (!version || !dist?.tarball)
+        throw new Error(`${name} has no version ${wanted}.`);
+    const tarball = await download(dist.tarball);
+    const sri = /^sha512-(.+)$/.exec(dist.integrity ?? "");
+    if (!sri)
+        throw new Error(`${name}@${version} has no sha512 integrity to check it against.`);
+    if (createHash("sha512").update(tarball).digest("base64") !== sri[1])
+        throw new Error(`${name}@${version}'s download doesn't match its integrity.`);
+    const { gunzipSync } = await fflate();
+    const dir = await mkdtemp(path.join(os.tmpdir(), "agent-kit-npm-"));
+    try {
+        // npm puts a package's files under package/.
+        const files = [...untar(gunzipSync(tarball))].flatMap(([file, data]) => (file.startsWith("package/") ? [[file.slice("package/".length), data]] : []));
+        await writeFiles(dir, files);
+        return { dir, version };
+    }
+    catch (error) {
+        await rm(dir, { recursive: true, force: true });
+        throw error;
+    }
+}
+/** A zip archive into a new temporary folder; the plugin is its root, or its only folder. */
+export async function fetchArchivePlugin(url, sha256) {
+    const zip = await download(url);
+    if (sha256 && createHash("sha256").update(zip).digest("hex") !== sha256.toLowerCase())
+        throw new Error(`${url} doesn't match its sha256.`);
+    const { unzipSync } = await fflate();
+    const files = Object.entries(unzipSync(zip)).filter(([name]) => !name.endsWith("/"));
+    const dir = await mkdtemp(path.join(os.tmpdir(), "agent-kit-archive-"));
+    try {
+        await writeFiles(dir, files);
+        const tops = new Set(files.map(([name]) => name.split("/")[0]));
+        const only = tops.size === 1 && files.every(([name]) => name.includes("/")) ? [...tops][0] : "";
+        return { dir, root: path.join(dir, only) };
+    }
+    catch (error) {
+        await rm(dir, { recursive: true, force: true });
+        throw error;
+    }
+}

package/dist/core/runner.js

@@ -1,4 +1,5 @@
 import { query } from "@anthropic-ai/claude-agent-sdk";
+import { sessionViewOf } from "./sessionFacts.js";
 /**
  * A turn's errors without the CLI's internal diagnostics: an interrupted turn ends with
  * one like "[ede_diagnostic] result_type=user ... stop_reason=tool_use" (seen on Esc),
@@ -27,11 +28,21 @@ export function toolResultText(content) {
  */
 export function runQuery(prompt, options) {
     const result = query({ prompt, options });
+    // What the session is, for an extension that asks (sessionFacts.ts): the controls now, the
+    // tools and skills when the session starts.
+    const view = sessionViewOf(options);
+    view?.attach({
+        supportedCommands: () => result.supportedCommands(),
+        contextUsage: () => contextUsage(),
+        toggleMcpServer: (server, enabled) => result.toggleMcpServer(server, enabled),
+        reloadPlugins: () => result.reloadPlugins(),
+    });
     // The main agent's tool calls by id, to name the results that come back for them.
     const toolNames = new Map();
     async function* generateEvents() {
         for await (const message of result) {
             if (message.type === "system" && message.subtype === "init") {
+                view?.attach({ tools: message.tools, skills: message.skills });
                 const failedServers = message.mcp_servers.filter((s) => s.status === "failed").map((s) => s.name);
                 if (failedServers.length > 0)
                     yield { type: "mcp-error", failedServers };
@@ -103,14 +114,15 @@ export function runQuery(prompt, options) {
         interrupt: () => result.interrupt(),
         close: () => result.close(),
         supportedCommands: () => result.supportedCommands(),
-        contextUsage: async () => {
-            try {
-                const usage = await result.getContextUsage();
-                return { percentage: usage.percentage, totalTokens: usage.totalTokens, maxTokens: usage.maxTokens };
-            }
-            catch {
-                return null;
-            }
-        },
+        contextUsage,
     };
+    async function contextUsage() {
+        try {
+            const usage = await result.getContextUsage();
+            return { percentage: usage.percentage, totalTokens: usage.totalTokens, maxTokens: usage.maxTokens };
+        }
+        catch {
+            return null;
+        }
+    }
 }

package/dist/core/session.d.ts

@@ -1,10 +1,12 @@
 import type { Options, SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
 import { type TranscriptLogger } from "./hooks/transcriptLogger.js";
 import { type ModeControl } from "./modeControl.js";
-import type { KnowledgeStore } from "./knowledgeStore.js";
+import { type ExtensionDirs, type InstalledExtension } from "./externalExtensions.js";
+import type { ToolLabels } from "./toolLabels.js";
 import type { AgentSpec, BaseSessionConfig } from "./agentSpec.js";
 import { type Language } from "./language.js";
 import { type RunFolder } from "./runs.js";
+import { type ExtensionSwitch } from "./liveExtensions.js";
 /**
  * Builds the `options` object passed to the Agent SDK's `query()` — everything about
  * *how* the agent runs a session (system prompt, tools, MCP servers, hooks), independent
@@ -12,9 +14,10 @@ import { type RunFolder } from "./runs.js";
  * one-shot run or an `AsyncIterable` for a multi-turn chat).
  *
  * Everything actually *about the domain* (which system prompt, which MCP servers besides
- * the generic human-in-the-loop/knowledge ones below, which plugin roots, which
- * subagents) is behind `spec` (see agentSpec.ts) — this function only knows the generic
- * fields on `BaseSessionConfig`.
+ * the generic human-in-the-loop ones below, which plugin roots, which subagents) is behind
+ * `spec` (see agentSpec.ts), and the kit's optional parts (the knowledge base, the sources
+ * folder) are extensions whose contributions this function puts together (extensions.ts,
+ * ADR-025): it names none of them.
  *
  * The per-mode behavioral differences (whether the approval/manual-intervention tools
  * exist, whether the interactive step gate or the plan gate decides) all fall out of
@@ -33,16 +36,45 @@ export declare function buildSessionOptions<TConfig extends BaseSessionConfig>(c
     transcriptPath: string;
     modeControl: ModeControl;
     language: Language;
-    /** The knowledge base's store, when the agent reaches it through the `knowledge_*` tools. */
-    knowledgeStore?: KnowledgeStore;
+    /** How the chat shows the extensions' tools (`runChatInk()` takes them from a session opener). */
+    toolLabels: ToolLabels;
+    /** The installed extensions and what this session runs with, for `/extensions` (#37). */
+    extensions: ExtensionsStatus;
+    /** What each active extension hands the host (its contribution's `api`), by its name: the sources' `addSource`, the knowledge base's `knowledgeStore`. */
+    apis: Record<string, Record<string, unknown>>;
+    /** Turns an installed extension off or on in the running session; false when that takes opening it again (#49). */
+    switchExtension: ExtensionSwitch;
 }>;
 export { createModeControl, togglePlanMode, type ModeControl } from "./modeControl.js";
+/** The extensions of a session: where they're installed, what's installed, what runs and what can't (with why). */
+export interface ExtensionsStatus {
+    dirs: ExtensionDirs;
+    installed: InstalledExtension[];
+    /** The names of the extensions this session runs with, the kit's and the agent's too. */
+    active: string[];
+    /** What each active one is, from its manifest: for a view that lists them. */
+    about: Record<string, {
+        description: string;
+        provides: string[];
+    }>;
+    inactive: {
+        name: string;
+        reason: string;
+    }[];
+}
 /**
  * The CLI's folder for a project, where it keeps each session's transcript and large tool
  * results (`<session>/tool-results/`): the project's path with every character but letters
  * and digits as "-" (confirmed empirically).
  */
 export declare function claudeProjectDir(projectDir: string): string;
+/**
+ * The SDK's `permissions.deny` rules for paths no file tool may read or change, each one and
+ * whatever is inside it. An absolute path is written `//` and POSIX: `C:\Users\x` is
+ * `//c/Users/x` (confirmed empirically on Windows; on POSIX `/home/x` is `//home/x`). `Read`
+ * rules reach the tools that read, `Edit` rules those that write.
+ */
+export declare function denyRules(paths: readonly string[]): string[];
 /**
  * The skills of the plugins in `roots`, as the SDK names them: `<plugin>:<folder>`, the
  * plugin's name from its `.claude-plugin/plugin.json` and the skill's folder under `skills/`,