@falkenslab/agent-kit 0.18.0 → 0.19.0

package/assets/extension-launcher.mjs

@@ -0,0 +1,24 @@
+// Starts an external extension's MCP server (ADR-025, #37) with a clean environment: the SDK
+// merges a server's `env` with the agent's own (confirmed empirically), so the kit starts this
+// launcher instead, which keeps only the variables the system needs and those the extension
+// declares, then loads the server in this same process.
+//
+// Usage: node extension-launcher.mjs <server script> <JSON array of variable names it may see> [its arguments…]
+import { pathToFileURL } from "node:url";
+
+const [entry, declared = "[]", ...args] = process.argv.slice(2);
+if (!entry) {
+  console.error("extension-launcher: no server entry given");
+  process.exit(1);
+}
+
+// What any process may need to run, on Windows and elsewhere; never a credential.
+const SYSTEM = ["PATH", "PATHEXT", "SYSTEMROOT", "SYSTEMDRIVE", "WINDIR", "COMSPEC", "TEMP", "TMP", "TMPDIR", "HOME", "USERPROFILE", "APPDATA", "LOCALAPPDATA", "LANG", "LC_ALL", "TZ"];
+const allowed = new Set([...SYSTEM, ...JSON.parse(declared)].map((name) => name.toUpperCase()));
+for (const name of Object.keys(process.env)) {
+  if (!allowed.has(name.toUpperCase())) delete process.env[name];
+}
+
+// The server reads its own arguments from argv: its own, none of the launcher's.
+process.argv = [process.argv[0], entry, ...args];
+await import(pathToFileURL(entry).href);

package/dist/chat/chatController.d.ts

