@falkenslab/agent-kit 0.10.1

package/dist/core/toolLabels.js

@@ -0,0 +1,114 @@
+/**
+ * Turns a raw tool name + input into a short, readable console description, instead of
+ * the tool's technical name (e.g. "mcp__playwright__browser_click"). Covers the tools
+ * this kit itself provides (Read/Write/Edit/Glob/Grep/Bash/Agent/WebFetch/WebSearch/Skill,
+ * plus its own human-approval/manual-intervention/save-to-sources MCP tools)
+ * generically; a
+ * concrete agent supplies a `describe` callback for its own domain-specific tools (e.g.
+ * Playwright's browser_* cases) via `createFriendlyToolLabel()`.
+ */
+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.
+export function truncatePath(text, max = 60) {
+    return text.length > max ? `…${text.slice(text.length - max + 1)}` : text;
+}
+/** Returns undefined for anything it doesn't specifically recognize — the caller decides the fallback. */
+function describeCore(shortName, input) {
+    switch (shortName) {
+        case "request_human_approval": {
+            const summary = typeof input.summary === "string" ? input.summary : "";
+            return `Asking for human approval: ${truncate(summary, 120)}`;
+        }
+        case "request_manual_login":
+            return "Waiting for a human to intervene manually";
+        case "save_to_sources": {
+            const destination = typeof input.destination === "string" ? input.destination : "sources/";
+            return `Saving a file to sources/${truncatePath(destination, 70)}`;
+        }
+        case "Read": {
+            const file = typeof input.file_path === "string" ? input.file_path : "a file";
+            return `Reading ${truncatePath(file, 80)}`;
+        }
+        case "Write": {
+            const file = typeof input.file_path === "string" ? input.file_path : "a file";
+            return `Writing to ${truncatePath(file, 80)}`;
+        }
+        case "Edit": {
+            const file = typeof input.file_path === "string" ? input.file_path : "a file";
+            return `Editing ${truncatePath(file, 80)}`;
+        }
+        case "Glob": {
+            const pattern = typeof input.pattern === "string" ? input.pattern : "*";
+            return `Searching for files matching "${truncate(pattern, 60)}"`;
+        }
+        case "Grep": {
+            const pattern = typeof input.pattern === "string" ? input.pattern : "";
+            return `Searching file contents for "${truncate(pattern, 60)}"`;
+        }
+        case "Bash": {
+            const command = typeof input.command === "string" ? input.command : "";
+            return `Running "${truncate(command, 80)}"`;
+        }
+        // The SDK's built-in subagent-delegation tool. Confirmed empirically (real
+        // transcript) its input is { description, prompt, subagent_type }, not
+        // { subagent_type, task } as its own tool description might suggest.
+        case "Agent": {
+            const subagentType = typeof input.subagent_type === "string" ? input.subagent_type : "a subagent";
+            const description = typeof input.description === "string" ? input.description : "";
+            return description
+                ? `Delegating to "${subagentType}": ${truncate(description, 80)}`
+                : `Delegating to "${subagentType}"`;
+        }
+        case "WebFetch": {
+            const url = typeof input.url === "string" ? input.url : "a page";
+            return `Fetching ${truncate(url, 80)}`;
+        }
+        case "WebSearch": {
+            const query = typeof input.query === "string" ? input.query : "";
+            return `Searching the web for "${truncate(query, 80)}"`;
+        }
+        // The SDK's own tool for invoking a skill (see session.ts for why it's listed
+        // explicitly in `tools`). Confirmed empirically: its input is `{ skill: "name" }`.
+        case "Skill": {
+            const skill = typeof input.skill === "string" ? input.skill : "a skill";
+            return `Applying the "${skill}" skill`;
+        }
+        default:
+            return undefined;
+    }
+}
+/**
+ * Builds a `friendlyToolLabel(toolName, toolInput)` — `describe` lets the host agent
+ * layer its own domain-specific cases (e.g. Playwright's browser_* tools) on top of this
+ * kit's generic ones; `extraLocalServers` names any *additional* MCP server (beyond this
+ * kit's own "approvals"/"manualLogin"/"sourceFiles") whose tools should be unwrapped
+ * without a "[server] " prefix, e.g. "playwright".
+ */
+export function createFriendlyToolLabel(options = {}) {
+    const localServers = new Set(["approvals", "manualLogin", "sourceFiles", ...(options.extraLocalServers ?? [])]);
+    const describe = (shortName, input) => options.describe?.(shortName, input) ?? describeCore(shortName, input) ?? shortName.replace(/_/g, " ");
+    return (toolName, toolInput) => {
+        const input = toolInput && typeof toolInput === "object" ? toolInput : {};
+        if (!toolName.startsWith("mcp__"))
+            return describe(toolName, input);
+        // MCP tool names are "mcp__<server>__<tool>" — split on the first literal "__" after
+        // the prefix rather than on every single "_", since both the server name and the
+        // tool name can themselves contain single underscores (e.g. "browser_click").
+        const rest = toolName.slice("mcp__".length);
+        const separatorIndex = rest.indexOf("__");
+        if (separatorIndex === -1)
+            return describe(rest, input);
+        const serverName = rest.slice(0, separatorIndex);
+        const shortName = rest.slice(separatorIndex + 2);
+        if (localServers.has(serverName))
+            return describe(shortName, input);
+        // describe() never has a specific case for a custom server's tools, so this is
+        // always its default-case cleanup — prefix it with the server name so the console
+        // still says where it came from, e.g. "[podman] container list".
+        return `[${serverName}] ${describe(shortName, input)}`;
+    };
+}

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

