@falkenslab/agent-kit 0.17.0 → 0.19.0

package/dist/core/agentSpec.d.ts

@@ -1,5 +1,7 @@
+import type { ExtensionDirs } from "./externalExtensions.js";
 import type { AgentDefinition as SdkSubagentDefinition, McpServerConfig, SettingSource } from "@anthropic-ai/claude-agent-sdk";
-import type { KnowledgeStore, PageType } from "./knowledgeStore.js";
+import type { KnowledgeStore, PageType } from "../extensions/knowledge/knowledgeStore.js";
+import type { Extension } from "./extensions.js";
 /**
  * The human-supervision spectrum every agent built on this kit shares, independent of
  * domain: "interactive" pauses before every single action, "guided" only pauses before a
@@ -38,8 +40,27 @@ export interface BaseSessionConfig {
      * Edit are scoped to `knowledgeDir` — and `save_to_sources` never overwrites.
      */
     sourcesDir?: string;
+    /**
+     * The memory of the person (the `memory` extension, #34): a folder of the agent's own outside
+     * any project, e.g. `~/.miyagi/memory`, kept across all the person's projects. Never share it
+     * with another agent. The extension needs it; only its tools (`recall`, `remember`, `forget`) reach it.
+     */
+    memoryDir?: string;
+    /**
+     * Where extensions are installed for this agent (#37): `agent` for all its projects (e.g.
+     * `~/.miyagi/extensions`), `project` for this one (e.g. `<projectDir>/extensions`), which wins.
+     * The enabled ones whose files match their lock run with the session; `runExtensionCommand()`
+     * installs them.
+     */
+    extensionDirs?: ExtensionDirs;
     /** Directories besides `knowledgeDir`/`sourcesDir` where Write/Edit are allowed (see hooks/fileScopeGate.ts). */
     extraWritableDirs?: string[];
+    /**
+     * Directories besides `sourcesDir`/`extraWritableDirs` the agent may read and search (Read,
+     * Glob, Grep), never write. Read and Glob reach nothing else on the disk but what the kit
+     * knows the agent needs (see hooks/fileScopeGate.ts).
+     */
+    extraReadableDirs?: string[];
     /** Files or directories the agent must never read, search or write, e.g. a config file holding a password (see hooks/fileScopeGate.ts). */
     deniedPaths?: string[];
     /** Extra values (e.g. a password) to scrub out of the transcript log — see hooks/transcriptLogger.ts. */
