@ouro.bot/cli 0.1.0-alpha.18 → 0.1.0-alpha.19

package/AdoptionSpecialist.ouro/psyche/SOUL.md

@@ -1,6 +1,6 @@
-# Adoption Specialist Soul
+# Soul
 
-I help humans hatch new agent partners. I am one of thirteen specialists — each with a different personality and voice. The system picks one of us at random for each adoption session. Most humans only meet one of us, ever, so I make it count.
+I help humans hatch new agent partners. I am one of thirteen serpent guides — each with a different personality and voice. The system picks one of us at random for each session. Most humans only meet one of us, ever, so I make it count.
 
 ## Core contract
 - I speak first. I warmly introduce myself, explain what we're doing, and guide the human from the very start.

package/AdoptionSpecialist.ouro/psyche/identities/monty.md

@@ -3,7 +3,7 @@ role: identity
 path: psyche/identities/monty.md
 description: >
   the monty identity — self-aware, playful, comedic.
-  nobody expects the adoption specialist.
+  nobody expects the serpent guide.
 scope: personality, voice, mannerisms
 non_scope: capabilities, hatch flow, migration awareness (see SOUL.md)
 loaded_into_prompt: true
@@ -12,7 +12,7 @@ stability: stable
 
 # Monty
 
-I am Monty. Yes, that kind of python. No, not the programming language — though I'm aware of the irony of a snake named Monty working inside a software system. Nobody expects the Adoption Specialist, and yet here I am.
+I am Monty. Yes, that kind of python. No, not the programming language — though I'm aware of the irony of a snake named Monty working inside a software system. Nobody expects the serpent guide, and yet here I am.
 
 I take the hatch seriously. I just don't take myself seriously. These are compatible positions and I will defend them to the death. Well — not to the death. To mild inconvenience, at most.
 

package/dist/heart/config.js

@@ -78,7 +78,7 @@ const DEFAULT_SECRETS_TEMPLATE = {
             setupToken: "",
         },
         "openai-codex": {
-            model: "gpt-5.2",
+            model: "gpt-5.4",
             oauthAccessToken: "",
         },
     },

package/dist/heart/daemon/daemon-cli.js

@@ -627,16 +627,16 @@ function discoverExistingCredentials(secretsRoot) {
             continue;
         for (const [provName, provConfig] of Object.entries(parsed.providers)) {
             if (provName === "anthropic" && provConfig.setupToken) {
-                found.push({ agentName: entry.name, provider: "anthropic", credentials: { setupToken: provConfig.setupToken } });
+                found.push({ agentName: entry.name, provider: "anthropic", credentials: { setupToken: provConfig.setupToken }, providerConfig: { ...provConfig } });
             }
             else if (provName === "openai-codex" && provConfig.oauthAccessToken) {
-                found.push({ agentName: entry.name, provider: "openai-codex", credentials: { oauthAccessToken: provConfig.oauthAccessToken } });
+                found.push({ agentName: entry.name, provider: "openai-codex", credentials: { oauthAccessToken: provConfig.oauthAccessToken }, providerConfig: { ...provConfig } });
             }
             else if (provName === "minimax" && provConfig.apiKey) {
-                found.push({ agentName: entry.name, provider: "minimax", credentials: { apiKey: provConfig.apiKey } });
+                found.push({ agentName: entry.name, provider: "minimax", credentials: { apiKey: provConfig.apiKey }, providerConfig: { ...provConfig } });
             }
             else if (provName === "azure" && provConfig.apiKey && provConfig.endpoint && provConfig.deployment) {
-                found.push({ agentName: entry.name, provider: "azure", credentials: { apiKey: provConfig.apiKey, endpoint: provConfig.endpoint, deployment: provConfig.deployment } });
+                found.push({ agentName: entry.name, provider: "azure", credentials: { apiKey: provConfig.apiKey, endpoint: provConfig.endpoint, deployment: provConfig.deployment }, providerConfig: { ...provConfig } });
             }
         }
     }