@@ -0,0 +1,264 @@
+import type { Options, SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
+import type { Mode } from "../core/agentSpec.js";
+import { type ApprovalPrompt, type ChoiceSettings } from "../core/interaction.js";
+import { type Language } from "../core/language.js";
+import { type AgentEvent, type AgentRun, type SessionUsage } from "../core/runner.js";
+import { type RunFolder } from "../core/runs.js";
+import { type ExtensionsStatus, type ModeControl } from "../core/session.js";
+import { type Todo } from "../core/todos.js";
+import { type ToolLabels } from "../core/toolLabels.js";
+import type { ToolPhrase } from "../core/messages/index.js";
+import { type SessionOpener } from "./runs.js";
+/**
+ * The chat's logic without an interface (ADR-026, #39): opening, reopening and resuming the
+ * session, the input queue and the agent run, the person's lines (commands or turns), the
+ * session log and the history. A view (the terminal chats, the web page) draws its `state`, a
+ * plain-data snapshot, or follows its `events`, and sends it the person's actions.
+ */
+/** What the controller needs besides the session: the chats' options it acts on. */
+export interface ChatSettings {
+    /** Lines (trimmed, case-insensitive) that end the chat. Default `/exit`, `/quit`. */
+    exitCommands?: readonly string[];
+    /** The first turn, sent before the person types anything, unless the run resumes a conversation. */
+    initialPrompt?: string;
+    /** The session log without runs (with runs, each run's `session.log`). */
+    sessionLogPath?: string;
+    /** The label before the person's lines in the session log. */
+    promptLabel?: string;
+    /** The label before the agent's reply in the session log. */
+    agentLabel?: string;
+    /** The person's lines, kept across runs (↑/↓). */
+    historyPath?: string;
+    historyLimit?: number;
+    /** With a session opener: where the runs are (required then). */
+    runsDir?: string;
+    /** Without one, the session's mode control and tool labels. */
+    modeControl?: ModeControl;
+    toolLabels?: ToolLabels;
+    /** Tool call labels and folded-group phrases on top of the kit's and the extensions'. */
+    formatAction?: (toolName: string, input: unknown) => string;
+    toolPhrase?: (toolName: string) => ToolPhrase | undefined;
+    /** Runs the agent: the SDK's (`runQuery()`) by default; another for tests, or a host of its own. */
+    runQuery?: (prompt: AsyncIterable<SDKUserMessage>, options: Options) => AgentRun;
+    /** The SDK's prompt suggestions (on by default). */
+    promptSuggestions?: boolean;
+    /**
+     * How a choice in place of the prompt is asked (the conversations of `/resume`): a terminal
+     * view asks it its way; without it, it's the state's `choice`, answered with `choose()`.
+     */
+    pick?: (title: string, options: {
+        label: string;
+        value: string;
+    }[]) => Promise<string | null>;
+    /** The view's own commands, by name without the slash (a terminal's `/copy`): logged and kept in the history like any line, then run by the view. */
+    commands?: Record<string, () => void | Promise<void>>;
+    /**
+     * Who asks the person at a checkpoint: `"view"` (the default) leaves the interaction port to
+     * the view (a terminal's panels); `"state"` installs the controller's own, whose panel is the
+     * state's `panel`, answered with `answer()`.
+     */
+    panels?: "view" | "state";
+}
+/** One tool call in the transcript. */
+export interface TranscriptCall {
+    id?: string;
+    toolName: string;
+    label: string;
+    result: {
+        isError: boolean;
+        text: string;
+    } | null;
+    /** What a subagent it started did, by label. */
+    children: string[];
+}
+/** One block of the conversation, as a view shows it. */
+export type TranscriptEntry = {
+    id: number;
+    kind: "user";
+    text: string;
+} | {
+    id: number;
+    kind: "agent";
+    text: string;
+} | {
+    id: number;
+    kind: "tools";
+    calls: TranscriptCall[];
+} | {
+    id: number;
+    kind: "notice";
+    tone: NoticeTone;
+    text: string;
+} | {
+    id: number;
+    kind: "turn-summary";
+    seconds: number;
+};
+/** How a notice reads: plain (the agent's own text), dim (a kit's aside), a warning or an error. */
+export type NoticeTone = "plain" | "dim" | "warn" | "error";
+/** What a checkpoint asks: an approval, a confirmation after a manual step, free text, or a choice. */
+export type ChatQuestion = {
+    kind: "decision" | "manual" | "text";
+    prompt: ApprovalPrompt;
+} | {
+    kind: "choice";
+    prompt: ApprovalPrompt;
+    choice: ChoiceSettings;
+};
+/** A checkpoint waiting for the person's answer, with `panels: "state"`. */
+export type ChatPanel = ChatQuestion & {
+    id: number;
+};
+/** The chat's state: plain data, the same for any view. */
+export interface ChatState {
+    transcript: TranscriptEntry[];
+    /** A turn is running. */
+    busy: boolean;
+    turnStartedAt: number | null;
+    /** The label of the agent's latest action in this turn, and of a subagent's. */
+    activity: string | null;
+    subagentActivity: string | null;
+    /** The agent's task list while any task is open. */
+    todos: Todo[] | null;
+    mode: Mode | null;
+    /** The modes the person can switch between (none in autonomous mode). */
+    switchableModes: readonly Mode[];
+    turns: number;
+    usage: SessionUsage | null;
+    /** How full the context window is (0-100), after the latest turn. */
+    contextPercent: number | null;
+    /** The model's predicted next prompt. */
+    suggestion: string | null;
+    /** The slash commands the person can type: the session's and the chat's own. */
+    commands: string[];
+    /** The same, with what each does and what it takes after it, for a view that lists them. */
+    commandDetails: {
+        name: string;
+        description: string;
+        argumentHint: string;
+    }[];
+    /** The kit's language now (it can change: `setLanguage()`). */
+    language: Language;
+    /** The person's earlier lines, oldest first. */
+    history: string[];
+    /** A checkpoint waiting for an answer (`panels: "state"`). */
+    panel: ChatPanel | null;
+    /** A choice waiting for an answer (without `pick`). */
+    choice: {
+        title: string;
+        options: {
+            label: string;
+            value: string;
+        }[];
+    } | null;
+    /** The run in use, with runs. */
+    run: RunFolder | null;
+    extensions: ExtensionsStatus | null;
+    closed: boolean;
+}
+/** What happens in the chat, in order, for a view that draws as it goes (a terminal). */
+export type ChatEvent = {
+    type: "agent";
+    event: AgentEvent;
+} | {
+    type: "user";
+    text: string;
+} | {
+    type: "notice";
+    tone: NoticeTone;
+    text: string;
+} | {
+    type: "turn-start";
+} | {
+    type: "turn-end";
+    seconds: number;
+}
+/** An earlier conversation to draw: the run's, at start or after `/resume`. */
+ | {
+    type: "conversation";
+    messages: {
+        role: "user" | "assistant";
+        text: string;
+    }[];
+    updatedAt: Date;
+    fromResume: boolean;
+}
+/** The mode changed (the person, or the agent leaving plan mode). */
+ | {
+    type: "mode";
+    mode: Mode;
+}
+/** The session was opened again (resumed, or an extension enabled or disabled). */
+ | {
+    type: "session";
+};
+/** A chat controller: its state, events and actions (see `createChatController()`). */
+export type ChatController = Awaited<ReturnType<typeof createChatController>>;
+/**
+ * Opens the chat's session (the first run with a session opener, `--continue` picking the
+ * latest) and loads the history; `start()` then draws the run's conversation and sends the
+ * initial prompt, `send()` each line the person types.
+ */
+export declare function createChatController(options: Options | SessionOpener, settings?: ChatSettings): Promise<{
+    /** The state now. */
+    getState: () => ChatState;
+    /** Calls `listener` with every new state; returns how to stop. */
+    subscribe(listener: (state: ChatState) => void): () => void;
+    /** Calls `listener` with every event, in order; returns how to stop. */
+    onEvent(listener: (event: ChatEvent) => void): () => void;
+    /** Tool call labels and phrases with the extensions' (for a view that renders events itself). */
+    formatAction: (toolName: string, toolInput: unknown) => string;
+    toolPhrase: (toolName: string) => ToolPhrase | undefined;
+    /** The folder the session works in. */
+    cwd: () => string;
+    /** Draws the run's earlier conversation, then sends the initial prompt (for a new run). */
+    start(): Promise<void>;
+    /**
+     * A line the person sent: an exit command ("exit"), one of the chat's commands, or a turn,
+     * resolved when it ends. An unknown slash command is caught before it reaches the model.
+     */
+    send(raw: string): Promise<"exit" | void>;
+    /** Stops the turn running, if any. */
+    interrupt(): void;
+    /** Switches to a mode the session allows; says so when it can't. */
+    setMode(mode: Mode): void;
+    /** The next mode the session allows (Shift+Tab). */
+    cycleMode(): void;
+    /** Into plan mode, or back to the mode it was entered from (`/plan`). */
+    togglePlan(): void;
+    /** The runs to resume, newest first, labelled for a person. */
+    listRuns(): Promise<{
+        label: string;
+        dir: string;
+    }[]>;
+    /** `/resume`: with `dir`, switches to that run; without it, asks which. */
+    resume(dir?: string): Promise<void>;
+    /**
+     * Starts a new conversation in a new run, leaving the current one to resume later: what a
+     * graphical view offers instead of quitting and starting again.
+     */
+    newConversation(): Promise<void>;
+    /** Enables or disables an installed extension, and opens the session again with the same conversation. */
+    setExtension(name: string, enabled: boolean): Promise<void>;
+    /**
+     * Switches the kit's language (`switchLanguage()`) and opens the session again in it, keeping
+     * the conversation: the agent's next reply, the labels and the kit's notices come in it.
+     * `note` adds the host's own words to what the model is told (the agent's name in that
+     * language: the earlier conversation keeps pulling the old one).
+     */
+    setLanguage(language: Language, { note }?: {
+        note?: string;
+    }): Promise<void>;
+    /** What an active extension hands the host (its `api`), e.g. the sources' `addSource`; `undefined` when it isn't active. */
+    api<T = Record<string, unknown>>(extension: string): T | undefined;
+    /** Answers the state's panel (`panels: "state"`). */
+    answer(panelId: number, answer: string): void;
+    /** Answers the state's choice (`null`: cancelled). */
+    choose(value: string | null): void;
+    /** A notice from the view (a welcome): in the transcript and the session log. */
+    notice: (text: string, tone?: NoticeTone) => void;
+    /** The agent's text in the latest turn that ended, plain (for `/copy`). */
+    lastReply: () => string;
+    /** Ends the chat: the agent run, the session log, the controller's port. */
+    close(): void;
+}>;