@ouro.bot/cli 0.1.0-alpha.8 → 0.1.0-alpha.81

package/dist/senses/cli.js

@@ -33,11 +33,18 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MarkdownStreamer = exports.InputController = exports.Spinner = void 0;
+exports.MarkdownStreamer = exports.InputController = exports.Spinner = exports.StreamingWordWrapper = exports.wrapCliText = exports.formatEchoedInputSummary = void 0;
+exports.formatPendingPrefix = formatPendingPrefix;
+exports.getCliContinuityIngressTexts = getCliContinuityIngressTexts;
+exports.pauseActiveSpinner = pauseActiveSpinner;
+exports.resumeActiveSpinner = resumeActiveSpinner;
+exports.setActiveSpinner = setActiveSpinner;
 exports.handleSigint = handleSigint;
 exports.addHistory = addHistory;
 exports.renderMarkdown = renderMarkdown;
 exports.createCliCallbacks = createCliCallbacks;
+exports.createDebouncedLines = createDebouncedLines;
+exports.runCliSession = runCliSession;
 exports.main = main;
 const readline = __importStar(require("readline"));
 const os = __importStar(require("os"));
@@ -49,9 +56,9 @@ const format_1 = require("../mind/format");
 const config_1 = require("../heart/config");
 const context_1 = require("../mind/context");
 const pending_1 = require("../mind/pending");
-const prompt_refresh_1 = require("../mind/prompt-refresh");
 const commands_1 = require("./commands");
 const identity_1 = require("../heart/identity");
+const mcp_manager_1 = require("../repertoire/mcp-manager");
 const nerves_1 = require("../nerves");
 const store_file_1 = require("../mind/friends/store-file");
 const resolver_1 = require("../mind/friends/resolver");
@@ -59,7 +66,42 @@ const tokens_1 = require("../mind/friends/tokens");
 const cli_logging_1 = require("../nerves/cli-logging");
 const runtime_1 = require("../nerves/runtime");
 const trust_gate_1 = require("./trust-gate");
+const pipeline_1 = require("./pipeline");
+const channel_1 = require("../mind/friends/channel");
 const session_lock_1 = require("./session-lock");