@@ -0,0 +1,14 @@
+export interface HumanApprovalTexts {
+    description: string;
+    approved: string;
+    rejected: string;
+}
+/** Domain-neutral defaults — a concrete agent should normally override these via `AgentSpec.humanApprovalTexts` with wording specific to what "publishing" means in its domain. */
+export declare const DEFAULT_HUMAN_APPROVAL_TEXTS: HumanApprovalTexts;
+/**
+ * Checkpoint tool for "guided" mode: the agent explores freely, but
+ * must call this tool and wait for human approval right before any action that publishes
+ * something visible to others and that's hard to naturally undo. Everything else —
+ * browsing and reading — doesn't go through this.
+ */
+export declare function createHumanApprovalServer(runDir: string, texts?: HumanApprovalTexts): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;

package/dist/core/tools/humanApproval.js

@@ -0,0 +1,37 @@
+import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+import { askForDecision } from "../hooks/humanInput.js";
+const APPROVED_ANSWERS = new Set(["", "y", "yes"]);
+/** Domain-neutral defaults — a concrete agent should normally override these via `AgentSpec.humanApprovalTexts` with wording specific to what "publishing" means in its domain. */
+export const DEFAULT_HUMAN_APPROVAL_TEXTS = {
+    description: "Ask for human confirmation right before an action that publishes something visible " +
+        "to others and is hard to naturally undo. Don't use it for anything else: not for " +
+        "browsing, not for reading, not before every intermediate step.",
+    approved: "Approved by the human. You may continue.",
+    rejected: "Rejected by the human. Don't proceed with that; ask what to do differently.",
+};
+/**
+ * Checkpoint tool for "guided" mode: the agent explores freely, but
+ * must call this tool and wait for human approval right before any action that publishes
+ * something visible to others and that's hard to naturally undo. Everything else —
+ * browsing and reading — doesn't go through this.
+ */
+export function createHumanApprovalServer(runDir, texts = DEFAULT_HUMAN_APPROVAL_TEXTS) {
+    const requestHumanApproval = tool("request_human_approval", texts.description, {
+        summary: z.string().describe("Brief summary of what you're about to submit or publish"),
+    }, async (args) => {
+        const answer = await askForDecision(runDir, {
+            title: "Human confirmation required before publishing",
+            lines: [`Summary: ${args.summary}`],
+        });
+        const approved = APPROVED_ANSWERS.has(answer);
+        return {
+            content: [{ type: "text", text: approved ? texts.approved : texts.rejected }],
+        };
+    });
+    return createSdkMcpServer({
+        name: "approvals",
+        version: "1.0.0",
+        tools: [requestHumanApproval],
+    });
+}

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

@@ -0,0 +1,16 @@
+export interface ManualInterventionTexts {
+    toolDescription: string;
+    confirmedMessage: string;
+    checkpointTitle: string;
+    checkpointLines: string[];
+    checkpointQuestion?: string;
+}
+/**
+ * Checkpoint tool for when the agent hits something it can't do itself (typically a login
+ * it has no credentials for, or one that fails unexpectedly). Pauses execution until a
+ * human confirms they've intervened by hand in whatever live interface the agent is driving
+ * (a browser window, say), and then lets the agent continue. There is deliberately no
+ * default wording: what counts as a manual intervention is entirely the domain's, so the
+ * concrete agent always supplies `texts` (see `AgentSpec.manualInterventionTexts`).
+ */
+export declare function createManualLoginServer(runDir: string, texts: ManualInterventionTexts): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;

