@falkenslab/agent-kit 0.18.0 → 0.20.0

package/dist/index.js

@@ -7,16 +7,24 @@ export { allowAnyMcpTool } from "./core/mcpPermissions.js";
 export { createPromptLoader } from "./core/promptTemplate.js";
 export { resolveClaudeAuth } from "./core/claudeAuth.js";
 export { ensureClaudeAuth } from "./tui/claudeAuth.js";
-export { createFriendlyToolLabel, truncate, truncatePath, } from "./core/toolLabels.js";
+export { createFriendlyToolLabel, truncate, truncatePath, withToolLabels, withToolPhrases, } from "./core/toolLabels.js";
 export { buildSessionOptions, createInputQueue, createDeferred, createModeControl, togglePlanMode } from "./core/session.js";
 export { runQuery } from "./core/runner.js";
-export { knowledgePluginRoot, knowledgePromptSection } from "./core/knowledge.js";
+export { knowledgePluginRoot, knowledgePromptSection } from "./extensions/knowledge/prompt.js";
+export { awareness } from "./extensions/awareness/index.js";
+export { sources } from "./extensions/sources/index.js";
+export { knowledge } from "./extensions/knowledge/index.js";
+export { memory } from "./extensions/memory/index.js";
+export { readExtensionManifest, } from "./core/extensions.js";
+export { addExtension, removeExtension, setExtensionEnabled, listInstalled, readExternalManifest, } from "./core/externalExtensions.js";
+export { addMarketplace, findPlugin, inspectMarketplace, installFromMarketplace, listMarketplaces, readMarketplaceManifest, removeMarketplace, resolvePluginSource, updateMarketplace, } from "./core/marketplaces.js";
+export { runExtensionCommand } from "./tui/extensionCommand.js";
 export { agentKitVersion } from "./core/version.js";
-export { BUILT_IN_PAGE_TYPES, isSlug, parseId, linkedIds, } from "./core/knowledgeStore.js";
-export { createFileKnowledgeStore } from "./core/fileKnowledgeStore.js";
-export { createKnowledgeServer } from "./core/tools/knowledgeTools.js";
+export { BUILT_IN_PAGE_TYPES, isSlug, parseId, linkedIds, } from "./extensions/knowledge/knowledgeStore.js";
+export { createFileKnowledgeStore } from "./extensions/knowledge/fileKnowledgeStore.js";
+export { createKnowledgeServer } from "./extensions/knowledge/tools.js";
 export { resolveLanguage, detectLanguage, SUPPORTED_LANGUAGES, } from "./core/language.js";
-export { setLanguage, getLanguage, messagesFor } from "./core/messages/index.js";
+export { setLanguage, switchLanguage, getLanguage, messagesFor } from "./core/messages/index.js";
 export { createRunStore, createRunFolder, listRuns, readConversation, } from "./core/runs.js";
 // And the two functions an agent needs for tools of its own (an in-process MCP server,
 // returned from AgentSpec.buildMcpServers()), so it doesn't need the SDK for those either.
@@ -36,8 +44,9 @@ export { terminalInteractionPort, setSharedReadline, getSharedReadline } from ".
 setInteractionPort(terminalInteractionPort);
 export { createHumanApprovalServer, DEFAULT_HUMAN_APPROVAL_TEXTS } from "./core/tools/humanApproval.js";
 export { createManualLoginServer } from "./core/tools/manualLogin.js";
-export { createSaveToSourcesServer, sourcesPromptSection } from "./core/tools/saveToSources.js";
+export { createSaveToSourcesServer, sourcesPromptSection } from "./extensions/sources/tools.js";
 export { runChatTui } from "./tui/chatTui.js";
+export { createChatController, } from "./chat/chatController.js";
 export { createConsoleRenderer } from "./tui/consoleRenderer.js";
 export { runChatInk } from "./tui/ink/runChatInk.js";
 export { createProgressView } from "./tui/ink/progressView.js";

package/dist/tui/chatTui.d.ts

@@ -1,8 +1,10 @@
 import type { Options } from "@anthropic-ai/claude-agent-sdk";
-import { type ModeControl } from "../core/session.js";
-import { type AgentEvent } from "../core/runner.js";
+import type { ModeControl } from "../core/session.js";
+import type { AgentEvent } from "../core/runner.js";
 import { type Theme } from "./theme.js";
