@ashulab/carrier 0.0.0-stage → 0.1.1

package/dist/chat/claude.js

@@ -0,0 +1,367 @@
+import { execFile, spawn } from 'node:child_process';
+import { query as sdkQuery } from '@anthropic-ai/claude-agent-sdk';
+import { createScopedLogger } from '@ashulab/universal-logger';
+import { endGroup, resolveAgentBinary } from './group.js';
+import { ChatRefused } from './runner.js';
+// The Claude adapter of the chat runner: the Agent SDK pointed at the user's own `claude` binary, which runs as the
+// leader of its own process group (docs/research/chat-spike.md). The SDK is only the transport: everything below the
+// `query` seam is Carrier's own parsing of the messages it yields, and a message it does not know gives no event.
+const log = createScopedLogger('chat');
+const PERMISSION_MODES = [
+    { id: 'default', label: 'Ask before each change' },
+    { id: 'acceptEdits', label: 'Accept edits' },
+    { id: 'plan', label: 'Plan only' },
+    { id: 'auto', label: 'Auto' },
+    { id: 'dontAsk', label: "Don't ask" },
+]; // `bypassPermissions` is left out: it needs a flag of its own and Carrier does not turn it on
+const resolveClaude = (command, env) => resolveAgentBinary('claude', command, env);
+const claudeLoggedIn = (binary, env) => new Promise((done) => {
+    execFile(binary, ['auth', 'status'], { env, timeout: 15_000 }, (_error, stdout) => {
+        try {
+            done(JSON.parse(stdout).loggedIn === true);
+        }
+        catch {
+            done(false);
+        }
+    });
+});
+const ownGroup = (o) => spawn(o.command, o.args, { cwd: o.cwd, env: o.env, stdio: ['pipe', 'pipe', 'pipe'], detached: true });
+export const realClaudeDeps = { query: sdkQuery, resolve: resolveClaude, loggedIn: claudeLoggedIn, spawn: ownGroup };
+export function claudeChatRunner(deps = realClaudeDeps) {
+    return {
+        async open({ folder, resume, options = {}, command, env }) {
+            let binary;
+            try {
+                binary = deps.resolve(command, env);
+            }
+            catch {
+                throw new ChatRefused(`Claude is not installed: ${command === undefined ? 'there is no "claude" on the path' : `"${command}" cannot be run`}`);
+            }
+            if (!(await deps.loggedIn(binary, env)))
+                throw new ChatRefused('Claude is not logged in; run "claude" once to log in');
+            const conversation = new ClaudeConversation(options, resume);
+            try {
+                await conversation.start(deps, { folder, binary, env });
+            }
+            catch (error) {
+                log.error('claude could not be started', error);
+                await conversation.close();
+                throw new ChatRefused(resume === undefined ? 'Claude could not be started' : 'Claude could not resume that conversation');
+            }
+            return conversation;
+        },
+    };
+}
+class ClaudeConversation {
+    nativeId;
+    listeners = [];
+    endListeners = [];
+    query;
+    models = [];
+    /** What the SDK lists to invoke (skills of the person, the project and plugins, and Claude Code's own commands). */
+    slash = [];
+    /** The ones whose use is the terminal's (`/exit`): a message box has no business listing them. */
+    terminalOnly = new Set();
+    mode;
+    model;
+    effort;
+    input = inputQueue();
+    pending = new Map();
+    tools = new Map();
+    turning = false;
+    interrupting = false;
+    /** Turns that Carrier started itself (an `/effort` change) and the person must not see. */
+    hidden = 0;
+    lastModel;
+    closing = false;
+    pid;
+    command;
+    chosen;
+    constructor(chosen, resume) {
+        this.chosen = chosen;
+        this.nativeId = resume;
+        this.mode = chosen.permissionMode ?? 'default';
+        this.model = chosen.model ?? 'default';
+        this.effort = chosen.effort ?? '';
+    }
+    async start(deps, { folder, binary, env }) {
+        const spawnOwn = deps.spawn && ((o) => {
+            const child = deps.spawn(o);
+            this.pid = child.pid;
+            this.command = o.command;
+            return child;
+        });
+        this.query = deps.query({
+            prompt: this.input.iterable,
+            options: {
+                cwd: folder,
+                env,
+                pathToClaudeCodeExecutable: binary,
+                includePartialMessages: true,
+                canUseTool: (tool, input, { toolUseID, suggestions = [], title }) => this.ask(toolUseID, tool, input, suggestions, title),
+                ...(spawnOwn && { spawnClaudeCodeProcess: spawnOwn }),
+                ...(this.chosen.model && { model: this.chosen.model }),
+                ...(this.chosen.permissionMode && { permissionMode: this.chosen.permissionMode }),
+                ...(this.chosen.effort && { effort: this.chosen.effort }),
+                ...(this.nativeId && { resume: this.nativeId }),
+            },
+        });
+        const ready = await this.query.initializationResult();
+        this.models = ready.models;
+        this.slash = ready.commands ?? [];
+        void this.pump();
+    }
+    get process() {
+        return this.pid === undefined || this.command === undefined ? undefined : { pid: this.pid, pgid: this.pid, command: this.command }; // it leads its own group (`ownGroup`)
+    }
+    get options() {
+        const efforts = this.models.find((m) => m.value === this.model)?.supportedEffortLevels ?? this.models.find((m) => m.value === 'default')?.supportedEffortLevels ?? [];
+        return [
+            { id: 'permissionMode', label: 'Permission mode', values: PERMISSION_MODES, current: this.mode },
+            { id: 'model', label: 'Model', values: this.models.map((m) => ({ id: m.value, label: m.displayName, ...(m.description && { detail: m.description }), ...(m.resolvedModel && { version: m.resolvedModel }) })), current: this.model },
+            ...(efforts.length > 0 ? [{ id: 'effort', label: 'Reasoning effort', values: efforts.map((id) => ({ id, label: id })), current: this.effort }] : []),
+        ];
+    }
+    get commands() {
+        return this.slash
+            .filter((c) => !this.terminalOnly.has(c.name))
+            .map((c) => ({ id: c.name, name: c.name, description: c.description, ...(c.argumentHint && { argumentHint: c.argumentHint }), kind: c.builtin ? 'command' : 'skill' }));
+    }
+    send(text, command) {
+        this.turning = true;
+        this.interrupting = false;
+        // Claude Code reads a slash at the start of a message as the command or skill that follows it
+        this.input.push(command === undefined ? text : `/${command.name}${text === '' ? '' : ` ${text}`}`);
+    }
+    answer(approvalId, choiceId) {
+        const ask = this.pending.get(approvalId);
+        if (ask === undefined)
+            throw new ChatRefused('That approval is not pending any more');
+        const suggestion = choiceId.startsWith('suggestion:') ? ask.suggestions[Number(choiceId.slice('suggestion:'.length))] : undefined;
+        if (choiceId === 'deny')
+            ask.resolve({ behavior: 'deny', message: 'The user declined this.' });
+        else if (choiceId === 'allow')
+            ask.resolve({ behavior: 'allow', updatedInput: ask.input });
+        else if (suggestion)
+            ask.resolve({ behavior: 'allow', updatedInput: ask.input, updatedPermissions: [suggestion] });
+        else
+            throw new ChatRefused('That is not one of the choices');
+        this.pending.delete(approvalId);
+        this.emit({ kind: 'approval_answered', approvalId, choiceId });
+    }
+    async interrupt() {
+        if (!this.turning)
+            return;
+        this.interrupting = true;
+        this.denyPending();
+        await this.query.interrupt();
+        // The turn ends at its `result`; wait for it, so the host never sees the next turn start before this one's end.
+        for (let waited = 0; this.turning && waited < 5_000; waited += 50)
+            await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    async setOption(id, value) {
+        const option = this.options.find((o) => o.id === id);
+        if (option === undefined)
+            throw new ChatRefused(`There is no option "${id}"`);
+        if (!option.values.some((v) => v.id === value))
+            throw new ChatRefused(`"${value}" is not a value of ${id}`);
+        if (id === 'permissionMode') {
+            await this.query.setPermissionMode(value);
+            this.mode = value;
+        }
+        else if (id === 'model') {
+            await this.query.setModel(value === 'default' ? undefined : value);
+            this.model = value;
+        }
+        else {
+            if (this.turning)
+                throw new ChatRefused('The reasoning effort can only change between turns');
+            this.hidden++;
+            this.input.push(`/effort ${value}`);
+            this.effort = value;
+        }
+        this.emit({ kind: 'option', id, value });
+    }
+    async close() {
+        if (this.closing)
+            return;
+        this.closing = true;
+        this.denyPending();
+        this.input.end();
+        this.query?.close();
+        if (this.pid !== undefined)
+            await endGroup(this.pid);
+    }
+    onEvent(listener) {
+        this.listeners.push(listener);
+    }
+    onEnd(listener) {
+        this.endListeners.push(listener);
+    }
+    emit(...events) {
+        for (const event of events)
+            for (const listener of this.listeners)
+                listener(event);
+    }
+    denyPending() {
+        for (const ask of this.pending.values())
+            ask.resolve({ behavior: 'deny', message: 'The turn was interrupted.', interrupt: true });
+        this.pending.clear();
+    }
+    ask(approvalId, tool, input, suggestions, title) {
+        const choices = [
+            { id: 'allow', label: 'Allow', allow: true },
+            { id: 'deny', label: 'Deny', allow: false },
+            ...suggestions.map((s, i) => ({ id: `suggestion:${i}`, label: labelOf(s), allow: true })),
+        ];
+        return new Promise((resolve) => {
+            this.pending.set(approvalId, { input, suggestions, resolve });
+            this.emit({ kind: 'approval', approvalId, tool, arg: argOf(input) ?? title, choices });
+        });
+    }
+    async pump() {
+        try {
+            for await (const message of this.query) {
+                try {
+                    this.emit(...this.translate(message));
+                }
+                catch (error) {
+                    log.error('a claude message could not be handled', error);
+                }
+            }
+        }
+        catch (error) {
+            if (!this.closing)
+                log.error('the claude stream failed', error);
+        }
+        if (this.closing)
+            return;
+        // The process ended on its own: that is the end of the turn that was running.
+        this.emit({ kind: 'error', text: 'The Claude process ended' });
+        if (this.turning)
+            this.emit({ kind: 'turn_end', outcome: 'error', model: this.lastModel });
+        this.turning = false;
+        for (const listener of this.endListeners)
+            listener();
+    }
+    /** The events of one SDK message. Never throws on a shape it does not know: that message gives none. */
+    translate(message) {
+        const m = message;
+        if (typeof m.session_id === 'string')
+            this.nativeId = m.session_id;
+        if (m.type === 'result')
+            return this.turnEnd(m);
+        if (this.hidden > 0)
+            return [];
+        switch (m.type) {
+            case 'system':
+                if (m.subtype === 'init' && typeof m.permissionMode === 'string')
+                    this.mode = m.permissionMode;
+                if (m.subtype === 'init' && Array.isArray(m.terminal_slash_commands))
+                    this.terminalOnly = new Set(m.terminal_slash_commands);
+                if (m.subtype === 'status' && typeof m.permissionMode === 'string' && m.permissionMode !== this.mode) {
+                    this.mode = m.permissionMode;
+                    return [{ kind: 'option', id: 'permissionMode', value: this.mode }];
+                }
+                return [];
+            case 'stream_event': {
+                const delta = m.event?.type === 'content_block_delta' && m.event.delta?.type === 'text_delta' ? m.event.delta.text : undefined;
+                return typeof delta === 'string' && delta !== '' ? [{ kind: 'delta', text: delta }] : [];
+            }
+            case 'assistant': {
+                if (typeof m.message?.model === 'string')
+                    this.lastModel = m.message.model;
+                const events = [];
+                for (const block of Array.isArray(m.message?.content) ? m.message.content : []) {
+                    if (block?.type === 'text' && typeof block.text === 'string' && block.text !== '')
+                        events.push({ kind: 'assistant', text: block.text });
+                    if (block?.type === 'tool_use' && typeof block.id === 'string') {
+                        this.tools.set(block.id, String(block.name));
+                        events.push({ kind: 'tool_start', callId: block.id, tool: String(block.name), arg: argOf(block.input) });
+                    }
+                }
+                return events;
+            }
+            case 'user': {
+                const events = [];
+                for (const block of Array.isArray(m.message?.content) ? m.message.content : []) {
+                    if (block?.type !== 'tool_result' || typeof block.tool_use_id !== 'string')
+                        continue;
+                    events.push({ kind: 'tool_end', callId: block.tool_use_id, tool: this.tools.get(block.tool_use_id) ?? '', output: textOf(block.content).split('\n'), status: block.is_error ? 'err' : 'ok' });
+                }
+                return events;
+            }
+            default:
+                return [];
+        }
+    }
+    turnEnd(m) {
+        if (this.hidden > 0) {
+            this.hidden--;
+            return [];
+        }
+        const interrupted = this.interrupting;
+        this.turning = false;
+        this.interrupting = false;
+        const events = [];
+        if (m.is_error && !interrupted)
+            events.push({ kind: 'error', text: Array.isArray(m.errors) && m.errors.length > 0 ? m.errors.join('\n') : 'The turn failed' });
+        const usage = {};
+        for (const [key, value] of Object.entries((m.usage ?? {})))
+            if (typeof value === 'number')
+                usage[key] = value;
+        if (typeof m.total_cost_usd === 'number')
+            usage.total_cost_usd = m.total_cost_usd;
+        const model = this.lastModel ?? Object.keys((m.modelUsage ?? {}))[0];
+        events.push({ kind: 'turn_end', outcome: interrupted ? 'interrupted' : m.is_error ? 'error' : 'ok', model, usage });
+        return events;
+    }
+}
+/** Messages the person typed, as the stream the SDK reads; it ends when the conversation closes. */
+function inputQueue() {
+    const waiting = [];
+    let wake;
+    let ended = false;
+    return {
+        push(text) {
+            waiting.push({ type: 'user', message: { role: 'user', content: text }, parent_tool_use_id: null });
+            wake?.();
+        },
+        end() {
+            ended = true;
+            wake?.();
+        },
+        iterable: (async function* () {
+            while (true) {
+                const next = waiting.shift();
+                if (next !== undefined)
+                    yield next;
+                else if (ended)
+                    return;
+                else
+                    await new Promise((resolve) => void (wake = resolve));
+            }
+        })(),
+    };
+}
+const textOf = (content) => typeof content === 'string' ? content : Array.isArray(content) ? content.map((c) => (typeof c?.text === 'string' ? c.text : '')).join('\n') : '';
+/** What a tool call is about, in one string: the command, the path, the pattern, else its input as JSON. */
+const argOf = (input) => {
+    if (typeof input !== 'object' || input === null)
+        return undefined;
+    const fields = input;
+    const main = [fields.command, fields.file_path, fields.path, fields.pattern, fields.url].find((v) => typeof v === 'string');
+    return typeof main === 'string' ? main : JSON.stringify(input);
+};
+const labelOf = (update) => {
+    switch (update.type) {
+        case 'addRules':
+            return `Always allow ${update.rules.map((r) => r.ruleContent ?? r.toolName).join(', ')}`;
+        case 'addDirectories':
+            return `Allow ${update.directories.join(', ')}`;
+        case 'setMode':
+            return `Allow and switch to ${update.mode}`;
+        default:
+            return 'Allow and change the permissions';
+    }
+};