package/dist/core/tools/manualLogin.js

@@ -0,0 +1,27 @@
+import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
+import { askForManualIntervention } from "../hooks/humanInput.js";
+/**
+ * Checkpoint tool for when the agent hits something it can't do itself (typically a login
+ * it has no credentials for, or one that fails unexpectedly). Pauses execution until a
+ * human confirms they've intervened by hand in whatever live interface the agent is driving
+ * (a browser window, say), and then lets the agent continue. There is deliberately no
+ * default wording: what counts as a manual intervention is entirely the domain's, so the
+ * concrete agent always supplies `texts` (see `AgentSpec.manualInterventionTexts`).
+ */
+export function createManualLoginServer(runDir, texts) {
+    const requestManualLogin = tool("request_manual_login", texts.toolDescription, {}, async () => {
+        await askForManualIntervention(runDir, {
+            title: texts.checkpointTitle,
+            lines: texts.checkpointLines,
+            question: texts.checkpointQuestion,
+        });
+        return {
+            content: [{ type: "text", text: texts.confirmedMessage }],
+        };
+    });
+    return createSdkMcpServer({
+        name: "manualLogin",
+        version: "1.0.0",
+        tools: [requestManualLogin],
+    });
+}

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

@@ -0,0 +1,10 @@
+/**
+ * `save_to_sources`: the only way the agent adds to `sourcesDir` (Write/Edit are scoped
+ * to the notes folder, see hooks/fileScopeGate.ts), so the originals stay as obtained.
+ * Deliberately just an fs.copyFile with COPYFILE_EXCL — no parsing, no format conversion,
+ * no overwriting. A document downloaded via a browser-automation tool typically lands in
+ * this run's own folder, which the file tools can't reach; this tool's only job is getting
+ * it into `sourcesDir`, where the SDK's own Read tool already knows how to interpret it
+ * (PDF/DOCX text extraction, multimodal images).
+ */
+export declare function createSaveToSourcesServer(runDir: string, sourcesDir: string, description?: string): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;

package/dist/core/tools/saveToSources.js