-import { type SessionOpener } from "./runs.js";
+import type { ToolLabels } from "../core/toolLabels.js";
+import { type SessionOpener } from "../chat/runs.js";
+export { capHistory, loadHistory, saveHistory, slashCommandToken } from "../chat/history.js";
 /** Options of the chats (`runChatTui()`, and `runChatInk()` through `InkChatOptions`). */
 export interface ChatTuiOptions {
     /**
@@ -80,6 +82,12 @@ export interface ChatTuiOptions {
      * returns is used instead.
      */
     modeControl?: ModeControl;
+    /**
+     * How the chat shows the extensions' tools (`buildSessionOptions()` returns them as
+     * `toolLabels`), before `formatAction`. With a session opener, the ones it returns are used
+     * instead.
+     */
+    toolLabels?: ToolLabels;
     /**
      * Colors for the kit's roles (see `Theme`), on top of the kit's defaults: only the roles
      * given change, e.g. `{ toolResult: "yellow", selection: "#00ff00" }`. One theme per
@@ -87,22 +95,6 @@ export interface ChatTuiOptions {
      */
     theme?: Partial<Theme>;
 }
-interface HistoryEntry {
-    text: string;
-    timestamp: string;
-}
-/** Keeps only the most recent `limit` entries (oldest-first order in, oldest-first out). */
-export declare function capHistory(entries: readonly HistoryEntry[], limit: number): HistoryEntry[];
-/** Oldest-first. Missing file reads as empty — nothing to load yet is the normal case. */
-export declare function loadHistory(filePath: string): Promise<HistoryEntry[]>;
-/** Overwrites the whole file (not appended) so a prior prune (oldest entries dropped) sticks. */
-export declare function saveHistory(filePath: string, entries: readonly HistoryEntry[]): Promise<void>;
-/**
- * The command name a typed line would invoke (e.g. "chiste" for both "/chiste" and
- * "/chiste con salsa"), or `null` for a line that isn't a slash command at all (doesn't
- * start with "/") or is just a bare "/" with nothing after it.
- */
-export declare function slashCommandToken(line: string): string | null;
 /**
  * Reads `events` one turn at a time — up to and including a `turn-end` — via manual
  * `.next()` calls, calling `onEvent` for each. Deliberately never uses
@@ -139,4 +131,3 @@ export declare function drainTurn(events: AsyncIterator<AgentEvent>, onEvent: (e
  * interface itself before returning.
  */
 export declare function runChatTui(options: Options | SessionOpener, tuiOptions?: ChatTuiOptions): Promise<void>;
-export {};

package/dist/tui/chatTui.js

@@ -1,66 +1,17 @@
 import readline from "node:readline/promises";
 import { stdin, stdout } from "node:process";
-import { createWriteStream } from "node:fs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import path from "node:path";
-import { createInputQueue, togglePlanMode } from "../core/session.js";
-import { runQuery } from "../core/runner.js";
-import { listRuns, readConversation } from "../core/runs.js";
 import { isSharedQuestionActive, setSharedReadline } from "./terminalInteraction.js";
 import * as ui from "./ui.js";
 import { t } from "../core/messages/index.js";
 import { applyLanguage } from "./language.js";
 import { applyTheme } from "./theme.js";
 import { createConsoleRenderer } from "./consoleRenderer.js";