+const update_hooks_1 = require("../heart/daemon/update-hooks");
+const bundle_meta_1 = require("../heart/daemon/hooks/bundle-meta");
+const bundle_manifest_1 = require("../mind/bundle-manifest");
+const cli_layout_1 = require("./cli-layout");
+var cli_layout_2 = require("./cli-layout");
+Object.defineProperty(exports, "formatEchoedInputSummary", { enumerable: true, get: function () { return cli_layout_2.formatEchoedInputSummary; } });
+Object.defineProperty(exports, "wrapCliText", { enumerable: true, get: function () { return cli_layout_2.wrapCliText; } });
+Object.defineProperty(exports, "StreamingWordWrapper", { enumerable: true, get: function () { return cli_layout_2.StreamingWordWrapper; } });
+/**
+ * Format pending messages as content-prefix strings for injection into
+ * the next user message. Self-messages (from === agentName) become
+ * `[inner thought: {content}]`, inter-agent messages become
+ * `[message from {name}: {content}]`.
+ */
+function formatPendingPrefix(messages, agentName) {
+    return messages
+        .map((msg) => msg.from === agentName
+        ? `[inner thought: ${msg.content}]`
+        : `[message from ${msg.from}: ${msg.content}]`)
+        .join("\n");
+}
+function getCliContinuityIngressTexts(input) {
+    const trimmed = input.trim();
+    return trimmed ? [trimmed] : [];
+}
+// Module-level active spinner for log coordination.
+// The terminal log sink calls these to avoid interleaving with spinner output.
+let _activeSpinner = null;
+/* v8 ignore start -- spinner coordination: exercised at runtime, not unit-testable without real terminal @preserve */
+function pauseActiveSpinner() { _activeSpinner?.pause(); }
+function resumeActiveSpinner() { _activeSpinner?.resume(); }
+/* v8 ignore stop */
+function setActiveSpinner(s) { _activeSpinner = s; }
 // spinner that only touches stderr, cleans up after itself
 // exported for direct testability (stop-without-start branch)
 class Spinner {
@@ -70,12 +112,14 @@ class Spinner {
     msg = "";
     phrases = null;
     lastPhrase = "";
+    stopped = false;
     constructor(m = "working", phrases) {
         this.msg = m;
         if (phrases && phrases.length > 0)
             this.phrases = phrases;
     }
     start() {
+        this.stopped = false;
         process.stderr.write("\r\x1b[K");
         this.spin();
         this.iv = setInterval(() => this.spin(), 80);
@@ -84,15 +128,37 @@ class Spinner {
         }
     }
     spin() {
-        process.stderr.write(`\r${this.frames[this.i]} ${this.msg}... `);
+        // Guard: clearInterval can't prevent already-dequeued callbacks
+        /* v8 ignore next -- race guard: timer callback fires after stop() @preserve */
+        if (this.stopped)
+            return;
+        process.stderr.write(`\r\x1b[K${this.frames[this.i]} ${this.msg}... `);
         this.i = (this.i + 1) % this.frames.length;
     }
     rotatePhrase() {
+        /* v8 ignore next -- race guard: timer callback fires after stop() @preserve */
+        if (this.stopped)
+            return;
         const next = (0, phrases_1.pickPhrase)(this.phrases, this.lastPhrase);
         this.lastPhrase = next;
         this.msg = next;
     }
+    /* v8 ignore start -- pause/resume: exercised at runtime via log sink coordination @preserve */
+    /** Clear the spinner line temporarily so other output can print cleanly. */
+    pause() {
+        if (this.stopped)
+            return;
+        process.stderr.write("\r\x1b[K");
+    }
+    /** Restore the spinner line after a pause. */
+    resume() {
+        if (this.stopped)
+            return;
+        this.spin();
+    }
+    /* v8 ignore stop */
     stop(ok) {
+        this.stopped = true;
         if (this.iv) {
             clearInterval(this.iv);
             this.iv = null;
@@ -279,38 +345,64 @@ function createCliCallbacks() {
         meta: {},
     });
     let currentSpinner = null;
+    function setSpinner(s) { currentSpinner = s; setActiveSpinner(s); }
     let hadReasoning = false;
     let hadToolRun = false;
     let textDirty = false; // true when text/reasoning was written without a trailing newline
     const streamer = new MarkdownStreamer();
+    const wrapper = new cli_layout_1.StreamingWordWrapper();
     return {
         onModelStart: () => {
             currentSpinner?.stop();
-            currentSpinner = null;
+            setSpinner(null);
             hadReasoning = false;
             textDirty = false;
             streamer.reset();
+            wrapper.reset();
             const phrases = (0, phrases_1.getPhrases)();
             const pool = hadToolRun ? phrases.followup : phrases.thinking;
             const first = (0, phrases_1.pickPhrase)(pool);
-            currentSpinner = new Spinner(first, pool);
+            setSpinner(new Spinner(first, pool));
             currentSpinner.start();
         },
         onModelStreamStart: () => {
-            currentSpinner?.stop();
-            currentSpinner = null;
+            // No-op: content callbacks (onTextChunk, onReasoningChunk) handle
+            // stopping the spinner. onModelStreamStart fires too early and
+            // doesn't fire at all for final_answer tool streaming.
+        },
+        onClearText: () => {
+            streamer.reset();
+            wrapper.reset();
         },
         onTextChunk: (text) => {
+            // Stop spinner if still running — final_answer streaming and Anthropic
+            // tool-only responses bypass onModelStreamStart, so the spinner would
+            // otherwise keep running (and its \r writes overwrite response text).
+            if (currentSpinner) {
+                currentSpinner.stop();
+                setSpinner(null);
+            }
             if (hadReasoning) {
-                process.stdout.write("\n\n");
+                // Single newline to separate reasoning from reply — reasoning
+                // output often ends with its own trailing newline(s)
+                process.stdout.write("\n");
                 hadReasoning = false;
             }
             const rendered = streamer.push(text);
-            if (rendered)
-                process.stdout.write(rendered);
+            /* v8 ignore start -- wrapper integration: tested via cli.test.ts onTextChunk tests @preserve */
+            if (rendered) {
+                const wrapped = wrapper.push(rendered);
+                if (wrapped)
+                    process.stdout.write(wrapped);
+            }
+            /* v8 ignore stop */
             textDirty = text.length > 0 && !text.endsWith("\n");
         },
         onReasoningChunk: (text) => {
+            if (currentSpinner) {
+                currentSpinner.stop();
+                setSpinner(null);
+            }
             hadReasoning = true;
             process.stdout.write(`\x1b[2m${text}\x1b[0m`);
             textDirty = text.length > 0 && !text.endsWith("\n");
@@ -328,13 +420,13 @@ function createCliCallbacks() {
             }
             const toolPhrases = (0, phrases_1.getPhrases)().tool;
             const first = (0, phrases_1.pickPhrase)(toolPhrases);
-            currentSpinner = new Spinner(first, toolPhrases);
+            setSpinner(new Spinner(first, toolPhrases));
             currentSpinner.start();
             hadToolRun = true;
         },
         onToolEnd: (name, argSummary, success) => {
             currentSpinner?.stop();
-            currentSpinner = null;
+            setSpinner(null);
             const msg = (0, format_1.formatToolResult)(name, argSummary, success);
             const color = success ? "\x1b[32m" : "\x1b[31m";
             process.stderr.write(`${color}${msg}\x1b[0m\n`);
@@ -342,17 +434,17 @@ function createCliCallbacks() {
         onError: (error, severity) => {
             if (severity === "transient") {
                 currentSpinner?.fail(error.message);
-                currentSpinner = null;
+                setSpinner(null);
             }
             else {
                 currentSpinner?.stop();
-                currentSpinner = null;
+                setSpinner(null);
                 process.stderr.write(`\x1b[31m${(0, format_1.formatError)(error)}\x1b[0m\n`);
             }
         },
         onKick: () => {
             currentSpinner?.stop();
-            currentSpinner = null;
+            setSpinner(null);
             if (textDirty) {
                 process.stdout.write("\n");
                 textDirty = false;
@@ -361,95 +453,101 @@ function createCliCallbacks() {
         },
         flushMarkdown: () => {
             currentSpinner?.stop();
-            currentSpinner = null;
+            setSpinner(null);
+            /* v8 ignore start -- wrapper flush: tested via cli.test.ts flushMarkdown tests @preserve */
             const remaining = streamer.flush();
-            if (remaining)
-                process.stdout.write(remaining);
+            if (remaining) {
+                const wrapped = wrapper.push(remaining);
+                if (wrapped)
+                    process.stdout.write(wrapped);
+            }
+            const tail = wrapper.flush();
+            if (tail)
+                process.stdout.write(tail);
+            /* v8 ignore stop */
         },
     };
 }
-async function main(agentName, options) {
-    if (agentName)
-        (0, identity_1.setAgentName)(agentName);
-    const pasteDebounceMs = options?.pasteDebounceMs ?? 50;
-    // Fail fast if provider is misconfigured (triggers human-readable error + exit)
-    (0, core_1.getProvider)();
-    const registry = (0, commands_1.createCommandRegistry)();
-    (0, commands_1.registerDefaultCommands)(registry);
-    // Resolve context kernel (identity + channel) for CLI
-    const friendsPath = path.join((0, identity_1.getAgentRoot)(), "friends");
-    const friendStore = new store_file_1.FileFriendStore(friendsPath);
-    const username = os.userInfo().username;
-    const hostname = os.hostname();
-    const localExternalId = `${username}@${hostname}`;
-    const resolver = new resolver_1.FriendResolver(friendStore, {
-        provider: "local",
-        externalId: localExternalId,
-        displayName: username,
-        channel: "cli",
-    });
-    const resolvedContext = await resolver.resolve();
-    const cliToolContext = {
-        /* v8 ignore next -- CLI has no OAuth sign-in; this no-op satisfies the interface @preserve */
-        signin: async () => undefined,
-        context: resolvedContext,
-        friendStore,
-        summarize: (0, core_1.createSummarize)(),
-    };
-    const friendId = resolvedContext.friend.id;
-    const agentConfig = (0, identity_1.loadAgentConfig)();
-    (0, cli_logging_1.configureCliRuntimeLogger)(friendId, {
-        level: agentConfig.logging?.level,
-        sinks: agentConfig.logging?.sinks,
-    });
-    const sessPath = (0, config_1.sessionPath)(friendId, "cli", "session");
-    let sessionLock = null;
-    try {
-        sessionLock = (0, session_lock_1.acquireSessionLock)(`${sessPath}.lock`, (0, identity_1.getAgentName)());
+// Debounced line iterator: collects rapid-fire lines (paste) into a single input.
+// When the debounce timeout wins the race, the pending iter.next() is saved
+// and reused in the next iteration to prevent it from silently consuming input.
+async function* createDebouncedLines(source, debounceMs) {
+    if (debounceMs <= 0) {
+        yield* source;
+        return;
     }
-    catch (error) {
-        /* v8 ignore start -- integration: main() is interactive, lock tested in session-lock.test.ts @preserve */
-        if (error instanceof session_lock_1.SessionLockError) {
-            process.stderr.write(`${error.message}\n`);
-            return;
+    const iter = source[Symbol.asyncIterator]();
+    let pending = null;
+    while (true) {
+        const first = pending ? await pending : await iter.next();
+        pending = null;
+        if (first.done)
+            break;
+        const lines = [first.value];
+        let more = true;
+        while (more) {
+            const nextPromise = iter.next();
+            const raced = await Promise.race([
+                nextPromise.then((r) => ({ kind: "line", result: r })),
+                new Promise((r) => setTimeout(() => r({ kind: "timeout" }), debounceMs)),
+            ]);
+            if (raced.kind === "timeout") {
+                pending = nextPromise;
+                more = false;
+            }
+            else if (raced.result.done) {
+                more = false;
+            }
+            else {
+                lines.push(raced.result.value);
+            }
         }
-        throw error;
-        /* v8 ignore stop */
+        yield lines.join("\n");
     }
-    // Load existing session or start fresh
-    const existing = (0, context_1.loadSession)(sessPath);
-    const messages = existing?.messages && existing.messages.length > 0
-        ? existing.messages
-        : [{ role: "system", content: await (0, prompt_1.buildSystem)("cli", undefined, resolvedContext) }];
-    // Pending queue drain: inject pending messages as harness-context + assistant-content pairs
-    const pendingDir = (0, pending_1.getPendingDir)((0, identity_1.getAgentName)(), friendId, "cli", "session");
-    const drainToMessages = () => {
-        const pending = (0, pending_1.drainPending)(pendingDir);
-        if (pending.length === 0)
-            return 0;
-        for (const msg of pending) {
-            messages.push({ role: "user", name: "harness", content: `[proactive message from ${msg.from}]` });
-            messages.push({ role: "assistant", content: msg.content });
-        }
-        return pending.length;
-    };
-    // Startup drain: deliver offline messages
-    const startupCount = drainToMessages();
-    if (startupCount > 0) {
-        (0, context_1.saveSession)(sessPath, messages);
+}
+async function runCliSession(options) {
+    /* v8 ignore start -- integration: runCliSession is interactive, tested via E2E @preserve */
+    const pasteDebounceMs = options.pasteDebounceMs ?? 50;
+    const registry = (0, commands_1.createCommandRegistry)();
+    if (!options.disableCommands) {
+        (0, commands_1.registerDefaultCommands)(registry);
     }
+    const messages = options.messages
+        ?? [{ role: "system", content: await (0, prompt_1.buildSystem)("cli") }];
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: true });
     const ctrl = new InputController(rl);
     let currentAbort = null;
     const history = [];
     let closed = false;
     rl.on("close", () => { closed = true; });
-    // eslint-disable-next-line no-console -- terminal UX: startup banner
-    console.log(`\n${(0, identity_1.getAgentName)()} (type /commands for help)\n`);
+    if (options.banner !== false) {
+        const bannerText = typeof options.banner === "string"
+            ? options.banner
+            : `${options.agentName} (type /commands for help)`;
+        // eslint-disable-next-line no-console -- terminal UX: startup banner
+        console.log(`\n${bannerText}\n`);
+    }
     const cliCallbacks = createCliCallbacks();
-    process.stdout.write("\x1b[36m> \x1b[0m");
+    // exitOnToolCall machinery: wrap execTool to detect target tool
+    let exitToolResult;
+    let exitToolFired = false;
+    const resolvedExecTool = options.execTool;
+    const wrappedExecTool = options.exitOnToolCall && resolvedExecTool
+        ? async (name, args, ctx) => {
+            const result = await resolvedExecTool(name, args, ctx);
+            if (name === options.exitOnToolCall) {
+                exitToolResult = result;
+                exitToolFired = true;
+                // Abort immediately so the model doesn't generate more output
+                // (e.g. reasoning about calling final_answer after complete_adoption)
+                currentAbort?.abort();
+            }
+            return result;
+        }
+        : resolvedExecTool;
+    // Resolve toolChoiceRequired: use explicit option if set, else fall back to toggle
+    const getEffectiveToolChoiceRequired = () => options.toolChoiceRequired !== undefined ? options.toolChoiceRequired : (0, commands_1.getToolChoiceRequired)();
     // Ctrl-C at the input prompt: clear line or warn/exit
-    // readline with terminal:true catches Ctrl-C in raw mode (no ^C echo)
     rl.on("SIGINT", () => {
         const rlInt = rl;
         const currentLine = rlInt.line || "";
@@ -470,38 +568,58 @@ async function main(agentName, options) {
             rl.close();
         }
     });
-    // Debounced line iterator: collects rapid-fire lines (paste) into a single input
-    async function* debouncedLines(source) {
-        if (pasteDebounceMs <= 0) {
-            yield* source;
-            return;
+    const debouncedLines = (source) => createDebouncedLines(source, pasteDebounceMs);
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.cli_session_start",
+        message: "runCliSession started",
+        meta: { agentName: options.agentName, hasExitOnToolCall: !!options.exitOnToolCall },
+    });
+    let exitReason = "user_quit";
+    // Auto-first-turn: process the last user message immediately so the agent
+    // speaks first (e.g. specialist greeting). Only triggers when explicitly opted in.
+    if (options.autoFirstTurn && messages.length > 0 && messages[messages.length - 1]?.role === "user") {
+        currentAbort = new AbortController();
+        const traceId = (0, nerves_1.createTraceId)();
+        ctrl.suppress(() => currentAbort.abort());
+        let result;
+        try {
+            result = await (0, core_1.runAgent)(messages, cliCallbacks, options.skipSystemPromptRefresh ? undefined : "cli", currentAbort.signal, {
+                toolChoiceRequired: getEffectiveToolChoiceRequired(),
+                traceId,
+                tools: options.tools,
+                execTool: wrappedExecTool,
+                toolContext: options.toolContext,
+            });
         }
-        const iter = source[Symbol.asyncIterator]();
-        while (true) {
-            const first = await iter.next();
-            if (first.done)
-                break;
-            // Collect any lines that arrive within the debounce window (paste detection)
-            const lines = [first.value];
-            let more = true;
-            while (more) {
-                const raced = await Promise.race([
-                    iter.next().then((r) => ({ kind: "line", result: r })),
-                    new Promise((r) => setTimeout(() => r({ kind: "timeout" }), pasteDebounceMs)),
-                ]);
-                if (raced.kind === "timeout") {
-                    more = false;
-                }
-                else if (raced.result.done) {
-                    more = false;
-                }
-                else {
-                    lines.push(raced.result.value);
-                }
+        catch (err) {
+            // AbortError (Ctrl-C) -- silently continue to prompt
+            // All other errors: show the user what happened
+            if (!(err instanceof DOMException && err.name === "AbortError")) {
+                process.stderr.write(`\x1b[31m${err instanceof Error ? err.message : String(err)}\x1b[0m\n`);
+            }
+        }
+        cliCallbacks.flushMarkdown();
+        ctrl.restore();
+        currentAbort = null;
+        if (exitToolFired) {
+            exitReason = "tool_exit";
+            rl.close();
+        }
+        else {
+            const lastMsg = messages[messages.length - 1];
+            if (lastMsg?.role === "assistant" && !(typeof lastMsg.content === "string" ? lastMsg.content : "").trim()) {
+                process.stderr.write("\x1b[33m(empty response)\x1b[0m\n");
+            }
+            process.stdout.write("\n\n");
+            if (options.onTurnEnd) {
+                await options.onTurnEnd(messages, result ?? { usage: undefined });
             }
-            yield lines.join("\n");
         }
     }
+    if (!exitToolFired) {
+        process.stdout.write("\x1b[36m> \x1b[0m");
+    }
     try {
         for await (const input of debouncedLines(rl)) {
             if (closed)
@@ -510,20 +628,18 @@ async function main(agentName, options) {
                 process.stdout.write("\x1b[36m> \x1b[0m");
                 continue;
             }
-            const trustGate = (0, trust_gate_1.enforceTrustGate)({
-                friend: resolvedContext.friend,
-                provider: "local",
-                externalId: localExternalId,
-                channel: "cli",
-            });
-            if (!trustGate.allowed) {
-                if (trustGate.reason === "stranger_first_reply") {
-                    process.stdout.write(`${trustGate.autoReply}\n`);
+            // Optional input gate (e.g. trust gate in main)
+            if (options.onInput) {
+                const gate = options.onInput(input);
+                if (!gate.allowed) {
+                    if (gate.reply) {
+                        process.stdout.write(`${gate.reply}\n`);
+                    }
+                    if (closed)
+                        break;
+                    process.stdout.write("\x1b[36m> \x1b[0m");
+                    continue;
                 }
-                if (closed)
-                    break;
-                process.stdout.write("\x1b[36m> \x1b[0m");
-                continue;
             }
             // Check for slash commands
             const parsed = (0, commands_1.parseSlashCommand)(input);
@@ -536,7 +652,7 @@ async function main(agentName, options) {
                     else if (dispatchResult.result.action === "new") {
                         messages.length = 0;
                         messages.push({ role: "system", content: await (0, prompt_1.buildSystem)("cli") });
-                        (0, context_1.deleteSession)(sessPath);
+                        await options.onNewSession?.();
                         // eslint-disable-next-line no-console -- terminal UX: session cleared
                         console.log("session cleared");
                         process.stdout.write("\x1b[36m> \x1b[0m");
@@ -550,55 +666,188 @@ async function main(agentName, options) {
                     }
                 }
             }
-            // Re-style the echoed input lines (readline terminal:true echoes each line)
-            // For multiline paste, each line was echoed separately — erase them all
+            // Re-style the echoed input lines without leaving wrapped paste remnants behind.
             const cols = process.stdout.columns || 80;
-            const inputLines = input.split("\n");
-            let echoRows = 0;
-            for (const line of inputLines) {
-                echoRows += Math.ceil((2 + line.length) / cols); // "> " prefix + line content
-            }
-            process.stdout.write(`\x1b[${echoRows}A\x1b[K` + `\x1b[1m> ${inputLines[0]}${inputLines.length > 1 ? ` (+${inputLines.length - 1} lines)` : ""}\x1b[0m\n\n`);
-            messages.push({ role: "user", content: input });
+            process.stdout.write((0, cli_layout_1.formatEchoedInputSummary)(input, cols));
             addHistory(history, input);
             currentAbort = new AbortController();
-            const traceId = (0, nerves_1.createTraceId)();
             ctrl.suppress(() => currentAbort.abort());
             let result;
             try {
-                result = await (0, core_1.runAgent)(messages, cliCallbacks, "cli", currentAbort.signal, {
-                    toolChoiceRequired: (0, commands_1.getToolChoiceRequired)(),
-                    toolContext: cliToolContext,
-                    traceId,
-                });
+                if (options.runTurn) {
+                    // Pipeline-based turn: the runTurn callback handles user message assembly,
+                    // pending drain, trust gate, runAgent, postTurn, and token accumulation.
+                    result = await options.runTurn(messages, input, cliCallbacks, currentAbort.signal);
+                }
+                else {
+                    // Legacy path: inline runAgent (used by adoption specialist and tests)
+                    const prefix = options.getContentPrefix?.();
+                    messages.push({ role: "user", content: prefix ? `${prefix}\n\n${input}` : input });
+                    const traceId = (0, nerves_1.createTraceId)();
+                    result = await (0, core_1.runAgent)(messages, cliCallbacks, options.skipSystemPromptRefresh ? undefined : "cli", currentAbort.signal, {
+                        toolChoiceRequired: getEffectiveToolChoiceRequired(),
+                        traceId,
+                        tools: options.tools,
+                        execTool: wrappedExecTool,
+                        toolContext: options.toolContext,
+                    });
+                }
             }
-            catch {
-                // AbortError — silently return to prompt
+            catch (err) {
+                // AbortError (Ctrl-C) -- silently return to prompt
+                // All other errors: show the user what happened
+                if (!(err instanceof DOMException && err.name === "AbortError")) {
+                    process.stderr.write(`\x1b[31m${err instanceof Error ? err.message : String(err)}\x1b[0m\n`);
+                }
             }
             cliCallbacks.flushMarkdown();
             ctrl.restore();
             currentAbort = null;
+            // Check if exit tool was fired during this turn
+            if (exitToolFired) {
+                exitReason = "tool_exit";
+                break;
+            }
             // Safety net: never silently swallow an empty response
             const lastMsg = messages[messages.length - 1];
             if (lastMsg?.role === "assistant" && !(typeof lastMsg.content === "string" ? lastMsg.content : "").trim()) {
                 process.stderr.write("\x1b[33m(empty response)\x1b[0m\n");
             }
             process.stdout.write("\n\n");
-            (0, context_1.postTurn)(messages, sessPath, result?.usage);
-            await (0, tokens_1.accumulateFriendTokens)(friendStore, resolvedContext.friend.id, result?.usage);
-            // Post-turn: drain any pending messages that arrived during runAgent
-            drainToMessages();
-            // Post-turn: refresh system prompt so active sessions metadata is current
-            await (0, prompt_refresh_1.refreshSystemPrompt)(messages, "cli", undefined, resolvedContext);
+            // Post-turn hook (session persistence, pending drain, prompt refresh, etc.)
+            if (options.onTurnEnd) {
+                await options.onTurnEnd(messages, result ?? { usage: undefined });
+            }
             if (closed)
                 break;
             process.stdout.write("\x1b[36m> \x1b[0m");
         }
     }
     finally {
-        sessionLock?.release();
         rl.close();
-        // eslint-disable-next-line no-console -- terminal UX: goodbye
-        console.log("bye");
+        if (options.banner !== false) {
+            // eslint-disable-next-line no-console -- terminal UX: goodbye
+            console.log("bye");
+        }
+    }
+    /* v8 ignore stop */
+    return { exitReason, toolResult: exitToolResult };
+}
+async function main(agentName, options) {
+    if (agentName)
+        (0, identity_1.setAgentName)(agentName);
+    const pasteDebounceMs = options?.pasteDebounceMs ?? 50;
+    // Register spinner hooks so log output clears the spinner before printing
+    (0, nerves_1.registerSpinnerHooks)(pauseActiveSpinner, resumeActiveSpinner);
+    // Fallback: apply pending updates for daemon-less direct CLI usage
+    (0, update_hooks_1.registerUpdateHook)(bundle_meta_1.bundleMetaHook);
+    await (0, update_hooks_1.applyPendingUpdates)((0, identity_1.getAgentBundlesRoot)(), (0, bundle_manifest_1.getPackageVersion)());
+    // Fail fast if provider is misconfigured (triggers human-readable error + exit)
+    (0, core_1.getProvider)();
+    // Resolve context kernel (identity + channel) for CLI
+    const friendsPath = path.join((0, identity_1.getAgentRoot)(), "friends");
+    const friendStore = new store_file_1.FileFriendStore(friendsPath);
+    const username = os.userInfo().username;
+    const hostname = os.hostname();
+    const localExternalId = `${username}@${hostname}`;
+    const resolver = new resolver_1.FriendResolver(friendStore, {
+        provider: "local",
+        externalId: localExternalId,
+        displayName: username,
+        channel: "cli",
+    });
+    const resolvedContext = await resolver.resolve();
+    const friendId = resolvedContext.friend.id;
+    const agentConfig = (0, identity_1.loadAgentConfig)();
+    (0, cli_logging_1.configureCliRuntimeLogger)(friendId, {
+        level: agentConfig.logging?.level,
+        sinks: agentConfig.logging?.sinks,
+    });
+    const sessPath = (0, config_1.sessionPath)(friendId, "cli", "session");
+    let sessionLock = null;
+    try {
+        sessionLock = (0, session_lock_1.acquireSessionLock)(`${sessPath}.lock`, (0, identity_1.getAgentName)());
+    }
+    catch (error) {
+        /* v8 ignore start -- integration: main() is interactive, lock tested in session-lock.test.ts @preserve */
+        if (error instanceof session_lock_1.SessionLockError) {
+            process.stderr.write(`${error.message}\n`);
+            return;
+        }
+        throw error;
+        /* v8 ignore stop */
+    }
+    // Load existing session or start fresh
+    const existing = (0, context_1.loadSession)(sessPath);
+    let sessionState = existing?.state;
+    const mcpManager = await (0, mcp_manager_1.getSharedMcpManager)() ?? undefined;
+    const sessionMessages = existing?.messages && existing.messages.length > 0
+        ? existing.messages
+        : [{ role: "system", content: await (0, prompt_1.buildSystem)("cli", { mcpManager }, resolvedContext) }];
+    // Per-turn pipeline input: CLI capabilities and pending dir
+    const cliCapabilities = (0, channel_1.getChannelCapabilities)("cli");
+    const currentAgentName = (0, identity_1.getAgentName)();
+    const pendingDir = (0, pending_1.getPendingDir)(currentAgentName, friendId, "cli", "session");
+    const summarize = (0, core_1.createSummarize)();
+    try {
+        await runCliSession({
+            agentName: currentAgentName,
+            pasteDebounceMs,
+            messages: sessionMessages,
+            runTurn: async (messages, userInput, callbacks, signal) => {
+                // Run the full per-turn pipeline: resolve -> gate -> session -> drain -> runAgent -> postTurn -> tokens
+                // User message passed via input.messages so the pipeline can prepend pending messages to it.
+                const result = await (0, pipeline_1.handleInboundTurn)({
+                    channel: "cli",
+                    sessionKey: "session",
+                    capabilities: cliCapabilities,
+                    messages: [{ role: "user", content: userInput }],
+                    continuityIngressTexts: getCliContinuityIngressTexts(userInput),
+                    callbacks,
+                    friendResolver: { resolve: () => Promise.resolve(resolvedContext) },
+                    sessionLoader: { loadOrCreate: () => Promise.resolve({ messages, sessionPath: sessPath, state: sessionState }) },
+                    pendingDir,
+                    friendStore,
+                    provider: "local",
+                    externalId: localExternalId,
+                    enforceTrustGate: trust_gate_1.enforceTrustGate,
+                    drainPending: pending_1.drainPending,
+                    drainDeferredReturns: (deferredFriendId) => (0, pending_1.drainDeferredReturns)(currentAgentName, deferredFriendId),
+                    runAgent: (msgs, cb, channel, sig, opts) => (0, core_1.runAgent)(msgs, cb, channel, sig, {
+                        ...opts,
+                        toolContext: {
+                            /* v8 ignore next -- default no-op signin; pipeline provides the real one @preserve */
+                            signin: async () => undefined,
+                            ...opts?.toolContext,
+                            summarize,
+                        },
+                    }),
+                    postTurn: (turnMessages, sessionPathArg, usage, hooks, state) => {
+                        (0, context_1.postTurn)(turnMessages, sessionPathArg, usage, hooks, state);
+                        sessionState = state;
+                    },
+                    accumulateFriendTokens: tokens_1.accumulateFriendTokens,
+                    signal,
+                    runAgentOptions: {
+                        toolChoiceRequired: (0, commands_1.getToolChoiceRequired)(),
+                        traceId: (0, nerves_1.createTraceId)(),
+                        mcpManager,
+                    },
+                });
+                // Handle gate rejection: display auto-reply if present
+                if (!result.gateResult.allowed) {
+                    if ("autoReply" in result.gateResult && result.gateResult.autoReply) {
+                        process.stdout.write(`${result.gateResult.autoReply}\n`);
+                    }
+                }
+                return { usage: result.usage };
+            },
+            onNewSession: () => {
+                (0, context_1.deleteSession)(sessPath);
+            },
+        });
+    }
+    finally {
+        sessionLock?.release();
     }
 }