@ouro.bot/cli 0.1.0-alpha.80 → 0.1.0-alpha.801

package/dist/senses/shared-turn.js

@@ -0,0 +1,571 @@
+"use strict";
+// Shared turn runner for non-interactive senses (MCP, future senses).
+// Follows the CLI pattern: resolves context, constructs InboundTurnInput,
+// calls handleInboundTurn, collects response text, detects ponder deferral.
+//
+// Does NOT refactor CLI — CLI is stable with 2280+ tests. This is a new
+// code path for new senses that follows the same pipeline pattern.
+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.stripThinkBlocks = stripThinkBlocks;
+exports.extractOutwardSenseDeliveryText = extractOutwardSenseDeliveryText;
+exports.getSenseSessionPath = getSenseSessionPath;
+exports.runSenseTurn = runSenseTurn;
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const core_1 = require("../heart/core");
+const identity_1 = require("../heart/identity");
+const config_1 = require("../heart/config");
+const session_events_1 = require("../heart/session-events");
+const context_1 = require("../mind/context");
+const prompt_1 = require("../mind/prompt");
+const friends_1 = require("@ouro.bot/friends");
+const pending_1 = require("../mind/pending");
+const context_2 = require("../mind/context");
+const trust_gate_1 = require("./trust-gate");
+const pipeline_1 = require("./pipeline");
+const mcp_manager_1 = require("../repertoire/mcp-manager");
+const runtime_1 = require("../nerves/runtime");
+const session_transaction_1 = require("../mind/session-transaction");
+const RESPONSE_CAP = 50_000;
+const OUTWARD_DELIVERY_TOOL_ACKS = new Map([
+    ["settle", "(delivered)"],
+    ["speak", "(spoken)"],
+]);
+/**
+ * Strip MiniMax-style `<think>...</think>` reasoning blocks from a response
+ * string. Handles unclosed open tags (treats everything from `<think>` to
+ * end of string as reasoning) and multiple blocks in sequence. Returns the
+ * trimmed remainder.
+ */
+function stripThinkBlocks(input) {
+    let out = input;
+    // Closed blocks first (greedy match removed by repeatedly slicing the leftmost pair).
+    for (;;) {
+        const open = out.indexOf("<think>");
+        if (open === -1)
+            break;
+        const close = out.indexOf("</think>", open + "<think>".length);
+        if (close === -1) {
+            // Unclosed — drop everything from <think> onward.
+            out = out.slice(0, open);
+            break;
+        }
+        out = out.slice(0, open) + out.slice(close + "</think>".length);
+    }
+    return out.trim();
+}
+function assistantContentText(content) {
+    if (typeof content !== "string")
+        return null;
+    const trimmed = content.trim();
+    return trimmed ? trimmed : null;
+}
+function parseToolStringArg(toolCall, toolName, argName) {
+    if (!toolCall || typeof toolCall !== "object")
+        return null;
+    const fn = toolCall.function;
+    if (fn?.name !== toolName || typeof fn.arguments !== "string")
+        return null;
+    try {
+        const parsed = JSON.parse(fn.arguments);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return null;
+        const value = parsed[argName];
+        if (typeof value !== "string")
+            return null;
+        const trimmed = value.trim();
+        return trimmed ? trimmed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function hasDeliveredToolResult(messages, assistantIndex, toolCallId, toolName) {
+    if (typeof toolCallId !== "string" || !toolCallId.trim())
+        return false;
+    const expectedAck = OUTWARD_DELIVERY_TOOL_ACKS.get(toolName);
+    for (let index = assistantIndex + 1; index < messages.length; index++) {
+        const message = messages[index];
+        if (message.role !== "tool")
+            return false;
+        if (message.tool_call_id === toolCallId
+            && typeof message.content === "string"
+            && message.content.trim() === expectedAck) {
+            return true;
+        }
+    }
+    return false;
+}
+function outwardDeliveryTextFromAssistantTools(messages, assistantIndex) {
+    const assistant = messages[assistantIndex];
+    const toolCalls = assistant.tool_calls;
+    const delivered = [];
+    for (let index = 0; index < toolCalls.length; index++) {
+        const toolCall = toolCalls[index];
+        const toolCallId = toolCall && typeof toolCall === "object"
+            ? toolCall.id
+            : undefined;
+        const settleAnswer = parseToolStringArg(toolCall, "settle", "answer");
+        if (settleAnswer && hasDeliveredToolResult(messages, assistantIndex, toolCallId, "settle")) {
+            delivered.push(settleAnswer);
+            continue;
+        }
+        const spokenMessage = parseToolStringArg(toolCall, "speak", "message");
+        if (spokenMessage && hasDeliveredToolResult(messages, assistantIndex, toolCallId, "speak")) {
+            delivered.push(spokenMessage);
+        }
+    }
+    return delivered.length > 0 ? delivered.join("\n") : null;
+}
+/**
+ * Recover the text that actually reached a friend in an outward sense turn.
+ *
+ * Ouro runs outward channels in tool-required mode. That means the visible
+ * response may be a `settle({ answer })` or `speak({ message })` tool call
+ * whose assistant message has `content: null`. The authoritative delivery
+ * signal is the following tool ack:
+ *
+ * - `(delivered)` for `settle.answer`
+ * - `(spoken)` for `speak.message`
+ *
+ * Private-runtime `(settled)`, malformed tool arguments, rejected tools, and
+ * interrupted tool-call sequences are not outward speech. Sense transports
+ * that need to replay the turn later (Voice/Twilio TTS, future meeting audio)
+ * should use this helper instead of reading `assistant.content` directly.
+ */
+function extractOutwardSenseDeliveryText(messages) {
+    const assistantIndex = messages.findLastIndex((message) => message.role === "assistant");
+    if (assistantIndex < 0)
+        return null;
+    const assistant = messages[assistantIndex];
+    return Array.isArray(assistant.tool_calls) && assistant.tool_calls.length > 0
+        ? outwardDeliveryTextFromAssistantTools(messages, assistantIndex)
+        : assistantContentText(assistant.content);
+}
+function hasAcceptedOutwardSessionAck(events, assistantIndex, toolCallId, toolName) {
+    const expectedAck = OUTWARD_DELIVERY_TOOL_ACKS.get(toolName);
+    for (let index = assistantIndex + 1; index < events.length; index++) {
+        const candidate = events[index];
+        if (candidate.role !== "tool")
+            return false;
+        if (candidate.toolCallId === toolCallId && typeof candidate.content === "string" && candidate.content.trim() === expectedAck)
+            return true;
+    }
+    return false;
+}
+function newOutwardCoordinates(events, existingEventIds, afterEventId) {
+    const boundaryIndex = events.findIndex((event) => event.id === afterEventId);
+    if (boundaryIndex < 0)
+        return [];
+    return events.flatMap((event, eventIndex) => {
+        if (eventIndex <= boundaryIndex || existingEventIds.has(event.id) || event.role !== "assistant" || event.provenance?.captureKind === "synthetic")
+            return [];
+        const outwardTools = event.toolCalls.flatMap((call) => {
+            if (call.function.name !== "speak" && call.function.name !== "settle")
+                return [];
+            if (!hasAcceptedOutwardSessionAck(events, eventIndex, call.id, call.function.name))
+                return [];
+            const text = stripThinkBlocks(parseToolStringArg(call, call.function.name, call.function.name === "speak" ? "message" : "answer") ?? "");
+            return text ? [{ kind: call.function.name, eventId: event.id, text }] : [];
+        });
+        if (outwardTools.length > 0)
+            return outwardTools;
+        if (event.toolCalls.length > 0)
+            return [];
+        const text = stripThinkBlocks(typeof event.content === "string" ? event.content : "");
+        return text ? [{ kind: "text", eventId: event.id, text }] : [];
+    });
+}
+function newestPlainAssistantText(messages) {
+    const message = messages.findLast((candidate) => candidate.role === "assistant"
+        && (!("tool_calls" in candidate) || !Array.isArray(candidate.tool_calls) || candidate.tool_calls.length === 0)
+        && typeof candidate.content === "string"
+        && candidate.content.trim().length > 0);
+    return message ? assistantContentText(message.content) : null;
+}
+function causalSessionEventIds(events, existingEventIds, attempts, afterEventId) {
+    if (!afterEventId)
+        return attempts.flatMap((attempt) => attempt.delivered ? [null] : []);
+    const coordinates = newOutwardCoordinates(events, existingEventIds, afterEventId);
+    let nextCoordinate = 0;
+    return attempts.flatMap((attempt) => {
+        if (!attempt.delivered)
+            return [];
+        const coordinateIndex = coordinates.findIndex((coordinate, index) => index >= nextCoordinate && coordinate.kind === attempt.kind && coordinate.text === attempt.text);
+        if (coordinateIndex < 0)
+            return [null];
+        nextCoordinate = coordinateIndex + 1;
+        return [coordinates[coordinateIndex].eventId];
+    });
+}
+function currentIngressEventId(events, existingEventIds, userMessage, precommittedIngress, ingressRelations) {
+    if (precommittedIngress)
+        return precommittedIngress.eventId;
+    const reference = ingressRelations?.references[0];
+    return events.findLast((event) => (!existingEventIds.has(event.id)
+        && event.role === "user"
+        && event.content === userMessage
+        && event.provenance?.captureKind !== "synthetic"
+        && (!reference || event.relations?.references.includes(reference))))?.id;
+}
+function getSenseSessionPath(agentName, friendId, channel, sessionKey, agentRootOverride) {
+    return path.join(agentRootOverride ?? (0, identity_1.getAgentRoot)(agentName), "state", "sessions", friendId, channel, `${(0, config_1.sanitizeKey)(sessionKey)}.json`);
+}
+/**
+ * Run a single agent turn through the inbound pipeline.
+ * Caller provides channel, session key, friend, and message;
+ * this function handles all pipeline wiring.
+ */
+async function runSenseTurn(options) {
+    const { agentName, channel, sessionKey, friendId, userMessage } = options;
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.shared_turn_start",
+        message: "shared turn runner starting",
+        meta: { agentName, channel, sessionKey, friendId },
+    });
+    // Resolve context
+    const agentRoot = (0, identity_1.getAgentRoot)(agentName);
+    const friendsPath = path.join(agentRoot, "friends");
+    const friendStore = new friends_1.FileFriendStore(friendsPath);
+    const capabilities = (0, friends_1.getChannelCapabilities)(channel);
+    // If friendId looks like a UUID, look up the friend record directly and use its identity.
+    // Otherwise, resolve as a local user (same pattern as CLI sense).
+    const isUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-/.test(friendId);
+    let resolverParams;
+    if (options.identity) {
+        resolverParams = {
+            provider: options.identity.provider,
+            externalId: options.identity.externalId,
+            displayName: options.identity.displayName,
+            channel,
+            ...(options.identity.tenantId ? { tenantId: options.identity.tenantId } : {}),
+        };
+    }
+    else if (isUuid) {
+        const existingFriend = await friendStore.get(friendId);
+        if (existingFriend) {
+            // Use the friend's first external ID for resolver context
+            const ext = existingFriend.externalIds?.[0];
+            resolverParams = {
+                provider: (ext?.provider ?? "local"),
+                externalId: ext?.externalId ?? friendId,
+                displayName: existingFriend.name ?? friendId,
+                channel,
+            };
+        }
+        else {
+            resolverParams = { provider: "local", externalId: friendId, displayName: friendId, channel };
+        }
+    }
+    else {
+        // Treat as local user identity (username@hostname pattern)
+        const username = os.userInfo().username;
+        resolverParams = { provider: "local", externalId: username, displayName: username, channel };
+    }
+    const resolver = new friends_1.FriendResolver(friendStore, resolverParams);
+    // Initialize MCP manager so MCP tools appear as first-class tools in the agent's tool list.
+    // Runtime MCP servers (e.g. Workbench's ouro_workbench) are passed per-turn for THIS agent only.
+    const mcpManager = await (0, mcp_manager_1.getSharedMcpManager)(options.runtimeMcpServers ? { runtimeServers: options.runtimeMcpServers } : undefined) ?? undefined;
+    // Session path and loading
+    const sessionDir = path.join(agentRoot, "state", "sessions", friendId, channel);
+    fs.mkdirSync(sessionDir, { recursive: true });
+    const sessPath = getSenseSessionPath(agentName, friendId, channel, sessionKey, agentRoot);
+    const runWithLease = options._withSessionTurnLease ?? session_transaction_1.withSessionTurnLease;
+    return runWithLease(sessPath, async (sessionTurnLease) => {
+        const baseSessionRevision = (0, session_transaction_1.readSessionTransaction)(sessPath, sessionTurnLease).revision;
+        const existing = (0, context_1.loadSession)(sessPath);
+        if (options.precommittedIngress) {
+            const event = existing?.events?.find((candidate) => candidate.id === options.precommittedIngress.eventId);
+            const latestUserEvent = existing?.events?.filter((candidate) => candidate.role === "user").at(-1);
+            if (!event || event !== latestUserEvent || event.role !== "user" || event.content !== userMessage
+                || !event.relations.references.includes(options.precommittedIngress.reference)) {
+                throw new Error("shared turn precommitted ingress is missing, mismatched, or no longer current");
+            }
+        }
+        const existingEventIds = new Set(existing?.events?.map((event) => event.id) ?? []);
+        let sessionState = existing?.state;
+        let persistPromise;
+        const sessionMessages = existing?.messages && existing.messages.length > 0
+            ? existing.messages
+            : [{ role: "system", content: (0, prompt_1.flattenSystemPrompt)(await (0, prompt_1.buildSystem)(channel, {}, undefined)) }];
+        const preTurnMessageCount = sessionMessages.length;
+        // Pending dir
+        const pendingDir = (0, pending_1.getPendingDir)(agentName, friendId, channel, sessionKey);
+        // Accumulate outward text through the same callback boundary used by chat
+        // channels. `speak` flushes pending text immediately; `settle` is delivered
+        // once the turn completes.
+        let committedResponseText = "";
+        let pendingResponseText = "";
+        let terminalDeliveryKind = "text";
+        const deliveries = [];
+        const deliveryFailures = [];
+        const deliveryAttempts = [];
+        let providerInvocationCount = 0;
+        let toolInvocationCount = 0;
+        let hadReasoningChunk = false;
+        const commitResponseText = (text) => {
+            const cleaned = stripThinkBlocks(text);
+            /* v8 ignore next -- deliverPending strips first; this is a defensive direct-call guard @preserve */
+            if (!cleaned)
+                return;
+            committedResponseText = committedResponseText
+                ? `${committedResponseText}\n${cleaned}`
+                : cleaned;
+        };
+        const deliveryErrorMessage = (error) => error instanceof Error ? error.message : String(error);
+        const deliverPending = async (kind, optionsForDelivery) => {
+            const text = stripThinkBlocks(pendingResponseText);
+            pendingResponseText = "";
+            if (!text)
+                return;
+            const delivery = { kind, text };
+            const attempt = { kind, text, delivered: false };
+            deliveryAttempts.push(attempt);
+            try {
+                await options.deliverySink?.onDelivery(delivery);
+                attempt.delivered = true;
+                deliveries.push(delivery);
+                commitResponseText(text);
+            }
+            catch (error) {
+                const failure = { ...delivery, error: deliveryErrorMessage(error) };
+                deliveryFailures.push(failure);
+                (0, runtime_1.emitNervesEvent)({
+                    level: "error",
+                    component: "senses",
+                    event: "senses.shared_turn_delivery_error",
+                    message: "shared turn outward delivery failed",
+                    meta: { agentName, channel, sessionKey, friendId, kind, error: failure.error, textLength: text.length },
+                });
+                if (optionsForDelivery.throwOnError)
+                    throw error;
+                commitResponseText(text);
+            }
+        };
+        /* v8 ignore start — callback stubs are exercised through the pipeline integration */
+        const callbacks = {
+            settleOutputMode: "retractable_buffer",
+            onModelStart: () => { providerInvocationCount += 1; if (options.turnMetricsObserver)
+                options.turnMetricsObserver.providerInvocationCount += 1; },
+            onModelStreamStart: () => { },
+            onTextChunk: (chunk) => { pendingResponseText += chunk; },
+            onReasoningChunk: () => { hadReasoningChunk = true; },
+            onToolStart: () => { toolInvocationCount += 1; if (options.turnMetricsObserver)
+                options.turnMetricsObserver.toolInvocationCount += 1; },
+            onToolEnd: (name, _summary, success) => {
+                if (name === "settle" && success)
+                    terminalDeliveryKind = "settle";
+            },
+            onError: () => { },
+            onClearText: () => { pendingResponseText = ""; },
+            flushNow: () => deliverPending("speak", { throwOnError: true }),
+        };
+        /* v8 ignore stop */
+        // Run the pipeline
+        const inboundMessages = [];
+        if (!options.precommittedIngress) {
+            const userMsg = { role: "user", content: userMessage };
+            (0, session_events_1.stampIngressTime)(userMsg);
+            if (options.ingressRelations)
+                (0, session_events_1.stampIngressRelations)(userMsg, options.ingressRelations);
+            inboundMessages.push(userMsg);
+        }
+        const turnResult = await (0, pipeline_1.handleInboundTurn)({
+            channel,
+            latencyMode: options.latencyMode,
+            sessionKey,
+            capabilities,
+            messages: inboundMessages,
+            callbacks,
+            sessionTurnLease,
+            /* v8 ignore start — delegation wrappers; pipeline integration tested separately */
+            friendResolver: { resolve: () => resolver.resolve() },
+            sessionLoader: {
+                loadOrCreate: () => Promise.resolve({
+                    messages: sessionMessages,
+                    sessionPath: sessPath,
+                    state: sessionState,
+                    events: existing?.events,
+                    structuredOutputs: existing?.structuredOutputs,
+                }),
+            },
+            /* v8 ignore stop */
+            pendingDir,
+            friendStore,
+            provider: resolverParams.provider,
+            externalId: resolverParams.externalId,
+            tenantId: resolverParams.tenantId,
+            enforceTrustGate: trust_gate_1.enforceTrustGate,
+            drainPending: pending_1.drainPending,
+            runAgentOptions: {
+                mcpManager,
+                ...(options.approvalCoordinatorFactory ? { approvalCoordinator: options.approvalCoordinatorFactory({ sessionPath: sessPath, baseSessionRevision }) } : {}),
+                ...(options.latencyMode === "live" ? { skipKeptNotes: true } : {}),
+                ...(options.orientationFrame ? { orientationFrame: options.orientationFrame } : {}),
+                toolContext: {
+                    signin: async () => undefined,
+                    ...(options.toolContext ? options.toolContext : {}),
+                    currentUserMessage: userMessage,
+                },
+            },
+            ...(options.prepareRunAgentOptions ? { prepareRunAgentOptions: options.prepareRunAgentOptions } : {}),
+            /* v8 ignore start — delegation wrappers; these just forward to the real functions */
+            runAgent: (msgs, cb, ch, sig, opts) => (0, core_1.runAgent)(msgs, cb, ch, sig, opts),
+            postTurn: (turnMessages, sessionPathArg, usage, hooks, state) => {
+                const prepared = (0, context_2.postTurnTrim)(turnMessages, usage, hooks);
+                sessionState = state;
+                persistPromise = (0, context_2.deferPostTurnPersist)(sessionPathArg, prepared, usage, state);
+            },
+            /* v8 ignore stop */
+            accumulateFriendTokens: friends_1.accumulateFriendTokens,
+        });
+        if (turnResult.gateResult && !turnResult.gateResult.allowed) {
+            const blockedResponse = "autoReply" in turnResult.gateResult
+                ? turnResult.gateResult.autoReply
+                : `(blocked by trust gate: ${turnResult.gateResult.reason})`;
+            return {
+                response: blockedResponse,
+                ponderDeferred: false,
+                deliveries,
+                deliveryFailures,
+                providerInvocationCount,
+                toolInvocationCount,
+                sessionPath: sessPath,
+            };
+        }
+        const persistedEvents = persistPromise ? await persistPromise : [];
+        const ingressEventId = currentIngressEventId(persistedEvents, existingEventIds, userMessage, options.precommittedIngress, options.ingressRelations);
+        const finalDeliveryKind = terminalDeliveryKind;
+        const acceptedTerminalOutcome = turnResult.turnOutcome === "settled" || turnResult.turnOutcome === "blocked";
+        const failoverText = turnResult.turnOutcome === "errored" ? turnResult.failoverMessage?.trim() : undefined;
+        const expectsOutwardResponse = acceptedTerminalOutcome || turnResult.turnOutcome === "command" || Boolean(failoverText);
+        const hadPendingCallbackText = stripThinkBlocks(pendingResponseText).length > 0;
+        let recoveredTerminalEventId;
+        if (acceptedTerminalOutcome) {
+            const completionText = turnResult.completion?.answer.trim();
+            const currentTurnMessages = Array.isArray(turnResult.messages) ? turnResult.messages.slice(preTurnMessageCount) : [];
+            const plainTerminalText = newestPlainAssistantText(currentTurnMessages);
+            const acknowledgedDeliveryText = finalDeliveryKind === "settle"
+                ? extractOutwardSenseDeliveryText(currentTurnMessages)
+                : null;
+            const authoritativeText = completionText || acknowledgedDeliveryText || plainTerminalText;
+            if (authoritativeText)
+                pendingResponseText = authoritativeText;
+            else
+                pendingResponseText = "";
+            if (!hadPendingCallbackText && plainTerminalText)
+                recoveredTerminalEventId = causalSessionEventIds(persistedEvents, existingEventIds, [{ kind: "text", text: stripThinkBlocks(plainTerminalText), delivered: true }], ingressEventId)[0] ?? undefined;
+        }
+        else if (turnResult.turnOutcome === "command") {
+            // Slash-command text is emitted directly by the pipeline and has no assistant event.
+        }
+        else if (failoverText) {
+            pendingResponseText = failoverText;
+        }
+        else {
+            pendingResponseText = "";
+        }
+        await deliverPending(finalDeliveryKind, { throwOnError: false });
+        const ponderDeferred = false;
+        // Build response
+        let finalResponse;
+        let responseCausalSessionEventId = recoveredTerminalEventId;
+        if (committedResponseText.length === 0) {
+            if (!expectsOutwardResponse) {
+                finalResponse = "";
+            }
+            else {
+                // The terminal turn had no committed text — check its session transcript for the delivered answer.
+                const postTurnSession = (0, context_1.loadSession)(sessPath);
+                const emptyFallback = options.emptyResponseFallback?.();
+                if (postTurnSession?.messages) {
+                    const recovered = extractOutwardSenseDeliveryText(postTurnSession.messages.slice(preTurnMessageCount));
+                    finalResponse = recovered ?? emptyFallback ?? (hadReasoningChunk ? "" : "(agent responded but response was empty)");
+                    if (recovered)
+                        responseCausalSessionEventId = causalSessionEventIds(persistedEvents, existingEventIds, [{ kind: finalDeliveryKind, text: stripThinkBlocks(recovered), delivered: true }], ingressEventId)[0] ?? undefined;
+                }
+                else {
+                    finalResponse = emptyFallback ?? (hadReasoningChunk ? "" : "(agent responded but response was empty)");
+                }
+            }
+        }
+        else {
+            finalResponse = committedResponseText;
+        }
+        // Strip MiniMax-style <think>...</think> blocks from the final response.
+        // When a reasoning-style model emits only a think block and no final answer
+        // (no settle tool call, no post-think text), the readback path above
+        // surfaces the raw saved assistant content — which includes the think tags
+        // and renders as empty (or as raw reasoning) on MCP/CLI clients. Strip
+        // here so the caller sees the actual delivered text. If only reasoning
+        // came through and nothing else, surface a clear diagnostic message
+        // instead of a blank response so the operator knows what happened.
+        finalResponse = stripThinkBlocks(finalResponse);
+        if (finalResponse.length === 0 && expectsOutwardResponse) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "senses",
+                event: "senses.shared_turn_only_reasoning",
+                message: "agent produced only <think> reasoning with no final answer — likely a model that closed the think tag without continuing",
+                meta: { agentName, channel, sessionKey, friendId },
+            });
+            finalResponse = "(agent produced reasoning but no final answer this turn — try again, or check the session transcript for the trace)";
+        }
+        // Cap response length
+        if (finalResponse.length > RESPONSE_CAP) {
+            finalResponse = finalResponse.slice(0, RESPONSE_CAP) + "\n\n[truncated — response exceeded 50K characters]";
+        }
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.shared_turn_end",
+            message: "shared turn runner complete",
+            meta: { agentName, channel, sessionKey, friendId, ponderDeferred, responseLength: finalResponse.length },
+        });
+        return {
+            response: finalResponse,
+            ponderDeferred,
+            deliveries,
+            deliveryFailures,
+            providerInvocationCount,
+            toolInvocationCount,
+            sessionPath: sessPath,
+            ...(deliveries.length > 0 ? { causalSessionEventIds: causalSessionEventIds(persistedEvents, existingEventIds, deliveryAttempts, ingressEventId) } : {}),
+            ...(responseCausalSessionEventId ? { responseCausalSessionEventId } : {}),
+        };
+    });
+}