-import { firstRun, openSession, runDate, runFolderOf, runLabel } from "./runs.js";
-// Only strips picocolors' own SGR sequences (`\x1b[<codes>m`) — the only kind this file
-// ever writes to the console — not a general-purpose ANSI stripper for arbitrary escape
-// sequences (cursor movement, OSC, ...) this kit never emits.
-// eslint-disable-next-line no-control-regex -- \x1b is the ESC byte SGR sequences start with, not an accident
-const ANSI_SGR = /\x1b\[[0-9;]*m/g;
-function stripAnsi(text) {
-    return text.replace(ANSI_SGR, "");
-}
+import { runDate } from "../chat/runs.js";
+import { createChatController } from "../chat/chatController.js";
+export { capHistory, loadHistory, saveHistory, slashCommandToken } from "../chat/history.js";
 const DEFAULT_PROMPT_LABEL = "\n> ";
 const DEFAULT_EXIT_COMMANDS = ["/exit", "/quit"];
 const DEFAULT_HISTORY_LIMIT = 100;
-/** Keeps only the most recent `limit` entries (oldest-first order in, oldest-first out). */
-export function capHistory(entries, limit) {
-    return entries.length > limit ? entries.slice(-limit) : entries.slice();
-}
-/** Oldest-first. Missing file reads as empty — nothing to load yet is the normal case. */
-export async function loadHistory(filePath) {
-    let raw;
-    try {
-        raw = await readFile(filePath, "utf8");
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return [];
-        throw error;
-    }
-    return raw
-        .split("\n")
-        .filter((line) => line.trim().length > 0)
-        .map((line) => JSON.parse(line));
-}
-/** Overwrites the whole file (not appended) so a prior prune (oldest entries dropped) sticks. */
-export async function saveHistory(filePath, entries) {
-    await mkdir(path.dirname(filePath), { recursive: true });
-    const body = entries.map((entry) => JSON.stringify(entry)).join("\n");
-    await writeFile(filePath, entries.length > 0 ? `${body}\n` : "", "utf8");
-}
-/**
- * The command name a typed line would invoke (e.g. "chiste" for both "/chiste" and
- * "/chiste con salsa"), or `null` for a line that isn't a slash command at all (doesn't
- * start with "/") or is just a bare "/" with nothing after it.
- */
-export function slashCommandToken(line) {
-    if (!line.startsWith("/"))
-        return null;
-    const token = line.slice(1).split(/\s/, 1)[0];
-    return token ? token : null;
-}
 /**
  * Reads `events` one turn at a time — up to and including a `turn-end` — via manual
  * `.next()` calls, calling `onEvent` for each. Deliberately never uses
@@ -108,65 +59,48 @@ export async function drainTurn(events, onEvent) {
 export async function runChatTui(options, tuiOptions = {}) {
     applyLanguage(tuiOptions.language);
     applyTheme(tuiOptions.theme);
-    const exitCommands = new Set((tuiOptions.exitCommands ?? DEFAULT_EXIT_COMMANDS).map((c) => c.toLowerCase()));
     const promptLabel = tuiOptions.promptLabel ?? DEFAULT_PROMPT_LABEL;
-    const opener = typeof options === "function" ? options : null;
-    const runsDir = opener ? tuiOptions.runsDir : undefined;
-    if (opener && !runsDir)
-        throw new Error("runChatTui(): a session opener needs `runsDir`.");
-    // The session in use: with runs, the run's folder, rebuilt on /resume.
-    let current = opener && runsDir ? await openSession(opener, await firstRun(runsDir)) : { options: options, run: null };
-    const modeControl = () => current.modeControl ?? tuiOptions.modeControl;
-    let queue = createInputQueue({ modeControl: modeControl() });
-    let run = runQuery(queue.iterable, current.options);
-    let events = run.events[Symbol.asyncIterator]();
     const historyLimit = tuiOptions.historyLimit ?? DEFAULT_HISTORY_LIMIT;
-    let historyEntries = tuiOptions.historyPath ? capHistory(await loadHistory(tuiOptions.historyPath), historyLimit) : [];
+    // The readline interface and its writer, set below once the history it starts with is loaded.
+    const late = {};
+    const controller = await createChatController(options, {
+        exitCommands: tuiOptions.exitCommands ?? DEFAULT_EXIT_COMMANDS,
+        initialPrompt: tuiOptions.initialPrompt,
+        sessionLogPath: tuiOptions.sessionLogPath,
+        promptLabel,
+        agentLabel: tuiOptions.agentLabel,
+        historyPath: tuiOptions.historyPath,
+        historyLimit,
+        runsDir: tuiOptions.runsDir,
+        modeControl: tuiOptions.modeControl,
+        toolLabels: tuiOptions.toolLabels,
+        formatAction: tuiOptions.formatAction,
+        // Nothing here shows them.
+        promptSuggestions: false,
+        // /resume: a numbered list, and a number typed.
+        async pick(title, choices) {
+            late.writeLine(ui.heading(title));
+            choices.forEach((choice) => late.writeLine(`  ${choice.label}`));
+            const answer = (await late.rl.question(t().resumeQuestion)).trim();
+            return choices[Number(answer) - 1]?.value ?? null;
+        },
+    });
     const rl = readline.createInterface({
         input: stdin,
         output: stdout,
-        // readline wants most-recent-first (↑ shows historyEntries' last/newest entry first);
-        // this file is stored oldest-first (append-friendly, reads top-to-bottom like a log).
-        history: historyEntries.map((entry) => entry.text).reverse(),
+        // readline wants most-recent-first (↑ shows the newest entry first); the history is oldest-first.
+        history: [...controller.getState().history].reverse(),
         historySize: historyLimit,
     });
     setSharedReadline(rl);
-    // With runs, the session log is the run's own; it moves with /resume.
-    let sessionLog = null;
-    function openLog() {
-        sessionLog?.end();
-        const file = current.run ? path.join(current.run.dir, "session.log") : tuiOptions.sessionLogPath;
-        sessionLog = file ? createWriteStream(file, { flags: "a" }) : null;
-    }
-    openLog();
-    // Mirrors to the log file only — for text already visible on the terminal some other
-    // way (readline's own prompt + the human's local echo), so it isn't printed twice.
-    function mirror(text) {
-        sessionLog?.write(stripAnsi(text));
-    }
-    // Prints to the console *and* mirrors to the log file — the normal case for anything
-    // this loop itself puts on screen (streamed reply text, action/error lines, ...).
-    // Tracks whether the terminal cursor currently sits at column 0 of a fresh row — true
-    // right after any write ending in "\n" (writeLine's normal case), false right after a
-    // streamed text delta that doesn't (the common case: deltas rarely end mid-sentence on a
-    // newline). Confirmed empirically (against a working chat loop that
-    // ends its streamed text block with an explicit newline): even with `prevRows` reset to 0 above, if the
-    // cursor is left *mid-row* when the next prompt redraws, `[kRefreshLine]`'s `cursorTo(0)`
-    // moves it to column 0 of that *same* row — the row still holding the tail of what we
-    // just wrote — and the following `clearScreenDown` wipes the row from there on, eating
-    // whatever was on it (for a short reply, potentially the whole thing, since "that row" is
-    // its only row). Ending every turn's output on a fresh blank row (see below, after
-    // `drainTurn()`) sidesteps this entirely: `clearScreenDown` then only ever clears blank
-    // space, on any row.
     // Every write goes through the shared console renderer (./consoleRenderer.ts), which
     // tracks whether the cursor sits at the start of a line and never emits a blank line
-    // between consecutive action lines.
+    // between consecutive action lines. The session log is the controller's.
     const renderer = createConsoleRenderer({
-        formatAction: tuiOptions.formatAction,
+        formatAction: controller.formatAction,
         agentLabel: tuiOptions.agentLabel,
         output: (text) => void stdout.write(text),
-        onWrite: (text) => {
-            mirror(text);
+        onWrite: () => {
             // node:readline's `Interface` tracks, on itself, how many terminal rows its own last
             // rendered prompt+line took (`prevRows`), so that the *next* time it redraws (the next
             // `rl.question()` for the following turn, but — confirmed empirically — also any
@@ -188,43 +122,45 @@ export async function runChatTui(options, tuiOptions = {}) {
         },
     });
     const { writeLine } = renderer;
-    // The mode can change from inside the session (the agent leaving plan mode with
-    // present_plan): say so, as /plan does.
-    let unsubscribeMode;
-    const watchMode = () => {
-        unsubscribeMode?.();
-        unsubscribeMode = modeControl()?.subscribe?.((mode) => writeLine(ui.dim(`⏵⏵ ${t().mode(mode)}`)));
-    };
-    watchMode();
-    // Cached lazily (not fetched until the first "/..." line, and only once — the SDK docs
-    // don't promise this list changes mid-session, and re-fetching per line would add a
-    // round-trip to the CLI subprocess for every turn): every registered command name/alias,
-    // built-ins (`/compact`, ...) included, so `/exit`-style local ones never false-flag.
-    let knownCommandTokens = null;
-    async function isKnownSlashCommand(token) {
-        if (!knownCommandTokens) {
-            const commands = await run.supportedCommands();
-            knownCommandTokens = new Set(commands.flatMap((c) => [c.name, ...(c.aliases ?? [])]));
+    Object.assign(late, { rl, writeLine });
+    const toned = (text, tone) => (tone === "plain" ? text : tone === "dim" ? ui.dim(text) : tone === "warn" ? ui.warn(text) : ui.error(text));
+    controller.onEvent((event) => {
+        switch (event.type) {
+            case "agent":
+                if (event.event.type !== "prompt-suggestion")
+                    renderer.render(event.event);
+                return;
+            case "notice":
+                writeLine(toned(event.text, event.tone));
+                return;
+            case "turn-start":
+                renderer.startTurn();
+                return;
+            case "turn-end":
+                // Every turn ends on a fresh row, so readline's redraw only ever clears blank space.
+                renderer.endLine();
+                return;
+            case "conversation":
+                for (const message of event.messages) {
+                    // Printed, not logged: the run's session log already has it.
+                    stdout.write(message.role === "user" ? `${promptLabel}${message.text}\n` : `\n${tuiOptions.agentLabel ? `${tuiOptions.agentLabel} ` : ""}${message.text}\n`);
+                }
+                writeLine(ui.dim(`\n${t().resumed(runDate(event.updatedAt))}`));
+                return;
+            case "mode":
+                // The mode changed (/plan, or the agent leaving plan mode with present_plan): say so.
+                writeLine(ui.dim(`⏵⏵ ${t().mode(event.mode)}`));
+                return;
+            case "user":
+            case "session":
+                return; // readline already echoed the line; nothing to draw for a reopened session
         }
-        return knownCommandTokens.has(token);
-    }
-    let turnInFlight = false;
-    let turnInterrupted = false;
-    function interruptTurn() {
-        if (turnInterrupted)
-            return;
-        turnInterrupted = true;
-        void run.interrupt();
-        writeLine(ui.warn(t().interrupted));
-    }
+    });
     rl.on("SIGINT", () => {
-        if (turnInFlight) {
-            interruptTurn();
-        }
-        else {
-            queue.end();
+        if (controller.getState().busy)
+            controller.interrupt();
+        else
             rl.close();
-        }
     });
     // Esc interrupts the turn in flight too, like Ctrl+C — but, unlike it, never ends the
     // chat, and does nothing while a human-in-the-loop checkpoint is asking on this same
@@ -232,121 +168,30 @@ export async function runChatTui(options, tuiOptions = {}) {
     // already emits "keypress" on stdin, and only reports name "escape" for a lone Esc, not
     // for the Esc-prefixed sequences of arrow/function keys.
     const onKeypress = (_chunk, key) => {
-        if (key?.name === "escape" && turnInFlight && !isSharedQuestionActive())
-            interruptTurn();
+        if (key?.name === "escape" && controller.getState().busy && !isSharedQuestionActive())
+            controller.interrupt();
     };
     stdin.on("keypress", onKeypress);
-    /** Prints the run's earlier conversation (when it has one) and says it was resumed. */
-    async function showConversation(folder) {
-        if (!folder.sessionId)
-            return;
-        for (const message of await readConversation(folder.dir)) {
-            // Printed, not logged: the run's session log already has it.
-            stdout.write(message.role === "user" ? `${promptLabel}${message.text}\n` : `\n${tuiOptions.agentLabel ? `${tuiOptions.agentLabel} ` : ""}${message.text}\n`);
-        }
-        const [summary] = (await listRuns(path.dirname(folder.dir))).filter((r) => path.resolve(r.dir) === path.resolve(folder.dir));
-        writeLine(ui.dim(`\n${t().resumed(runDate(summary?.updatedAt ?? new Date()))}`));
-    }
-    /** /resume: lists the runs, asks for one and switches the session to it. */
-    async function resume() {
-        if (!opener || !runsDir)
-            return;
-        const runs = await listRuns(runsDir);
-        if (runs.length === 0) {
-            writeLine(ui.dim(t().noEarlierRuns));
-            return;
-        }
-        writeLine(ui.heading(t().resumeTitle));
-        runs.forEach((summary, i) => writeLine(`  ${i + 1}. ${runLabel(summary, current.run ?? undefined)}`));
-        const answer = (await rl.question(t().resumeQuestion)).trim();
-        const summary = runs[Number(answer) - 1];
-        if (!answer || !summary || (current.run && path.resolve(summary.dir) === path.resolve(current.run.dir)))
-            return;
-        queue.end();
-        run.close();
-        current = await openSession(opener, await runFolderOf(summary));
-        openLog();
-        queue = createInputQueue({ modeControl: modeControl() });
-        run = runQuery(queue.iterable, current.options);
-        events = run.events[Symbol.asyncIterator]();
-        watchMode();
-        knownCommandTokens = null;
-        await showConversation(current.run);
-    }
     if (tuiOptions.welcomeMessage)
-        writeLine(tuiOptions.welcomeMessage);
+        controller.notice(tuiOptions.welcomeMessage, "plain");
     try {
-        if (current.run)
-            await showConversation(current.run);
-        if (tuiOptions.initialPrompt && !current.run?.sessionId) {
-            mirror(`${promptLabel}${tuiOptions.initialPrompt}\n`);
-            queue.push(tuiOptions.initialPrompt);
-            turnInFlight = true;
-            turnInterrupted = false;
-            renderer.startTurn();
-            await drainTurn(events, renderer.render);
-            turnInFlight = false;
-            renderer.endLine();
-        }
+        await controller.start();
         while (true) {
             let line;
             try {
-                line = (await rl.question(promptLabel)).trim();
+                line = await rl.question(promptLabel);
             }
             catch {
                 break; // the interface closed underneath us (SIGINT/EOF while idle)
             }
-            if (!line)
-                continue;
-            mirror(`${promptLabel}${line}\n`);
-            if (tuiOptions.historyPath) {
-                historyEntries = capHistory([...historyEntries, { text: line, timestamp: new Date().toISOString() }], historyLimit);
-                await saveHistory(tuiOptions.historyPath, historyEntries);
-            }
-            if (exitCommands.has(line.toLowerCase()))
+            if ((await controller.send(line)) === "exit")
                 break;
-            if (runsDir && line.toLowerCase() === "/resume") {
-                await resume();
-                continue;
-            }
-            // Plan mode on and off (the Ink chat also has Shift+Tab); the line says where it is now.
-            if (line.toLowerCase() === "/plan") {
-                const control = modeControl();
-                const next = control ? togglePlanMode(control) : null;
-                // The new mode's line comes from watchMode(); a control without subscribe() says it here.
-                if (!next)
-                    writeLine(ui.dim(t().modeLocked(control?.mode)));
-                else if (!control?.subscribe)
-                    writeLine(ui.dim(`⏵⏵ ${t().mode(next)}`));
-                continue;
-            }
-            // A line that *looks* like a slash command but matches nothing registered (a typo,
-            // an unnamespaced plugin command, ...) would otherwise reach the model as literal
-            // text with no special handling — confirmed empirically (captain-whiskers'
-            // /chiste before it was renamed /captain-whiskers:chiste) that this can look
-            // exactly like nothing happened at all. Caught here, before the turn even starts,
-            // so it's an immediate, unambiguous message instead of a guess at what the model's
-            // silence on unrecognized input might mean.
-            const commandToken = slashCommandToken(line);
-            if (commandToken && !(await isKnownSlashCommand(commandToken))) {
-                writeLine(ui.warn(t().unknownCommand(commandToken)));
-                continue;
-            }
-            queue.push(line);
-            turnInFlight = true;
-            turnInterrupted = false;
-            renderer.startTurn();
-            await drainTurn(events, renderer.render);
-            turnInFlight = false;
-            renderer.endLine();
         }
     }
     finally {
         stdin.off("keypress", onKeypress);
-        queue.end();
-        run.close();
+        controller.close();
         setSharedReadline(null);
         rl.close();
-        sessionLog?.end();
     }
 }

