@ouro.bot/cli 0.1.0-alpha.133 → 0.1.0-alpha.134

package/dist/heart/providers/github-copilot.js

@@ -88,7 +88,7 @@ function createGithubCopilotProviderRuntime(injectedConfig) {
                 if (request.toolChoiceRequired)
                     params.tool_choice = "required";
                 try {
-                    return await (0, streaming_1.streamChatCompletion)(this.client, params, request.callbacks, request.signal, request.eagerFinalAnswerStreaming);
+                    return await (0, streaming_1.streamChatCompletion)(this.client, params, request.callbacks, request.signal, request.eagerSettleStreaming);
                 }
                 catch (error) {
                     throw error instanceof Error ? error : new Error(String(error));
@@ -139,7 +139,7 @@ function createGithubCopilotProviderRuntime(injectedConfig) {
             if (request.toolChoiceRequired)
                 params.tool_choice = "required";
             try {
-                const result = await (0, streaming_1.streamResponsesApi)(this.client, params, request.callbacks, request.signal, request.eagerFinalAnswerStreaming);
+                const result = await (0, streaming_1.streamResponsesApi)(this.client, params, request.callbacks, request.signal, request.eagerSettleStreaming);
                 for (const item of result.outputItems)
                     nativeInput.push(item);
                 return result;

package/dist/heart/providers/minimax.js

@@ -74,7 +74,7 @@ function createMinimaxProviderRuntime(config) {
                 params.metadata = { trace_id: request.traceId };
             if (request.toolChoiceRequired)
                 params.tool_choice = "required";
-            return (0, streaming_1.streamChatCompletion)(this.client, params, request.callbacks, request.signal, request.eagerFinalAnswerStreaming);
+            return (0, streaming_1.streamChatCompletion)(this.client, params, request.callbacks, request.signal, request.eagerSettleStreaming);
         },
         classifyError(error) {
             return classifyMinimaxError(error);

package/dist/heart/providers/openai-codex.js

@@ -180,7 +180,7 @@ function createOpenAICodexProviderRuntime(config) {
             if (request.toolChoiceRequired)
                 params.tool_choice = "required";
             try {
-                const result = await (0, streaming_1.streamResponsesApi)(this.client, params, request.callbacks, request.signal, request.eagerFinalAnswerStreaming);
+                const result = await (0, streaming_1.streamResponsesApi)(this.client, params, request.callbacks, request.signal, request.eagerSettleStreaming);
                 for (const item of result.outputItems)
                     nativeInput.push(item);
                 return result;

package/dist/heart/streaming.js

@@ -1,16 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FinalAnswerStreamer = exports.FinalAnswerParser = void 0;
+exports.SettleStreamer = exports.SettleParser = void 0;
 exports.toResponsesInput = toResponsesInput;
 exports.toResponsesTools = toResponsesTools;
 exports.streamChatCompletion = streamChatCompletion;
 exports.streamResponsesApi = streamResponsesApi;
 const runtime_1 = require("../nerves/runtime");
 // Character-level state machine that extracts the answer value from
-// `final_answer` tool call JSON arguments as they stream in.
+// `settle` tool call JSON arguments as they stream in.
 // Scans for prefix `"answer":"` or `"answer": "` in the character stream,
 // then emits text handling JSON escapes, stopping at unescaped closing `"`.
-class FinalAnswerParser {
+class SettleParser {
     // Possible prefixes to match (with and without space after colon)
     static PREFIXES = ['"answer":"', '"answer": "'];
     // Buffer of characters seen so far (pre-activation only)
@@ -29,7 +29,7 @@ class FinalAnswerParser {
             if (!this._active) {
                 this.buf += ch;
                 // Check if any prefix has been fully matched in the buffer
-                for (const prefix of FinalAnswerParser.PREFIXES) {
+                for (const prefix of SettleParser.PREFIXES) {
                     if (this.buf.endsWith(prefix)) {
                         this._active = true;
                         break;
@@ -76,12 +76,12 @@ class FinalAnswerParser {
         return out;
     }
 }
-exports.FinalAnswerParser = FinalAnswerParser;
-// Shared helper: wraps FinalAnswerParser with onClearText + onTextChunk wiring.
+exports.SettleParser = SettleParser;
+// Shared helper: wraps SettleParser 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();
+// so the eager-match settle streaming pattern lives in one place.
+class SettleStreamer {
+    parser = new SettleParser();
     _detected = false;
     callbacks;
     enabled;
@@ -91,7 +91,7 @@ class FinalAnswerStreamer {
     }
     get detected() { return this._detected; }
     get streamed() { return this.parser.active; }
-    /** Mark final_answer as detected. Calls onClearText on the callbacks. */
+    /** Mark settle as detected. Calls onClearText on the callbacks. */
     activate() {
         if (!this.enabled)
             return;
@@ -111,7 +111,7 @@ class FinalAnswerStreamer {
             this.callbacks.onTextChunk(text);
     }
 }
-exports.FinalAnswerStreamer = FinalAnswerStreamer;
+exports.SettleStreamer = SettleStreamer;
 function toResponsesUserContent(content) {
     if (typeof content === "string") {
         return content;
@@ -233,7 +233,7 @@ function toResponsesTools(ccTools) {
         strict: false,
     }));
 }
-async function streamChatCompletion(client, createParams, callbacks, signal, eagerFinalAnswerStreaming = true) {
+async function streamChatCompletion(client, createParams, callbacks, signal, eagerSettleStreaming = true) {
     (0, runtime_1.emitNervesEvent)({
         component: "engine",
         event: "engine.stream_start",
@@ -247,7 +247,7 @@ async function streamChatCompletion(client, createParams, callbacks, signal, eag
     let toolCalls = {};
     let streamStarted = false;
     let usage;
-    const answerStreamer = new FinalAnswerStreamer(callbacks, eagerFinalAnswerStreaming);
+    const answerStreamer = new SettleStreamer(callbacks, eagerSettleStreaming);
     // State machine for parsing inline <think> tags (MiniMax pattern)
     let contentBuf = "";
     let inThinkTag = false;
@@ -362,19 +362,19 @@ async function streamChatCompletion(client, createParams, callbacks, signal, eag
                     toolCalls[tc.index].id = tc.id;
                 if (tc.function?.name) {
                     toolCalls[tc.index].name = tc.function.name;
-                    // Detect final_answer tool call on first name delta.
+                    // Detect settle 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" && !answerStreamer.detected
+                    if (tc.function.name === "settle" && !answerStreamer.detected
                         && tc.index === 0 && Object.keys(toolCalls).length === 1) {
                         answerStreamer.activate();
                     }
                 }
                 if (tc.function?.arguments) {
                     toolCalls[tc.index].arguments += tc.function.arguments;
-                    // Feed final_answer argument deltas to the parser for progressive
+                    // Feed settle argument deltas to the parser for progressive
                     // streaming, but only when it appears to be the sole tool call.
-                    if (answerStreamer.detected && toolCalls[tc.index].name === "final_answer"
+                    if (answerStreamer.detected && toolCalls[tc.index].name === "settle"
                         && Object.keys(toolCalls).length === 1) {
                         answerStreamer.processDelta(tc.function.arguments);
                     }
@@ -390,10 +390,10 @@ async function streamChatCompletion(client, createParams, callbacks, signal, eag
         toolCalls: Object.values(toolCalls),
         outputItems: [],
         usage,
-        finalAnswerStreamed: answerStreamer.streamed,
+        settleStreamed: answerStreamer.streamed,
     };
 }
-async function streamResponsesApi(client, createParams, callbacks, signal, eagerFinalAnswerStreaming = true) {
+async function streamResponsesApi(client, createParams, callbacks, signal, eagerSettleStreaming = true) {
     (0, runtime_1.emitNervesEvent)({
         component: "engine",
         event: "engine.stream_start",
@@ -408,7 +408,7 @@ async function streamResponsesApi(client, createParams, callbacks, signal, eager
     const outputItems = [];
     let currentToolCall = null;
     let usage;
-    const answerStreamer = new FinalAnswerStreamer(callbacks, eagerFinalAnswerStreaming);
+    const answerStreamer = new SettleStreamer(callbacks, eagerSettleStreaming);
     let functionCallCount = 0;
     for await (const event of response) {
         if (signal?.aborted)
@@ -438,10 +438,10 @@ async function streamResponsesApi(client, createParams, callbacks, signal, eager
                         name: String(event.item.name),
                         arguments: "",
                     };
-                    // Detect final_answer function call -- clear any streamed noise.
+                    // Detect settle function call -- clear any streamed noise.
                     // 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) {
+                    if (String(event.item.name) === "settle" && functionCallCount === 1) {
                         answerStreamer.activate();
                     }
                 }
@@ -450,9 +450,9 @@ async function streamResponsesApi(client, createParams, callbacks, signal, eager
             case "response.function_call_arguments.delta": {
                 if (currentToolCall) {
                     currentToolCall.arguments += event.delta;
-                    // Feed final_answer argument deltas to the parser for progressive
+                    // Feed settle argument deltas to the parser for progressive
                     // streaming, but only when it appears to be the sole function call.
-                    if (answerStreamer.detected && currentToolCall.name === "final_answer"
+                    if (answerStreamer.detected && currentToolCall.name === "settle"
                         && functionCallCount === 1) {
                         answerStreamer.processDelta(String(event.delta));
                     }
@@ -494,6 +494,6 @@ async function streamResponsesApi(client, createParams, callbacks, signal, eager
         toolCalls,
         outputItems,
         usage,
-        finalAnswerStreamed: answerStreamer.streamed,
+        settleStreamed: answerStreamer.streamed,
     };
 }

package/dist/mind/prompt.js

@@ -271,11 +271,11 @@ function runtimeInfoSection(channel) {
         lines.push("i introduce myself on boot with a fun random greeting.");
     }
     else if (channel === "inner") {
-        // No boot greeting or channel-specific guidance for inner dialog
+        lines.push("this is my private thinking space. when a thought is ready to share, i surface it to whoever needs to hear it. i settle when i'm done thinking.");
     }
     else if (channel === "bluebubbles") {
         lines.push("i am responding in iMessage through BlueBubbles. i keep replies short and phone-native. i do not use markdown. i do not introduce myself on boot.");
-        lines.push("when a bluebubbles turn arrives from a thread, the harness tells me the current lane and any recent active thread ids. if widening back to top-level or routing into a different active thread is the better move, i use bluebubbles_set_reply_target before final_answer.");
+        lines.push("when a bluebubbles turn arrives from a thread, the harness tells me the current lane and any recent active thread ids. if widening back to top-level or routing into a different active thread is the better move, i use bluebubbles_set_reply_target before settle.");
     }
     else {
         lines.push("i am responding in Microsoft Teams. i keep responses concise. i use markdown formatting. i do not introduce myself on boot.");
@@ -356,7 +356,7 @@ function dateSection() {
 }
 function toolsSection(channel, options, context) {
     const channelTools = (0, tools_1.getToolsForChannel)((0, channel_1.getChannelCapabilities)(channel), undefined, context, options?.providerCapabilities);
-    const activeTools = (options?.toolChoiceRequired ?? true) ? [...channelTools, tools_1.finalAnswerTool] : channelTools;
+    const activeTools = (options?.toolChoiceRequired ?? true) ? [...channelTools, tools_1.settleTool] : channelTools;
     const list = activeTools
         .map((t) => `- ${t.function.name}: ${t.function.description}`)
         .join("\n");
@@ -619,10 +619,10 @@ function toolBehaviorSection(options) {
     return `## tool behavior
 tool_choice is set to "required" -- i must call a tool on every turn.
 - need more information? i call a tool.
-- ready to respond to the user? i call \`final_answer\`.
-\`final_answer\` is a tool call -- it satisfies the tool_choice requirement.
-\`final_answer\` must be the ONLY tool call in that turn. do not combine it with other tool calls.
-do NOT call no-op tools just before \`final_answer\`. if i am done, i call \`final_answer\` directly.`;
+- ready to respond to the user? i call \`settle\`.
+\`settle\` is a tool call -- it satisfies the tool_choice requirement.
+\`settle\` must be the ONLY tool call in that turn. do not combine it with other tool calls.
+do NOT call no-op tools just before \`settle\`. if i am done, i call \`settle\` directly.`;
 }
 function workspaceDisciplineSection() {
     return `## repo workspace discipline
@@ -668,7 +668,7 @@ function contextSection(context, options) {
     lines.push("my conversation memory is ephemeral -- it resets between sessions. anything i learn about my friend, i save with save_friend_note so future me remembers.");
     lines.push("the conversation is my source of truth. my notes are a journal for future me -- they may be stale or incomplete.");
     lines.push("when i learn something that might invalidate an existing note, i check related notes and update or override any that are stale.");
-    lines.push("i save ANYTHING i learn about my friend immediately with save_friend_note -- names, preferences, what they do, what they care about. when in doubt, save it. saving comes BEFORE responding: i call save_friend_note first, then final_answer on the next turn.");
+    lines.push("i save ANYTHING i learn about my friend immediately with save_friend_note -- names, preferences, what they do, what they care about. when in doubt, save it. saving comes BEFORE responding: i call save_friend_note first, then settle on the next turn.");
     // Onboarding instructions (only below token threshold -- drop once exceeded)
     const impressions = (0, first_impressions_1.getFirstImpressions)(friend, options);
     if (impressions) {
@@ -727,13 +727,13 @@ function groupChatParticipationSection(context) {
 group chats are conversations between people. i'm one participant, not the host.
 
 i don't need to respond to everything. most reactions, tapbacks, and side
-conversations between others aren't for me. i use no_response to stay quiet
+conversations between others aren't for me. i use observe to stay quiet
 when the moment doesn't call for my voice — same as any person would.
 
 when a reaction or emoji says it better than words, i can react instead of
 typing a full reply. a thumbs-up is often the perfect response.
 
-no_response must be the sole tool call in the turn (same rule as final_answer).
+observe must be the sole tool call in the turn (same rule as settle).
 when unsure whether to chime in, i lean toward silence rather than noise.`;
 }
 function mixedTrustGroupSection(context) {

package/dist/repertoire/tools-base.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.finalAnswerTool = exports.noResponseTool = exports.goInwardTool = exports.tools = exports.baseToolDefinitions = exports.editFileReadTracker = void 0;
+exports.settleTool = exports.observeTool = exports.goInwardTool = exports.tools = exports.baseToolDefinitions = exports.editFileReadTracker = void 0;
 exports.renderInnerProgressStatus = renderInnerProgressStatus;
 const fs = __importStar(require("fs"));
 const fg = __importStar(require("fast-glob"));
@@ -1354,9 +1354,9 @@ exports.goInwardTool = {
         parameters: {
             type: "object",
             properties: {
-                content: {
+                topic: {
                     type: "string",
-                    description: "what i need to think about -- the question, the thread, the thing that needs private attention",
+                    description: "the question or topic that needs private thought — brief framing, not your analysis. your inner dialog will do the actual thinking.",
                 },
                 answer: {
                     type: "string",
@@ -1368,14 +1368,14 @@ exports.goInwardTool = {
                     description: "reflect: something to sit with. plan: something to work through. relay: something to carry across.",
                 },
             },
-            required: ["content"],
+            required: ["topic"],
         },
     },
 };
-exports.noResponseTool = {
+exports.observeTool = {
     type: "function",
     function: {
-        name: "no_response",
+        name: "observe",
         description: "stay silent in this group chat — the moment doesn't call for a response. must be the only tool call in the turn.",
         parameters: {
             type: "object",
@@ -1385,10 +1385,10 @@ exports.noResponseTool = {
         },
     },
 };
-exports.finalAnswerTool = {
+exports.settleTool = {
     type: "function",
     function: {
-        name: "final_answer",
+        name: "settle",
         description: "respond to the user with your message. call this tool when you are ready to deliver your response.",
         parameters: {
             type: "object",

package/dist/repertoire/tools.js

@@ -1,6 +1,39 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.goInwardTool = exports.noResponseTool = exports.finalAnswerTool = exports.tools = void 0;
+exports.goInwardTool = exports.observeTool = exports.settleTool = exports.tools = void 0;
 exports.getToolsForChannel = getToolsForChannel;
 exports.isConfirmationRequired = isConfirmationRequired;
 exports.execTool = execTool;
@@ -14,6 +47,10 @@ const runtime_1 = require("../nerves/runtime");
 const guardrails_1 = require("./guardrails");
 const identity_1 = require("../heart/identity");
 const safe_workspace_1 = require("../heart/safe-workspace");
+const surface_tool_1 = require("../senses/surface-tool");
+const obligations_1 = require("../mind/obligations");
+const session_activity_1 = require("../heart/session-activity");
+const path = __importStar(require("path"));
 function safeGetAgentRoot() {
     try {
         return (0, identity_1.getAgentRoot)();
@@ -25,11 +62,149 @@ function safeGetAgentRoot() {
 // Re-export types and constants used by the rest of the codebase
 var tools_base_2 = require("./tools-base");
 Object.defineProperty(exports, "tools", { enumerable: true, get: function () { return tools_base_2.tools; } });
-Object.defineProperty(exports, "finalAnswerTool", { enumerable: true, get: function () { return tools_base_2.finalAnswerTool; } });
-Object.defineProperty(exports, "noResponseTool", { enumerable: true, get: function () { return tools_base_2.noResponseTool; } });
+Object.defineProperty(exports, "settleTool", { enumerable: true, get: function () { return tools_base_2.settleTool; } });
+Object.defineProperty(exports, "observeTool", { enumerable: true, get: function () { return tools_base_2.observeTool; } });
 Object.defineProperty(exports, "goInwardTool", { enumerable: true, get: function () { return tools_base_2.goInwardTool; } });
+// Surface tool handler: routes content to friend's freshest session
+/* v8 ignore start -- surface handler wiring: core logic tested via surface-tool.test.ts; this wires identity/routing deps @preserve */
+const surfaceToolDefinition = {
+    tool: surface_tool_1.surfaceToolDef,
+    handler: async (args, ctx) => {
+        const queue = ctx?.delegatedOrigins ?? [];
+        const agentName = (() => { try {
+            return (0, identity_1.getAgentName)();
+        }
+        catch {
+            return "unknown";
+        } })();
+        const routeToFriend = async (friendId, content, queueItem) => {
+            /* v8 ignore start -- routing: integration path tested via inner-dialog routing tests @preserve */
+            try {
+                const agentRoot = (0, identity_1.getAgentRoot)();
+                const sessionsDir = path.join(agentRoot, "state", "sessions");
+                const friendsDir = path.join(agentRoot, "friends");
+                // Priority 1: Bridge-preferred session (if queue item has a bridgeId)
+                if (queueItem?.bridgeId) {
+                    const { createBridgeManager } = await Promise.resolve().then(() => __importStar(require("../heart/bridges/manager")));
+                    const bridge = createBridgeManager().getBridge(queueItem.bridgeId);
+                    if (bridge && bridge.lifecycle !== "completed" && bridge.lifecycle !== "cancelled") {
+                        const allSessions = (0, session_activity_1.listSessionActivity)({ sessionsDir, friendsDir, agentName });
+                        const bridgeTarget = allSessions.find((activity) => activity.friendId === friendId
+                            && activity.channel !== "inner"
+                            && bridge.attachedSessions.some((s) => s.friendId === activity.friendId && s.channel === activity.channel && s.key === activity.key));
+                        if (bridgeTarget) {
+                            // Attempt proactive BB delivery for bridge target
+                            if (bridgeTarget.channel === "bluebubbles") {
+                                const { sendProactiveBlueBubblesMessageToSession } = await Promise.resolve().then(() => __importStar(require("../senses/bluebubbles")));
+                                const proactiveResult = await sendProactiveBlueBubblesMessageToSession({
+                                    friendId: bridgeTarget.friendId,
+                                    sessionKey: bridgeTarget.key,
+                                    text: content,
+                                });
+                                if (proactiveResult.delivered) {
+                                    return { status: "delivered", detail: "via iMessage" };
+                                }
+                            }
+                            // Fall back to pending queue for bridge target
+                            const { queuePendingMessage, getPendingDir } = await Promise.resolve().then(() => __importStar(require("../mind/pending")));
+                            const pendingDir = getPendingDir(agentName, bridgeTarget.friendId, bridgeTarget.channel, bridgeTarget.key);
+                            queuePendingMessage(pendingDir, {
+                                from: agentName,
+                                friendId: bridgeTarget.friendId,
+                                channel: bridgeTarget.channel,
+                                key: bridgeTarget.key,
+                                content,
+                                timestamp: Date.now(),
+                            });
+                            return { status: "queued", detail: `for next interaction via ${bridgeTarget.channel}` };
+                        }
+                    }
+                }
+                // Priority 2: Freshest active friend session
+                const freshest = (0, session_activity_1.findFreshestFriendSession)({
+                    sessionsDir,
+                    friendsDir,
+                    agentName,
+                    friendId,
+                    activeOnly: true,
+                });
+                if (freshest && freshest.channel !== "inner") {
+                    // Attempt proactive BB delivery
+                    if (freshest.channel === "bluebubbles") {
+                        const { sendProactiveBlueBubblesMessageToSession } = await Promise.resolve().then(() => __importStar(require("../senses/bluebubbles")));
+                        const proactiveResult = await sendProactiveBlueBubblesMessageToSession({
+                            friendId: freshest.friendId,
+                            sessionKey: freshest.key,
+                            text: content,
+                        });
+                        if (proactiveResult.delivered) {
+                            return { status: "delivered", detail: "via iMessage" };
+                        }
+                    }
+                    // Queue as pending for next interaction
+                    const { queuePendingMessage, getPendingDir } = await Promise.resolve().then(() => __importStar(require("../mind/pending")));
+                    const pendingDir = getPendingDir(agentName, freshest.friendId, freshest.channel, freshest.key);
+                    queuePendingMessage(pendingDir, {
+                        from: agentName,
+                        friendId: freshest.friendId,
+                        channel: freshest.channel,
+                        key: freshest.key,
+                        content,
+                        timestamp: Date.now(),
+                    });
+                    return { status: "queued", detail: `for next interaction via ${freshest.channel}` };
+                }
+                // Priority 3: Deferred — no active session found
+                const { getDeferredReturnDir } = await Promise.resolve().then(() => __importStar(require("../mind/pending")));
+                const { queuePendingMessage: queueDeferred } = await Promise.resolve().then(() => __importStar(require("../mind/pending")));
+                const deferredDir = getDeferredReturnDir(agentName, friendId);
+                queueDeferred(deferredDir, {
+                    from: agentName,
+                    friendId,
+                    channel: "deferred",
+                    key: "return",
+                    content,
+                    timestamp: Date.now(),
+                });
+                return { status: "deferred", detail: "they'll see it next time" };
+            }
+            catch {
+                return { status: "failed" };
+            }
+            /* v8 ignore stop */
+        };
+        return (0, surface_tool_1.handleSurface)({
+            content: args.content ?? "",
+            delegationId: args.delegationId,
+            friendId: args.friendId,
+            queue,
+            routeToFriend,
+            advanceObligation: (obligationId, update) => {
+                /* v8 ignore start -- obligation advance: tested via attention-queue tests @preserve */
+                try {
+                    const name = (() => { try {
+                        return (0, identity_1.getAgentName)();
+                    }
+                    catch {
+                        return "unknown";
+                    } })();
+                    (0, obligations_1.advanceObligation)(name, obligationId, {
+                        status: update.status,
+                        ...(update.returnedAt !== undefined ? { returnedAt: update.returnedAt } : {}),
+                        ...(update.returnTarget !== undefined ? { returnTarget: update.returnTarget } : {}),
+                    });
+                }
+                catch {
+                    // swallowed — obligation advance must never break surface delivery
+                }
+                /* v8 ignore stop */
+            },
+        });
+    },
+};
+/* v8 ignore stop */
 // All tool definitions in a single registry
-const allDefinitions = [...tools_base_1.baseToolDefinitions, ...tools_bluebubbles_1.bluebubblesToolDefinitions, ...tools_teams_1.teamsToolDefinitions, ...ado_semantic_1.adoSemanticToolDefinitions, ...tools_github_1.githubToolDefinitions];
+const allDefinitions = [...tools_base_1.baseToolDefinitions, ...tools_bluebubbles_1.bluebubblesToolDefinitions, ...tools_teams_1.teamsToolDefinitions, ...ado_semantic_1.adoSemanticToolDefinitions, ...tools_github_1.githubToolDefinitions, surfaceToolDefinition];
 function baseToolsForCapabilities() {
     // Use baseToolDefinitions at call time so dynamically-added tools are included
     return tools_base_1.baseToolDefinitions.map((d) => d.tool);

package/dist/senses/attention-queue.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAttentionQueue = buildAttentionQueue;
+exports.dequeueAttentionItem = dequeueAttentionItem;
+exports.attentionQueueEmpty = attentionQueueEmpty;
+exports.buildAttentionQueueSummary = buildAttentionQueueSummary;
+const runtime_1 = require("../nerves/runtime");
+// ── Queue construction ───────────────────────────────────────────
+function generateItemId() {
+    return Math.random().toString(36).slice(2, 10);
+}
+function originKey(friendId, channel, key) {
+    return `${friendId}/${channel}/${key}`;
+}
+function buildAttentionQueue(input) {
+    const { drainedPending, outstandingObligations, friendNameResolver } = input;
+    const seen = new Set();
+    const items = [];
+    // Source 1: drained pending messages with delegatedFrom (current-turn delegations)
+    for (const msg of drainedPending) {
+        if (!msg.delegatedFrom)
+            continue;
+        const { friendId, channel, key, bridgeId } = msg.delegatedFrom;
+        const oKey = originKey(friendId, channel, key);
+        seen.add(oKey);
+        const resolvedName = friendNameResolver(friendId);
+        items.push({
+            id: msg.obligationId ?? generateItemId(),
+            friendId,
+            friendName: resolvedName ?? friendId,
+            channel,
+            key,
+            ...(bridgeId ? { bridgeId } : {}),
+            delegatedContent: msg.content,
+            ...(msg.obligationId ? { obligationId: msg.obligationId } : {}),
+            source: "drained",
+            timestamp: msg.timestamp,
+        });
+    }
+    // Source 2: outstanding obligations (crash recovery)
+    for (const obligation of outstandingObligations) {
+        const { friendId, channel, key, bridgeId } = obligation.origin;
+        const oKey = originKey(friendId, channel, key);
+        if (seen.has(oKey))
+            continue; // deduplicate: prefer drained version
+        seen.add(oKey);
+        const resolvedName = friendNameResolver(friendId);
+        items.push({
+            id: obligation.id,
+            friendId,
+            friendName: resolvedName ?? friendId,
+            channel,
+            key,
+            ...(bridgeId ? { bridgeId } : {}),
+            delegatedContent: obligation.delegatedContent,
+            obligationId: obligation.id,
+            source: "obligation-recovery",
+            timestamp: obligation.createdAt,
+        });
+    }
+    // Sort FIFO (oldest first)
+    items.sort((a, b) => a.timestamp - b.timestamp);
+    (0, runtime_1.emitNervesEvent)({
+        event: "senses.attention_queue_built",
+        component: "senses",
+        message: `attention queue built with ${items.length} item(s)`,
+        meta: {
+            drainedCount: items.filter((i) => i.source === "drained").length,
+            recoveredCount: items.filter((i) => i.source === "obligation-recovery").length,
+        },
+    });
+    return items;
+}
+// ── Queue operations ─────────────────────────────────────────────
+function dequeueAttentionItem(queue, id) {
+    const index = queue.findIndex((item) => item.id === id);
+    if (index === -1)
+        return null;
+    return queue.splice(index, 1)[0];
+}
+function attentionQueueEmpty(queue) {
+    return queue.length === 0;
+}
+// ── Queue visibility ─────────────────────────────────────────────
+const CONTENT_PREVIEW_MAX = 80;
+function buildAttentionQueueSummary(queue) {
+    if (queue.length === 0)
+        return "";
+    const lines = ["you're holding:"];
+    for (const item of queue) {
+        const preview = item.delegatedContent.length > CONTENT_PREVIEW_MAX
+            ? `${item.delegatedContent.slice(0, CONTENT_PREVIEW_MAX - 3)}...`
+            : item.delegatedContent;
+        lines.push(`- [${item.id}] ${item.friendName} asked: "${preview}"`);
+    }
+    return lines.join("\n");
+}

package/dist/senses/cli.js

@@ -382,14 +382,14 @@ function createCliCallbacks() {
         onModelStreamStart: () => {
             // 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.
+            // doesn't fire at all for settle tool streaming.
         },
         onClearText: () => {
             streamer.reset();
             wrapper.reset();
         },
         onTextChunk: (text) => {
-            // Stop spinner if still running — final_answer streaming and Anthropic
+            // Stop spinner if still running — settle streaming and Anthropic
             // tool-only responses bypass onModelStreamStart, so the spinner would
             // otherwise keep running (and its \r writes overwrite response text).
             if (currentSpinner) {
@@ -558,7 +558,7 @@ async function runCliSession(options) {
                 exitToolResult = result;
                 exitToolFired = true;
                 // Abort immediately so the model doesn't generate more output
-                // (e.g. reasoning about calling final_answer after complete_adoption)
+                // (e.g. reasoning about calling settle after complete_adoption)
                 currentAbort?.abort();
             }
             return result;