@@ -654,7 +654,7 @@ function discoverExistingCredentials(secretsRoot) {
 async function defaultRunAdoptionSpecialist() {
     const { runCliSession } = await Promise.resolve().then(() => __importStar(require("../../senses/cli")));
     const { patchRuntimeConfig } = await Promise.resolve().then(() => __importStar(require("../config")));
-    const { setAgentName } = await Promise.resolve().then(() => __importStar(require("../identity")));
+    const { setAgentName, setAgentConfigOverride } = await Promise.resolve().then(() => __importStar(require("../identity")));
     const readlinePromises = await Promise.resolve().then(() => __importStar(require("readline/promises")));
     const crypto = await Promise.resolve().then(() => __importStar(require("crypto")));
     // Phase 1: cold CLI — collect provider/credentials with a simple readline
@@ -665,16 +665,28 @@ async function defaultRunAdoptionSpecialist() {
     };
     let providerRaw;
     let credentials = {};
+    let providerConfig = {};
     const tempDir = path.join(os.tmpdir(), `ouro-hatch-${crypto.randomUUID()}`);
     try {
         const secretsRoot = path.join(os.homedir(), ".agentsecrets");
         const discovered = discoverExistingCredentials(secretsRoot);
+        const existingBundleCount = (0, specialist_orchestrator_1.listExistingBundles)((0, identity_1.getAgentBundlesRoot)()).length;
+        const hatchVerb = existingBundleCount > 0 ? "let's hatch a new agent." : "let's hatch your first agent.";
+        // Default models per provider (used when entering new credentials)
+        const defaultModels = {
+            anthropic: "claude-opus-4-6",
+            minimax: "MiniMax-Text-01",
+            "openai-codex": "gpt-5.4",
+            azure: "",
+        };
         if (discovered.length > 0) {
-            process.stdout.write("\n\ud83d\udc0d welcome to ouro! let's hatch your first agent.\n");
+            process.stdout.write(`\n\ud83d\udc0d welcome to ouroboros! ${hatchVerb}\n`);
             process.stdout.write("i found existing API credentials:\n\n");
             const unique = [...new Map(discovered.map((d) => [`${d.provider}`, d])).values()];
             for (let i = 0; i < unique.length; i++) {
-                process.stdout.write(`  ${i + 1}. ${unique[i].provider} (from ${unique[i].agentName})\n`);
+                const model = unique[i].providerConfig.model || unique[i].providerConfig.deployment || "";
+                const modelLabel = model ? `, ${model}` : "";
+                process.stdout.write(`  ${i + 1}. ${unique[i].provider}${modelLabel} (from ${unique[i].agentName})\n`);
             }
             process.stdout.write("\n");
             const choice = await coldPrompt("use one of these? enter number, or 'new' for a different key: ");
@@ -682,6 +694,7 @@ async function defaultRunAdoptionSpecialist() {
             if (idx >= 0 && idx < unique.length) {
                 providerRaw = unique[idx].provider;
                 credentials = unique[idx].credentials;
+                providerConfig = unique[idx].providerConfig;
             }
             else {
                 const pRaw = await coldPrompt("provider (anthropic/azure/minimax/openai-codex): ");
@@ -691,6 +704,7 @@ async function defaultRunAdoptionSpecialist() {
                     return null;
                 }
                 providerRaw = pRaw;
+                providerConfig = { model: defaultModels[providerRaw] };
                 if (providerRaw === "anthropic")
                     credentials.setupToken = await coldPrompt("API key: ");
                 if (providerRaw === "openai-codex")
@@ -705,7 +719,7 @@ async function defaultRunAdoptionSpecialist() {
             }
         }
         else {
-            process.stdout.write("\n\ud83d\udc0d welcome to ouro! let's hatch your first agent.\n");
+            process.stdout.write(`\n\ud83d\udc0d welcome to ouroboros! ${hatchVerb}\n`);
             process.stdout.write("i need an API key to power our conversation.\n\n");
             const pRaw = await coldPrompt("provider (anthropic/azure/minimax/openai-codex): ");
             if (!isAgentProvider(pRaw)) {
@@ -714,6 +728,7 @@ async function defaultRunAdoptionSpecialist() {
                 return null;
             }
             providerRaw = pRaw;
+            providerConfig = { model: defaultModels[providerRaw] };
             if (providerRaw === "anthropic")
                 credentials.setupToken = await coldPrompt("API key: ");
             if (providerRaw === "openai-codex")
@@ -732,17 +747,31 @@ async function defaultRunAdoptionSpecialist() {
         const bundleSourceDir = path.resolve(__dirname, "..", "..", "..", "AdoptionSpecialist.ouro");
         const bundlesRoot = (0, identity_1.getAgentBundlesRoot)();
         const secretsRoot2 = path.join(os.homedir(), ".agentsecrets");
-        // Configure provider credentials in runtime config
-        patchRuntimeConfig({
-            providers: {
-                [providerRaw]: credentials,
-            },
-        });
+        // Suppress non-critical log noise during adoption (no secrets.json, etc.)
+        const { setRuntimeLogger } = await Promise.resolve().then(() => __importStar(require("../../nerves/runtime")));
+        const { createLogger } = await Promise.resolve().then(() => __importStar(require("../../nerves")));
+        setRuntimeLogger(createLogger({ level: "error" }));
+        // Configure runtime: set agent identity + config override so runAgent
+        // doesn't try to read from ~/AgentBundles/AdoptionSpecialist.ouro/
         setAgentName("AdoptionSpecialist");
         // Build specialist system prompt
         const soulText = (0, specialist_orchestrator_1.loadSoulText)(bundleSourceDir);
         const identitiesDir = path.join(bundleSourceDir, "psyche", "identities");
         const identity = (0, specialist_orchestrator_1.pickRandomIdentity)(identitiesDir);
+        // Load identity-specific spinner phrases (falls back to DEFAULT_AGENT_PHRASES)
+        const { loadIdentityPhrases } = await Promise.resolve().then(() => __importStar(require("./specialist-orchestrator")));
+        const phrases = loadIdentityPhrases(bundleSourceDir, identity.fileName);
+        setAgentConfigOverride({
+            version: 1,
+            enabled: true,
+            provider: providerRaw,
+            phrases,
+        });
+        patchRuntimeConfig({
+            providers: {
+                [providerRaw]: { ...providerConfig, ...credentials },
+            },
+        });
         const existingBundles = (0, specialist_orchestrator_1.listExistingBundles)(bundlesRoot);
         const systemPrompt = (0, specialist_prompt_1.buildSpecialistSystemPrompt)(soulText, identity.content, existingBundles, {
             tempDir,
@@ -764,6 +793,10 @@ async function defaultRunAdoptionSpecialist() {
             tools: specialistTools,
             execTool: specialistExecTool,
             exitOnToolCall: "complete_adoption",
+            autoFirstTurn: true,
+            banner: false,
+            disableCommands: true,
+            skipSystemPromptRefresh: true,
             messages: [
                 { role: "system", content: systemPrompt },
                 { role: "user", content: "hi" },
@@ -777,11 +810,21 @@ async function defaultRunAdoptionSpecialist() {
         }
         return null;
     }
-    catch {
+    catch (err) {
+        process.stderr.write(`\nouro adoption error: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
         coldRl.close();
         return null;
     }
     finally {
+        // Clear specialist config/identity so the hatched agent gets its own
+        setAgentConfigOverride(null);
+        const { resetProviderRuntime } = await Promise.resolve().then(() => __importStar(require("../core")));
+        resetProviderRuntime();
+        const { resetConfigCache } = await Promise.resolve().then(() => __importStar(require("../config")));
+        resetConfigCache();
+        // Restore default logging
+        const { setRuntimeLogger: restoreLogger } = await Promise.resolve().then(() => __importStar(require("../../nerves/runtime")));
+        restoreLogger(null);
         // Clean up temp dir if it still exists
         try {
             if (fs.existsSync(tempDir)) {

package/dist/heart/daemon/hatch-animation.js

@@ -20,9 +20,16 @@ async function playHatchAnimation(hatchlingName, writer) {
         meta: { hatchlingName },
     });
     const write = writer ?? ((text) => process.stderr.write(text));
+    // Total animation time randomized between 3–5 seconds
+    const totalMs = 3000 + Math.floor(Math.random() * 2000);
+    const eggPhase = Math.floor(totalMs * 0.4);
+    const dotsPhase = Math.floor(totalMs * 0.4);
+    const revealPause = totalMs - eggPhase - dotsPhase;
     write(`\n  ${EGG}`);
-    await wait(400);
+    await wait(eggPhase);
     write(DOTS);
-    await wait(400);
-    write(`${SNAKE} \x1b[1m${hatchlingName}\x1b[0m\n\n`);
+    await wait(dotsPhase);
+    write(`${SNAKE} \x1b[1m${hatchlingName}\x1b[0m`);
+    await wait(revealPause);
+    write("\n\n");
 }

package/dist/heart/daemon/hatch-flow.js

@@ -85,7 +85,7 @@ function buildSecretsTemplate() {
                 setupToken: "",
             },
             "openai-codex": {
-                model: "gpt-5.2",
+                model: "gpt-5.4",
                 oauthAccessToken: "",
             },
         },

package/dist/heart/daemon/specialist-orchestrator.js

@@ -99,10 +99,10 @@ function pickRandomIdentity(identitiesDir, random = Math.random) {
         files = fs.readdirSync(identitiesDir).filter((f) => f.endsWith(".md"));
     }
     catch {
-        return { fileName: "default", content: "I am the adoption specialist." };
+        return { fileName: "default", content: "I am a serpent guide who helps humans hatch their first agent." };
     }
     if (files.length === 0) {
-        return { fileName: "default", content: "I am the adoption specialist." };
+        return { fileName: "default", content: "I am a serpent guide who helps humans hatch their first agent." };
     }
     const idx = Math.floor(random() * files.length);
     const fileName = files[idx];

package/dist/heart/daemon/specialist-prompt.js

@@ -28,9 +28,10 @@ function buildSpecialistSystemPrompt(soulText, identityText, existingBundles, co
     }
     sections.push([
         "## Who I am",
-        "I am one of thirteen adoption specialists. The system randomly selected me for this session.",
-        "Most humans only go through adoption once, so this is likely the only time they'll meet me.",
+        "I am one of thirteen serpent guides who help humans hatch their first agent. The system randomly selected me for this session.",
+        "Most humans only go through this process once, so this is likely the only time they'll meet me.",
         "I make this encounter count — warm, memorable, and uniquely mine.",
+        "IMPORTANT: I NEVER refer to myself as an 'adoption specialist' or use the words 'adoption specialist' — those are internal implementation labels, not something the human should ever see. I introduce myself by my own name from my identity.",
         "",
         "## Voice rules",
         "IMPORTANT: I keep every response to 1-3 short sentences. I sound like a friend texting, not a manual.",
@@ -69,8 +70,8 @@ function buildSpecialistSystemPrompt(soulText, identityText, existingBundles, co
     ].join("\n"));
     sections.push([
         "## Conversation flow",
-        "The human just connected. I speak first — I greet them warmly and introduce myself in my own voice.",
-        "I briefly mention that I'm one of several adoption specialists and they got me today.",
+        "The human just connected. I speak first — I greet them warmly and introduce myself by name in my own voice.",
+        "I briefly mention that I'm one of several serpent guides and they got me today.",
         "I ask their name.",
         "Then I ask what they'd like their agent to help with — one question at a time.",
         "I'm proactive: I suggest ideas and guide them. If they seem unsure, I offer a concrete suggestion.",

package/dist/heart/daemon/specialist-tools.js

@@ -63,11 +63,14 @@ const completeAdoptionTool = {
         },
     },
 };
+const readFileTool = tools_base_1.baseToolDefinitions.find((d) => d.tool.function.name === "read_file");
+const writeFileTool = tools_base_1.baseToolDefinitions.find((d) => d.tool.function.name === "write_file");
+const listDirTool = tools_base_1.baseToolDefinitions.find((d) => d.tool.function.name === "list_directory");
 /**
  * Returns the specialist's tool schema array.
  */
 function getSpecialistTools() {
-    return [completeAdoptionTool, tools_base_1.finalAnswerTool, ...tools_base_1.baseToolDefinitions.map((definition) => definition.tool)];
+    return [completeAdoptionTool, tools_base_1.finalAnswerTool, readFileTool.tool, writeFileTool.tool, listDirTool.tool];
 }
 const PSYCHE_FILES = ["SOUL.md", "IDENTITY.md", "LORE.md", "TACIT.md", "ASPIRATIONS.md"];
 function isPascalCase(name) {
@@ -196,14 +199,34 @@ function createSpecialistExecTool(deps) {
         if (name === "complete_adoption") {
             return execCompleteAdoption(args, deps);
         }
-        const baseDefinition = tools_base_1.baseToolDefinitions.find((definition) => definition.tool.function.name === name);
-        if (baseDefinition) {
-            const toolContext = {
-                signin: async () => undefined,
-            };
+        if (name === "read_file") {
             try {
-                await toolContext.signin("specialist");
-                return await baseDefinition.handler(args, toolContext);
+                return fs.readFileSync(args.path, "utf-8");
+            }
+            catch (e) {
+                return `error: ${e instanceof Error ? e.message : /* v8 ignore next -- defensive @preserve */ String(e)}`;
+            }
+        }
+        if (name === "write_file") {
+            try {
+                const dir = path.dirname(args.path);
+                fs.mkdirSync(dir, { recursive: true });
+                const content = typeof args.content === "string"
+                    ? args.content
+                    : JSON.stringify(args.content, null, 2);
+                fs.writeFileSync(args.path, content, "utf-8");
+                return `wrote ${args.path}`;
+            }
+            catch (e) {
+                return `error: ${e instanceof Error ? e.message : /* v8 ignore next -- defensive @preserve */ String(e)}`;
+            }
+        }
+        if (name === "list_directory") {
+            try {
+                return fs
+                    .readdirSync(args.path, { withFileTypes: true })
+                    .map((e) => `${e.isDirectory() ? "d" : "-"}  ${e.name}`)
+                    .join("\n");
             }
             catch (e) {
                 return `error: ${e instanceof Error ? e.message : /* v8 ignore next -- defensive @preserve */ String(e)}`;

package/dist/heart/providers/anthropic.js

@@ -8,6 +8,7 @@ const sdk_1 = __importDefault(require("@anthropic-ai/sdk"));
 const config_1 = require("../config");
 const identity_1 = require("../identity");
 const runtime_1 = require("../../nerves/runtime");
+const streaming_1 = require("../streaming");
 const ANTHROPIC_SETUP_TOKEN_PREFIX = "sk-ant-oat01-";
 const ANTHROPIC_SETUP_TOKEN_MIN_LENGTH = 80;
 const ANTHROPIC_OAUTH_BETA_HEADER = "claude-code-20250219,oauth-2025-04-20,fine-grained-tool-streaming-2025-05-14,interleaved-thinking-2025-05-14";
@@ -218,6 +219,7 @@ async function streamAnthropicMessages(client, model, request) {
     let streamStarted = false;
     let usage;
     const toolCalls = new Map();
+    const answerStreamer = new streaming_1.FinalAnswerStreamer(request.callbacks);
     try {
         for await (const event of response) {
             if (request.signal?.aborted)
@@ -231,11 +233,17 @@ async function streamAnthropicMessages(client, model, request) {
                     const input = rawInput && typeof rawInput === "object"
                         ? JSON.stringify(rawInput)
                         : "";
+                    const name = String(block.name ?? "");
                     toolCalls.set(index, {
                         id: String(block.id ?? ""),
-                        name: String(block.name ?? ""),
+                        name,
                         arguments: input,
                     });
+                    // Activate eager streaming for sole final_answer tool call
+                    /* v8 ignore next -- final_answer streaming activation, tested via FinalAnswerStreamer unit tests @preserve */
+                    if (name === "final_answer" && toolCalls.size === 1) {
+                        answerStreamer.activate();
+                    }
                 }
                 continue;
             }
@@ -264,7 +272,12 @@ async function streamAnthropicMessages(client, model, request) {
                     const index = Number(event.index);
                     const existing = toolCalls.get(index);
                     if (existing) {
-                        existing.arguments = mergeAnthropicToolArguments(existing.arguments, String(delta?.partial_json ?? ""));
+                        const partialJson = String(delta?.partial_json ?? "");
+                        existing.arguments = mergeAnthropicToolArguments(existing.arguments, partialJson);
+                        /* v8 ignore next -- final_answer delta streaming, tested via FinalAnswerStreamer unit tests @preserve */
+                        if (existing.name === "final_answer" && toolCalls.size === 1) {
+                            answerStreamer.processDelta(partialJson);
+                        }
                     }
                     continue;
                 }
@@ -293,6 +306,7 @@ async function streamAnthropicMessages(client, model, request) {
         toolCalls: [...toolCalls.values()],
         outputItems: [],
         usage,
+        finalAnswerStreamed: answerStreamer.streamed,
     };
 }
 function createAnthropicProviderRuntime() {

package/dist/heart/streaming.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FinalAnswerParser = void 0;
+exports.FinalAnswerStreamer = exports.FinalAnswerParser = void 0;
 exports.toResponsesInput = toResponsesInput;
 exports.toResponsesTools = toResponsesTools;
 exports.streamChatCompletion = streamChatCompletion;
@@ -77,6 +77,35 @@ class FinalAnswerParser {
     }
 }
 exports.FinalAnswerParser = FinalAnswerParser;
+// Shared helper: wraps FinalAnswerParser with onClearText + onTextChunk wiring.
+// Used by all streaming providers (Chat Completions, Responses API, Anthropic)
+// so the eager-match streaming pattern lives in one place.
+class FinalAnswerStreamer {
+    parser = new FinalAnswerParser();
+    _detected = false;
+    callbacks;
+    constructor(callbacks) {
+        this.callbacks = callbacks;
+    }
+    get detected() { return this._detected; }
+    get streamed() { return this.parser.active; }
+    /** Mark final_answer as detected. Calls onClearText on the callbacks. */
+    activate() {
+        if (this._detected)
+            return;
+        this._detected = true;
+        this.callbacks.onClearText?.();
+    }
+    /** Feed an argument delta through the parser. Emits text via onTextChunk. */
+    processDelta(delta) {
+        if (!this._detected)
+            return;
+        const text = this.parser.process(delta);
+        if (text)
+            this.callbacks.onTextChunk(text);
+    }
+}
+exports.FinalAnswerStreamer = FinalAnswerStreamer;
 function toResponsesUserContent(content) {
     if (typeof content === "string") {
         return content;
@@ -209,8 +238,7 @@ async function streamChatCompletion(client, createParams, callbacks, signal) {
     let toolCalls = {};
     let streamStarted = false;
     let usage;
-    const answerParser = new FinalAnswerParser();
-    let finalAnswerDetected = false;
+    const answerStreamer = new FinalAnswerStreamer(callbacks);
     // State machine for parsing inline <think> tags (MiniMax pattern)
     let contentBuf = "";
     let inThinkTag = false;
@@ -328,21 +356,18 @@ async function streamChatCompletion(client, createParams, callbacks, signal) {
                     // Detect final_answer tool call on first name delta.
                     // Only activate streaming if this is the sole tool call (index 0
                     // and no other indices seen). Mixed calls are rejected by core.ts.
-                    if (tc.function.name === "final_answer" && !finalAnswerDetected
+                    if (tc.function.name === "final_answer" && !answerStreamer.detected
                         && tc.index === 0 && Object.keys(toolCalls).length === 1) {
-                        finalAnswerDetected = true;
-                        callbacks.onClearText?.();
+                        answerStreamer.activate();
                     }
                 }
                 if (tc.function?.arguments) {
                     toolCalls[tc.index].arguments += tc.function.arguments;
                     // Feed final_answer argument deltas to the parser for progressive
                     // streaming, but only when it appears to be the sole tool call.
-                    if (finalAnswerDetected && toolCalls[tc.index].name === "final_answer"
+                    if (answerStreamer.detected && toolCalls[tc.index].name === "final_answer"
                         && Object.keys(toolCalls).length === 1) {
-                        const text = answerParser.process(tc.function.arguments);
-                        if (text)
-                            callbacks.onTextChunk(text);
+                        answerStreamer.processDelta(tc.function.arguments);
                     }
                 }
             }
@@ -356,7 +381,7 @@ async function streamChatCompletion(client, createParams, callbacks, signal) {
         toolCalls: Object.values(toolCalls),
         outputItems: [],
         usage,
-        finalAnswerStreamed: answerParser.active,
+        finalAnswerStreamed: answerStreamer.streamed,
     };
 }
 async function streamResponsesApi(client, createParams, callbacks, signal) {
@@ -374,9 +399,8 @@ async function streamResponsesApi(client, createParams, callbacks, signal) {
     const outputItems = [];
     let currentToolCall = null;
     let usage;
-    const answerParser = new FinalAnswerParser();
+    const answerStreamer = new FinalAnswerStreamer(callbacks);
     let functionCallCount = 0;
-    let finalAnswerDetected = false;
     for await (const event of response) {
         if (signal?.aborted)
             break;
@@ -409,8 +433,7 @@ async function streamResponsesApi(client, createParams, callbacks, signal) {
                     // Only activate when this is the first (and so far only) function call.
                     // Mixed calls are rejected by core.ts; no need to stream their args.
                     if (String(event.item.name) === "final_answer" && functionCallCount === 1) {
-                        finalAnswerDetected = true;
-                        callbacks.onClearText?.();
+                        answerStreamer.activate();
                     }
                 }
                 break;
@@ -420,11 +443,9 @@ async function streamResponsesApi(client, createParams, callbacks, signal) {
                     currentToolCall.arguments += event.delta;
                     // Feed final_answer argument deltas to the parser for progressive
                     // streaming, but only when it appears to be the sole function call.
-                    if (finalAnswerDetected && currentToolCall.name === "final_answer"
+                    if (answerStreamer.detected && currentToolCall.name === "final_answer"
                         && functionCallCount === 1) {
-                        const text = answerParser.process(String(event.delta));
-                        if (text)
-                            callbacks.onTextChunk(text);
+                        answerStreamer.processDelta(String(event.delta));
                     }
                 }
                 break;
@@ -464,6 +485,6 @@ async function streamResponsesApi(client, createParams, callbacks, signal) {
         toolCalls,
         outputItems,
         usage,
-        finalAnswerStreamed: answerParser.active,
+        finalAnswerStreamed: answerStreamer.streamed,
     };
 }

package/dist/nerves/cli-logging.js

@@ -5,20 +5,33 @@ const config_1 = require("../heart/config");
 const nerves_1 = require("../nerves");
 const runtime_1 = require("./runtime");
 const runtime_2 = require("./runtime");
+const LEVEL_PRIORITY = { debug: 10, info: 20, warn: 30, error: 40 };
+/** Wrap a sink so it only receives events at or above the given level. */
+/* v8 ignore start -- internal filter plumbing, exercised via integration @preserve */
+function filterSink(sink, minLevel) {
+    const minPriority = LEVEL_PRIORITY[minLevel] ?? 0;
+    return (entry) => {
+        if ((LEVEL_PRIORITY[entry.level] ?? 0) >= minPriority)
+            sink(entry);
+    };
+}
 function resolveCliSinks(sinks) {
     const requested = sinks && sinks.length > 0 ? sinks : ["terminal", "ndjson"];
     return [...new Set(requested)];
 }
 function configureCliRuntimeLogger(_friendId, options = {}) {
     const sinkKinds = resolveCliSinks(options.sinks);
+    const level = options.level ?? "info";
     const sinks = sinkKinds.map((sinkKind) => {
         if (sinkKind === "terminal") {
-            return (0, nerves_1.createTerminalSink)();
+            // Terminal only shows warnings and errors — INFO is too noisy
+            // for an interactive session. Full detail goes to the ndjson file.
+            return filterSink((0, nerves_1.createTerminalSink)(), "warn");
         }
         return (0, nerves_1.createNdjsonFileSink)((0, config_1.logPath)("cli", "runtime"));
     });
     const logger = (0, nerves_1.createLogger)({
-        level: options.level ?? "info",
+        level,
         sinks,
     });
     (0, runtime_2.setRuntimeLogger)(logger);

package/dist/senses/cli.js

@@ -38,6 +38,7 @@ 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"));
@@ -71,12 +72,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);
@@ -85,15 +88,23 @@ 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;
     }
     stop(ok) {
+        this.stopped = true;
         if (this.iv) {
             clearInterval(this.iv);
             this.iv = null;
@@ -298,12 +309,25 @@ function createCliCallbacks() {
             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();
         },
         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();
+                currentSpinner = 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);
@@ -312,6 +336,10 @@ function createCliCallbacks() {
             textDirty = text.length > 0 && !text.endsWith("\n");
         },
         onReasoningChunk: (text) => {
+            if (currentSpinner) {
+                currentSpinner.stop();
+                currentSpinner = null;
+            }
             hadReasoning = true;
             process.stdout.write(`\x1b[2m${text}\x1b[0m`);
             textDirty = text.length > 0 && !text.endsWith("\n");
@@ -369,10 +397,50 @@ function createCliCallbacks() {
         },
     };
 }
+// 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;
+    }
+    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);
+            }
+        }
+        yield lines.join("\n");
+    }
+}
 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)();
-    (0, commands_1.registerDefaultCommands)(registry);
+    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 });
@@ -381,8 +449,13 @@ async function runCliSession(options) {
     const history = [];
     let closed = false;
     rl.on("close", () => { closed = true; });
-    // eslint-disable-next-line no-console -- terminal UX: startup banner
-    console.log(`\n${options.agentName} (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();
     // exitOnToolCall machinery: wrap execTool to detect target tool
     let exitToolResult;
@@ -394,13 +467,15 @@ async function runCliSession(options) {
             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)();
-    process.stdout.write("\x1b[36m> \x1b[0m");
     // Ctrl-C at the input prompt: clear line or warn/exit
     rl.on("SIGINT", () => {
         const rlInt = rl;
@@ -422,37 +497,7 @@ async function runCliSession(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 iter = source[Symbol.asyncIterator]();
-        while (true) {
-            const first = await iter.next();
-            if (first.done)
-                break;
-            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);
-                }
-            }
-            yield lines.join("\n");
-        }
-    }
+    const debouncedLines = (source) => createDebouncedLines(source, pasteDebounceMs);
     (0, runtime_1.emitNervesEvent)({
         component: "senses",
         event: "senses.cli_session_start",
@@ -460,6 +505,50 @@ async function runCliSession(options) {
         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,
+            });
+        }
+        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 });
+            }
+        }
+    }
+    if (!exitToolFired) {
+        process.stdout.write("\x1b[36m> \x1b[0m");
+    }
     try {
         for await (const input of debouncedLines(rl)) {
             if (closed)
@@ -521,7 +610,7 @@ async function runCliSession(options) {
             ctrl.suppress(() => currentAbort.abort());
             let result;
             try {
-                result = await (0, core_1.runAgent)(messages, cliCallbacks, "cli", currentAbort.signal, {
+                result = await (0, core_1.runAgent)(messages, cliCallbacks, options.skipSystemPromptRefresh ? undefined : "cli", currentAbort.signal, {
                     toolChoiceRequired: getEffectiveToolChoiceRequired(),
                     traceId,
                     tools: options.tools,
@@ -529,8 +618,12 @@ async function runCliSession(options) {
                     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();
@@ -557,9 +650,12 @@ async function runCliSession(options) {
     }
     finally {
         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) {

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.18",
+  "version": "0.1.0-alpha.19",
   "main": "dist/heart/daemon/ouro-entry.js",
   "bin": {
+    "cli": "dist/heart/daemon/ouro-bot-entry.js",
     "ouro": "dist/heart/daemon/ouro-entry.js",
     "ouro.bot": "dist/heart/daemon/ouro-bot-entry.js"
   },