@falkenslab/agent-kit 0.10.1

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

@@ -0,0 +1,62 @@
+export type WizardAnswers = Record<string, unknown>;
+/** A value, or one computed from the answers given so far. */
+type FromAnswers<T> = T | ((answers: WizardAnswers) => T);
+interface BaseStep {
+    /** Key of this step's answer in the result. */
+    name: string;
+    message: FromAnswers<string>;
+    /** Skips the step (leaving no answer) when it returns false. */
+    when?: (answers: WizardAnswers) => boolean;
+}
+export interface SelectStep<T = unknown> extends BaseStep {
+    type: "select";
+    choices: FromAnswers<{
+        name: string;
+        value: T;
+    }[]>;
+    /** Preselects the choice with this value. */
+    default?: FromAnswers<T>;
+}
+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;
+}
+export interface PasswordStep extends BaseStep {
+    type: "password";
+    validate?: (value: string, answers: WizardAnswers) => true | string;
+}
+export interface ConfirmStep extends BaseStep {
+    type: "confirm";
+    default?: FromAnswers<boolean>;
+}
+export type WizardStep = SelectStep | InputStep | PasswordStep | ConfirmStep;
+export interface WizardOptions {
+    /** Printed above the first question. */
+    title?: string;
+    /** Use the plain @inquirer/prompts questions even on a TTY. */
+    plain?: boolean;
+}
+/**
+ * How many choices a select shows at once, so the question, its choices and a validation
+ * line stay shorter than the terminal: Ink clears the whole screen to redraw anything
+ * taller (see SessionView.tsx's previewLines()).
+ */
+export declare function visibleOptions(choices: number, messageRows: number, terminalRows: number | undefined): number;
+export declare function Wizard({ steps, title, onDone }: {
+    steps: WizardStep[];
+    title?: string;
+    onDone(answers: WizardAnswers | null): void;
+}): import("react").JSX.Element;
+/**
+ * Asks `steps` in order and resolves with every answer by step name. A step's message,
+ * choices or default can depend on earlier answers, and `when` skips it, so a consumer's
+ * whole interactive menu becomes a list of step definitions.
+ *
+ * Ctrl+C rejects with an error named "ExitPromptError", like @inquirer/prompts, so
+ * `isExitPromptError()` keeps working. Without a TTY (or with `plain`) it asks the same
+ * steps through @inquirer/prompts.
+ */
+export declare function runWizard(steps: WizardStep[], options?: WizardOptions): Promise<WizardAnswers>;
+export {};

package/dist/tui/ink/wizard.js

