@falkenslab/agent-kit 0.30.1 → 0.32.0

package/README.md

@@ -1,111 +1,175 @@
-<h1>
-  <img src="https://raw.githubusercontent.com/falkenslab/agent-kit/main/docs/assets/logo-readme-any.svg" alt="agent-kit" height="64">
-</h1>
-
-[![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-4453b8)](https://falkenslab.github.io/agent-kit/)
-
-**[📖 Documentation](https://falkenslab.github.io/agent-kit/)** · [📖 Documentación en español](https://falkenslab.github.io/agent-kit/es/)
-
-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
-
-- **Work at different levels of oversight.** Autonomous, guided (it asks for permission before anything that can't be undone or that other people will see) or step by step (it asks before every action), and a plan mode where it only reads and plans until you let it act. Within the same conversation you can switch among guided, step by step and plan.
-- **Ask a person for help.** It asks for approvals, or stops so someone can do something by hand, such as signing in to a website. It can be answered from the keyboard or from another program driving it, for example a desktop app.
-- **Remember between sessions.** It keeps its own knowledge base, a small wiki of notes that grows with every session, and keeps the original documents you give it or that it downloads untouched. Each conversation stays in the project's folder, so you can pick it up again with `--continue` (the latest one) or `/resume` (any of them).
-- **Speak your language.** Its interface comes in English, Spanish, French or German, the system's by default or the one you ask for with `--language=fr`, and it answers in that language unless you write to it in another one.
-- **Delegate to subagents safely.** Only to the ones it declares, always waiting for their result, and without the main agent being able to slip past its own limits through them.
-- **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 shown in as much detail as the agent chooses (each call with its result, the calls alone, or one line per group; Ctrl+O unfolds them), 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.
-
-## Examples
-
-### Captain Whiskers
-
-[Captain Whiskers](./examples/captain-whiskers) is a toy agent to see the kit in action: a retired pirate cat who tells jokes in the terminal, in your language. It starts full screen with its logo and has a small crew of subagents: one looks for new jokes on the web, another rates them before they're told, and a third tells the time with a tool of the captain's own. It lets you try the different levels of oversight and is the best starting point for an agent of your own. Its README explains how to run it.
-
-![Captain Whiskers in Windows Terminal: his logo with the mode and the agent-kit version at the top, his crew at work in the middle, a task list under the spinner, and the framed prompt and status bar at the bottom](docs/assets/captain-whiskers.png)
-
-See [everything he can do](https://falkenslab.github.io/agent-kit/docs/next/examples/captain-whiskers#what-he-can-do), with screenshots.
-
-### miyagi
-
-[miyagi](https://github.com/falkenslab/miyagi) is a real assistant for Moodle teachers. It signs in with your account in a Chrome window and works as you would: it grades submissions, answers in the forum, creates or reviews content and sums up how the class is going. It asks for your permission before publishing anything students will see, and takes notes about the course to remember everything in the next session.
-
-Oversight, memory, safety and the chat come from the kit; miyagi brings what it knows about Moodle and driving the browser.
-
-## Installation
-
-```
-npm install @falkenslab/agent-kit
-```
-
-To try changes to the kit without publishing them, point to a local clone with `"file:../agent-kit"` in your `package.json` and build it with `npm run build` after each change.
-
-Requires Node.js 20 or later.
-
-## A minimal agent
-
-An agent only describes what belongs to it (who it is, which MCP servers, skills and subagents it has) and picks a level of oversight; the kit sets up the session and the chat:
-
-```ts
-import path from "node:path";
-import { buildSessionOptions, ensureClaudeAuth, runChatInk, type AgentSpec, type BaseSessionConfig } from "@falkenslab/agent-kit";
-
-// The only part specific to the agent: who it is and what it has.
-const spec: AgentSpec<BaseSessionConfig> = {
-  buildSystemPrompt: () => "You are a pirate cat who tells jokes. Always answer in character.",
-  buildMcpServers: () => ({}), // its own MCP servers, if any
-  pluginRoots: () => [], // folders with skills and commands
-  buildSubagents: () => undefined, // subagents, if it delegates to any
-};
-
-await ensureClaudeAuth(); // offers to create a Claude token if it finds none
-
-const config: BaseSessionConfig = { mode: "guided", projectDir: process.cwd() };
-
-// Each run gets a folder of its own under .run/ (keep it out of git): its log, its
-// transcript and the conversation, to pick it up again with --continue or /resume.
-await runChatInk((run) => buildSessionOptions(config, run.dir, spec, { run }), {
-  runsDir: path.resolve(".run"),
-  header: { title: "My agent" },
-  mode: config.mode, // Shift+Tab cycles through guided, step by step and plan
-  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.
-
-## 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.
-
-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
-
-| Command | What it does |
-| --- | --- |
-| `npm run build` | Builds the kit into `dist/` |
-| `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:
-
-```
-npx tsx --test test/tui/promptErrors.test.ts
-```
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/falkenslab/agent-kit/main/docs/static/img/logo.svg" alt="agent-kit logo: three blue building blocks and a coral one being set in place" width="112"/>
+
+# agent-kit
+
+**Build an AI agent on Claude that asks before it acts, remembers, and chats like Claude Code.**<br/>
+You write what your agent knows and does; the kit brings oversight, safety, memory and the interface.
+
+[![npm](https://img.shields.io/npm/v/@falkenslab/agent-kit?color=cb3837&logo=npm)](https://www.npmjs.com/package/@falkenslab/agent-kit)
+![Node.js 20+](https://img.shields.io/badge/node-20%2B-339933?logo=node.js&logoColor=white)
+![Claude Agent SDK](https://img.shields.io/badge/Claude-Agent%20SDK-d97757?logo=anthropic&logoColor=white)
+![TypeScript](https://img.shields.io/badge/types-included-3178c6?logo=typescript&logoColor=white)
+[![License: MIT](https://img.shields.io/badge/license-MIT-16a34a)](LICENSE)
+
+**[📖 Documentation](https://falkenslab.github.io/agent-kit/)** · [📖 Documentación en español](https://falkenslab.github.io/agent-kit/es/)
+
+</div>
+
+agent-kit is 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 (levels of oversight, approvals, safe limits, memory across sessions, extensions, and a terminal chat as good as Claude Code's), so each agent writes only what belongs to its own domain: what it knows how to do, with which tools, and how it talks. A teacher's assistant for Moodle and a pirate cat who tells jokes are built the same way.
+
+## ✨ Why agent-kit
+
+- 🎚️ **You choose how much it acts alone.** Autonomous, guided (it asks before what others will see or can't be undone), step by step, or a plan mode where it only reads and plans; switch among them in the same conversation.
+- ✋ **It asks a person, and the kit makes sure.** Approvals, choices, a file, a sign-in by hand; an installed extension's tool that changes things waits for a yes whatever the model decided, and answers can last for the session or for good.
+- 🧠 **It remembers.** A knowledge base that grows with every session, the original documents it learns from kept untouched, a memory of the person, and every conversation to pick up again with `--continue` or `/resume`.
+- 🛡️ **It stays within limits.** Only its own folders, never protected files, subagents that can't slip past the main agent's limits, secrets hidden from the logs, remote servers allowed, asked about or denied.
+- 🧩 **It grows with extensions.** Claude Code plugins with MCP servers, skills and commands, installed from a marketplace or a folder, with their own options, sign-in and a catalog in the chat; no Git needed.
+- 🌐 **It speaks your language.** Its interface in English, Spanish, French or German, and it answers in that language unless you write in another.
+- 🖥️ **A terminal chat like Claude Code's, or none at all.** Full screen, live markdown, folded tool calls, panels, history, themes; or the same agent inside a desktop app or a web page with its own interface.
+
+## 🚀 Quick start
+
+You need [Node.js](https://nodejs.org) 20 or later and a Claude account. In a project with `"type": "module"` in its `package.json`:
+
+```bash
+npm install @falkenslab/agent-kit tsx
+```
+
+Save this as `agent.ts`: the only part that's your agent's is the spec at the top.
+
+```ts
+import path from "node:path";
+import { buildSessionOptions, ensureClaudeAuth, runChatInk, type AgentSpec, type BaseSessionConfig } from "@falkenslab/agent-kit";
+
+const spec: AgentSpec<BaseSessionConfig> = {
+  buildSystemPrompt: () => "You are a pirate cat who tells jokes. Always answer in character.",
+  buildMcpServers: () => ({}), // its own MCP servers, if any
+  pluginRoots: () => [], // folders with skills and commands
+  buildSubagents: () => undefined, // subagents, if it delegates to any
+};
+
+await ensureClaudeAuth(); // offers to sign in with your Claude account, on Anthropic's page, if it isn't
+const config: BaseSessionConfig = { mode: "guided", projectDir: process.cwd() };
+
+// Each run gets a folder under .run/ (keep it out of git): its log, transcript and conversation.
+await runChatInk((run) => buildSessionOptions(config, run.dir, spec, { run }), {
+  runsDir: path.resolve(".run"),
+  header: { title: "My agent" },
+  mode: config.mode, // Shift+Tab cycles through guided, step by step and plan
+  fullscreen: true,
+});
+```
+
+Run it with `npx tsx agent.ts`: a full-screen chat opens, in your system's language, and the agent asks before anything it shouldn't do alone. The [tutorial](https://falkenslab.github.io/agent-kit/docs/getting-started/first-agent) takes it from there.
+
+## 🧪 A taste of the code
+
+Give it a memory and a folder of sources, with the kit's own extensions:
+
+```ts
+import { knowledge, memory, sources } from "@falkenslab/agent-kit";
+
+const spec: AgentSpec<BaseSessionConfig> = {
+  // …
+  extensions: [sources({ dir: "sources" }), knowledge({ dir: "knowledge" }), memory({ dir: "memory" })],
+};
+```
+
+Let it install extensions from your marketplace, and keep its data from leaving the computer without asking:
+
+```ts
+const config: BaseSessionConfig = {
+  mode: "guided",
+  projectDir: process.cwd(),
+  extensionDirs: { agent: path.join(os.homedir(), ".my-agent", "extensions") },
+  officialMarketplace: "falkenslab/agent-extensions",
+  remoteServers: "ask",
+};
+```
+
+Make a tool always wait for the person's yes, on every call:
+
+```ts
+const spec: AgentSpec<BaseSessionConfig> = {
+  // …
+  extensionGate: { confirmTools: { canva: ["create-design", "publish-design"] } },
+};
+```
+
+## 📸 See it at work
+
+[Captain Whiskers](./examples/captain-whiskers), the kit's example agent: a retired pirate cat who tells jokes in your language, with a crew of subagents (one looks for new jokes on the web, one rates them, one tells the time), a logbook and an extension of his own. He runs in the terminal, in a browser and as a Windows app.
+
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/falkenslab/agent-kit/main/docs/assets/captain-whiskers.png" alt="Captain Whiskers in Windows Terminal: his logo with the mode and the agent-kit version at the top, his crew at work in the middle, a task list under the spinner, and the framed prompt and status bar at the bottom" width="760"/>
+
+</div>
+
+See [everything he can do](https://falkenslab.github.io/agent-kit/docs/examples/captain-whiskers#what-he-can-do), with screenshots. For a real one, [miyagi](https://github.com/falkenslab/miyagi) is an assistant for Moodle teachers: it grades, answers the forum, builds content and sums up how the class is going, asking before publishing anything students will see. Oversight, memory, safety and the chat come from the kit; miyagi brings what it knows about Moodle.
+
+## 🧰 What's inside
+
+| Area | For example |
+| --- | --- |
+| 🎚️ Modes and gates | Autonomous, guided, step by step and plan; the guided gate for extensions' tools, the plan gate, the step gate |
+| ✋ Human in the loop | Approvals, choices, free text, files, manual steps, MCP elicitation forms, a response file for hosts without a keyboard |
+| 🧠 Memory | A knowledge base (an LLM wiki), sources kept as obtained, a memory of the person, runs resumed with `--continue` and `/resume` |
+| 🧩 Extensions | Claude Code plugins with MCP servers (local, npm, remote with OAuth), skills, commands and subagents; scopes, a lock, workspace trust, options, marketplaces and a catalog |
+| 🛡️ Security | A file scope gate, denied paths, subagent gates, a remote-servers gate, isolation from the runner's own Claude Code, redacted transcripts |
+| 🤖 Subagents | Declared types only, in the foreground, without Bash for the main agent |
+| 🖥️ Interfaces | A full-screen Ink chat, a plain readline chat, a progress view, a wizard, themes; a chat controller for desktop apps and web pages |
+| 🌐 Languages | English, Spanish, French and German, for the interface, the replies and the extensions' servers |
+
+Every export, with what it takes and what it gives, is in the [API reference](https://falkenslab.github.io/agent-kit/docs/api).
+
+## 📚 Documentation
+
+- **[Getting started](https://falkenslab.github.io/agent-kit/docs/getting-started/installation)**: installation and a first agent, step by step.
+- **[Modes](https://falkenslab.github.io/agent-kit/docs/core-concepts/modes)** and **[human in the loop](https://falkenslab.github.io/agent-kit/docs/human-in-the-loop/overview)**: how much the agent does alone, and how it asks.
+- **[Extensions](https://falkenslab.github.io/agent-kit/docs/extensions/overview)**: installing, writing and publishing them.
+- **[Security](https://falkenslab.github.io/agent-kit/docs/security/overview)**: every guardrail, and what the kit doesn't protect.
+- **[The terminal chat](https://falkenslab.github.io/agent-kit/docs/terminal-ui/ink-chat)**: its keys, panels, options and themes.
+- **[Captain Whiskers](https://falkenslab.github.io/agent-kit/docs/examples/captain-whiskers)**: the example agent, piece by piece.
+
+## 🛠️ Developing
+
+The design decisions, and the SDK behaviors checked by hand behind several safeguards, are in [`.minispec/`](./.minispec/README.md).
+
+| Command | What it does |
+| --- | --- |
+| `npm run build` | Builds the kit into `dist/` |
+| `npm run typecheck` | Checks the types without building |
+| `npm run lint` | Checks the code style |
+| `npm test` | Runs all the tests (one file: `npx tsx --test test/tui/promptErrors.test.ts`) |
+| `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 try changes to the kit in an agent without publishing them, point its `package.json` to a local clone (`"file:../agent-kit"`) and run `npm run build` after each change.
+
+Working on the kit with Claude Code goes through Falken's Lab's own skills (commit, verify, update-docs, release, sync-issues, and the house style for READMEs, sites and Markdown), from the [falkenslab/falkenslab-plugins](https://github.com/falkenslab/falkenslab-plugins) marketplace. Install them once, for all of Falken's Lab's repositories:
+
+```bash
+claude plugin marketplace add falkenslab/falkenslab-plugins
+claude plugin install falkenslab-dev@falkenslab-plugins
+claude plugin install falkenslab-style@falkenslab-plugins
+```
+
+<details>
+<summary>What each plugin brings, and what stays in this repository</summary>
+
+- 🔧 **falkenslab-dev**: `commit`, `verify`, `update-docs`, `release`, `sync-issues`, `upgrade-deps` and `add-tool`.
+- 🎨 **falkenslab-style**: `falkenslab-docs`, `falkenslab-site-style`, `falkenslab-terminal-screenshots` and `markdown-writing`.
+
+Inside Claude Code, the same with `/plugin marketplace add falkenslab/falkenslab-plugins` and `/plugin install falkenslab-dev@falkenslab-plugins`; `/plugin marketplace update falkenslab-plugins` brings their latest version. This repository keeps only the skills that are agent-kit's own, in `.claude/skills/` (`add-export`, the MiniSpec ones and `upgrade-sdk`), and what its release adds to the general one is in [`CLAUDE.md`](./CLAUDE.md#releasing).
+
+</details>
+
+<div align="center">
+
+Made with 💖 by Falken's Lab Team
+
+</div>

package/dist/chat/chatController.d.ts

@@ -71,6 +71,14 @@ export interface ChatSettings {
      * The link is shown either way, on a line of its own, for another computer.
      */
     openBrowser?: boolean | ((url: string) => Promise<boolean>);
+    /**
+     * Claude Code's own commands in the `/` menu and the state's `commands` (#87): none by default,
+     * since they're for whoever develops with Claude Code (`/batch`, `/agents`, `/mcp`…), not for the
+     * agent's person; `"all"`, or the ones named (`["compact", "context"]`). The agent's own, its
+     * plugins', its extensions', the project's, the kit's and the view's are always there, and a
+     * command typed by hand still reaches the SDK.
+     */
+    cliCommands?: "all" | readonly string[];
 }
 /** One tool call in the transcript. */
 export interface TranscriptCall {

package/dist/chat/chatController.js

@@ -183,7 +183,10 @@ export async function createChatController(options, settings = {}) {
                 { name: "extensions", description: t().commandExtensions, argumentHint: "[enable|disable|config|search|install|update|remove|reload]" },
             ];
             const details = new Map();
-            for (const command of [...(commands ?? []).map(({ name, description, argumentHint }) => ({ name, description: description ?? "", argumentHint: argumentHint ?? "" })), ...local])
+            // Claude Code's own (builtin) only when the agent asks for them (#87).
+            const cli = settings.cliCommands;
+            const offered = (commands ?? []).filter((command) => !command.builtin || cli === "all" || (Array.isArray(cli) && cli.includes(command.name)));
+            for (const command of [...offered.map(({ name, description, argumentHint }) => ({ name, description: description ?? "", argumentHint: argumentHint ?? "" })), ...local])
                 details.set(command.name, command);
             for (const name of exits)
                 if (!details.has(name))

package/dist/core/agentSpec.d.ts

@@ -154,8 +154,11 @@ export interface AgentSpec<TConfig extends BaseSessionConfig> {
      * Whether the kit tells the agent (and each subagent) to reply in the resolved language
      * (`config.language`, `--language`, the system's), following the human if they write in
      * another one. On by default; `false` leaves the reply language to the agent's own prompt.
+     * When the language isn't English, the kit also says it again after each of the main agent's
+     * tool calls and with each message of the person (#85), since the narration between tool calls
+     * drifted to English after an English result; `"prompt-only"` keeps only the prompt's line.
      */
-    replyInLanguage?: boolean;
+    replyInLanguage?: boolean | "prompt-only";
     /**
      * Which filesystem settings the session loads (the SDK's `settingSources`): "project" is
      * the project's `.claude/` (settings, skills, commands) and its CLAUDE.md files, "local"

package/dist/core/claudeAuth.d.ts

@@ -1,25 +1,57 @@
-/** 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
-     * that read/wrote `~/.<appName>/config.json` itself (see git history). Sourcing this
-     * value across runs, if a concrete agent wants that at all, is entirely its own concern. */
-    claudeCodeOAuthToken?: string;
+/**
+ * The Claude Code binary the Agent SDK ships (`@anthropic-ai/claude-agent-sdk-<platform>-<arch>`),
+ * unmodified: the copy unpacked next to the archive when the agent runs packaged, or else the
+ * one resolved from `node_modules` as the SDK resolves it. `undefined` when it isn't installed.
+ * `resolve` and the platform are replaceable for tests.
+ */
+export declare function claudeExecutable(resolve?: (request: string) => string, platform?: NodeJS.Platform, arch?: string): string | undefined;
+/** What `claudeSignedIn()` and `startClaudeSignIn()` accept. */
+export interface ClaudeAuthOptions {
+    /** The binary to run instead of the SDK's own (`claudeExecutable()`); a `.js`/`.mjs` file runs with Node, as the SDK runs one. */
+    executable?: string;
 }
+/** The binary and its arguments as a process to spawn: a JavaScript file runs with this Node. */
+export declare function claudeCommand(executable: string, args: string[]): {
+    file: string;
+    args: string[];
+};
 /**
- * Pure lookup, no I/O and no console output of any kind — safe to call from a
- * headless/non-interactive consumer (a server, an Electron main process) as much as from a
- * terminal one.
+ * Whether the agent can reach Claude: true when the person's environment has `ANTHROPIC_API_KEY`
+ * or `CLAUDE_CODE_OAUTH_TOKEN` (their own setting); otherwise what the Claude Code binary says
+ * (`claude auth status --json`, its `loggedIn`). Never reads the credentials file, and prints
+ * nothing: safe from a server or an Electron main process. False when there is no binary.
+ */
+export declare function claudeSignedIn(options?: ClaudeAuthOptions): Promise<boolean>;
+/** A sign-in in progress (`startClaudeSignIn()`): Claude Code's own `auth login`, which keeps the credentials itself. */
+export interface ClaudeSignIn {
+    /** Anthropic's sign-in page, to show as a link in case the browser didn't open; `undefined` if the binary ended without printing one. */
+    url: Promise<string | undefined>;
+    /** The code Anthropic's page shows after signing in, when it shows one: handed to the binary, which waits for it. */
+    sendCode(code: string): void;
+    /** Once the binary has ended: whether the person is signed in (`claudeSignedIn()`). */
+    done: Promise<boolean>;
+    /** Stops the sign-in; `done` then resolves with whether the person is signed in anyway. */
+    cancel(): void;
+}
+/**
+ * Signs the person in to their Claude account through Anthropic's own flow, for a host without a
+ * terminal (a web page, a desktop app): runs `claude auth login` (`console: true` for an
+ * Anthropic Console account, billed by API usage) with plain pipes. The binary opens the browser
+ * itself; the host shows `url` as a link in case it didn't, and a box for the code Anthropic's
+ * page shows (`sendCode`). The binary keeps the credentials: the kit never sees a token. Throws
+ * when the binary isn't installed.
  *
- * Checks, in order: `ANTHROPIC_API_KEY` (a complete authentication path on its own — API
- * billing instead of subscription, so nothing else is checked when it's set),
- * `CLAUDE_CODE_OAUTH_TOKEN`, then `config.claudeCodeOAuthToken` if the caller passed one.
- * Returns `true` and (for the `config` case) sets `CLAUDE_CODE_OAUTH_TOKEN` on the process
- * as a side effect once a token is found — the SDK's own subprocess reads that env var
- * directly, never anything this kit passes it explicitly; `false` when none of the three
- * has one. Getting a token in that case (e.g. by walking the user through
- * `claude setup-token`) is a terminal-UX concern, not this function's — see
- * `ensureClaudeAuth()` in tui/claudeAuth.ts, which calls this first and only falls back to
- * that interactive flow when it returns `false`.
+ * Confirmed empirically (Claude Code 2.1.310): without a TTY, `auth login` prints "If the browser
+ * didn't open, visit: <url>" (the URL may come wrapped in OSC 8 hyperlink escapes) and then waits
+ * at "Paste code here if prompted >".
+ */
+export declare function startClaudeSignIn(options?: ClaudeAuthOptions & {
+    console?: boolean;
+}): ClaudeSignIn;
+/**
+ * The sign-in URL in what `claude auth login` printed so far: an OSC 8 hyperlink's target, or a
+ * URL in the text with its escapes removed, Anthropic's authorize page (`/oauth/authorize`)
+ * first. A URL in the text counts only once whitespace follows it (the rest may still be on its
+ * way), unless `complete` says the output is all there is.
  */
-export declare function resolveClaudeAuth(config?: ClaudeAuthConfig): boolean;
+export declare function signInUrl(output: string, complete?: boolean): string | undefined;

package/dist/core/claudeAuth.js

@@ -1,27 +1,140 @@
+import { execFile, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { claudeBinaryRequests, unpackedClaudeExecutable } from "./packaged.js";
+/*
+ * Signing in to Claude without ever touching a credential (ADR-009, #90). Anthropic's terms
+ * (https://code.claude.com/docs/en/legal-and-compliance, "Authentication and credential use")
+ * say an Agent SDK developer may not collect, store or intermediate Claude.ai credentials or
+ * session tokens: a Claude account signs in through Anthropic's own flow, in the unmodified
+ * Claude Code binary. The SDK ships that binary, so the kit runs its `auth status` and
+ * `auth login` and nothing else: the binary opens Anthropic's page and keeps the credentials
+ * itself (`~/.claude/.credentials.json`, the Keychain on macOS), where the SDK's sessions find
+ * them. The kit never reads, returns or stores a token. An API key (`ANTHROPIC_API_KEY`) is
+ * allowed, and so is a person's own `CLAUDE_CODE_OAUTH_TOKEN`: both are their setting, not
+ * something the kit collects.
+ */
 /**
- * Pure lookup, no I/O and no console output of any kind — safe to call from a
- * headless/non-interactive consumer (a server, an Electron main process) as much as from a
- * terminal one.
- *
- * Checks, in order: `ANTHROPIC_API_KEY` (a complete authentication path on its own — API
- * billing instead of subscription, so nothing else is checked when it's set),
- * `CLAUDE_CODE_OAUTH_TOKEN`, then `config.claudeCodeOAuthToken` if the caller passed one.
- * Returns `true` and (for the `config` case) sets `CLAUDE_CODE_OAUTH_TOKEN` on the process
- * as a side effect once a token is found — the SDK's own subprocess reads that env var
- * directly, never anything this kit passes it explicitly; `false` when none of the three
- * has one. Getting a token in that case (e.g. by walking the user through
- * `claude setup-token`) is a terminal-UX concern, not this function's — see
- * `ensureClaudeAuth()` in tui/claudeAuth.ts, which calls this first and only falls back to
- * that interactive flow when it returns `false`.
+ * The Claude Code binary the Agent SDK ships (`@anthropic-ai/claude-agent-sdk-<platform>-<arch>`),
+ * unmodified: the copy unpacked next to the archive when the agent runs packaged, or else the
+ * one resolved from `node_modules` as the SDK resolves it. `undefined` when it isn't installed.
+ * `resolve` and the platform are replaceable for tests.
  */
-export function resolveClaudeAuth(config = {}) {
-    if (process.env.ANTHROPIC_API_KEY)
-        return true;
-    if (process.env.CLAUDE_CODE_OAUTH_TOKEN)
-        return true;
-    if (config.claudeCodeOAuthToken) {
-        process.env.CLAUDE_CODE_OAUTH_TOKEN = config.claudeCodeOAuthToken;
+export function claudeExecutable(resolve = createRequire(import.meta.url).resolve, platform = process.platform, arch = process.arch) {
+    const unpacked = unpackedClaudeExecutable(resolve, platform, arch);
+    if (unpacked)
+        return unpacked;
+    for (const request of claudeBinaryRequests(platform, arch)) {
+        try {
+            const file = resolve(request);
+            if (existsSync(file))
+                return file;
+        }
+        catch {
+            // That package isn't installed: the next one.
+        }
+    }
+    return undefined;
+}
+/** The binary and its arguments as a process to spawn: a JavaScript file runs with this Node. */
+export function claudeCommand(executable, args) {
+    return /\.(c|m)?js$/i.test(executable) ? { file: process.execPath, args: [executable, ...args] } : { file: executable, args };
+}
+/**
+ * Whether the agent can reach Claude: true when the person's environment has `ANTHROPIC_API_KEY`
+ * or `CLAUDE_CODE_OAUTH_TOKEN` (their own setting); otherwise what the Claude Code binary says
+ * (`claude auth status --json`, its `loggedIn`). Never reads the credentials file, and prints
+ * nothing: safe from a server or an Electron main process. False when there is no binary.
+ */
+export async function claudeSignedIn(options = {}) {
+    if (process.env.ANTHROPIC_API_KEY || process.env.CLAUDE_CODE_OAUTH_TOKEN)
         return true;
+    const executable = options.executable ?? claudeExecutable();
+    if (!executable)
+        return false;
+    const command = claudeCommand(executable, ["auth", "status", "--json"]);
+    // Exit code 1 when signed out, with the same JSON (confirmed empirically): read it either way.
+    const output = await new Promise((resolve) => {
+        execFile(command.file, command.args, { timeout: 30_000, windowsHide: true }, (_error, stdout) => resolve(String(stdout ?? "")));
+    });
+    try {
+        return JSON.parse(output).loggedIn === true;
     }
-    return false;
+    catch {
+        return false;
+    }
+}
+/**
+ * Signs the person in to their Claude account through Anthropic's own flow, for a host without a
+ * terminal (a web page, a desktop app): runs `claude auth login` (`console: true` for an
+ * Anthropic Console account, billed by API usage) with plain pipes. The binary opens the browser
+ * itself; the host shows `url` as a link in case it didn't, and a box for the code Anthropic's
+ * page shows (`sendCode`). The binary keeps the credentials: the kit never sees a token. Throws
+ * when the binary isn't installed.
+ *
+ * Confirmed empirically (Claude Code 2.1.310): without a TTY, `auth login` prints "If the browser
+ * didn't open, visit: <url>" (the URL may come wrapped in OSC 8 hyperlink escapes) and then waits
+ * at "Paste code here if prompted >".
+ */
+export function startClaudeSignIn(options = {}) {
+    const executable = options.executable ?? claudeExecutable();
+    if (!executable)
+        throw new Error("Claude Code's binary, which the Agent SDK ships (@anthropic-ai/claude-agent-sdk-<platform>-<arch>), isn't installed.");
+    const command = claudeCommand(executable, ["auth", "login", ...(options.console ? ["--console"] : [])]);
+    const child = spawn(command.file, command.args, { stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
+    let output = "";
+    let resolveUrl;
+    const url = new Promise((resolve) => (resolveUrl = resolve));
+    const read = (chunk) => {
+        output += chunk.toString("utf8");
+        // Anthropic's page as soon as it's all there; any other URL only once the binary has ended.
+        const found = signInUrl(output);
+        if (found?.includes("/oauth/authorize"))
+            resolveUrl(found);
+    };
+    child.stdout?.on("data", read);
+    child.stderr?.on("data", read);
+    // A write after the binary ended fails on the stream: nothing to tell then.
+    child.stdin?.on("error", () => { });
+    const ended = new Promise((resolve) => {
+        child.on("error", () => resolve());
+        child.on("close", () => resolve());
+    });
+    const done = ended.then(() => {
+        resolveUrl(signInUrl(output, true));
+        return claudeSignedIn(options);
+    });
+    return {
+        url,
+        sendCode(code) {
+            if (child.stdin?.writable)
+                child.stdin.write(`${code.trim()}\n`);
+        },
+        done,
+        cancel() {
+            if (child.exitCode === null && child.signalCode === null)
+                child.kill();
+        },
+    };
+}
+// An OSC sequence (a hyperlink's `ESC ] 8 ; ; URL ESC \`, a title), ended by BEL or ST.
+// eslint-disable-next-line no-control-regex -- ESC and BEL delimit terminal escapes, on purpose
+const OSC = /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g;
+// A CSI sequence (colors, cursor moves).
+// eslint-disable-next-line no-control-regex -- ESC starts the sequence
+const CSI = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
+// eslint-disable-next-line no-control-regex -- an OSC 8 hyperlink's target, between ESC/BEL delimiters
+const HYPERLINK_TARGET = /\x1b\]8;[^;\x07\x1b]*;(https:\/\/[^\x07\x1b]+)(?:\x07|\x1b\\)/g;
+/**
+ * The sign-in URL in what `claude auth login` printed so far: an OSC 8 hyperlink's target, or a
+ * URL in the text with its escapes removed, Anthropic's authorize page (`/oauth/authorize`)
+ * first. A URL in the text counts only once whitespace follows it (the rest may still be on its
+ * way), unless `complete` says the output is all there is.
+ */
+export function signInUrl(output, complete = false) {
+    const targets = [...output.matchAll(HYPERLINK_TARGET)].map((match) => match[1]);
+    const text = output.replace(OSC, " ").replace(CSI, "");
+    const inText = [...text.matchAll(complete ? /https:\/\/\S+/g : /https:\/\/\S+(?=\s)/g)].map((match) => match[0]);
+    const urls = [...targets, ...inText];
+    return urls.find((url) => url.includes("/oauth/authorize")) ?? urls[0];
 }