@falkenslab/agent-kit 0.19.0 → 0.20.0

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

@@ -31,7 +31,12 @@ export function runQuery(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() });
+    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() {

package/dist/core/session.d.ts

@@ -1,12 +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 "../extensions/knowledge/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
@@ -40,10 +40,10 @@ export declare function buildSessionOptions<TConfig extends BaseSessionConfig>(c
     toolLabels: ToolLabels;
     /** The installed extensions and what this session runs with, for `/extensions` (#37). */
     extensions: ExtensionsStatus;
-    /** The knowledge base's store, when the knowledge extension is on (for a host that reads the knowledge base). */
-    knowledgeStore?: KnowledgeStore;
-    /** What each active extension hands the host (its contribution's `api`), by its name: the sources' `addSource`, the knowledge base's store. */
+    /** 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). */
@@ -68,6 +68,13 @@ export interface ExtensionsStatus {
  * 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/`,

package/dist/core/session.js

@@ -1,4 +1,4 @@
-import { readdir, readFile } from "node:fs/promises";
+import { cp, readdir, readFile, rm } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { createTranscriptLogger } from "./hooks/transcriptLogger.js";
@@ -22,6 +22,7 @@ import { replyLanguageInstruction } from "./language.js";
 import { chooseLanguage } from "./messages/index.js";
 import { createRunStore } from "./runs.js";
 import { createSessionView, registerSessionView } from "./sessionFacts.js";
+import { createExtensionSwitch } from "./liveExtensions.js";
 import { agentKitVersion } from "./version.js";
 /**
  * Builds the `options` object passed to the Agent SDK's `query()` — everything about
@@ -69,32 +70,39 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
         runDir,
         mode,
         interactive: mode !== "autonomous",
+        // What the active ones provide, once they're resolved below.
+        capabilities: new Set(),
         session: () => (late.view ? late.view.facts() : Promise.reject(new Error("The session isn't built yet: call session() from a tool, not from contribute()."))),
     };
     // The installed ones (#37), the project's over the agent's: those that can't load are off with
     // why, and so is one named like an extension the spec enables.
     const extensionDirs = config.extensionDirs ?? {};
     const external = await loadExternalExtensions(extensionDirs);
-    const enabledNames = new Set((spec.extensions ?? []).map((entry) => (typeof entry === "string" ? entry : entry.name)));
+    const enabledNames = new Set((spec.extensions ?? []).map((extension) => extension.name));
     const resolved = resolveExtensions([...(spec.extensions ?? []), ...external.extensions.filter((extension) => !enabledNames.has(extension.name))], extensionContext);
     resolved.inactive.push(...external.off, ...external.extensions.filter((extension) => enabledNames.has(extension.name)).map((extension) => ({ name: extension.name, reason: "has the name of one this agent already has" })));
+    // Each installed one's plugin, copied into the run's folder: the running session empties and
+    // fills the copy to turn the extension off and on (liveExtensions.ts), never what's installed.
+    const installedDirs = new Map();
+    for (const { extension } of resolved.active.filter(({ extension }) => extension.external)) {
+        const copy = path.join(runDir, "extensions", extension.name);
+        await rm(copy, { recursive: true, force: true });
+        await cp(extension.plugin, copy, { recursive: true });
+        installedDirs.set(extension.name, extension.plugin);
+        extension.plugin = copy;
+    }
     const externalPlugins = new Set(resolved.active.filter(({ extension }) => extension.external).map(({ extension }) => path.resolve(extension.plugin)));
+    extensionContext.capabilities = resolved.capabilities;
     const added = await Promise.all(resolved.active.map(({ extension }) => extension.contribute(extensionContext)));
     const extensionPlugins = resolved.active.map(({ extension }) => extension.plugin);
     const fromExtensions = (pick) => added.flatMap((contribution) => pick(contribution) ?? []);
-    const knowledgeStore = added.map((contribution) => contribution.api?.knowledgeStore).find(Boolean);
-    // An extension may claim `knowledgeDir` as reached only through its tools (the knowledge base,
-    // ADR-024); otherwise it's a folder of the agent's own notes, kept with the file tools under
-    // its own rules.
-    const claimed = (dir) => fromExtensions((contribution) => contribution.toolOnlyDirs).some((only) => path.resolve(only.dir) === path.resolve(dir));
-    const notesDir = config.knowledgeDir && !claimed(config.knowledgeDir) ? config.knowledgeDir : undefined;
     const extraDirs = config.extraWritableDirs ?? [];
     const readableExtras = config.extraReadableDirs ?? [];
-    // The file tools the session needs: all five for the notes and the extra writable folders,
-    // the reading ones for the extra readable folders, and whatever the extensions ask for (the
-    // sources' reading ones); without any of them, none.
+    // The file tools the session needs: all five for the extra writable folders, the reading ones
+    // for the extra readable folders, and whatever the extensions ask for (the sources' reading
+    // ones); without any of them, none.
     const wantedFileTools = new Set([
-        ...(notesDir || extraDirs.length ? FILE_TOOLS : []),
+        ...(extraDirs.length ? FILE_TOOLS : []),
         ...(readableExtras.length ? ["Read", "Glob", "Grep"] : []),
         ...fromExtensions((contribution) => contribution.fileTools),
     ]);
@@ -105,10 +113,10 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
     // searchable but deliberately NOT writable: the only way to add to them is its tools.
     const readOnlyDirs = fromExtensions((contribution) => contribution.readOnlyDirs);
     const toolOnlyDirs = fromExtensions((contribution) => contribution.toolOnlyDirs);
-    const writableDirs = [notesDir, ...extraDirs].filter((d) => Boolean(d));
-    const searchableDirs = [notesDir, ...readOnlyDirs, ...extraDirs, ...readableExtras].filter((d) => Boolean(d));
+    const writableDirs = extraDirs;
+    const searchableDirs = [...readOnlyDirs, ...extraDirs, ...readableExtras];
     // Skills/commands/plugins are a separate concern from the file tools: an agent that
-    // wants a plugin-provided skill/command but has no notes or sources folder shouldn't have
+    // wants a plugin-provided skill/command but has no folder of its own shouldn't have
     // to invent one just to get `cwd`/`skills: "all"`/`plugins` wired up. Gated on either
     // signal, not on `pluginRoots` alone, so an agent with file tools keeps getting the SDK's
     // own project-level `.claude/skills`/`.claude/commands` discovery.
@@ -160,6 +168,10 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
     // map, and inherits the full session tools (Bash included) rather than the narrow list
     // each declared subagent actually declares.
     const allowedSubagentTypes = [...new Set([...(subagents?.allowedSubagentTypes ?? []), ...Object.keys(fromPlugins)])];
+    // The extensions' read-only tools, for the plan gate: a list the live switch changes (liveExtensions.ts).
+    const readOnlyTools = fromExtensions((contribution) => contribution.readOnlyTools);
+    // What no file tool may touch: the agent's denied paths and the SDK's own credentials.
+    const deniedPaths = [...(config.deniedPaths ?? []), path.join(claudeConfigDir(), ".credentials.json")];
     const transcriptPath = path.join(runDir, "transcript.jsonl");
     const transcriptLogger = createTranscriptLogger(transcriptPath, config.secrets ?? []);
     const promptSections = [
@@ -195,6 +207,9 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
             // An installed extension's plugin may carry hooks: none run (ADR-025). The kit's own,
             // passed in `hooks`, still do (confirmed empirically).
             ...(externalPlugins.size ? { disableAllHooks: true } : {}),
+            // The denied paths again, as the SDK's own rules: a second layer under the file scope gate,
+            // which a tool the gate doesn't know of can't pass either (#49).
+            permissions: { deny: denyRules(deniedPaths) },
         },
         // No built-in tools except, if applicable, Read/Write/Edit/Glob/Grep scoped to the
         // project's own folders (fileScopeGate below), and WebFetch/WebSearch
@@ -230,7 +245,7 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
                 // skills, on top of the plugin-provided built-ins from spec.pluginRoots()
                 // below. skipMcpDiscovery: true on those plugins is the caller's choice.
                 cwd: config.projectDir,
-                // Empty when there's no knowledgeDir/sourcesDir (the plugin-only case) — an
+                // Empty when there's no folder of the agent's or its extensions' (the plugin-only case) — an
                 // empty array is a valid, no-op value for this SDK option, not omitted, since
                 // this whole block is already conditioned on includeSkillsAndPlugins.
                 additionalDirectories: searchableDirs,
@@ -264,7 +279,7 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
                                     searchableDirs,
                                     readOnlyDirs,
                                     // The SDK's own credentials, whatever the agent denies.
-                                    deniedPaths: [...(config.deniedPaths ?? []), path.join(claudeConfigDir(), ".credentials.json")],
+                                    deniedPaths,
                                     // Read and Glob only in the agent's folders, plus what only the kit knows it
                                     // needs: the run folder, the plugins, the project's .claude/ (when loaded) and
                                     // the SDK's large tool results. Never the rest of the disk (~/.ssh, other
@@ -287,7 +302,7 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
                             hooks: [
                                 createPlanGate({
                                     projectDir: config.projectDir,
-                                    readOnlyTools: fromExtensions((contribution) => contribution.readOnlyTools),
+                                    readOnlyTools,
                                     ...(spec.planMode?.isPlanFile ? { isPlanFile: (filePath) => spec.planMode.isPlanFile(filePath, config) } : {}),
                                     ...(spec.planMode?.isReadOnlyTool ? { isReadOnlyTool: spec.planMode.isReadOnlyTool } : {}),
                                 }, () => modeControl.mode === "plan"),
@@ -321,7 +336,7 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
         inactive: resolved.inactive,
     };
     // What the session is, for the extensions that ask (sessionFacts.ts, #43).
-    late.view = createSessionView({
+    const viewBase = {
         ...(spec.identity ? { identity: spec.identity } : {}),
         kitVersion: agentKitVersion(),
         language,
@@ -333,15 +348,39 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
                 servers: Object.keys(added[index]?.mcpServers ?? {}),
                 help: added[index]?.helpLines ?? [],
             })),
-            inactive: resolved.inactive,
+            // Its own list: /extensions' status has another, and the live switch changes both.
+            inactive: [...resolved.inactive],
         },
         subagents: Object.entries(allAgents).map(([name, agent]) => ({ name, description: agent.description })),
         skills: sdkOptions.skills === "all" ? await pluginSkills(pluginRoots) : [...(sdkOptions.skills ?? [])],
         runDir,
-    }, modeControl);
+    };
+    late.view = createSessionView(viewBase, modeControl);
     registerSessionView(sdkOptions, late.view);
+    // Turning an installed extension off and on while the session runs (#49).
+    const switchExtension = createExtensionSwitch(resolved.active.flatMap(({ extension, manifest }, index) => {
+        const installedDir = installedDirs.get(extension.name);
+        if (!installedDir)
+            return [];
+        const contribution = added[index];
+        return [
+            {
+                name: extension.name,
+                installedDir,
+                scopeDir: path.dirname(installedDir),
+                pluginCopy: extension.plugin,
+                servers: Object.keys(contribution?.mcpServers ?? {}),
+                readOnlyTools: contribution?.readOnlyTools ?? [],
+                toolLabels: contribution?.toolLabels ?? {},
+                agents: Object.keys(fromPlugins).filter((agent) => agent.startsWith(`${extension.name}:`)),
+                description: manifest.description,
+                provides: manifest.provides,
+                help: contribution?.helpLines ?? [],
+            },
+        ];
+    }), { readOnlyTools, allowedSubagentTypes, toolLabels, status: extensions, facts: viewBase, controls: () => late.view?.controls() ?? {} });
     const apis = Object.fromEntries(resolved.active.flatMap(({ extension }, index) => (added[index]?.api ? [[extension.name, added[index].api]] : [])));
-    return { options: sdkOptions, transcriptLogger, transcriptPath, modeControl, language, toolLabels, extensions, apis, ...(knowledgeStore ? { knowledgeStore } : {}) };
+    return { options: sdkOptions, transcriptLogger, transcriptPath, modeControl, language, toolLabels, extensions, apis, switchExtension };
 }
 export { createModeControl, togglePlanMode } from "./modeControl.js";
 /** The Claude Code configuration folder the SDK's CLI uses: `CLAUDE_CONFIG_DIR`, or `~/.claude`. */
@@ -356,6 +395,19 @@ function claudeConfigDir() {
 export function claudeProjectDir(projectDir) {
     return path.join(claudeConfigDir(), "projects", path.resolve(projectDir).replace(/[^a-zA-Z0-9]/g, "-"));
 }
+/**
+ * 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 function denyRules(paths) {
+    return paths.flatMap((denied) => {
+        const posix = path.resolve(denied).replace(/\\/g, "/").replace(/^([A-Za-z]):/, (_, drive) => `/${drive.toLowerCase()}`);
+        const rule = `/${posix}`;
+        return [`Read(${rule})`, `Read(${rule}/**)`, `Edit(${rule})`, `Edit(${rule}/**)`];
+    });
+}
 /** The built-in file tools, in the order the session lists them. */
 const FILE_TOOLS = ["Read", "Write", "Edit", "Glob", "Grep"];
 /**

package/dist/core/sessionFacts.d.ts

@@ -58,6 +58,9 @@ export interface SessionLive {
     skills?: string[];
     supportedCommands?: () => Promise<SlashCommand[]>;
     contextUsage?: () => Promise<ContextUsage | null>;
+    /** The running session's controls an installed extension is turned off and on with (liveExtensions.ts). */
+    toggleMcpServer?: (server: string, enabled: boolean) => Promise<void>;
+    reloadPlugins?: () => Promise<unknown>;
 }
 /** The facts known when the options are built: everything but the mode and what only the running session knows. */
 export type StaticSessionFacts = Omit<SessionFacts, "mode" | "switchableModes" | "tools" | "commands" | "context" | "extensions"> & {
@@ -71,6 +74,8 @@ export type StaticSessionFacts = Omit<SessionFacts, "mode" | "switchableModes" |
 export interface SessionView {
     facts(): Promise<SessionFacts>;
     attach(live: SessionLive): void;
+    /** What the running session has attached so far. */
+    controls(): SessionLive;
 }
 /** The view of a session: its static facts, the mode read from `modeControl` on every call, and what the running session attaches. */
 export declare function createSessionView(base: StaticSessionFacts, modeControl: ModeControl): SessionView;

package/dist/core/sessionFacts.js

@@ -8,6 +8,7 @@ export function createSessionView(base, modeControl) {
         attach(more) {
             live = { ...live, ...more };
         },
+        controls: () => live,
         async facts() {
             const tools = live.tools ?? [];
             const [commands, context] = await Promise.all([

package/dist/extensions/awareness/index.d.ts

@@ -4,10 +4,19 @@ import type { Extension } from "../../core/extensions.js";
 export declare function awarenessPluginRoot(): string;
 /** The "Who you are" section of the system prompt: name, version, what it is, the kit's version, and where to look. */
 export declare function identityPromptSection(identity: AgentIdentity): string;
+/** The awareness extension's options. */
+export interface AwarenessOptions {
+    /**
+     * Absolute path of a markdown guide to the agent's own domain (its commands, configuration,
+     * folders), which `about_me` gives the agent when the person asks.
+     */
+    guide?: string;
+}
 /**
  * The awareness (#43): the agent knows who it is and what it is at each moment of a session,
  * and the person can ask it. A "Who you are" section, `about_me` (the session's facts, read
- * anew on every call through `ExtensionContext.session()`, and the agent's `helpGuide`), and
- * the `help` skill, how the kit's chat is used, which doesn't change.
+ * anew on every call through `ExtensionContext.session()`, and the agent's `guide`), and
+ * the `help` skill, how the kit's chat is used, which doesn't change. It needs the spec's
+ * `identity`.
  */
-export declare const awarenessExtension: Extension;
+export declare function awareness(options?: AwarenessOptions): Extension;

package/dist/extensions/awareness/index.js

@@ -21,19 +21,22 @@ You are ${who}. You are built on agent-kit ${agentKitVersion()}, which provides
 /**
  * The awareness (#43): the agent knows who it is and what it is at each moment of a session,
  * and the person can ask it. A "Who you are" section, `about_me` (the session's facts, read
- * anew on every call through `ExtensionContext.session()`, and the agent's `helpGuide`), and
- * the `help` skill, how the kit's chat is used, which doesn't change.
+ * anew on every call through `ExtensionContext.session()`, and the agent's `guide`), and
+ * the `help` skill, how the kit's chat is used, which doesn't change. It needs the spec's
+ * `identity`.
  */
-export const awarenessExtension = {
-    name: "awareness",
-    plugin: awarenessPluginRoot(),
-    missing: ({ spec }) => (spec.identity ? undefined : "needs `identity` in the spec"),
-    async contribute({ spec, session }) {
-        return {
-            mcpServers: { awareness: createAwarenessServer(session, spec.helpGuide) },
-            promptSection: identityPromptSection(spec.identity),
-            readOnlyTools: ["mcp__awareness__about_me"],
-            toolLabels: awarenessToolLabels(),
-        };
-    },
-};
+export function awareness(options = {}) {
+    return {
+        name: "awareness",
+        plugin: awarenessPluginRoot(),
+        missing: ({ spec }) => (spec.identity ? undefined : "needs `identity` in the spec"),
+        async contribute({ spec, session }) {
+            return {
+                mcpServers: { awareness: createAwarenessServer(session, options.guide) },
+                promptSection: identityPromptSection(spec.identity),
+                readOnlyTools: ["mcp__awareness__about_me"],
+                toolLabels: awarenessToolLabels(),
+            };
+        },
+    };
+}

package/dist/extensions/awareness/tools.d.ts

@@ -2,4 +2,4 @@ import type { SessionFacts } from "../../core/sessionFacts.js";
 /** The session's facts as the model reads them: markdown, in English (ADR-019). */
 export declare function describeSession(facts: SessionFacts): string;
 /** The awareness's MCP server: `about_me`, from the session's facts and the agent's guide. */
-export declare function createAwarenessServer(session: () => Promise<SessionFacts>, helpGuide?: string): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;
+export declare function createAwarenessServer(session: () => Promise<SessionFacts>, guide?: string): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;

package/dist/extensions/awareness/tools.js

@@ -41,12 +41,12 @@ export function describeSession(facts) {
     return sections.join("\n\n");
 }
 /** The awareness's MCP server: `about_me`, from the session's facts and the agent's guide. */
-export function createAwarenessServer(session, helpGuide) {
+export function createAwarenessServer(session, guide) {
     const aboutMe = tool("about_me", "What you are right now: your mode and the ones the person can switch to, your extensions with their tools and the ones off (with why), your subagents, the commands the person can type, how full your context is. With `part: \"guide\"`, your own guide to your domain (your commands, configuration, folders). It changes during a session: call it whenever the person asks about you, rather than answering from memory.", { part: z.enum(["now", "guide"]).optional().describe("`now` (the default): what you are right now. `guide`: your own guide to your domain.") }, async ({ part }) => {
         if (part === "guide") {
-            if (!helpGuide)
+            if (!guide)
                 return ok("You have no guide of your own: for your domain, say only what your instructions tell you, and that the rest isn't documented.");
-            return ok(await readFile(helpGuide, "utf8"));
+            return ok(await readFile(guide, "utf8"));
         }
         return ok(describeSession(await session()));
     }, { annotations: { readOnlyHint: true } });

package/dist/extensions/knowledge/index.d.ts

@@ -1,8 +1,22 @@
-import type { Extension } from "../../core/extensions.js";
+import type { BaseSessionConfig } from "../../core/agentSpec.js";
+import { type Extension, type FolderOption } from "../../core/extensions.js";
+import type { KnowledgeStore, PageType } from "./knowledgeStore.js";
+/** The knowledge base's options. */
+export interface KnowledgeOptions<TConfig extends BaseSessionConfig = BaseSessionConfig> {
+    /** The knowledge base's folder, reached only through its tools, never the file tools. Without a folder the extension is off. */
+    dir: FolderOption<TConfig>;
+    /**
+     * The agent's own page types, besides the kit's (summary, concept, entity, synthesis,
+     * preference): each with its folder (`""` for the root), index section, description (told to
+     * the model) and template.
+     */
+    pageTypes?: PageType[];
+    /** Its store, instead of the kit's over markdown files in `dir` (e.g. a database or a vector store implementing `KnowledgeStore`). */
+    store?(config: TConfig, dir: string): KnowledgeStore;
+}
 /**
- * The built-in knowledge base (`config.knowledgeDir`, ADR-008, ADR-024): an interlinked wiki the
- * agent keeps only through its `knowledge_*` tools, over a `KnowledgeStore` (the kit's over
- * markdown files, or the agent's own). Not enabled, `knowledgeDir` is left to the core as a
- * folder of the agent's own notes.
+ * The built-in knowledge base (ADR-008, ADR-024): an interlinked wiki the agent keeps only through
+ * its `knowledge_*` tools, over a `KnowledgeStore` (the kit's over markdown files, or the agent's
+ * own). The host reads it through `apis.knowledge.knowledgeStore`.
  */
-export declare const knowledgeExtension: Extension;
+export declare function knowledge<TConfig extends BaseSessionConfig = BaseSessionConfig>(options: KnowledgeOptions<TConfig>): Extension;

package/dist/extensions/knowledge/index.js

@@ -1,35 +1,38 @@
+import { folderOf } from "../../core/extensions.js";
 import { createFileKnowledgeStore } from "./fileKnowledgeStore.js";
 import { knowledgeToolLabels } from "./labels.js";
 import { knowledgePluginRoot, knowledgePromptSection } from "./prompt.js";
 import { createKnowledgeServer } from "./tools.js";
 /**
- * The built-in knowledge base (`config.knowledgeDir`, ADR-008, ADR-024): an interlinked wiki the
- * agent keeps only through its `knowledge_*` tools, over a `KnowledgeStore` (the kit's over
- * markdown files, or the agent's own). Not enabled, `knowledgeDir` is left to the core as a
- * folder of the agent's own notes.
+ * The built-in knowledge base (ADR-008, ADR-024): an interlinked wiki the agent keeps only through
+ * its `knowledge_*` tools, over a `KnowledgeStore` (the kit's over markdown files, or the agent's
+ * own). The host reads it through `apis.knowledge.knowledgeStore`.
  */
-export const knowledgeExtension = {
-    name: "knowledge",
-    plugin: knowledgePluginRoot(),
-    missing: ({ config }) => (config.knowledgeDir ? undefined : "needs `knowledgeDir` in the config"),
-    async contribute({ config, spec, runDir, interactive }) {
-        const knowledgeDir = config.knowledgeDir;
-        const store = spec.knowledgeStore?.(config) ?? createFileKnowledgeStore(knowledgeDir, { pageTypes: spec.knowledgePageTypes });
-        // The person's preferences, by title, for its prompt section (#33).
-        const preferences = (await store.list()).filter((page) => page.type === "preference" && page.status === "active").map(({ id, title }) => ({ id, title }));
-        return {
-            // knowledge_retire asks a person, so it exists only where there is one.
-            mcpServers: { knowledge: createKnowledgeServer(store, { runDir, interactive }) },
-            promptSection: knowledgePromptSection({ withSources: Boolean(config.sourcesDir), pageTypes: store.types(), preferences }),
-            // Never the file tools on the knowledge folder (ADR-024): the denial points to the tools.
-            toolOnlyDirs: [{ dir: knowledgeDir, instead: "the knowledge_* tools" }],
-            readOnlyTools: ["mcp__knowledge__knowledge_index", "mcp__knowledge__knowledge_search", "mcp__knowledge__knowledge_read", "mcp__knowledge__knowledge_check"],
-            selfAskingTools: ["mcp__knowledge__knowledge_retire"],
-            toolLabels: knowledgeToolLabels(),
-            helpLines: [
-                "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).",
-            ],
-            api: { knowledgeStore: store },
-        };
-    },
-};
+export function knowledge(options) {
+    return {
+        name: "knowledge",
+        plugin: knowledgePluginRoot(),
+        missing: ({ config }) => (folderOf(options.dir, config) ? undefined : "needs a folder (`dir`)"),
+        async contribute({ config, runDir, interactive, capabilities }) {
+            const knowledgeDir = folderOf(options.dir, config);
+            const store = options.store?.(config, knowledgeDir) ?? createFileKnowledgeStore(knowledgeDir, { pageTypes: options.pageTypes });
+            // The person's preferences, by title, for its prompt section (#33).
+            const preferences = (await store.list()).filter((page) => page.type === "preference" && page.status === "active").map(({ id, title }) => ({ id, title }));
+            return {
+                // knowledge_retire asks a person, so it exists only where there is one.
+                mcpServers: { knowledge: createKnowledgeServer(store, { runDir, interactive }) },
+                // Beside the sources, its summaries say which original they're about.
+                promptSection: knowledgePromptSection({ withSources: capabilities.has("sources"), pageTypes: store.types(), preferences }),
+                // Never the file tools on the knowledge folder (ADR-024): the denial points to the tools.
+                toolOnlyDirs: [{ dir: knowledgeDir, instead: "the knowledge_* tools" }],
+                readOnlyTools: ["mcp__knowledge__knowledge_index", "mcp__knowledge__knowledge_search", "mcp__knowledge__knowledge_read", "mcp__knowledge__knowledge_check"],
+                selfAskingTools: ["mcp__knowledge__knowledge_retire"],
+                toolLabels: knowledgeToolLabels(),
+                helpLines: [
+                    "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).",
+                ],
+                api: { knowledgeStore: store },
+            };
+        },
+    };
+}

package/dist/extensions/knowledge/knowledgeStore.d.ts

@@ -5,7 +5,7 @@
  * skills. A page is identified by its type and slug, `concept/bowline`, and links between
  * pages use that id too: `[Bowline](concept/bowline)`.
  */
-/** A kind of page: one of the kit's, or one an agent declares (`AgentSpec.knowledgePageTypes`). */
+/** A kind of page: one of the kit's, or one an agent declares (`knowledge({ pageTypes })`). */
 export interface PageType {
     /** Its name, lowercase: `concept`, `topic`. Page ids start with it. */
     type: string;