@@ -0,0 +1,105 @@
+import path from "node:path";
+import { constants, copyFile, mkdir, readdir, stat } from "node:fs/promises";
+import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+/** Resolves `candidate` against `base`; returns the absolute path only if it stays inside it. */
+function resolveWithin(base, candidate) {
+    const resolved = path.isAbsolute(candidate) ? path.resolve(candidate) : path.resolve(base, candidate);
+    const relative = path.relative(base, resolved);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative)) ? resolved : undefined;
+}
+/**
+ * `resolvedPath` as given if it exists; otherwise, a same-directory sibling whose
+ * filename is Unicode-equal under NFC normalization. Needed because a file downloaded via
+ * a real browser navigation can land on disk with an accented filename in NFD
+ * (decomposed) form, while the model's own `source` argument, being ordinary typed/read
+ * text, is normally NFC (composed). The two look character-for-character identical but
+ * differ byte-for-byte, so a literal `copyFile` throws ENOENT even though the file is
+ * right there under a name that reads identically.
+ */
+async function resolveExistingFileToleratingNormalization(resolvedPath) {
+    try {
+        await stat(resolvedPath);
+        return resolvedPath;
+    }
+    catch {
+        // fall through to the normalization-tolerant lookup below
+    }
+    const dir = path.dirname(resolvedPath);
+    const wantName = path.basename(resolvedPath).normalize("NFC");
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return undefined;
+    }
+    const match = entries.find((name) => name.normalize("NFC") === wantName);
+    return match ? path.join(dir, match) : undefined;
+}
+const DEFAULT_DESCRIPTION = "Copy a file from this run's own folder (e.g. something just downloaded) into a folder " +
+    "under sources/, where original files are kept as they were obtained, apart from your " +
+    "own notes. It becomes readable there with the SDK's own Read tool, which already " +
+    "extracts text from PDF/DOCX and interprets images directly. This tool does no parsing " +
+    "or conversion itself, it only relocates the file, and it never overwrites a file " +
+    "that's already in sources/. Use it right after downloading a document you're about to " +
+    "study in depth, so it's still there for later sessions instead of only existing for " +
+    "this run.";
+/**
+ * `save_to_sources`: the only way the agent adds to `sourcesDir` (Write/Edit are scoped
+ * to the notes folder, see hooks/fileScopeGate.ts), so the originals stay as obtained.
+ * Deliberately just an fs.copyFile with COPYFILE_EXCL — no parsing, no format conversion,
+ * no overwriting. A document downloaded via a browser-automation tool typically lands in
+ * this run's own folder, which the file tools can't reach; this tool's only job is getting
+ * it into `sourcesDir`, where the SDK's own Read tool already knows how to interpret it
+ * (PDF/DOCX text extraction, multimodal images).
+ */
+export function createSaveToSourcesServer(runDir, sourcesDir, description = DEFAULT_DESCRIPTION) {
+    const saveToSources = tool("save_to_sources", description, {
+        source: z.string().describe("Path to the file, relative to this run's own folder - not a URL"),
+        destination: z.string().describe('Path to save it under, relative to sources/, e.g. "topic-3/slides.pdf"'),
+    }, async (args) => {
+        const candidate = resolveWithin(runDir, args.source);
+        if (!candidate) {
+            return {
+                content: [{ type: "text", text: `"${args.source}" isn't inside this run's folder - refusing to read it.` }],
+                isError: true,
+            };
+        }
+        const resolvedSource = await resolveExistingFileToleratingNormalization(candidate);
+        if (!resolvedSource) {
+            return {
+                content: [{ type: "text", text: `Couldn't find "${args.source}" in this run's folder (checked byte-for-byte and Unicode-normalized names) - double check the exact path, e.g. with Glob.` }],
+                isError: true,
+            };
+        }
+        const resolvedDestination = resolveWithin(sourcesDir, args.destination);
+        if (!resolvedDestination) {
+            return {
+                content: [{ type: "text", text: `"${args.destination}" isn't inside sources/ - refusing to write there.` }],
+                isError: true,
+            };
+        }
+        try {
+            await mkdir(path.dirname(resolvedDestination), { recursive: true });
+            await copyFile(resolvedSource, resolvedDestination, constants.COPYFILE_EXCL);
+        }
+        catch (error) {
+            const exists = error.code === "EEXIST";
+            return {
+                content: [{
+                        type: "text",
+                        text: exists
+                            ? `"${args.destination}" already exists in sources/ - originals are never overwritten; pick another destination name.`
+                            : `Couldn't copy "${args.source}" to sources/: ${error instanceof Error ? error.message : String(error)}`,
+                    }],
+                isError: true,
+            };
+        }
+        const savedAs = path.relative(sourcesDir, resolvedDestination).split(path.sep).join("/");
+        return {
+            content: [{ type: "text", text: `Saved to sources/${savedAs} - read it from there with Read.` }],
+        };
+    });
+    return createSdkMcpServer({ name: "sourceFiles", version: "1.0.0", tools: [saveToSources] });
+}

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+export * as ui from "./tui/ui.js";
+export { isExitPromptError } from "./tui/promptErrors.js";
+export { allowAnyMcpTool } from "./core/mcpPermissions.js";
+export { createPromptLoader } from "./core/promptTemplate.js";
+export { resolveClaudeAuth, type ClaudeAuthConfig } from "./core/claudeAuth.js";
+export { ensureClaudeAuth } from "./tui/claudeAuth.js";
+export { createFriendlyToolLabel, truncate, truncatePath, type ToolDescriber, } from "./core/toolLabels.js";
+export type { Mode, BaseSessionConfig, AgentSpec } from "./core/agentSpec.js";
+export { buildSessionOptions, createInputQueue, createDeferred, createModeControl, type ModeControl } from "./core/session.js";
+export { runQuery, type AgentEvent, type AgentRun, type SessionUsage, type ContextUsage } from "./core/runner.js";
+export { knowledgePluginRoot, knowledgePromptSection } from "./core/knowledge.js";
+export type { Options, McpServerConfig, AgentDefinition } from "@anthropic-ai/claude-agent-sdk";
+export { createTranscriptLogger, summarizeToolResponse, type TranscriptLogger } from "./core/hooks/transcriptLogger.js";
+export { createStepGate } from "./core/hooks/stepGate.js";
+export { createSubagentBashGate } from "./core/hooks/subagentBashGate.js";
+export { createSubagentTypeGate } from "./core/hooks/subagentTypeGate.js";
+export { createSubagentForegroundGate } from "./core/hooks/subagentForegroundGate.js";
+export { createFileScopeGate, checkFileScope, type FileScope } from "./core/hooks/fileScopeGate.js";
+export { askForDecision, askForManualIntervention } from "./core/hooks/humanInput.js";
+export { setInteractionPort, getInteractionPort, type InteractionPort, type ApprovalPrompt } from "./core/interaction.js";
+export { terminalInteractionPort, setSharedReadline, getSharedReadline } from "./tui/terminalInteraction.js";
+export { createHumanApprovalServer, DEFAULT_HUMAN_APPROVAL_TEXTS, type HumanApprovalTexts } from "./core/tools/humanApproval.js";
+export { createManualLoginServer, type ManualInterventionTexts } from "./core/tools/manualLogin.js";
+export { createSaveToSourcesServer } from "./core/tools/saveToSources.js";
+export { runChatTui, type ChatTuiOptions } from "./tui/chatTui.js";
+export { createConsoleRenderer, type ConsoleRenderer, type ConsoleRendererOptions } from "./tui/consoleRenderer.js";
+export { runChatInk, type InkChatOptions, type HeaderInfo } from "./tui/ink/runChatInk.js";
+export type { ToolPhrase } from "./tui/ink/toolGroup.js";
+export type { RenderApproval } from "./tui/ink/SessionView.js";
+export { createProgressView, type ProgressView, type ProgressViewOptions } from "./tui/ink/progressView.js";
+export { runWizard, type WizardStep, type SelectStep, type InputStep, type PasswordStep, type ConfirmStep, type WizardAnswers, type WizardOptions, } from "./tui/ink/wizard.js";