@@ -0,0 +1,167 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { stdin, stdout } from "node:process";
+import { useState } from "react";
+import { Box, render, Static, Text, useApp, useInput, useStdout } from "ink";
+import wrapAnsi from "wrap-ansi";
+import { liveWidth } from "./sessionModel.js";
+import { ConfirmInput, PasswordInput, Select, TextInput } from "@inkjs/ui";
+import * as inquirer from "@inquirer/prompts";
+import * as ui from "../ui.js";
+function resolve(value, answers) {
+    return typeof value === "function" ? value(answers) : value;
+}
+/** The error @inquirer/prompts throws on Ctrl+C, so `isExitPromptError()` covers both. */
+function exitPromptError() {
+    const error = new Error("User force closed the prompt with Ctrl+C");
+    error.name = "ExitPromptError";
+    return error;
+}
+function StepInput({ step, answers, onAnswer }) {
+    const [error, setError] = useState(null);
+    const { stdout } = useStdout();
+    const width = liveWidth(stdout.columns);
+    const message = `${ui.success("?")} ${ui.heading(resolve(step.message, answers))}`;
+    function validated(value) {
+        const check = step.type === "input" || step.type === "password" ? (step.validate?.(value, answers) ?? true) : true;
+        if (check === true)
+            onAnswer(value);
+        else
+            setError(check);
+    }
+    let field;
+    switch (step.type) {
+        case "select": {
+            const choices = resolve(step.choices, answers);
+            const preselected = step.default === undefined ? -1 : choices.findIndex((c) => c.value === resolve(step.default, answers));
+            field = (_jsx(Select, { visibleOptionCount: visibleOptions(choices.length, wrapAnsi(message, width, { hard: true }).split(NEWLINE).length, stdout.rows), options: choices.map((choice, index) => ({ label: choice.name, value: String(index) })), defaultValue: preselected >= 0 ? String(preselected) : undefined, onChange: (index) => onAnswer(choices[Number(index)].value) }));
+            break;
+        }
+        case "input":
+            field = _jsx(TextInput, { defaultValue: step.default === undefined ? undefined : resolve(step.default, answers), onSubmit: validated });
+            break;
+        case "password":
+            field = _jsx(PasswordInput, { onSubmit: validated });
+            break;
+        case "confirm": {
+            const yes = step.default === undefined ? true : resolve(step.default, answers);
+            field = _jsx(ConfirmInput, { defaultChoice: yes ? "confirm" : "cancel", onConfirm: () => onAnswer(true), onCancel: () => onAnswer(false) });
+            break;
+        }
+    }
+    return (_jsxs(Box, { flexDirection: "column", width: width, children: [_jsx(Text, { children: message }), field, error ? _jsx(Text, { children: ui.error(error) }) : null] }));
+}
+const NEWLINE = String.fromCharCode(10);
+/**
+ * How many choices a select shows at once, so the question, its choices and a validation
+ * line stay shorter than the terminal: Ink clears the whole screen to redraw anything
+ * taller (see SessionView.tsx's previewLines()).
+ */
+export function visibleOptions(choices, messageRows, terminalRows) {
+    return Math.max(1, Math.min(choices, (terminalRows || 24) - messageRows - 3));
+}
+function summary(step, value, answers) {
+    if (step.type === "password")
+        return "*".repeat(String(value).length);
+    if (step.type === "confirm")
+        return value ? "Yes" : "No";
+    if (step.type === "select")
+        return resolve(step.choices, answers).find((c) => c.value === value)?.name ?? String(value);
+    return String(value);
+}
+export function Wizard({ steps, title, onDone }) {
+    const { exit } = useApp();
+    const [answers, setAnswers] = useState({});
+    const [done, setDone] = useState([]);
+    const [index, setIndex] = useState(() => nextIndex(steps, -1, {}));
+    useInput((input, key) => {
+        if (key.ctrl && input === "c") {
+            onDone(null);
+            exit();
+        }
+    });
+    function answer(value) {
+        const step = steps[index];
+        const next = { ...answers, [step.name]: value };
+        setAnswers(next);
+        setDone([...done, { message: resolve(step.message, answers), text: summary(step, value, answers) }]);
+        const following = nextIndex(steps, index, next);
+        setIndex(following);
+        if (following >= steps.length) {
+            onDone(next);
+            exit();
+        }
+    }
+    // The title and the answered steps go to <Static>: written once, never redrawn, so a long
+    // menu can't grow the live area past the terminal's height.
+    const history = [
+        ...(title ? [{ id: "title", text: ui.heading(title) }] : []),
+        ...done.map(({ message, text }, i) => ({ id: String(i), text: `${ui.success("✔")} ${message} ${ui.agent(text)}` })),
+    ];
+    const current = steps[index];
+    return (_jsxs(_Fragment, { children: [_jsx(Static, { items: history, children: (item) => _jsx(Text, { children: item.text }, item.id) }), current ? _jsx(StepInput, { step: current, answers: answers, onAnswer: answer }, index) : null] }));
+}
+function nextIndex(steps, from, answers) {
+    let index = from + 1;
+    while (index < steps.length && steps[index].when && !steps[index].when(answers))
+        index++;
+    return index;
+}
+/** The same steps as plain @inquirer/prompts questions, for hosts without a TTY. */
+async function runPlainWizard(steps, title) {
+    if (title)
+        console.log(ui.heading(title));
+    const answers = {};
+    for (const step of steps) {
+        if (step.when && !step.when(answers))
+            continue;
+        const message = resolve(step.message, answers);
+        switch (step.type) {
+            case "select":
+                answers[step.name] = await inquirer.select({
+                    message,
+                    choices: resolve(step.choices, answers),
+                    default: step.default === undefined ? undefined : resolve(step.default, answers),
+                });
+                break;
+            case "input":
+                answers[step.name] = await inquirer.input({
+                    message,
+                    default: step.default === undefined ? undefined : resolve(step.default, answers),
+                    validate: step.validate ? (value) => step.validate(value, answers) : undefined,
+                });
+                break;
+            case "password":
+                answers[step.name] = await inquirer.password({
+                    message,
+                    mask: "*",
+                    validate: step.validate ? (value) => step.validate(value, answers) : undefined,
+                });
+                break;
+            case "confirm":
+                answers[step.name] = await inquirer.confirm({ message, default: step.default === undefined ? true : resolve(step.default, answers) });
+                break;
+        }
+    }
+    return answers;
+}
+/**
+ * Asks `steps` in order and resolves with every answer by step name. A step's message,
+ * choices or default can depend on earlier answers, and `when` skips it, so a consumer's
+ * whole interactive menu becomes a list of step definitions.
+ *
+ * Ctrl+C rejects with an error named "ExitPromptError", like @inquirer/prompts, so
+ * `isExitPromptError()` keeps working. Without a TTY (or with `plain`) it asks the same
+ * steps through @inquirer/prompts.
+ */
+export async function runWizard(steps, options = {}) {
+    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 });
+    await app.waitUntilExit();
+    if (result === null)
+        throw exitPromptError();
+    return result;
+}