package/dist/senses/surface-tool.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleSurface = handleSurface;
+const attention_queue_1 = require("./attention-queue");
+const runtime_1 = require("../nerves/runtime");
+async function handleSurface(input) {
+    const { content, delegationId, friendId, deliveryHint, queue, routeToFriend, advanceObligation, completePonderPacket, fulfillHeartObligation, onRouteResult, } = input;
+    // Resolve target friend
+    let targetFriendId;
+    let queueItem;
+    const matchesFriend = (item, target) => item.friendId === target || item.friendName.toLowerCase() === target.toLowerCase();
+    const inferQueueItem = (target) => {
+        if (queue.length === 0)
+            return undefined;
+        const candidates = target
+            ? queue.filter((item) => matchesFriend(item, target))
+            : queue;
+        if (candidates.length === 1)
+            return candidates[0];
+        if (candidates.length > 1) {
+            return `multiple held thoughts match ${target ?? "this surface call"} — use delegationId to choose one`;
+        }
+        return undefined;
+    };
+    if (delegationId) {
+        // Look up in attention queue
+        const found = queue.find((item) => item.id === delegationId);
+        if (!found) {
+            return `no delegation found with id ${delegationId} — check your attention queue`;
+        }
+        targetFriendId = found.friendId;
+        queueItem = found;
+    }
+    else if (friendId) {
+        const inferred = inferQueueItem(friendId);
+        if (typeof inferred === "string")
+            return inferred;
+        queueItem = inferred;
+        targetFriendId = queueItem?.friendId ?? friendId;
+    }
+    else {
+        const inferred = inferQueueItem();
+        if (typeof inferred === "string")
+            return inferred;
+        if (inferred) {
+            queueItem = inferred;
+            targetFriendId = inferred.friendId;
+        }
+        else {
+            return "specify who this thought is for — use delegationId to address a held thought, or friendId for spontaneous outreach";
+        }
+    }
+    if (queueItem?.packetId && !delegationId) {
+        return `held private return ${queueItem.id} is waiting — call surface with delegationId="${queueItem.id}" so the return is tied to the correct packet`;
+    }
+    // Route to target
+    const result = deliveryHint
+        ? await routeToFriend(targetFriendId, content, queueItem, deliveryHint)
+        : await routeToFriend(targetFriendId, content, queueItem);
+    (0, runtime_1.emitNervesEvent)({
+        event: "senses.surface_routed",
+        component: "senses",
+        message: `surface routed to ${targetFriendId}: ${result.status}`,
+        meta: {
+            targetFriendId,
+            status: result.status,
+            hasDelegationId: !!delegationId,
+            ...(result.detail ? { detail: result.detail } : {}),
+        },
+    });
+    onRouteResult?.({ targetFriendId, queueItem, result });
+    // On successful routing with delegationId:
+    // 1. Advance obligation to "returned" (disk FIRST — crash safety)
+    // 2. Dequeue from process-local queue (AFTER obligation advance)
+    if (queueItem && result.status !== "failed") {
+        if (queueItem.obligationId) {
+            advanceObligation(queueItem.obligationId, {
+                status: "returned",
+                returnedAt: Date.now(),
+                returnTarget: "surface",
+            });
+        }
+        if (completePonderPacket && queueItem.packetId) {
+            try {
+                completePonderPacket(queueItem.packetId);
+            }
+            catch {
+                // swallowed — packet completion must never break surface delivery
+            }
+        }
+        // Fulfill the heart obligation for this origin (separate from inner/mind obligation)
+        if (fulfillHeartObligation) {
+            try {
+                fulfillHeartObligation({
+                    friendId: queueItem.friendId,
+                    channel: queueItem.channel,
+                    key: queueItem.key,
+                });
+            }
+            catch {
+                // swallowed — heart obligation fulfillment must never break surface delivery
+            }
+        }
+        (0, attention_queue_1.dequeueAttentionItem)(queue, queueItem.id);
+    }
+    // Return delivery status
+    const detail = result.detail ? ` — ${result.detail}` : "";
+    return `${result.status}${detail}`;
+}