package/dist/index.js

@@ -0,0 +1,32 @@
+import { setInteractionPort } from "./core/interaction.js";
+import { terminalInteractionPort } from "./tui/terminalInteraction.js";
+export * as ui from "./tui/ui.js";
+export { isExitPromptError } from "./tui/promptErrors.js";
+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 { buildSessionOptions, createInputQueue, createDeferred, createModeControl } from "./core/session.js";
+export { runQuery } from "./core/runner.js";
+export { knowledgePluginRoot, knowledgePromptSection } from "./core/knowledge.js";
+export { createTranscriptLogger, summarizeToolResponse } from "./core/hooks/transcriptLogger.js";
+export { createStepGate } from "./core/hooks/stepGate.js";
+export { createSubagentBashGate } from "./core/hooks/subagentBashGate.js";
+export { createSubagentTypeGate } from "./core/hooks/subagentTypeGate.js";
+export { createSubagentForegroundGate } from "./core/hooks/subagentForegroundGate.js";
+export { createFileScopeGate, checkFileScope } from "./core/hooks/fileScopeGate.js";
+export { askForDecision, askForManualIntervention } from "./core/hooks/humanInput.js";
+export { setInteractionPort, getInteractionPort } from "./core/interaction.js";
+export { terminalInteractionPort, setSharedReadline, getSharedReadline } from "./tui/terminalInteraction.js";
+// The checkpoints answer on the terminal by default, as they always have; a non-terminal
+// host replaces the port with its own (or null, to answer through the response file only).
+setInteractionPort(terminalInteractionPort);
+export { createHumanApprovalServer, DEFAULT_HUMAN_APPROVAL_TEXTS } from "./core/tools/humanApproval.js";
+export { createManualLoginServer } from "./core/tools/manualLogin.js";
+export { createSaveToSourcesServer } from "./core/tools/saveToSources.js";
+export { runChatTui } from "./tui/chatTui.js";
+export { createConsoleRenderer } from "./tui/consoleRenderer.js";
+export { runChatInk } from "./tui/ink/runChatInk.js";
+export { createProgressView } from "./tui/ink/progressView.js";
+export { runWizard, } from "./tui/ink/wizard.js";

package/dist/tui/chatTui.d.ts