package/dist/tui/promptErrors.d.ts

@@ -0,0 +1,2 @@
+/** True for the error @inquirer/prompts throws when the user cancels (Ctrl+C) a prompt. */
+export declare function isExitPromptError(error: unknown): boolean;

package/dist/tui/promptErrors.js

@@ -0,0 +1,4 @@
+/** True for the error @inquirer/prompts throws when the user cancels (Ctrl+C) a prompt. */
+export function isExitPromptError(error) {
+    return error instanceof Error && error.name === "ExitPromptError";
+}

package/dist/tui/terminalInteraction.d.ts

@@ -0,0 +1,18 @@
+import readline from "node:readline/promises";
+import type { InteractionPort } from "../core/interaction.js";
+export declare function setSharedReadline(rl: readline.Interface | null): void;
+export declare function getSharedReadline(): readline.Interface | null;
+/**
+ * Asks `question` on the shared interface, flagging it as in progress meanwhile — so the
+ * REPL that owns the interface can tell a human-in-the-loop checkpoint waiting on the
+ * keyboard apart from a turn simply streaming (e.g. Esc must not interrupt the turn while
+ * an approval question is on screen).
+ */
+export declare function askOnSharedReadline(rl: readline.Interface, question: string): Promise<string>;
+export declare function isSharedQuestionActive(): boolean;
+/**
+ * The default `InteractionPort`, installed by the package entry point: prints the
+ * checkpoint and reads the answer on the terminal, on the chat's own readline when one is
+ * registered via `setSharedReadline()`. Without a TTY it prints nothing and never answers.
+ */
+export declare const terminalInteractionPort: InteractionPort;

package/dist/tui/terminalInteraction.js