package/dist/tui/extensionCommand.d.ts

@@ -0,0 +1,30 @@
+import { type ExtensionDirs } from "../core/externalExtensions.js";
+export { chatExtensionsCommand, describe } from "../chat/extensions.js";
+/**
+ * The `extension` command an agent exposes in its own binary (#37), e.g. `captain extension add
+ * ./jokebook --project`: installs, removes, enables, disables and lists the extensions in its two
+ * scopes. Returns `false` when `argv` isn't this command (so the agent goes on), and sets
+ * `process.exitCode` to 1 on an error.
+ *
+ * - `extension list`
+ * - `extension info <name>`: its metadata, what it offers and where its README is
+ * - `extension add <folder | git URL[#ref] | plugin[@marketplace]> [--project] [--path <subfolder>] [--yes]`
+ * - `extension remove|enable|disable <name> [--project | --agent]`
+ * - `extension search [words]`: what the known marketplaces offer
+ * - `extension marketplace add <folder | git URL[#ref] | owner/repo> [--yes]`, `list`, `update [name]`, `remove <name>`
+ *
+ * Without a scope, `add` installs into the agent's (the project's when the agent has no scope of
+ * its own); the others act where the extension is, the project's first. The marketplaces live in
+ * the same folder. `official` is the agent's own marketplace (a folder or git URL): known without
+ * asking, and installed from without a confirmation. Any other is added after a warning and
+ * typing its name, and installing from it asks first; `--yes` answers for the person (a script).
+ */
+export declare function runExtensionCommand(argv: readonly string[], options: {
+    dirs: ExtensionDirs;
+    command?: string;
+    write?: (line: string) => void;
+    /** The agent's official marketplace: a folder or a git URL (`#ref`). */
+    official?: string;
+    /** Asks the person (a confirmation); by default on the terminal, and nothing without one. */
+    ask?: (question: string) => Promise<string>;
+}): Promise<boolean>;