@@ -0,0 +1,105 @@
+import type { Options } from "@anthropic-ai/claude-agent-sdk";
+import { type AgentEvent } from "../core/runner.js";
+export interface ChatTuiOptions {
+    /**
+     * Turns a tool call into a one-line console label. Defaults to `createFriendlyToolLabel()`
+     * with no domain overrides — pass your own (e.g.
+     * `createFriendlyToolLabel({ describe, extraLocalServers })`) to cover a concrete agent's
+     * own domain-specific tools (Playwright's `browser_*`, etc.).
+     */
+    formatAction?: (toolName: string, input: unknown) => string;
+    /** Printed once before the first prompt, if given. */
+    welcomeMessage?: string;
+    /** Shown before the cursor at each prompt. */
+    promptLabel?: string;
+    /**
+     * Shown once per turn, right before the agent's streamed reply text starts (not before
+     * any action lines that precede it) — and, when set, also colors that reply text via
+     * `ui.agent()`. Pass a pre-colored string (e.g. `ui.agent("Captain Whiskers>")`); omit to
+     * keep the plain, unlabeled/uncolored text streaming this kit had before.
+     */
+    agentLabel?: string;
+    /** Lines (trimmed, case-insensitive) that end the chat. */
+    exitCommands?: readonly string[];
+    /**
+     * When set, submitted as the very first turn — before the human is ever prompted —
+     * exactly as if they'd typed it themselves (mirrored to `sessionLogPath`/history like
+     * any other line). For an agent that should act proactively at the start of a chat (log
+     * into a site, load some state) instead of sitting idle at the prompt until the human
+     * says something first. Omit for the plain "wait at the prompt" behavior this kit had
+     * before.
+     */
+    initialPrompt?: string;
+    /**
+     * When set, mirrors everything this loop prints — the welcome message, each prompt
+     * line the human types, the agent's streamed reply, action lines, and any error/warning
+     * — into this file as it happens (appended, plain text with ANSI color codes stripped),
+     * so a session leaves behind an exact, always-present transcript of what the terminal
+     * showed even when the agent never calls a single tool (unlike `transcriptPath` from
+     * `buildSessionOptions()`, which only gets written to on the first tool call). Omit to
+     * skip session logging entirely.
+     */
+    sessionLogPath?: string;
+    /**
+     * When set, every non-empty line the human submits (including exit commands — a shell's
+     * own history keeps those too) is appended here as one JSON object per line
+     * (`{ text: string, timestamp: string }`, ISO 8601), trimmed to the most recent
+     * `historyLimit` entries (oldest dropped first). Loaded back at startup — including
+     * across separate runs of the same agent, since this path is normally a fixed file, not
+     * one under a per-run timestamped directory — into `readline`'s own history, so ↑/↓ at
+     * the prompt cycles through prior prompts. Omit to skip persistence entirely (↑/↓ still
+     * works for the current session alone, via readline's own in-memory default).
+     */
+    historyPath?: string;
+    /** Max entries kept in `historyPath` (and in the in-session ↑/↓ list). Defaults to 100. */
+    historyLimit?: number;
+}
+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
+ * `for await...of` + `break`: `run.events` (see runner.ts) is one long-lived generator
+ * spanning the *whole* multi-turn session, not one per turn, and breaking out of a
+ * `for-await-of` loop calls the generator's `.return()`, permanently closing it — the next
+ * turn's drain would then see `done: true` immediately and silently lose the rest of the
+ * conversation. Exported on its own (not part of the package's public API — see index.ts)
+ * so this exact behavior has a direct regression test.
+ */
+export declare function drainTurn(events: AsyncIterator<AgentEvent>, onEvent: (event: AgentEvent) => void): Promise<void>;
+/**
+ * A ready-to-run interactive terminal chat loop, assembled from this kit's own chat
+ * primitives: `createInputQueue()` feeds typed lines into a multi-turn `query()` session,
+ * `runQuery()`'s normalized event stream is rendered to the console (streamed text,
+ * friendly action labels via `createFriendlyToolLabel()`, turn failures), and this loop's
+ * own `readline.Interface` is registered via `setSharedReadline()` so any human-in-the-loop
+ * checkpoint the session hits (the interactive-mode step gate, or the guided-mode approval/
+ * manual-login tools — see terminalInteraction.ts) prompts on the same interface instead of a
+ * second one fighting it for stdin's raw mode.
+ *
+ * Takes the SDK `Options` produced by `buildSessionOptions()` rather than an `AgentSpec`
+ * directly, so it stays reusable for an `Options` assembled any other way:
+ *
+ *   const { options } = await buildSessionOptions(config, runDir, spec);
+ *   await runChatTui(options, { welcomeMessage: "Ready. Type /exit to quit." });
+ *
+ * Resolves once the chat ends (an exit command, Ctrl+C/Ctrl+D at an idle prompt) — this
+ * function owns the whole session lifecycle, closing the underlying query and readline
+ * interface itself before returning.
+ */
+export declare function runChatTui(options: Options, tuiOptions?: ChatTuiOptions): Promise<void>;
+export {};