@@ -0,0 +1,85 @@
+import readline from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+const DEFAULT_QUESTION = "Allow this to continue? [Y/n/q] ";
+/**
+ * A long-lived chat REPL's readline interface (if any), so that the terminal port reuses
+ * it instead of creating its own.
+ *
+ * Closing a readline.Interface desyncs stdin's raw mode for *any* other interface still
+ * alive on the same stream — Interface.close() calls input.setRawMode(false) directly on
+ * the shared stream, not something private to that instance (confirmed by reading
+ * node:readline/promises). If the port creates and closes its own interface while a chat
+ * REPL's own is still open waiting at its prompt, that second interface stops receiving
+ * keystroke events — the prompt sits there accepting no input. By registering the REPL's
+ * interface here, the port reuses it (creating or closing nothing) whenever it's available.
+ */
+let sharedReadline = null;
+export function setSharedReadline(rl) {
+    sharedReadline = rl;
+}
+export function getSharedReadline() {
+    return sharedReadline;
+}
+let activeQuestions = 0;
+/**
+ * Asks `question` on the shared interface, flagging it as in progress meanwhile — so the
+ * REPL that owns the interface can tell a human-in-the-loop checkpoint waiting on the
+ * keyboard apart from a turn simply streaming (e.g. Esc must not interrupt the turn while
+ * an approval question is on screen).
+ */
+export async function askOnSharedReadline(rl, question) {
+    activeQuestions++;
+    try {
+        return await rl.question(question);
+    }
+    finally {
+        activeQuestions--;
+    }
+}
+export function isSharedQuestionActive() {
+    return activeQuestions > 0;
+}
+function never() {
+    return new Promise(() => { });
+}
+/**
+ * Whether the keyboard channel (and any console output at all) is even attempted is
+ * decided from `stdin.isTTY` — confirmed empirically that a non-TTY `rl.question()` still
+ * writes its query text to `stdout` even though it can never resolve from real keystrokes,
+ * so skipping the whole readline.Interface (not just not reading from it) is what actually
+ * keeps a non-interactive host's stdout silent: it depends entirely on the response file.
+ */
+async function askOnTerminal(prompt, signal) {
+    if (!stdin.isTTY)
+        return await never();
+    console.log(`\n=== ${prompt.title} ===`);
+    for (const line of prompt.lines)
+        console.log(line);
+    const question = prompt.question ?? DEFAULT_QUESTION;
+    const shared = sharedReadline;
+    if (shared)
+        return await askOnSharedReadline(shared, question);
+    const rl = readline.createInterface({ input: stdin, output: stdout });
+    const close = () => rl.close();
+    signal.addEventListener("abort", close, { once: true });
+    try {
+        return await rl.question(question);
+    }
+    finally {
+        signal.removeEventListener("abort", close);
+        rl.close();
+    }
+}
+/**
+ * The default `InteractionPort`, installed by the package entry point: prints the
+ * checkpoint and reads the answer on the terminal, on the chat's own readline when one is
+ * registered via `setSharedReadline()`. Without a TTY it prints nothing and never answers.
+ */
+export const terminalInteractionPort = {
+    askDecision: askOnTerminal,
+    askManualIntervention: askOnTerminal,
+    notify(message) {
+        if (stdin.isTTY)
+            console.log(message);
+    },
+};

package/dist/tui/ui.d.ts

@@ -0,0 +1,21 @@
+/** Color palette for a consistent console look across whatever CLI is built on this kit. */
+export declare const agent: (s: string) => string;
+export declare const user: (s: string) => string;
+export declare const action: (s: string) => string;
+export declare const heading: (s: string) => string;
+export declare const success: (s: string) => string;
+export declare const warn: (s: string) => string;
+export declare const error: (s: string) => string;
+export declare const dim: (s: string) => string;
+/** The orange accent: spinner, turn summary, mode. */
+export declare const accent: (s: string) => string;
+/** The spinner and what the agent is doing. */
+export declare const working: (s: string) => string;
+/** Inline code and code blocks. */
+export declare const code: (s: string) => string;
+/** The background of the human's lines. */
+export declare const userBar: (s: string) => string;
+export declare const bold: (s: string) => string;
+export declare const italic: (s: string) => string;
+export declare const strike: (s: string) => string;
+export declare const toolBullet: (s: string) => string;

package/dist/tui/ui.js

@@ -0,0 +1,25 @@
+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);
+/** The spinner and what the agent is doing. */
+export const working = rgb(137, 180, 250);
+/** Inline code and code blocks. */
+export const code = rgb(177, 185, 249);
+/** 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 bold = (s) => pc.bold(s);
+export const italic = (s) => pc.italic(s);
+export const strike = (s) => pc.strikethrough(s);
+export const toolBullet = (s) => pc.green(s);

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@falkenslab/agent-kit",
+  "version": "0.10.1",
+  "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"
+  }
+}