@falkenslab/agent-kit 0.12.0 → 0.13.0

package/README.md

@@ -1,5 +1,12 @@
 # agent-kit
 
+[![npm](https://img.shields.io/npm/v/@falkenslab/agent-kit?logo=npm)](https://www.npmjs.com/package/@falkenslab/agent-kit)
+[![npm downloads](https://img.shields.io/npm/dm/@falkenslab/agent-kit)](https://www.npmjs.com/package/@falkenslab/agent-kit)
+[![types](https://img.shields.io/npm/types/@falkenslab/agent-kit)](https://www.npmjs.com/package/@falkenslab/agent-kit)
+[![node](https://img.shields.io/node/v/@falkenslab/agent-kit)](https://nodejs.org/)
+[![license](https://img.shields.io/npm/l/@falkenslab/agent-kit)](LICENSE)
+[![docs](https://img.shields.io/badge/docs-falkenslab.github.io%2Fagent--kit-d77757)](https://falkenslab.github.io/agent-kit/)
+
 A foundation for building AI agents on top of the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk). It isn't an agent itself: it solves once what every agent needs (human oversight, safety, memory and a good terminal interface), so each concrete agent only has to write what belongs to its own domain: what it knows how to do, with which tools, and how it talks.
 
 ## What an agent built with it can do
@@ -12,6 +19,7 @@ A foundation for building AI agents on top of the [Claude Agent SDK](https://www
 - **Stay within limits.** It only reads and writes in the folders that belong to it, and never in protected files, such as one holding passwords.
 - **Use external tools.** MCP servers of its own or of the project, and skills and commands organized in plugins.
 - **Leave a trail.** It records every action and the whole conversation, with secrets hidden.
+- **Look the way you want.** The terminal's colors come from a theme by roles (the agent's replies, tool results, the focused option, borders…): pass only the ones you want to change, as a color name, a hex or a function.
 - **Chat in a terminal the way Claude Code does.** Full screen, with the reply written live and its markdown already formatted, the tools it uses summed up in one line (Ctrl+O unfolds it), panels for approvals, history and search, a suggestion for the next message, pasted blocks, file mentions with `@`, mouse selection (right-click to copy), and the agent's status in the tab and in the Windows taskbar.
 - **Also work without a terminal.** The same foundation runs inside a desktop app or a server, which bring their own interface.
 
@@ -66,14 +74,17 @@ await runChatInk((run) => buildSessionOptions(config, run.dir, spec, { run }), {
   header: { title: "My agent" },
   mode: config.mode, // Shift+Tab switches between guided and step by step
   fullscreen: true,
+  theme: { toolResult: "gray", selection: "#ffb86c" }, // only the colors you want to change
 });
 ```
 
 Save it as `agent.ts` in a project with the kit and `tsx` installed and `"type": "module"` in its `package.json`, and run it with `npx tsx agent.ts`. Captain Whiskers is this same skeleton with more pieces: skills, subagents and its logo.
 
-## More details
+## Documentation
+
+The full documentation is at **[falkenslab.github.io/agent-kit](https://falkenslab.github.io/agent-kit/)**: a tutorial, guides for every part of the kit (modes, human in the loop, security, tools, subagents, the knowledge base, the terminal UI, runs, languages, themes, hosts without a terminal), recipes, and an API reference generated from the source, for each released version.
 
-The specification in [`.minispec/`](./.minispec/README.md) explains how each part is built and why, including the SDK behaviors checked by hand that motivate several of its safeguards. Captain Whiskers' code is the quickest way to see how an agent is put together.
+For whoever works on the kit itself, the specification in [`.minispec/`](./.minispec/README.md) explains how each part is built and why, including the SDK behaviors checked by hand that motivate several of its safeguards.
 
 ## Development
 
@@ -83,6 +94,9 @@ The specification in [`.minispec/`](./.minispec/README.md) explains how each par
 | `npm run typecheck` | Checks the types without building |
 | `npm run lint` | Checks the code style |
 | `npm test` | Runs all the tests |
+| `npm run docs:install` | Installs the documentation site's dependencies (once) |
+| `npm run docs:start` | Serves the documentation site locally, reloading on changes |
+| `npm run docs:build` | Builds the documentation site (fails on broken links) |
 
 To run a single test file:
 

package/dist/core/claudeAuth.d.ts

@@ -1,3 +1,4 @@
+/** What `resolveClaudeAuth()` and `ensureClaudeAuth()` accept besides the environment. */
 export interface ClaudeAuthConfig {
     /** A previously-resolved token the caller already has (from wherever it stores one, if
      * anywhere) — this module owns no persistence of its own, unlike an earlier version

package/dist/core/hooks/transcriptLogger.d.ts

@@ -1,4 +1,5 @@
 import type { HookCallback } from "@anthropic-ai/claude-agent-sdk";
+/** The two hooks that write `transcript.jsonl`: register `preToolUse` as a `PreToolUse` hook and `postToolUse` as a `PostToolUse` one. */
 export interface TranscriptLogger {
     preToolUse: HookCallback;
     postToolUse: HookCallback;

package/dist/core/interaction.d.ts

@@ -1,3 +1,4 @@
+/** What a checkpoint shows the person: a title, detail lines and, in a plain terminal, the question. */
 export interface ApprovalPrompt {
     title: string;
     lines: string[];
@@ -25,5 +26,7 @@ export interface InteractionPort {
     /** A one-way message for the person. */
     notify(message: string): void;
 }
+/** Installs the port every checkpoint asks through (`null`: answer through the response file only). One per process. */
 export declare function setInteractionPort(port: InteractionPort | null): void;
+/** The port checkpoints ask through right now, or `null`. */
 export declare function getInteractionPort(): InteractionPort | null;

package/dist/core/interaction.js

@@ -1,7 +1,9 @@
 let current = null;
+/** Installs the port every checkpoint asks through (`null`: answer through the response file only). One per process. */
 export function setInteractionPort(port) {
     current = port;
 }
+/** The port checkpoints ask through right now, or `null`. */
 export function getInteractionPort() {
     return current;
 }

package/dist/core/language.d.ts

@@ -1,5 +1,6 @@
 /** The languages the kit's own texts come in. */
 export type Language = "en" | "es" | "fr" | "de";
+/** The language codes the kit's texts come in. */
 export declare const SUPPORTED_LANGUAGES: readonly Language[];
 /** Each language's name in English, as the model is told it (the kit's text for the model stays in English). */
 export declare const LANGUAGE_NAMES: Record<Language, string>;
@@ -14,6 +15,7 @@ export interface LanguageSources {
     /** The environment, for `LC_ALL`, `LC_MESSAGES` and `LANG` (e.g. "fr_FR.UTF-8"). */
     env?: Readonly<Record<string, string | undefined>>;
 }
+/** The result of `resolveLanguage()`: the language to use and why any asked-for code was skipped. */
 export interface ResolvedLanguage {
     language: Language;
     /** One line per code that was asked for and isn't supported (English text, for the caller to show). */

package/dist/core/language.js

@@ -1,3 +1,4 @@
+/** The language codes the kit's texts come in. */
 export const SUPPORTED_LANGUAGES = ["en", "es", "fr", "de"];
 /** Each language's name in English, as the model is told it (the kit's text for the model stays in English). */
 export const LANGUAGE_NAMES = { en: "English", es: "Spanish", fr: "French", de: "German" };

package/dist/core/runner.d.ts

@@ -109,12 +109,14 @@ export interface SessionUsage {
 export declare function visibleErrors(errors: readonly string[]): string[];
 /** A tool result's content as plain text: its text parts joined, anything else skipped. */
 export declare function toolResultText(content: unknown): string;
+/** How full the session's context window is (see `AgentRun.contextUsage()`). */
 export interface ContextUsage {
     /** 0-100. */
     percentage: number;
     totalTokens: number;
     maxTokens: number;
 }
+/** A running session, as `runQuery()` returns it: its events and the controls of the SDK's `Query`. */
 export interface AgentRun {
     /** Normalized events for this run — iterate with `for await`. */
     events: AsyncIterable<AgentEvent>;

package/dist/core/runs.d.ts

@@ -10,6 +10,7 @@ export interface RunFolder {
     /** The SDK session kept in this folder (to resume it), or null for a new run. */
     sessionId: string | null;
 }
+/** A run that kept a conversation, as `listRuns()` lists it for a person to pick (see `/resume`). */
 export interface RunSummary extends RunFolder {
     sessionId: string;
     /** When the run's conversation last changed. */
@@ -17,6 +18,7 @@ export interface RunSummary extends RunFolder {
     /** The human's last message, on one line (empty if none). */
     lastMessage: string;
 }
+/** One message of a kept conversation: something the person wrote, or the agent's text reply. */
 export interface ConversationMessage {
     role: "user" | "assistant";
     text: string;

package/dist/core/session.d.ts

@@ -47,6 +47,7 @@ export interface ModeControl {
     /** Switches to `next` if this session allows it; returns whether it did. */
     set(next: Mode): boolean;
 }
+/** A `ModeControl` starting at `initial` (`buildSessionOptions()` returns one for its session). */
 export declare function createModeControl(initial: Mode): ModeControl;
 /**
  * User message queue backed by a single long-lived generator, for any multi-turn

package/dist/core/session.js

@@ -186,6 +186,7 @@ function skillList(skills, includeKnowledgeBase) {
         return "all";
     return includeKnowledgeBase ? [...new Set([...skills, ...KNOWLEDGE_SKILLS])] : skills;
 }
+/** A `ModeControl` starting at `initial` (`buildSessionOptions()` returns one for its session). */
 export function createModeControl(initial) {
     let current = initial;
     const switchable = initial === "autonomous" ? ["autonomous"] : ["guided", "interactive"];

package/dist/core/toolLabels.d.ts

@@ -8,8 +8,14 @@
  * Playwright's browser_* cases) via `createFriendlyToolLabel()`. The kit's own labels are in
  * the current language (see messages/).
  */
+/** Cuts `text` to `max` characters, with "…" at the end. */
 export declare function truncate(text: string, max?: number): string;
+/**
+ * Cuts a path to `max` characters from the front, with "…": unlike `truncate()` (which cuts
+ * the tail off long freeform text), a path's most useful part, the file name, is at the end.
+ */
 export declare function truncatePath(text: string, max?: number): string;
+/** An agent's labels for its own tools: the tool's short name and input, to a label, or `undefined` for the kit's default. */
 export type ToolDescriber = (shortName: string, input: Record<string, unknown>) => string | undefined;
 /**
  * Builds a `friendlyToolLabel(toolName, toolInput)` — `describe` lets the host agent

package/dist/core/toolLabels.js

@@ -9,12 +9,14 @@ import { t } from "./messages/index.js";
  * Playwright's browser_* cases) via `createFriendlyToolLabel()`. The kit's own labels are in
  * the current language (see messages/).
  */
+/** Cuts `text` to `max` characters, with "…" at the end. */
 export function truncate(text, max = 60) {
     return text.length > max ? `${text.slice(0, max)}…` : text;
 }
-// Unlike truncate() above (which cuts the tail off long freeform text), a path's most
-// useful part — the filename — is at the *end*, so this keeps the tail and cuts the
-// front instead.
+/**
+ * Cuts a path to `max` characters from the front, with "…": unlike `truncate()` (which cuts
+ * the tail off long freeform text), a path's most useful part, the file name, is at the end.
+ */
 export function truncatePath(text, max = 60) {
     return text.length > max ? `…${text.slice(text.length - max + 1)}` : text;
 }

package/dist/core/tools/humanApproval.d.ts

@@ -1,3 +1,4 @@
+/** The approval tool's texts: its description (when the model should call it) and what it returns when approved or rejected. */
 export interface HumanApprovalTexts {
     description: string;
     approved: string;

package/dist/core/tools/manualLogin.d.ts

@@ -1,3 +1,4 @@
+/** The manual-intervention tool's texts: for the model (`toolDescription`, `confirmedMessage`) and for the person (the checkpoint). */
 export interface ManualInterventionTexts {
     toolDescription: string;
     confirmedMessage: string;

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * as ui from "./tui/ui.js";
+export { setTheme, getTheme, DEFAULT_THEME, type Theme, type ThemeColor } from "./tui/theme.js";
 export { isExitPromptError } from "./tui/promptErrors.js";
 export { allowAnyMcpTool } from "./core/mcpPermissions.js";
 export { createPromptLoader } from "./core/promptTemplate.js";

package/dist/index.js

@@ -1,6 +1,7 @@
 import { setInteractionPort } from "./core/interaction.js";
 import { terminalInteractionPort } from "./tui/terminalInteraction.js";
 export * as ui from "./tui/ui.js";
+export { setTheme, getTheme, DEFAULT_THEME } from "./tui/theme.js";
 export { isExitPromptError } from "./tui/promptErrors.js";
 export { allowAnyMcpTool } from "./core/mcpPermissions.js";
 export { createPromptLoader } from "./core/promptTemplate.js";

package/dist/tui/chatTui.d.ts

@@ -1,6 +1,8 @@
 import type { Options } from "@anthropic-ai/claude-agent-sdk";
 import { type AgentEvent } from "../core/runner.js";
+import { type Theme } from "./theme.js";
 import { type SessionOpener } from "./runs.js";
+/** Options of the chats (`runChatTui()`, and `runChatInk()` through `InkChatOptions`). */
 export interface ChatTuiOptions {
     /**
      * Turns a tool call into a one-line console label. Defaults to `createFriendlyToolLabel()`
@@ -70,6 +72,12 @@ export interface ChatTuiOptions {
      * conversation, tool results included and not redacted: keep it out of version control.
      */
     runsDir?: string;
+    /**
+     * 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
+     * process: without this option, the one already set stays.
+     */
+    theme?: Partial<Theme>;
 }
 interface HistoryEntry {
     text: string;

package/dist/tui/chatTui.js

@@ -10,6 +10,7 @@ import { isSharedQuestionActive, setSharedReadline } from "./terminalInteraction
 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
@@ -106,6 +107,7 @@ 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;

package/dist/tui/consoleRenderer.d.ts

@@ -1,4 +1,5 @@
 import type { AgentEvent } from "../core/runner.js";
+/** Options of `createConsoleRenderer()`. */
 export interface ConsoleRendererOptions {
     /** Turns a tool call into its console label; defaults to `createFriendlyToolLabel()`. */
     formatAction?: (toolName: string, toolInput: unknown) => string;
@@ -9,6 +10,7 @@ export interface ConsoleRendererOptions {
     /** Called after every write with the same text, e.g. to mirror it into a log file. */
     onWrite?: (text: string) => void;
 }
+/** Prints `runQuery()`'s events as plain console lines (see `createConsoleRenderer()`). */
 export interface ConsoleRenderer {
     /** Prints one normalized event from `runQuery()`. */
     render(event: AgentEvent): void;

package/dist/tui/ink/SessionView.js

@@ -9,6 +9,7 @@ import { isFocusReport } from "./terminalStatus.js";
 import { fitWidth, stripAnsi } from "./lineBuffer.js";
 import * as ui from "../ui.js";
 import { t } from "../../core/messages/index.js";
+import { inkColor } from "../theme.js";
 // Numbered as in the Claude Code CLI's permission prompt; the digits and y/n/q answer too.
 const decisionOptions = () => [
     { label: `1. ${t().yes}`, value: "y" },
@@ -17,7 +18,6 @@ const decisionOptions = () => [
 ];
 const manualOptions = () => [{ label: `1. ${t().doneContinue}`, value: "continue" }];
 const DECISION_KEYS = { "1": "y", "2": "n", "3": "q", y: "y", n: "n", q: "q" };
-const ACCENT_HEX = "#d77757";
 /**
  * The preview's lines, capped so the whole live area stays shorter than the terminal: Ink
  * clears the entire screen (scrollback included) to redraw anything taller, and a step-gate
@@ -39,7 +39,7 @@ function CheckpointPanel({ checkpoint, renderApproval }) {
     });
     const { prompt } = checkpoint;
     const { stdout } = useStdout();
-    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: ACCENT_HEX, paddingX: 1, children: [renderApproval ? (renderApproval(prompt)) : (_jsxs(_Fragment, { children: [_jsx(Text, { bold: true, children: prompt.title }), previewLines(prompt.lines, stdout.rows).map((line, index) => (_jsx(Text, { children: line }, index))), !decision && prompt.question ? _jsx(Text, { dimColor: true, children: prompt.question }) : null] })), decision ? (_jsx(Box, { marginTop: 1, children: _jsx(Text, { children: t().proceed }) })) : null, _jsx(Box, { marginTop: decision ? 0 : 1, children: _jsx(Select, { options: decision ? decisionOptions() : manualOptions(), onChange: (value) => checkpoint.answer(decision ? value : "") }, checkpoint.id) })] }));
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: inkColor("accent"), paddingX: 1, children: [renderApproval ? (renderApproval(prompt)) : (_jsxs(_Fragment, { children: [_jsx(Text, { bold: true, children: prompt.title }), previewLines(prompt.lines, stdout.rows).map((line, index) => (_jsx(Text, { children: line }, index))), !decision && prompt.question ? _jsx(Text, { dimColor: true, children: prompt.question }) : null] })), decision ? (_jsx(Box, { marginTop: 1, children: _jsx(Text, { children: t().proceed }) })) : null, _jsx(Box, { marginTop: decision ? 0 : 1, children: _jsx(Select, { options: decision ? decisionOptions() : manualOptions(), onChange: (value) => checkpoint.answer(decision ? value : "") }, checkpoint.id) })] }));
 }
 function formatTokens(count) {
     return count >= 1000 ? `${(count / 1000).toFixed(1)}k` : String(count);

package/dist/tui/ink/header.d.ts

@@ -1,3 +1,4 @@
+/** The top of the Ink chat: a title, optional fields and an optional logo. */
 export interface HeaderInfo {
     title: string;
     /** Shown under the title as "name value" pairs, e.g. the workspace or the model. */

package/dist/tui/ink/inkTheme.d.ts

@@ -0,0 +1,9 @@
+import type { ReactNode } from "react";
+/**
+ * `@inkjs/ui`'s components in the kit's theme: the focused option of a `Select` (and its
+ * `❯`) in the theme's `selection` color and bold, instead of the library's blue, which on
+ * most dark terminals is a navy that barely shows.
+ */
+export declare function KitTheme({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/tui/ink/inkTheme.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { defaultTheme, extendTheme, ThemeProvider } from "@inkjs/ui";
+import { inkColor } from "../theme.js";
+/**
+ * `@inkjs/ui`'s components in the kit's theme: the focused option of a `Select` (and its
+ * `❯`) in the theme's `selection` color and bold, instead of the library's blue, which on
+ * most dark terminals is a navy that barely shows.
+ */
+export function KitTheme({ children }) {
+    const selection = inkColor("selection");
+    const theme = extendTheme(defaultTheme, {
+        components: {
+            Select: {
+                styles: {
+                    focusIndicator: () => ({ color: selection }),
+                    label: ({ isFocused, isSelected }) => ({
+                        color: isFocused ? selection : isSelected ? "green" : undefined,
+                        bold: isFocused,
+                    }),
+                },
+            },
+        },
+    });
+    return _jsx(ThemeProvider, { theme: theme, children: children });
+}

package/dist/tui/ink/markdown.js

@@ -79,16 +79,57 @@ function renderList(list, width) {
     });
     return lines;
 }
+const visibleWidth = (text) => stringWidth(stripAnsi(text));
+/**
+ * The widest columns shrunk, one column at a time, until the grid (`widths` plus one border
+ * and two spaces of padding per column, plus the last border) fits `room`; a column never
+ * goes below 3.
+ */
+function fitColumns(widths, room) {
+    const fitted = [...widths];
+    const total = () => fitted.reduce((sum, w) => sum + w, 0) + fitted.length * 3 + 1;
+    while (total() > room) {
+        const widest = fitted.indexOf(Math.max(...fitted));
+        if (fitted[widest] <= 3)
+            break;
+        fitted[widest]--;
+    }
+    return fitted;
+}
+/**
+ * A table as a grid: dimmed box-drawing borders, one space of padding, the header in bold,
+ * a rule between rows and each column aligned as its markdown says. A table wider than the
+ * room shrinks its widest columns and wraps their cells onto more lines.
+ */
 function renderTable(table, width) {
     const cell = (c) => inline(c.tokens, c.text);
-    const header = table.header.map(cell);
-    const rows = table.rows.map((row) => row.map(cell));
-    const widths = header.map((h, i) => Math.max(stringWidth(stripAnsi(h)), ...rows.map((row) => stringWidth(stripAnsi(row[i] ?? "")))));
-    const pad = (text, i) => text + " ".repeat(Math.max(0, widths[i] - stringWidth(stripAnsi(text))));
-    const line = (cells) => cells.map(pad).join("  ").trimEnd();
-    const out = [ui.bold(line(header)), ui.dim(widths.map((w) => "─".repeat(w)).join("  ")), ...rows.map(line)];
-    // A table wider than the room is cut, not wrapped: wrapping would scramble the columns.
-    return out.map((row) => (stringWidth(stripAnsi(row)) > width ? wrapAnsi(row, width, { hard: true, wordWrap: false }).split("\n")[0] : row));
+    const header = table.header.map((c) => ui.bold(cell(c)));
+    const rows = table.rows.map((row) => table.header.map((_, i) => (row[i] ? cell(row[i]) : "")));
+    const natural = header.map((h, i) => Math.max(1, visibleWidth(h), ...rows.map((row) => visibleWidth(row[i]))));
+    const widths = fitColumns(natural, width);
+    const place = (text, i) => {
+        const room = widths[i] - visibleWidth(text);
+        if (room <= 0)
+            return text;
+        if (table.align[i] === "right")
+            return " ".repeat(room) + text;
+        if (table.align[i] === "center")
+            return " ".repeat(Math.floor(room / 2)) + text + " ".repeat(Math.ceil(room / 2));
+        return text + " ".repeat(room);
+    };
+    const border = (left, middle, right) => ui.dim(left + widths.map((w) => "─".repeat(w + 2)).join(middle) + right);
+    const bar = ui.dim("│");
+    // A row's cells wrapped to their columns: as many lines as its tallest cell.
+    const rowLines = (cells) => {
+        const wrapped = cells.map((text, i) => wrapAnsi(text, widths[i], { hard: true, trim: true }).split("\n"));
+        const height = Math.max(...wrapped.map((lines) => lines.length));
+        return Array.from({ length: height }, (_, line) => `${bar}${wrapped.map((lines, i) => ` ${place(lines[line] ?? "", i)} `).join(bar)}${bar}`);
+    };
+    const lines = [border("┌", "┬", "┐"), ...rowLines(header)];
+    for (const row of rows)
+        lines.push(border("├", "┼", "┤"), ...rowLines(row));
+    lines.push(border("└", "┴", "┘"));
+    return lines;
 }
 /** Inline tokens (bold, italic, code, links...) as styled text. */
 function inline(tokens, fallback) {

package/dist/tui/ink/progressView.d.ts

@@ -2,6 +2,8 @@ import type { Mode } from "../../core/agentSpec.js";
 import { type ConsoleRenderer, type ConsoleRendererOptions } from "../consoleRenderer.js";
 import { type RenderApproval } from "./SessionView.js";
 import type { ToolPhrase } from "./toolGroup.js";
+import { type Theme } from "../theme.js";
+/** Options of `createProgressView()`. */
 export interface ProgressViewOptions extends Omit<ConsoleRendererOptions, "output"> {
     /** How one of the agent's own tools counts in a folded group's summary (see `InkChatOptions.toolPhrase`). */
     toolPhrase?: (toolName: string) => ToolPhrase | undefined;
@@ -11,6 +13,12 @@ export interface ProgressViewOptions extends Omit<ConsoleRendererOptions, "outpu
     mode?: Mode;
     /** Use the plain console renderer even on a TTY. */
     plain?: boolean;
+    /**
+     * 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
+     * process: without this option, the one already set stays.
+     */
+    theme?: Partial<Theme>;
     /**
      * The language of the kit's texts ("en", "es", "fr", "de"). `--language=<code>` on the
      * command line wins; without either, the one `buildSessionOptions()` chose from
@@ -18,6 +26,7 @@ export interface ProgressViewOptions extends Omit<ConsoleRendererOptions, "outpu
      */
     language?: string;
 }
+/** A one-shot run's live view: a console renderer drawn with Ink, plus `close()`. */
 export interface ProgressView extends ConsoleRenderer {
     /** Removes the live area and restores the previous interaction port; await it before printing anything else. */
     close(): Promise<void>;

package/dist/tui/ink/progressView.js

@@ -8,6 +8,8 @@ import { createInkInteraction } from "./inkInteraction.js";
 import { createSessionModel, liveWidth } from "./sessionModel.js";
 import { SessionView } from "./SessionView.js";
 import { applyLanguage } from "../language.js";
+import { applyTheme } from "../theme.js";
+import { KitTheme } from "./inkTheme.js";
 function ProgressApp({ model, interaction, renderApproval, mode, closed }) {
     const checkpoint = useSyncExternalStore(interaction.subscribe, interaction.getSnapshot);
     // Only a panel reads the keyboard (and so puts stdin in raw mode, where Ctrl+C no longer
@@ -31,6 +33,7 @@ function ProgressApp({ model, interaction, renderApproval, mode, closed }) {
  */
 export function createProgressView(options = {}) {
     applyLanguage(options.language);
+    applyTheme(options.theme);
     if (options.plain || !stdin.isTTY || !stdout.isTTY) {
         const renderer = createConsoleRenderer(options);
         return Object.assign(renderer, { close: async () => { } });
@@ -39,7 +42,7 @@ export function createProgressView(options = {}) {
     const interaction = createInkInteraction((text) => model.note(text));
     const previousPort = getInteractionPort();
     setInteractionPort(interaction.port);
-    const app = (closed) => (_jsx(ProgressApp, { model: model, interaction: interaction, renderApproval: options.renderApproval, mode: options.mode, closed: closed }));
+    const app = (closed) => (_jsx(KitTheme, { children: _jsx(ProgressApp, { model: model, interaction: interaction, renderApproval: options.renderApproval, mode: options.mode, closed: closed }) }));
     const instance = render(app(false), { exitOnCtrlC: false });
     model.startTurn();
     let closing = null;

package/dist/tui/ink/runChatInk.d.ts

@@ -7,6 +7,7 @@ import { type RenderApproval } from "./SessionView.js";
 import type { ToolPhrase } from "./toolGroup.js";
 import { type HeaderInfo } from "./header.js";
 export type { HeaderInfo } from "./header.js";
+/** Options of `runChatInk()`: the chat's options plus the Ink-only ones. */
 export interface InkChatOptions extends ChatTuiOptions {
     /**
      * Title, fields and an optional logo for the top of the chat: fixed at the top in full

package/dist/tui/ink/runChatInk.js

@@ -13,6 +13,8 @@ import { capHistory, loadHistory, runChatTui, saveHistory, slashCommandToken } f
 import * as ui from "../ui.js";
 import { t } from "../../core/messages/index.js";
 import { applyLanguage } from "../language.js";
+import { applyTheme, inkColor } from "../theme.js";
+import { KitTheme } from "./inkTheme.js";
 import { firstRun, openSession, runDate, runFolderOf, runLabel } from "../runs.js";
 import { createInkInteraction } from "./inkInteraction.js";
 import { PromptInput } from "./PromptInput.js";
@@ -114,7 +116,7 @@ function PickerPanel({ picker }) {
             picker.resolve(null);
     });
     const width = liveWidth(columns) - PROMPT_FRAME_COLUMNS;
-    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "gray", paddingX: 1, children: [_jsx(Text, { bold: true, children: picker.title }), _jsx(Select, { options: picker.options.map((option) => ({ ...option, label: fitWidth(option.label, Math.max(10, width - 2)) })), visibleOptionCount: Math.min(8, picker.options.length), onChange: (value) => picker.resolve(value) }), _jsx(Text, { dimColor: true, children: t().resumeHint })] }));
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: inkColor("border"), paddingX: 1, children: [_jsx(Text, { bold: true, children: picker.title }), _jsx(Select, { options: picker.options.map((option) => ({ ...option, label: fitWidth(option.label, Math.max(10, width - 2)) })), visibleOptionCount: Math.min(8, picker.options.length), onChange: (value) => picker.resolve(value) }), _jsx(Text, { dimColor: true, children: t().resumeHint })] }));
 }
 function ChatApp({ model, interaction, input, promptLabel, renderApproval, mode, fullscreen, header, onFocusChange, modeControl: currentModeControl, onInterrupt }) {
     const chat = useSyncExternalStore(input.subscribe, input.getSnapshot);
@@ -160,7 +162,7 @@ function ChatApp({ model, interaction, input, promptLabel, renderApproval, mode,
             onInterrupt();
         }
     });
-    return (_jsx(SessionView, { model: model, interaction: interaction, renderApproval: renderApproval, mode: chat.mode ?? mode, modeSwitchable: (modeControl?.switchable.length ?? 0) > 1, closed: chat.closed, fullscreen: fullscreen, header: header, onCopy: fullscreen ? (text) => void stdout.write(clipboardSequence(text)) : undefined, children: _jsxs(Box, { flexDirection: "column", children: [chat.queued.map((line, index) => (_jsx(Text, { wrap: "truncate-end", children: ui.dim(`  ${t().queued(line)}`) }, index))), chat.picker ? (_jsx(PickerPanel, { picker: chat.picker })) : (_jsx(Box, { borderStyle: "round", borderColor: "gray", paddingX: 1, children: _jsx(PromptInput, { label: promptLabel.replace(/^\n+/, ""), history: chat.history, commands: chat.commands, inset: PROMPT_FRAME_COLUMNS, suggestion: chat.suggestion, onSubmit: (line) => input.submit(line), onRecallQueued: () => input.unqueueLast(), files: chat.files, onExit: () => input.submit(null) }) }))] }) }));
+    return (_jsx(SessionView, { model: model, interaction: interaction, renderApproval: renderApproval, mode: chat.mode ?? mode, modeSwitchable: (modeControl?.switchable.length ?? 0) > 1, closed: chat.closed, fullscreen: fullscreen, header: header, onCopy: fullscreen ? (text) => void stdout.write(clipboardSequence(text)) : undefined, children: _jsxs(Box, { flexDirection: "column", children: [chat.queued.map((line, index) => (_jsx(Text, { wrap: "truncate-end", children: ui.dim(`  ${t().queued(line)}`) }, index))), chat.picker ? (_jsx(PickerPanel, { picker: chat.picker })) : (_jsx(Box, { borderStyle: "round", borderColor: inkColor("border"), paddingX: 1, children: _jsx(PromptInput, { label: promptLabel.replace(/^\n+/, ""), history: chat.history, commands: chat.commands, inset: PROMPT_FRAME_COLUMNS, suggestion: chat.suggestion, onSubmit: (line) => input.submit(line), onRecallQueued: () => input.unqueueLast(), files: chat.files, onExit: () => input.submit(null) }) }))] }) }));
 }
 /**
  * The Ink counterpart of `runChatTui()`, with the same options, session log and history
@@ -183,6 +185,7 @@ export async function runChatInk(options, tuiOptions = {}) {
     // Warnings about an unsupported language code go into the chat, not behind the full screen.
     const languageWarnings = [];
     applyLanguage(tuiOptions.language, (line) => languageWarnings.push(line));
+    applyTheme(tuiOptions.theme);
     const opener = typeof options === "function" ? options : null;
     const runsDir = opener ? tuiOptions.runsDir : undefined;
     if (opener && !runsDir)
@@ -331,7 +334,7 @@ export async function runChatInk(options, tuiOptions = {}) {
     const cursor = tuiOptions.fullscreen ? createCursorController(stdout) : null;
     const status = tuiOptions.terminalIntegration === false ? null : createTerminalStatus((text) => void stdout.write(text), tuiOptions.header?.title ?? "agent");
     status?.start();
-    const app = render(_jsx(CursorContext.Provider, { value: cursor, children: _jsx(ChatApp, { model: model, interaction: interaction, input: input, promptLabel: promptLabel, renderApproval: tuiOptions.renderApproval, mode: tuiOptions.mode, fullscreen: tuiOptions.fullscreen, header: tuiOptions.header && tuiOptions.fullscreen ? headerLines(tuiOptions.header) : undefined, onFocusChange: status ? (focused) => status.setFocused(focused) : undefined, modeControl: modeControl, onInterrupt: interruptTurn }) }), 
+    const app = render(_jsx(CursorContext.Provider, { value: cursor, children: _jsx(KitTheme, { children: _jsx(ChatApp, { model: model, interaction: interaction, input: input, promptLabel: promptLabel, renderApproval: tuiOptions.renderApproval, mode: tuiOptions.mode, fullscreen: tuiOptions.fullscreen, header: tuiOptions.header && tuiOptions.fullscreen ? headerLines(tuiOptions.header) : undefined, onFocusChange: status ? (focused) => status.setFocused(focused) : undefined, modeControl: modeControl, onInterrupt: interruptTurn }) }) }), 
     // In full screen Ink writes through the cursor controller, which places the terminal's cursor.
     { exitOnCtrlC: false, ...(cursor ? { stdout: cursor.stream } : {}) });
     try {

package/dist/tui/ink/toolGroup.js

@@ -1,4 +1,4 @@
-import { fitWidth } from "./lineBuffer.js";
+import { fitWidth, stripAnsi } from "./lineBuffer.js";
 import { renderMarkdown } from "./markdown.js";
 import * as ui from "../ui.js";
 import { t } from "../../core/messages/index.js";
@@ -39,7 +39,9 @@ export function resultSummary(result, markdown = false) {
     if (result.isError)
         return ui.error(first) + more;
     // Rendered wide, as one row: the summary line is cut to the room left afterwards.
-    return (markdown ? (renderMarkdown(first, 1000)[0] ?? first) : first) + more;
+    // Plain before the theme's color: a style the markdown opened and closed (bold's reset)
+    // would cancel a dim around it.
+    return ui.toolResult(markdown ? stripAnsi(renderMarkdown(first, 1000)[0] ?? first) : first) + more;
 }
 /**
  * The calls one by one: each behind a `●`, then after `⎿` the calls a subagent made (the
@@ -57,7 +59,7 @@ export function toolGroupExpanded(calls, width) {
             result,
         ];
         return [
-            `${ui.toolBullet("●")} ${fitWidth(call.label, width - 2)}`,
+            `${ui.toolBullet("●")} ${fitWidth(ui.toolLabel(call.label), width - 2)}`,
             ...under.map((line, i) => (line === "" ? "" : `  ${i === 0 ? ui.dim("⎿") : " "}  ${line}`)),
         ];
     });

package/dist/tui/ink/wizard.d.ts

@@ -1,3 +1,5 @@
+import { type Theme } from "../theme.js";
+/** The wizard's answers, by step name. */
 export type WizardAnswers = Record<string, unknown>;
 /** A value, or one computed from the answers given so far. */
 type FromAnswers<T> = T | ((answers: WizardAnswers) => T);
@@ -8,6 +10,7 @@ interface BaseStep {
     /** Skips the step (leaving no answer) when it returns false. */
     when?: (answers: WizardAnswers) => boolean;
 }
+/** A choice among `choices`; the answer is the chosen `value`. */
 export interface SelectStep<T = unknown> extends BaseStep {
     type: "select";
     choices: FromAnswers<{
@@ -17,26 +20,37 @@ export interface SelectStep<T = unknown> extends BaseStep {
     /** Preselects the choice with this value. */
     default?: FromAnswers<T>;
 }
+/** A line of text. */
 export interface InputStep extends BaseStep {
     type: "input";
     default?: FromAnswers<string>;
     /** `true` to accept, or the message to show. */
     validate?: (value: string, answers: WizardAnswers) => true | string;
 }
+/** A line of text, masked while typed and in the summary. */
 export interface PasswordStep extends BaseStep {
     type: "password";
     validate?: (value: string, answers: WizardAnswers) => true | string;
 }
+/** A yes/no question; the answer is a boolean. */
 export interface ConfirmStep extends BaseStep {
     type: "confirm";
     default?: FromAnswers<boolean>;
 }
+/** One question of `runWizard()`. */
 export type WizardStep = SelectStep | InputStep | PasswordStep | ConfirmStep;
+/** Options of `runWizard()`. */
 export interface WizardOptions {
     /** Printed above the first question. */
     title?: string;
     /** Use the plain @inquirer/prompts questions even on a TTY. */
     plain?: boolean;
+    /**
+     * 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
+     * process: without this option, the one already set stays.
+     */
+    theme?: Partial<Theme>;
     /**
      * The language of the kit's texts ("en", "es", "fr", "de"). `--language=<code>` on the
      * command line wins; without either, the one `buildSessionOptions()` chose from

package/dist/tui/ink/wizard.js

@@ -9,6 +9,8 @@ import * as inquirer from "@inquirer/prompts";
 import * as ui from "../ui.js";
 import { t } from "../../core/messages/index.js";
 import { applyLanguage } from "../language.js";
+import { applyTheme } from "../theme.js";
+import { KitTheme } from "./inkTheme.js";
 function resolve(value, answers) {
     return typeof value === "function" ? value(answers) : value;
 }
@@ -157,12 +159,13 @@ async function runPlainWizard(steps, title) {
  */
 export async function runWizard(steps, options = {}) {
     applyLanguage(options.language);
+    applyTheme(options.theme);
     if (options.plain || !stdin.isTTY || !stdout.isTTY)
         return await runPlainWizard(steps, options.title);
     if (nextIndex(steps, -1, {}) >= steps.length)
         return {};
     let result = null;
-    const app = render(_jsx(Wizard, { steps: steps, title: options.title, onDone: (answers) => (result = answers) }), { exitOnCtrlC: false });
+    const app = render(_jsx(KitTheme, { children: _jsx(Wizard, { steps: steps, title: options.title, onDone: (answers) => (result = answers) }) }), { exitOnCtrlC: false });
     await app.waitUntilExit();
     if (result === null)
         throw exitPromptError();

package/dist/tui/terminalInteraction.d.ts

@@ -1,6 +1,8 @@
 import readline from "node:readline/promises";
 import type { InteractionPort } from "../core/interaction.js";
+/** Registers the chat's `readline` interface, so checkpoints ask on it instead of opening a second one (`null` to unregister). */
 export declare function setSharedReadline(rl: readline.Interface | null): void;
+/** The registered `readline` interface, or `null`. */
 export declare function getSharedReadline(): readline.Interface | null;
 /**
  * Asks `question` on the shared interface, flagging it as in progress meanwhile — so the

package/dist/tui/terminalInteraction.js

@@ -14,9 +14,11 @@ import { t } from "../core/messages/index.js";
  * interface here, the port reuses it (creating or closing nothing) whenever it's available.
  */
 let sharedReadline = null;
+/** Registers the chat's `readline` interface, so checkpoints ask on it instead of opening a second one (`null` to unregister). */
 export function setSharedReadline(rl) {
     sharedReadline = rl;
 }
+/** The registered `readline` interface, or `null`. */
 export function getSharedReadline() {
     return sharedReadline;
 }

package/dist/tui/theme.d.ts

@@ -0,0 +1,60 @@
+/**
+ * A color for one role of the theme: a color name (`"gray"`, `"cyanBright"`: picocolors' and
+ * Ink's names), a hex (`"#ff8800"`), or a function that styles the text itself (bold, a
+ * background...). Roles drawn by Ink props (`border`, `selection`, the panels' `accent`) need
+ * a name or a hex: a function there falls back to the default color.
+ */
+export type ThemeColor = string | ((text: string) => string);
+/** The terminal UI's colors, by what they're for. */
+export interface Theme {
+    /** The agent's replies and its label. */
+    agent: ThemeColor;
+    /** The human's prompt label. */
+    user: ThemeColor;
+    /** The background of the human's lines in the Ink chat (a name or a hex). */
+    userBar: ThemeColor;
+    /** The border of the approval and manual-intervention panels (a name or a hex). */
+    accent: ThemeColor;
+    /** The spinner with what the agent is doing, and the mode in the status bar. */
+    working: ThemeColor;
+    /** Inline code and code blocks in the agent's replies. */
+    code: ThemeColor;
+    /** The `●` before each tool call. */
+    toolBullet: ThemeColor;
+    /** A tool call's label (`● Reading notes.md`). */
+    toolLabel: ThemeColor;
+    /** The one-line result under a tool call (`⎿ …`); an error is `error` instead. */
+    toolResult: ThemeColor;
+    /** The focused option of a choice list (approval panels, /resume, the wizard), in bold. */
+    selection: ThemeColor;
+    /** The frame around the prompt and the /resume list. */
+    border: ThemeColor;
+    /** Secondary text: notices, summaries, hints. */
+    dim: ThemeColor;
+    /** Titles (checkpoints, the wizard's questions). */
+    heading: ThemeColor;
+    /** The plain console's `[action]` lines. */
+    action: ThemeColor;
+    success: ThemeColor;
+    warn: ThemeColor;
+    error: ThemeColor;
+}
+/** The kit's own look. */
+export declare const DEFAULT_THEME: Readonly<Theme>;
+/** The kit's default theme with `overrides` on top: only the roles given change. */
+export declare function setTheme(overrides?: Partial<Theme>): void;
+/** The theme in use right now. */
+export declare function getTheme(): Readonly<Theme>;
+/** Changes the theme when an entry point was given one; without it, keeps the current one. */
+export declare function applyTheme(overrides: Partial<Theme> | undefined): void;
+/**
+ * `text` in `color`: a function is applied as given; a name or a hex becomes the terminal's
+ * escape codes, or nothing when the terminal has no color (`enabled`). `background` for a
+ * background color (a name becomes its `bg` form).
+ */
+export declare function paint(color: ThemeColor, text: string, options?: {
+    background?: boolean;
+    enabled?: boolean;
+}): string;
+/** A role's color as an Ink prop (a name or a hex); a function falls back to the default's. */
+export declare function inkColor(role: "accent" | "border" | "selection"): string;

package/dist/tui/theme.js

@@ -0,0 +1,65 @@
+import pc from "picocolors";
+/** The kit's own look. */
+export const DEFAULT_THEME = {
+    agent: "cyanBright",
+    user: "white",
+    userBar: "#373737",
+    accent: "#d77757",
+    working: "#89b4fa",
+    code: "#b1b9f9",
+    toolBullet: "green",
+    toolLabel: (text) => pc.dim(text),
+    toolResult: (text) => pc.dim(text),
+    selection: "#d77757",
+    border: "gray",
+    dim: (text) => pc.dim(text),
+    heading: (text) => pc.bold(text),
+    action: "magenta",
+    success: "green",
+    warn: "yellow",
+    error: "red",
+};
+// One theme per process, like the language (ADR-019).
+let current = { ...DEFAULT_THEME };
+/** The kit's default theme with `overrides` on top: only the roles given change. */
+export function setTheme(overrides = {}) {
+    current = { ...DEFAULT_THEME, ...overrides };
+}
+/** The theme in use right now. */
+export function getTheme() {
+    return current;
+}
+/** Changes the theme when an entry point was given one; without it, keeps the current one. */
+export function applyTheme(overrides) {
+    if (overrides)
+        setTheme(overrides);
+}
+const HEX = /^#?([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i;
+const COLORS = pc.createColors(true);
+const NAMES = new Set(Object.keys(pc).filter((key) => typeof pc[key] === "function" && key !== "createColors"));
+/**
+ * `text` in `color`: a function is applied as given; a name or a hex becomes the terminal's
+ * escape codes, or nothing when the terminal has no color (`enabled`). `background` for a
+ * background color (a name becomes its `bg` form).
+ */
+export function paint(color, text, options = {}) {
+    if (typeof color === "function")
+        return color(text);
+    const enabled = options.enabled ?? pc.isColorSupported;
+    if (!enabled)
+        return text;
+    const hex = HEX.exec(color);
+    if (hex) {
+        const [r, g, b] = hex.slice(1).map((part) => parseInt(part, 16));
+        return options.background ? `\x1b[48;2;${r};${g};${b}m${text}\x1b[49m` : `\x1b[38;2;${r};${g};${b}m${text}\x1b[39m`;
+    }
+    const name = options.background ? `bg${color.charAt(0).toUpperCase()}${color.slice(1)}` : color;
+    if (!NAMES.has(name))
+        return text;
+    return COLORS[name](text);
+}
+/** A role's color as an Ink prop (a name or a hex); a function falls back to the default's. */
+export function inkColor(role) {
+    const color = current[role];
+    return typeof color === "string" ? color : DEFAULT_THEME[role];
+}

package/dist/tui/ui.d.ts

@@ -1,13 +1,25 @@
-/** Color palette for a consistent console look across whatever CLI is built on this kit. */
+/**
+ * The terminal palette: one function per theme role, drawing text in the current theme.
+ *
+ * @packageDocumentation
+ */
+/** The agent's label and texts (`agent` role). */
 export declare const agent: (s: string) => string;
+/** The person's prompt label (`user` role). */
 export declare const user: (s: string) => string;
+/** The plain console's `[action]` lines (`action` role). */
 export declare const action: (s: string) => string;
+/** Titles (`heading` role, bold by default). */
 export declare const heading: (s: string) => string;
+/** Good outcomes (`success` role). */
 export declare const success: (s: string) => string;
+/** Warnings and notices (`warn` role). */
 export declare const warn: (s: string) => string;
+/** Errors (`error` role). */
 export declare const error: (s: string) => string;
+/** Secondary text (`dim` role). */
 export declare const dim: (s: string) => string;
-/** The orange accent: spinner, turn summary, mode. */
+/** The accent (the approval panels' border). */
 export declare const accent: (s: string) => string;
 /** The spinner and what the agent is doing. */
 export declare const working: (s: string) => string;
@@ -15,7 +27,15 @@ export declare const working: (s: string) => string;
 export declare const code: (s: string) => string;
 /** The background of the human's lines. */
 export declare const userBar: (s: string) => string;
+/** The `●` before a tool call (`toolBullet` role). */
+export declare const toolBullet: (s: string) => string;
+/** A tool call's label. */
+export declare const toolLabel: (s: string) => string;
+/** The one-line result under a tool call. */
+export declare const toolResult: (s: string) => string;
+/** Bold, whatever the theme. */
 export declare const bold: (s: string) => string;
+/** Italics, whatever the theme. */
 export declare const italic: (s: string) => string;
+/** Strikethrough, whatever the theme. */
 export declare const strike: (s: string) => string;
-export declare const toolBullet: (s: string) => string;

package/dist/tui/ui.js

@@ -1,25 +1,49 @@
+/**
+ * The terminal palette: one function per theme role, drawing text in the current theme.
+ *
+ * @packageDocumentation
+ */
 import pc from "picocolors";
-/** Color palette for a consistent console look across whatever CLI is built on this kit. */
-export const agent = (s) => pc.cyanBright(s);
-export const user = (s) => pc.white(s);
-export const action = (s) => pc.magenta(s);
-export const heading = (s) => pc.bold(s);
-export const success = (s) => pc.green(s);
-export const warn = (s) => pc.yellow(s);
-export const error = (s) => pc.red(s);
-export const dim = (s) => pc.dim(s);
-// The Claude Code-like look of the Ink views (see the feature ink-claude-style), in 24-bit
-// color when the terminal supports color at all, like the rest of this palette.
-const rgb = (r, g, b) => (s) => pc.isColorSupported ? `\x1b[38;2;${r};${g};${b}m${s}\x1b[39m` : s;
-/** The orange accent: spinner, turn summary, mode. */
-export const accent = rgb(215, 119, 87);
+import { getTheme, paint } from "./theme.js";
+/*
+ * Color palette for a consistent console look across whatever CLI is built on this kit.
+ * Each function draws its role in the current theme (see theme.ts), so an agent's theme
+ * reaches everything that uses them, its own texts included.
+ */
+/** The agent's label and texts (`agent` role). */
+export const agent = (s) => paint(getTheme().agent, s);
+/** The person's prompt label (`user` role). */
+export const user = (s) => paint(getTheme().user, s);
+/** The plain console's `[action]` lines (`action` role). */
+export const action = (s) => paint(getTheme().action, s);
+/** Titles (`heading` role, bold by default). */
+export const heading = (s) => paint(getTheme().heading, s);
+/** Good outcomes (`success` role). */
+export const success = (s) => paint(getTheme().success, s);
+/** Warnings and notices (`warn` role). */
+export const warn = (s) => paint(getTheme().warn, s);
+/** Errors (`error` role). */
+export const error = (s) => paint(getTheme().error, s);
+/** Secondary text (`dim` role). */
+export const dim = (s) => paint(getTheme().dim, s);
+// The Claude Code-like look of the Ink views (see the feature ink-claude-style).
+/** The accent (the approval panels' border). */
+export const accent = (s) => paint(getTheme().accent, s);
 /** The spinner and what the agent is doing. */
-export const working = rgb(137, 180, 250);
+export const working = (s) => paint(getTheme().working, s);
 /** Inline code and code blocks. */
-export const code = rgb(177, 185, 249);
+export const code = (s) => paint(getTheme().code, s);
 /** The background of the human's lines. */
-export const userBar = (s) => (pc.isColorSupported ? `\x1b[48;2;55;55;55m${s}\x1b[49m` : s);
+export const userBar = (s) => paint(getTheme().userBar, s, { background: true });
+/** The `●` before a tool call (`toolBullet` role). */
+export const toolBullet = (s) => paint(getTheme().toolBullet, s);
+/** A tool call's label. */
+export const toolLabel = (s) => paint(getTheme().toolLabel, s);
+/** The one-line result under a tool call. */
+export const toolResult = (s) => paint(getTheme().toolResult, s);
+/** Bold, whatever the theme. */
 export const bold = (s) => pc.bold(s);
+/** Italics, whatever the theme. */
 export const italic = (s) => pc.italic(s);
+/** Strikethrough, whatever the theme. */
 export const strike = (s) => pc.strikethrough(s);
-export const toolBullet = (s) => pc.green(s);

package/package.json

@@ -1,75 +1,79 @@
-{
-  "name": "@falkenslab/agent-kit",
-  "version": "0.12.0",
-  "description": "Library for building an agent on top of the Claude Agent SDK",
-  "author": "Francisco Vargas Ruiz",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/falkenslab/agent-kit.git"
-  },
-  "homepage": "https://github.com/falkenslab/agent-kit#readme",
-  "bugs": {
-    "url": "https://github.com/falkenslab/agent-kit/issues"
-  },
-  "keywords": [
-    "claude",
-    "claude-agent-sdk",
-    "ai-agent",
-    "agent",
-    "anthropic",
-    "ink",
-    "tui",
-    "cli",
-    "human-in-the-loop",
-    "mcp"
-  ],
-  "type": "module",
-  "engines": {
-    "node": ">=20"
-  },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "files": [
-    "dist",
-    "assets"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "typecheck": "tsc --noEmit",
-    "test": "tsx --test \"test/**/*.test.ts\" \"test/**/*.test.tsx\"",
-    "lint": "eslint .",
-    "prepare": "npm run build",
-    "prepublishOnly": "npm run typecheck && npm run lint && npm test && npm run build"
-  },
-  "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.234",
-    "@inkjs/ui": "^2.0.0",
-    "@inquirer/prompts": "^8.5.2",
-    "@types/react": "^19.3.0",
-    "ink": "^6.8.0",
-    "marked": "^18.0.14",
-    "picocolors": "^1.1.1",
-    "react": "^19.3.0",
-    "slice-ansi": "^8.0.0",
-    "string-width": "^8.3.0",
-    "wrap-ansi": "^9.0.2",
-    "zod": "^4.4.3"
-  },
-  "devDependencies": {
-    "@eslint/js": "^10.0.1",
-    "@types/node": "^24.0.0",
-    "eslint": "^10.9.1",
-    "globals": "^17.11.0",
-    "ink-testing-library": "^4.0.0",
-    "tsx": "^4.19.0",
-    "typescript": "^5.7.0",
-    "typescript-eslint": "^8.68.0"
-  },
-  "allowScripts": {
-    "esbuild@0.28.2": true
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@falkenslab/agent-kit",
+  "version": "0.13.0",
+  "description": "Library for building an agent on top of the Claude Agent SDK",
+  "author": "Francisco Vargas Ruiz",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/falkenslab/agent-kit.git"
+  },
+  "homepage": "https://github.com/falkenslab/agent-kit#readme",
+  "bugs": {
+    "url": "https://github.com/falkenslab/agent-kit/issues"
+  },
+  "keywords": [
+    "claude",
+    "claude-agent-sdk",
+    "ai-agent",
+    "agent",
+    "anthropic",
+    "ink",
+    "tui",
+    "cli",
+    "human-in-the-loop",
+    "mcp"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "assets"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test \"test/**/*.test.ts\" \"test/**/*.test.tsx\"",
+    "lint": "eslint .",
+    "docs:install": "npm --prefix docs ci",
+    "docs:start": "npm --prefix docs start",
+    "docs:build": "npm --prefix docs run build",
+    "docs:version": "npm --prefix docs run docs:version --",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run typecheck && npm run lint && npm test && npm run build"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.234",
+    "@inkjs/ui": "^2.0.0",
+    "@inquirer/prompts": "^8.5.2",
+    "@types/react": "^19.3.0",
+    "ink": "^6.8.0",
+    "marked": "^18.0.14",
+    "picocolors": "^1.1.1",
+    "react": "^19.3.0",
+    "slice-ansi": "^8.0.0",
+    "string-width": "^8.3.0",
+    "wrap-ansi": "^9.0.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.0.0",
+    "eslint": "^10.9.1",
+    "globals": "^17.11.0",
+    "ink-testing-library": "^4.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.68.0"
+  },
+  "allowScripts": {
+    "esbuild@0.28.2": true
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}