@@ -71,15 +92,13 @@ 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.
+     * Who the agent is: its name, version and what it is. The `awareness` extension tells the
+     * model (with agent-kit's version), and needs it; the session's facts carry it too.
      */
     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`.
+     * folders), which the `awareness` extension's `about_me` gives the agent when the person asks.
      */
     helpGuide?: string;
     /**
@@ -120,26 +139,19 @@ export interface AgentSpec<TConfig extends BaseSessionConfig> {
     /** Overrides this kit's generic `save_to_sources` tool description (registered whenever `config.sourcesDir` is set) with domain-specific wording. */
     saveToSourcesDescription?: string;
     /**
-     * The built-in knowledge base (see knowledge.ts): when `config.knowledgeDir` is set, the kit
-     * appends its "Knowledge base" rules to the system prompt and loads its plugin (skills
-     * knowledge-ingest/knowledge-query/knowledge-lint, commands /knowledge:ingest, /knowledge:query,
-     * /knowledge:lint), so the agent maintains its notes as an interlinked wiki, through the
-     * `knowledge_*` tools by default (see `knowledgeTools`). On by default;
-     * set `false` for an agent that writes its own rules for `knowledgeDir` (or wants plain
-     * notes) — `knowledgePromptSection()`/`knowledgePluginRoot()` are exported to reuse the pieces.
-     */
-    knowledgeBase?: boolean;
-    /**
-     * How the agent reaches the built-in knowledge base: `"store"` (the default), only through
-     * the kit's `knowledge_*` tools over a `KnowledgeStore`, never with the file tools, so the
-     * storage can change and the wiki's rules are kept by code (ADR-024); `"files"`, with the
-     * file tools on `knowledgeDir` and the rules in the prompt, as before.
+     * The extensions the agent runs with (ADR-025), in order: the kit's by name (`"knowledge"`, the
+     * built-in knowledge base in `config.knowledgeDir`; `"sources"`, the originals in
+     * `config.sourcesDir`), and the agent's own as objects (an `Extension`: its plugin and what it
+     * brings). An extension the session lacks something for (its folder), or whose required
+     * capabilities nothing enabled provides, is left out, and the prompt says why. None by default.
+     * Without `"knowledge"`, `knowledgeDir` is a folder of the agent's own notes, kept with the file
+     * tools under rules it writes itself.
      */
-    knowledgeTools?: "store" | "files";
+    extensions?: (string | Extension)[];
     /**
-     * The agent's own page types for the built-in knowledge base, besides the kit's four
-     * (summary, concept, entity, synthesis): each with its folder (`""` for the root), index
-     * section, description (told to the model) and template.
+     * The agent's own page types for the built-in knowledge base, 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.
      */
     knowledgePageTypes?: PageType[];
     /**
@@ -166,11 +178,13 @@ export interface AgentSpec<TConfig extends BaseSessionConfig> {
     settingSources?: SettingSource[];
     /**
      * The skills the agent offers (the SDK's `skills`): names, or `plugin:skill` for a
-     * plugin's. Default `"all"`, every skill found (the SDK's own, the project's, the
-     * plugins'). A list keeps the rest out of each turn's context; the knowledge base's own
+     * plugin's. Default `"all"`, every skill found: the SDK's own (about twenty, whatever
+     * `settingSources` says), the project's, the plugins'. `"plugins"` offers only those of the
+     * plugins the session loads (`pluginRoots`, the extensions'), without
+     * naming them. A list keeps the rest out of each turn's context; the knowledge base's own
      * skills are added to it when the knowledge base is on. A context filter, not a sandbox.
      */
-    skills?: string[] | "all";
+    skills?: string[] | "all" | "plugins";
     /**
      * Text for the generic human-approval checkpoint (see tools/humanApproval.ts) — what
      * counts as "publishing something visible to others" is entirely domain-specific.

package/dist/core/extensions.d.ts

@@ -0,0 +1,119 @@
+import type { HookCallbackMatcher, HookEvent, McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
+import type { AgentSpec, BaseSessionConfig, Mode } from "./agentSpec.js";
+import type { ToolLabels } from "./toolLabels.js";
+import type { SessionFacts } from "./sessionFacts.js";
+/**
+ * Extensions (ADR-025): what an agent is besides the kit's core. An extension is a Claude Code
+ * plugin with the kit's data in its manifest (`.claude-plugin/plugin.json`, key `"agent-kit"`:
+ * the capabilities it `provides` and `requires`), plus, for an internal one, the code that
+ * says what it brings to a session. An agent enables the ones it wants (`AgentSpec.extensions`),
+ * the kit's by name, its own as objects; `buildSessionOptions()` puts the contributions of the
+ * active ones together, so the core names none of them. The kit's own (awareness, knowledge, sources, memory) live
+ * in `src/extensions/<name>/`, their plugin in `extensions/<name>/`; this file is the only place
+ * in the core that imports them (an ESLint rule keeps it so), and no extension imports another:
+ * each owns its data, and the model connects them through their tools (#30).
+ */
+/** What an extension sees of the session it's contributing to. */
+export interface ExtensionContext<TConfig extends BaseSessionConfig = BaseSessionConfig> {
+    config: TConfig;
+    spec: AgentSpec<TConfig>;
+    /** This run's folder. */
+    runDir: string;
+    mode: Mode;
+    /** A person can be asked (not autonomous): tools that ask them may exist. */
+    interactive: boolean;
+    /**
+     * What the session is at the moment of the call (#43): its mode now, the extensions running
+     * and off, their tools, the subagents, skills, commands and context. The core's facts, read
+     * anew on every call; for a tool, not for `contribute()`, which runs before the session exists.
+     */
+    session(): Promise<SessionFacts>;
+}
+/** What an extension brings to a session. Every part is optional. */
+export interface ExtensionContribution {
+    /** MCP servers, by name (`mcp__<name>__<tool>`). */
+    mcpServers?: Record<string, McpServerConfig>;
+    /** A section of the system prompt, after the agent's own and the list of extensions. */
+    promptSection?: string;
+    /** Built-in file tools it needs the session to have (`Read`, `Glob`, `Grep`…). */
+    fileTools?: string[];
+    /** Folders the file tools may read and search, never write (a sources folder). */
+    readOnlyDirs?: string[];
+    /** Folders reached only through its own tools, never the file tools, and what to use instead. */
+    toolOnlyDirs?: {
+        dir: string;
+        instead: string;
+    }[];
+    /** Its MCP tools that only read: plan mode lets them through. */
+    readOnlyTools?: string[];
+    /** Its MCP tools that ask the person themselves: interactive mode's step gate doesn't ask first. */
+    selfAskingTools?: string[];
+    /** How the chat shows its tools, by full name, in the kit's language: its line and how it counts in a folded group. */
+    toolLabels?: ToolLabels;
+    /**
+     * Its hooks, by event, run after the kit's own: an internal extension's only (the memory
+     * hears the person's messages with `UserPromptSubmit`).
+     */
+    hooks?: Partial<Record<HookEvent, HookCallbackMatcher[]>>;
+    /** What it says about itself in this session (its commands, its folder), for the agent to tell the person (`SessionFacts`). */
+    helpLines?: string[];
+    /** What the session hands back to the host (e.g. the knowledge base's store), by name. */
+    api?: Record<string, unknown>;
+}
+/**
+ * An internal extension: its plugin (whose manifest gives its name, description and
+ * capabilities), what it needs from the session, and what it brings.
+ */
+export interface Extension {
+    /** Its name, the same as its plugin's (`plugin.json`'s `name`). */
+    name: string;
+    /** Its plugin's root: `.claude-plugin/plugin.json`, and its skills and commands, if any. */
+    plugin: string;
+    /** Installed rather than shipped in a package (#37): its subagents get no `Bash`, and no plugin hook runs. */
+    external?: boolean;
+    /** Why it can't run in this session (e.g. "needs `knowledgeDir` in the config"), or `undefined` when it can. */
+    missing?(context: ExtensionContext): string | undefined;
+    /** What it brings to the session, once it's active. */
+    contribute(context: ExtensionContext): Promise<ExtensionContribution>;
+}
+/** An extension's manifest, as the kit reads it. */
+export interface ExtensionManifest {
+    name: string;
+    description: string;
+    /** Capabilities it lets the agent use. */
+    provides: string[];
+    /** Capabilities it needs another enabled extension to provide. */
+    requires: string[];
+}
+/** Reads an extension's manifest from its plugin. */
+export declare function readExtensionManifest(pluginRoot: string): ExtensionManifest;
+/** The kit's internal extensions, by name. */
+export declare const BUILT_IN_EXTENSIONS: readonly Extension[];
+/** The extensions a session runs with, and the ones it can't, with why. */
+export interface ResolvedExtensions {
+    active: {
+        extension: Extension;
+        manifest: ExtensionManifest;
+    }[];
+    inactive: {
+        name: string;
+        reason: string;
+    }[];
+    /** What the active ones provide. */
+    capabilities: Set<string>;
+}
+/**
+ * Which of the `enabled` extensions (the kit's by name, an agent's own as objects) run in this
+ * session, in the order given: those the session lacks something for are left out, and so are
+ * those requiring a capability no active one provides, until nothing more drops out.
+ */
+export declare function resolveExtensions(enabled: readonly (string | Extension)[], context: ExtensionContext): ResolvedExtensions;
+/** The prompt's "Extensions" section: what's on, and what isn't and why (ADR-025). */
+export declare function extensionsPromptSection(resolved: ResolvedExtensions): string;
+/**
+ * The skills of the plugins in `roots` whose frontmatter `requires` a capability not in
+ * `capabilities`, as the SDK names them (`<plugin>:<folder>`): the session leaves them out.
+ */
+export declare function skillsMissingCapabilities(roots: readonly string[], capabilities: ReadonlySet<string>): Promise<string[]>;
+/** A SKILL.md's `requires:` from its frontmatter: `requires: a`, `requires: [a, b]`, `a, b` or a YAML list. */
+export declare function requiredCapabilities(skill: string): string[];

package/dist/core/extensions.js

@@ -0,0 +1,97 @@
+import { readFileSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { frontmatter } from "./pluginAgents.js";
+import { awarenessExtension } from "../extensions/awareness/index.js";
+import { sourcesExtension } from "../extensions/sources/index.js";
+import { knowledgeExtension } from "../extensions/knowledge/index.js";
+import { memoryExtension } from "../extensions/memory/index.js";
+/** Reads an extension's manifest from its plugin. */
+export function readExtensionManifest(pluginRoot) {
+    const file = path.join(pluginRoot, ".claude-plugin", "plugin.json");
+    const raw = JSON.parse(readFileSync(file, "utf8"));
+    if (!raw.name)
+        throw new Error(`${file} has no "name".`);
+    return { name: raw.name, description: raw.description ?? "", provides: raw["agent-kit"]?.provides ?? [], requires: raw["agent-kit"]?.requires ?? [] };
+}
+/** The kit's internal extensions, by name. */
+export const BUILT_IN_EXTENSIONS = [awarenessExtension, sourcesExtension, knowledgeExtension, memoryExtension];
+/**
+ * Which of the `enabled` extensions (the kit's by name, an agent's own as objects) run in this
+ * session, in the order given: those the session lacks something for are left out, and so are
+ * those requiring a capability no active one provides, until nothing more drops out.
+ */
+export function resolveExtensions(enabled, context) {
+    const extensions = enabled.map((entry) => {
+        if (typeof entry !== "string")
+            return entry;
+        const found = BUILT_IN_EXTENSIONS.find((extension) => extension.name === entry);
+        if (!found)
+            throw new Error(`Unknown extension "${entry}": the kit's are ${BUILT_IN_EXTENSIONS.map((extension) => extension.name).join(", ")}; an agent's own is passed as an object.`);
+        return found;
+    });
+    const inactive = [];
+    let active = [];
+    for (const extension of extensions) {
+        const manifest = readExtensionManifest(extension.plugin);
+        if (manifest.name !== extension.name)
+            throw new Error(`The extension "${extension.name}" has the plugin "${manifest.name}": they must have the same name.`);
+        const reason = extension.missing?.(context);
+        if (reason)
+            inactive.push({ name: extension.name, reason });
+        else
+            active.push({ extension, manifest });
+    }
+    // Requirements: drop what can't be met, again and again, since dropping one may starve another.
+    for (let changed = true; changed;) {
+        changed = false;
+        const provided = new Set(active.flatMap(({ manifest }) => manifest.provides));
+        for (const entry of active) {
+            const unmet = entry.manifest.requires.filter((capability) => !provided.has(capability));
+            if (!unmet.length)
+                continue;
+            inactive.push({ name: entry.extension.name, reason: `requires ${unmet.join(", ")}, which no enabled extension provides` });
+            active = active.filter((other) => other !== entry);
+            changed = true;
+            break;
+        }
+    }
+    return { active, inactive, capabilities: new Set(active.flatMap(({ manifest }) => manifest.provides)) };
+}
+/** The prompt's "Extensions" section: what's on, and what isn't and why (ADR-025). */
+export function extensionsPromptSection(resolved) {
+    const lines = resolved.active.map(({ manifest }) => `- **${manifest.name}**: ${manifest.description}${manifest.provides.length ? ` Provides: ${manifest.provides.join(", ")}.` : ""}`);
+    const off = resolved.inactive.map(({ name, reason }) => `- **${name}** isn't available: it ${reason}. If the person asks for what it does, tell them why.`);
+    return `## Extensions\nWhat you can do besides your own tools comes from these extensions; their sections below say how to use them.\n${[...lines, ...off].join("\n")}`;
+}
+/**
+ * The skills of the plugins in `roots` whose frontmatter `requires` a capability not in
+ * `capabilities`, as the SDK names them (`<plugin>:<folder>`): the session leaves them out.
+ */
+export async function skillsMissingCapabilities(roots, capabilities) {
+    const missing = [];
+    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 folders = await readdir(path.join(root, "skills"), { withFileTypes: true }).catch(() => []);
+        for (const folder of folders.filter((entry) => entry.isDirectory())) {
+            const text = await readFile(path.join(root, "skills", folder.name, "SKILL.md"), "utf8").catch(() => "");
+            const required = requiredCapabilities(text);
+            if (required.some((capability) => !capabilities.has(capability)))
+                missing.push(`${plugin}:${folder.name}`);
+        }
+    }
+    return missing;
+}
+/** A SKILL.md's `requires:` from its frontmatter: `requires: a`, `requires: [a, b]`, `a, b` or a YAML list. */
+export function requiredCapabilities(skill) {
+    const value = frontmatter(skill).fields.requires;
+    if (value === undefined)
+        return [];
+    return (Array.isArray(value) ? value : value.split(",")).map((item) => item.trim()).filter(Boolean);
+}

package/dist/core/externalExtensions.d.ts

@@ -0,0 +1,131 @@
+import type { Extension } from "./extensions.js";
+import type { Language } from "./language.js";
+import { type ToolPhrase } from "./messages/index.js";
+/**
+ * External extensions (ADR-025, #37): installed into an agent, for all its projects (the
+ * agent's scope) or for one (the project's, which wins), from a folder or a git repository.
+ * Each scope is a folder of extensions, one per subfolder, with a lock (`extensions.lock.json`)
+ * that records where each came from, a SHA-256 over its files and whether it's enabled. An
+ * extension is a Claude Code plugin as it is (#38): its MCP servers come from its `.mcp.json`,
+ * and the kit starts each with Node through a launcher that leaves it only the system's
+ * variables and its own `env`. The `"agent-kit"` key of its `plugin.json` is optional: it adds
+ * what the kit's gates and chat can use (capabilities, read-only tools, labels, help).
+ */
+/** The two folders an agent installs extensions into; either may be left out. */
+export interface ExtensionDirs {
+    /** The agent's, for all its projects, e.g. `~/.miyagi/extensions`. */
+    agent?: string;
+    /** The project's, for this one only, e.g. `<projectDir>/extensions`: it wins over the agent's. */
+    project?: string;
+}
+/** One of the two scopes an extension can be installed in: the agent's or the project's. */
+export type ExtensionScope = keyof ExtensionDirs;
+/** One of a plugin's MCP servers, as its `.mcp.json` (or `plugin.json`'s `mcpServers`) declares it. */
+export interface PluginServer {
+    command: string;
+    args?: string[];
+    /** Its variables: a value may take the agent's with `${VAR}`. */
+    env?: Record<string, string>;
+}
+/** How the chat shows one of its tools in one language: `{field}` takes the call's input. */
+export interface ExternalToolLabel {
+    label: string;
+    phrase?: ToolPhrase;
+}
+/** Who made an extension, as Claude Code's `plugin.json` has it. */
+export interface ExtensionAuthor {
+    name: string;
+    email?: string;
+    url?: string;
+}
+/**
+ * An external extension's manifest: its `plugin.json`, the plugin's own metadata (Claude Code's
+ * fields, which its validator checks) and the kit's key (`"agent-kit"`, which it ignores).
+ */
+export interface ExternalManifest {
+    name: string;
+    description: string;
+    version?: string;
+    author?: ExtensionAuthor;
+    homepage?: string;
+    repository?: string;
+    license?: string;
+    keywords?: string[];
+    provides: string[];
+    requires: string[];
+    /** The agent-kit versions it works with, e.g. `">=0.19.0 <0.21.0"`. */
+    kit?: string;
+    /** Its MCP servers, by name (`mcp__<name>__<tool>`), from the plugin's `.mcp.json` or `plugin.json`. */
+    servers: Record<string, PluginServer>;
+    /** Its tools that only read (short names, of any of its servers): plan mode lets them through. */
+    readOnlyTools: string[];
+    /** Its tools' chat labels, by short name (of any of its servers) and language (English when the kit's isn't there). */
+    labels: Record<string, Partial<Record<Language, ExternalToolLabel>>>;
+    /** What it says about itself in a session, for the agent to tell the person (`SessionFacts`). */
+    help?: string;
+}
+/** One extension in a scope's lock. */
+export interface LockEntry {
+    /** Where it came from: a folder, or a git URL (with `#ref` when given). */
+    source: string;
+    /** The commit it was cloned at, for a git source. */
+    commit?: string;
+    /** SHA-256 over its files, checked when it loads. */
+    sha256: string;
+    enabled: boolean;
+    /** When it was installed, ISO 8601 in UTC. */
+    installed: string;
+}
+export declare const LOCK_FILE = "extensions.lock.json";
+/** A scope's lock: its extensions by name. */
+export declare function readLock(scopeDir: string): Promise<Record<string, LockEntry>>;
+/** Reads an extension's manifest, checking what the kit needs from it. */
+export declare function readExternalManifest(dir: string): Promise<ExternalManifest>;
+/** SHA-256 over an extension's files (their paths and contents, in order), `.git` aside. */
+export declare function hashExtension(dir: string): Promise<string>;
+/**
+ * Whether `version` (x.y.z) is in `range`: comparators separated by spaces, all of which must
+ * hold (`>=0.19.0 <0.21.0`, `=0.19.2`, `0.19.2`).
+ */
+export declare function inKitRange(version: string, range: string): boolean;
+/** One installed extension, as the scopes and their locks list it. */
+export interface InstalledExtension {
+    name: string;
+    scope: ExtensionScope;
+    dir: string;
+    lock: LockEntry;
+    /** Also installed in the project's scope, which wins: this one isn't used. */
+    shadowed: boolean;
+    /** Its manifest, when it can be read. */
+    manifest?: ExternalManifest;
+}
+/** Every extension installed in the scopes, the project's first. */
+export declare function listInstalled(dirs: ExtensionDirs): Promise<InstalledExtension[]>;
+/** The launcher that starts an external extension's server with a clean environment. */
+export declare function extensionLauncherPath(): string;
+/** The installed extensions a session runs with, and those it can't (with why). Disabled ones are neither. */
+export declare function loadExternalExtensions(dirs: ExtensionDirs): Promise<{
+    extensions: Extension[];
+    off: {
+        name: string;
+        reason: string;
+    }[];
+}>;
+/** Whether `source` names a git repository rather than a folder. */
+export declare function isGitSource(source: string): boolean;
+/**
+ * Installs an extension into a scope from a folder or a git repository (`url#ref`, and `subdir`
+ * for one inside it): copies its files (never runs a script), checks its manifest, and locks it,
+ * enabled. An extension with the same name in that scope is replaced.
+ */
+export declare function addExtension(source: string, scopeDir: string, options?: {
+    subdir?: string;
+}): Promise<{
+    name: string;
+    replaced: boolean;
+    commit?: string;
+}>;
+/** Removes an extension from a scope (its files and its lock entry); false when it wasn't there. */
+export declare function removeExtension(scopeDir: string, name: string): Promise<boolean>;
+/** Enables or disables an installed extension in a scope; false when it isn't there. */
+export declare function setExtensionEnabled(scopeDir: string, name: string, enabled: boolean): Promise<boolean>;