@ouro.bot/cli 0.1.0-alpha.99 → 0.1.0-alpha.991

package/dist/senses/shared-turn.js

@@ -0,0 +1,832 @@
+"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.erroredTurnReply = erroredTurnReply;
+exports.runSenseTurn = runSenseTurn;
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const delegated_command_1 = require("../a2a/delegated-command");
+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 orientation_frame_1 = require("../heart/orientation-frame");
+const turn_execution_lease_1 = require("../heart/turn-execution-lease");
+const RESPONSE_CAP = 50_000;
+const OUTWARD_DELIVERY_TOOL_ACKS = new Map([
+    ["settle", "(delivered)"],
+    ["speak", "(spoken)"],
+]);
+async function releaseRuntimeMcpServersAfterTurn(owner) {
+    const manager = await Promise.resolve().then(() => __importStar(require("../repertoire/mcp-manager")));
+    await manager.releaseRuntimeMcpServers(owner);
+}
+/**
+ * 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) {
+    if (typeof toolCallId !== "string" || !toolCallId.trim())
+        return false;
+    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 && candidate.relations?.toolCallId !== toolCallId)
+            continue;
+        return candidate.toolCallId === toolCallId
+            && candidate.relations?.toolCallId === toolCallId
+            && candidate.provenance?.captureKind === "live"
+            && Array.isArray(candidate.toolCalls)
+            && candidate.toolCalls.length === 0
+            && typeof candidate.content === "string"
+            && candidate.content === expectedAck;
+    }
+    return false;
+}
+function newOutwardCoordinates(events, existingEventIds, boundaryIndex) {
+    return events.flatMap((event, eventIndex) => {
+        if (eventIndex <= boundaryIndex || existingEventIds.has(event.id) || event.role !== "assistant" || event.provenance?.captureKind !== "live" || !Array.isArray(event.toolCalls))
+            return [];
+        const outwardTools = event.toolCalls.flatMap((call) => {
+            const toolName = call?.function?.name;
+            if (toolName !== "speak" && toolName !== "settle")
+                return [];
+            if (!hasAcceptedOutwardSessionAck(events, eventIndex, call.id, toolName))
+                return [];
+            const text = stripThinkBlocks(parseToolStringArg(call, toolName, toolName === "speak" ? "message" : "answer") ?? "");
+            return text ? [{ kind: toolName, eventId: event.id, eventIndex, 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, eventIndex, text }] : [];
+    });
+}
+function alignedDeliveryCoordinates(view, attempts, finalAttemptIndex, finalCoordinate) {
+    if (!view)
+        return attempts.flatMap((attempt) => attempt.delivered ? [null] : []);
+    const terminalCoordinate = finalCoordinate ?? (finalAttemptIndex === undefined ? view.terminal : undefined);
+    const reservedAttemptIndex = terminalCoordinate
+        ? finalAttemptIndex !== undefined
+            ? (attempts[finalAttemptIndex]?.delivered && attempts[finalAttemptIndex]?.kind === terminalCoordinate.kind && attempts[finalAttemptIndex]?.text === terminalCoordinate.text ? finalAttemptIndex : -1)
+            : attempts.findLastIndex((attempt) => attempt.delivered && attempt.kind === terminalCoordinate.kind && attempt.text === terminalCoordinate.text)
+        : -1;
+    const availableCoordinates = terminalCoordinate ? view.coordinates.filter((coordinate) => coordinate !== terminalCoordinate) : view.coordinates;
+    let nextCoordinate = 0;
+    return attempts.flatMap((attempt, attemptIndex) => {
+        if (!attempt.delivered)
+            return [];
+        if (attemptIndex === finalAttemptIndex)
+            return finalCoordinate && finalCoordinate.kind === attempt.kind && finalCoordinate.text === attempt.text ? [finalCoordinate] : [null];
+        if (attemptIndex === reservedAttemptIndex && terminalCoordinate)
+            return [terminalCoordinate];
+        const coordinateIndex = availableCoordinates.findIndex((coordinate, index) => index >= nextCoordinate && coordinate.kind === attempt.kind && coordinate.text === attempt.text);
+        if (coordinateIndex < 0)
+            return [null];
+        nextCoordinate = coordinateIndex + 1;
+        return [availableCoordinates[coordinateIndex]];
+    });
+}
+function causalSessionEventIds(view, attempts, finalAttemptIndex, finalCoordinate) {
+    return alignedDeliveryCoordinates(view, attempts, finalAttemptIndex, finalCoordinate).map((coordinate) => coordinate?.eventId ?? null);
+}
+function currentIngressEventId(events, existingEventIds, userMessage, precommittedIngress, ingressRelations) {
+    const reference = ingressRelations?.references[0];
+    const carriesReference = (event, expected) => Array.isArray(event.relations?.references) && event.relations.references.includes(expected);
+    const matches = (0, session_events_1.selectEffectiveSessionEvents)(events).filter((event) => (event.role === "user"
+        && event.content === userMessage
+        && event.provenance?.captureKind === "live"
+        && (precommittedIngress
+            ? ((event.id === precommittedIngress.eventId && carriesReference(event, precommittedIngress.reference))
+                || (!existingEventIds.has(event.id) && carriesReference(event, precommittedIngress.reference)))
+            : !existingEventIds.has(event.id) && (!reference || carriesReference(event, reference)))));
+    return matches.length === 1 ? matches[0].id : undefined;
+}
+function rawSessionEvents(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return [];
+    const record = value;
+    return record.version === 2 && Array.isArray(record.events) ? record.events : [];
+}
+// What the agent said in a replied-to message: the settle answer it delivered, else its text.
+// Only the agent's own messages are quoted; a control card or notice is not something it asked.
+function spokenText(event) {
+    if (event?.role !== "assistant")
+        return "";
+    for (const call of event.toolCalls) {
+        if (call.function.name !== "settle")
+            continue;
+        try {
+            const answer = JSON.parse(call.function.arguments).answer;
+            if (typeof answer === "string" && answer.trim())
+                return answer.trim().slice(0, 1200);
+        }
+        catch { /* a malformed settle names nothing */ }
+    }
+    return typeof event.content === "string" ? event.content.trim().slice(0, 1200) : "";
+}
+function exactProjectedIngressMessage(existing, messages, eventId, nativeValue) {
+    if (!nativeValue || typeof nativeValue !== "object" || Array.isArray(nativeValue))
+        return null;
+    const native = nativeValue;
+    if (native.version !== 2 || !native.projection || typeof native.projection !== "object" || Array.isArray(native.projection))
+        return null;
+    const projection = native.projection;
+    if (!Array.isArray(projection.eventIds))
+        return null;
+    // Authorization must inspect stored IDs before a reader filters unresolved entries.
+    const projectionIds = projection.eventIds.length > 0
+        ? projection.eventIds
+        : projection.trimmed === true ? [] : existing.projectionEventIds;
+    const eventsById = new Map(existing.events.map((event) => [event.id, event]));
+    if (eventsById.size !== existing.events.length)
+        return null;
+    const seenProjectionIds = new Set();
+    const effectiveIds = new Set((0, session_events_1.selectEffectiveSessionEvents)(existing.events).map((event) => event.id));
+    const projectedEvents = [];
+    for (const projectedId of projectionIds) {
+        if (typeof projectedId !== "string" || !projectedId.trim() || seenProjectionIds.has(projectedId))
+            return null;
+        const event = eventsById.get(projectedId);
+        if (!event)
+            return null;
+        seenProjectionIds.add(projectedId);
+        if (effectiveIds.has(event.id))
+            projectedEvents.push(event);
+    }
+    if (projectionIds.filter((projectedId) => projectedId === eventId).length !== 1)
+        return null;
+    const projectedUsers = projectedEvents.filter((event) => event.role === "user");
+    const providerUsers = messages.filter((message) => message.role === "user");
+    if (projectedUsers.at(-1)?.id !== eventId || projectedUsers.length !== providerUsers.length)
+        return null;
+    return providerUsers.at(-1);
+}
+function currentTurnEventView(events, existingEventIds, userMessage, precommittedIngress, ingressRelations) {
+    const eventIds = new Set();
+    let previousSequence = 0;
+    for (const event of events) {
+        if (!event || typeof event !== "object" || typeof event.id !== "string" || !event.id.trim() || eventIds.has(event.id) || !Number.isSafeInteger(event.sequence) || event.sequence <= previousSequence)
+            return null;
+        eventIds.add(event.id);
+        previousSequence = event.sequence;
+    }
+    const ingressEventId = currentIngressEventId(events, existingEventIds, userMessage, precommittedIngress, ingressRelations);
+    if (!ingressEventId)
+        return null;
+    const ingressIndex = events.findIndex((event) => event.id === ingressEventId);
+    if (events.some((event, eventIndex) => eventIndex > ingressIndex && existingEventIds.has(event.id)))
+        return null;
+    const coordinates = newOutwardCoordinates(events, existingEventIds, ingressIndex);
+    const newestAssistantIndex = events.findLastIndex((event, eventIndex) => eventIndex > ingressIndex && event.role === "assistant");
+    const terminal = coordinates.findLast((coordinate) => coordinate.eventIndex === newestAssistantIndex);
+    return { coordinates, ...(terminal ? { terminal } : {}) };
+}
+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.
+ */
+/**
+ * What an outward sense says when a turn errors and provider failover has nothing to say.
+ * Such turns used to end in silence: the owner saw no reply, prodded, and later got
+ * the late answer followed by a greeting to a prod (D-004); the step-limit stop was the
+ * observed cause (D-007). The engine still refuses to answer without evidence.
+ */
+function erroredTurnReply(errorMessage) {
+    return /iteration limit exhausted/u.test(errorMessage ?? "")
+        ? "I hit my step limit in the middle of that job and couldn't finish it. Tell me to continue and I'll pick up from where I stopped."
+        : "I couldn't finish that one: something went wrong before I had an answer. Ask me again and I'll retry.";
+}
+async function runSenseTurn(options) {
+    options = { ...options, ...(options.shepherdSession ? { shepherdSession: Object.freeze({ ...options.shepherdSession }) } : {}) };
+    return (0, turn_execution_lease_1.withTurnExecutionLease)(async () => {
+        const owner = Object.freeze({ agentName: options.agentName, agentRoot: (0, identity_1.getAgentRoot)(options.agentName) });
+        (0, identity_1.setAgentName)(owner.agentName);
+        try {
+            return await runSenseTurnExclusive(options, owner);
+        }
+        finally {
+            if (options.runtimeMcpServers && !options.disableTools) {
+                await releaseRuntimeMcpServersAfterTurn(owner);
+            }
+        }
+    });
+}
+async function runSenseTurnExclusive(options, owner) {
+    const { channel, sessionKey, friendId } = options;
+    const { agentName, agentRoot } = owner;
+    // Only the A2A server writes the delegated-command banner, in front of a command it admitted (its body is shielded there). On every
+    // other turn, on any channel, a typed banner is marked as the sender's own words. A precommitted ingress is already stored verbatim.
+    const userMessage = options.precommittedIngress || options.toolContext?.delegatedCommand ? options.userMessage : (0, delegated_command_1.shieldDelegatedBanner)(options.userMessage);
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.shared_turn_start",
+        message: "shared turn runner starting",
+        meta: { agentName, channel, sessionKey, friendId },
+    });
+    // Resolve context
+    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 = options.disableTools
+        ? undefined
+        : await (0, mcp_manager_1.getSharedMcpManager)({ ...owner, runtimeServers: options.runtimeMcpServers }) ?? undefined;
+    // Session path and loading
+    const ephemeralRoot = options.disablePersistence
+        ? fs.mkdtempSync(path.join(os.tmpdir(), "ouro-observe-only-"))
+        : null;
+    const sessionDir = ephemeralRoot ?? path.join(agentRoot, "state", "sessions", friendId, channel);
+    fs.mkdirSync(sessionDir, { recursive: true });
+    const sessPath = ephemeralRoot
+        ? path.join(ephemeralRoot, "session.json")
+        : getSenseSessionPath(agentName, friendId, channel, sessionKey, agentRoot);
+    const reportedSessionPath = ephemeralRoot ? undefined : sessPath;
+    const runWithLease = options._withSessionTurnLease ?? session_transaction_1.withSessionTurnLease;
+    try {
+        return await runWithLease(sessPath, async (sessionTurnLease) => {
+            const baseSession = (0, session_transaction_1.readSessionTransaction)(sessPath, sessionTurnLease);
+            const baseSessionRevision = baseSession.revision;
+            const existing = options.disablePersistence ? undefined : (0, context_1.loadSession)(sessPath);
+            const precommittedIngressEvent = options.precommittedIngress
+                ? existing?.events?.find((candidate) => candidate.id === options.precommittedIngress.eventId)
+                : undefined;
+            if (options.precommittedIngress) {
+                const latestUserEvent = (0, session_events_1.selectEffectiveSessionEvents)(existing?.events ?? []).filter((candidate) => candidate.role === "user").at(-1);
+                if (!precommittedIngressEvent || precommittedIngressEvent !== latestUserEvent || precommittedIngressEvent.role !== "user" || precommittedIngressEvent.content !== userMessage
+                    || !precommittedIngressEvent.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) ?? []);
+            const existingStructuredOutputIds = new Set(existing?.structuredOutputs?.map((output) => output.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, options.disableTools ? { tools: [], hardDisableTools: true } : {}, undefined)),
+                    }];
+            if (options.shepherdSession) {
+                // Replace rather than accumulate context as the conversation reloads. It is bounded
+                // metadata, not a human instruction, and focus changes cannot alter its stable UUID.
+                const marker = "[Ouro Shepherd terminal context]";
+                const system = sessionMessages.find(message => message.role === "system");
+                if (system && typeof system.content === "string") {
+                    system.content = system.content.split(`\n${marker}`)[0] + `\n${marker}\n${JSON.stringify(options.shepherdSession)}\nUse this exact UUID for shepherd_read/shepherd_send. If gone, fail explicitly; never substitute a short ref. This locator grants no authority.`;
+                }
+            }
+            const replyToEventId = precommittedIngressEvent?.relations.replyToEventId ?? options.ingressRelations?.replyToEventId;
+            const matchedReplyText = spokenText(existing?.events?.find((event) => event.id === replyToEventId));
+            const fallbackReplyText = options.replyingTo?.text.trim().slice(0, 1200) ?? "";
+            const repliedTo = matchedReplyText
+                ? { text: matchedReplyText, author: "agent" }
+                : fallbackReplyText ? { text: fallbackReplyText, author: options.replyingTo.author } : undefined;
+            if (precommittedIngressEvent) {
+                const projectedIngress = exactProjectedIngressMessage(existing, sessionMessages, precommittedIngressEvent.id, baseSession.value);
+                if (!projectedIngress || projectedIngress.role !== "user" || projectedIngress.content !== userMessage)
+                    throw new Error("shared turn precommitted ingress is absent from the provider projection");
+                (0, session_events_1.stampIngressRelations)(projectedIngress, {
+                    replyToEventId: precommittedIngressEvent.relations.replyToEventId,
+                    threadRootEventId: precommittedIngressEvent.relations.threadRootEventId,
+                    references: precommittedIngressEvent.relations.references,
+                });
+                if (repliedTo)
+                    (0, orientation_frame_1.stampReplyingToText)(projectedIngress, repliedTo.text, repliedTo.author);
+            }
+            // 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 terminalErrorMessage;
+            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 emitFrontendEvent = (event) => {
+                options.frontendEventSink?.onEvent(event);
+            };
+            const deliverPending = async (kind, optionsForDelivery) => {
+                const text = stripThinkBlocks(pendingResponseText);
+                pendingResponseText = "";
+                if (!text)
+                    return undefined;
+                const delivery = { kind, text };
+                const attempt = { kind, text, delivered: false };
+                const attemptIndex = deliveryAttempts.length;
+                deliveryAttempts.push(attempt);
+                try {
+                    await options.deliverySink?.onDelivery(delivery);
+                    attempt.delivered = true;
+                    deliveries.push(delivery);
+                    commitResponseText(text);
+                    emitFrontendEvent({ type: "assistant_delivery", data: { kind, 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);
+                }
+                return attemptIndex;
+            };
+            /* 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;
+                    emitFrontendEvent({ type: "model_started", data: {} });
+                },
+                onModelStreamStart: () => emitFrontendEvent({ type: "model_stream_started", data: {} }),
+                onTextChunk: (chunk) => {
+                    pendingResponseText += chunk;
+                    emitFrontendEvent({ type: "text_delta", data: { text: chunk } });
+                },
+                onReasoningChunk: (chunk) => {
+                    hadReasoningChunk = true;
+                    emitFrontendEvent({ type: "reasoning_delta", data: { text: chunk } });
+                },
+                onToolStart: (name, args) => {
+                    toolInvocationCount += 1;
+                    if (options.turnMetricsObserver)
+                        options.turnMetricsObserver.toolInvocationCount += 1;
+                    emitFrontendEvent({ type: "tool_started", data: { name, args } });
+                },
+                onToolEnd: (name, _summary, success) => {
+                    if (name === "settle" && success)
+                        terminalDeliveryKind = "settle";
+                    emitFrontendEvent({ type: "tool_completed", data: { name, summary: _summary, success } });
+                },
+                onError: (error, severity) => {
+                    if (severity === "terminal")
+                        terminalErrorMessage = error.message;
+                    emitFrontendEvent({ type: "error", data: { message: error.message, severity } });
+                },
+                onClearText: () => {
+                    pendingResponseText = "";
+                    emitFrontendEvent({ type: "text_cleared", data: {} });
+                },
+                flushNow: async () => { await 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);
+                if (repliedTo)
+                    (0, orientation_frame_1.stampReplyingToText)(userMsg, repliedTo.text, repliedTo.author);
+                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,
+                signal: options.signal,
+                provider: resolverParams.provider,
+                externalId: resolverParams.externalId,
+                tenantId: resolverParams.tenantId,
+                enforceTrustGate: trust_gate_1.enforceTrustGate,
+                drainPending: options.disablePersistence ? () => [] : pending_1.drainPending,
+                runAgentOptions: {
+                    mcpManager,
+                    ...(options.disableTools ? { tools: [], hardDisableTools: true } : {}),
+                    ...(options.approvalCoordinatorFactory && !options.disablePersistence ? { approvalCoordinator: options.approvalCoordinatorFactory({ sessionPath: sessPath, baseSessionRevision }) } : {}),
+                    ...(options.latencyMode === "live" ? { skipKeptNotes: true } : {}),
+                    ...(options.orientationFrame ? { orientationFrame: options.orientationFrame } : {}),
+                    toolContext: {
+                        signin: async () => undefined,
+                        ...(options.toolContext ? options.toolContext : {}),
+                        agentName,
+                        agentRoot,
+                        currentUserMessage: userMessage,
+                        ...(options.shepherdSession ? { currentShepherdSurface: Object.freeze({ ...options.shepherdSession }) } : {}),
+                    },
+                },
+                ...(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;
+                    if (options.disablePersistence)
+                        return;
+                    persistPromise = (0, context_2.deferPostTurnPersist)(sessionPathArg, prepared, usage, state);
+                },
+                /* v8 ignore stop */
+                accumulateFriendTokens: options.disablePersistence ? async () => undefined : 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: reportedSessionPath,
+                    turnOutcome: turnResult.turnOutcome ?? "blocked",
+                };
+            }
+            if (turnResult.turnOutcome === "aborted") {
+                pendingResponseText = "";
+                if (persistPromise)
+                    await persistPromise;
+                return {
+                    response: "",
+                    ponderDeferred: false,
+                    deliveries,
+                    deliveryFailures,
+                    providerInvocationCount,
+                    toolInvocationCount,
+                    sessionPath: reportedSessionPath,
+                    turnOutcome: "aborted",
+                };
+            }
+            if (turnResult.turnOutcome === "suspended") {
+                if (!turnResult.suspension)
+                    throw new Error("suspended shared turn omitted durable approval suspension");
+                pendingResponseText = "";
+                return {
+                    response: "",
+                    ponderDeferred: false,
+                    deliveries,
+                    deliveryFailures,
+                    providerInvocationCount,
+                    toolInvocationCount,
+                    sessionPath: reportedSessionPath,
+                    turnOutcome: "suspended",
+                    suspension: turnResult.suspension,
+                };
+            }
+            const persistedEvents = persistPromise ? await persistPromise : [];
+            const terminalEvents = persistedEvents.length > 0
+                ? persistedEvents
+                : rawSessionEvents((0, session_transaction_1.readSessionTransaction)(sessPath, sessionTurnLease).value);
+            const eventView = currentTurnEventView(terminalEvents, existingEventIds, userMessage, options.precommittedIngress, options.ingressRelations);
+            let finalDeliveryKind = terminalDeliveryKind;
+            const acceptedTerminalOutcome = turnResult.turnOutcome === "settled" || turnResult.turnOutcome === "blocked";
+            const failoverText = turnResult.turnOutcome === "errored"
+                ? turnResult.failoverMessage?.trim() || (channel === "inner" ? undefined : erroredTurnReply(terminalErrorMessage))
+                : undefined;
+            const expectsOutwardResponse = acceptedTerminalOutcome || turnResult.turnOutcome === "command" || Boolean(failoverText);
+            let finalCausalCoordinate;
+            if (acceptedTerminalOutcome) {
+                const completionText = stripThinkBlocks(turnResult.completion?.answer ?? "");
+                let authoritativeText = completionText;
+                if (!authoritativeText && eventView?.terminal) {
+                    authoritativeText = eventView.terminal.text;
+                    finalDeliveryKind = eventView.terminal.kind;
+                }
+                if (eventView?.terminal?.kind === finalDeliveryKind && eventView.terminal.text === authoritativeText)
+                    finalCausalCoordinate = eventView.terminal;
+                const terminalAlreadyDelivered = finalCausalCoordinate
+                    ? alignedDeliveryCoordinates(eventView, deliveryAttempts).includes(finalCausalCoordinate)
+                    : false;
+                pendingResponseText = authoritativeText && !terminalAlreadyDelivered ? authoritativeText : "";
+            }
+            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 = "";
+            }
+            if (persistPromise && options.frontendEventSink && !options.disablePersistence) {
+                const currentStructuredOutputs = (0, context_1.loadSession)(sessPath)?.structuredOutputs ?? [];
+                for (const output of currentStructuredOutputs) {
+                    if (!existingStructuredOutputIds.has(output.id)) {
+                        emitFrontendEvent({ type: "structured_output", data: { output } });
+                    }
+                }
+            }
+            const finalDeliveryAttemptIndex = await deliverPending(finalDeliveryKind, { throwOnError: false });
+            const ponderDeferred = false;
+            // Build response
+            let finalResponse;
+            const finalDeliveryAttempt = finalDeliveryAttemptIndex === undefined ? undefined : deliveryAttempts[finalDeliveryAttemptIndex];
+            const responseDeliveryFailure = finalDeliveryAttempt && !finalDeliveryAttempt.delivered ? deliveryFailures.at(-1) : undefined;
+            const responseCausalSessionEventId = finalDeliveryAttempt && !finalDeliveryAttempt.delivered ? finalCausalCoordinate?.eventId : undefined;
+            if (committedResponseText.length === 0) {
+                if (!expectsOutwardResponse) {
+                    finalResponse = "";
+                }
+                else {
+                    const emptyFallback = options.emptyResponseFallback?.();
+                    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,
+                ...(responseDeliveryFailure ? { responseDeliveryFailure } : {}),
+                providerInvocationCount,
+                toolInvocationCount,
+                sessionPath: reportedSessionPath,
+                turnOutcome: turnResult.turnOutcome,
+                ...(deliveries.length > 0 ? { causalSessionEventIds: causalSessionEventIds(eventView, deliveryAttempts, finalDeliveryAttemptIndex, finalCausalCoordinate) } : {}),
+                ...(responseCausalSessionEventId ? { responseCausalSessionEventId } : {}),
+            };
+        });
+    }
+    finally {
+        if (ephemeralRoot) {
+            for (const entry of fs.readdirSync(ephemeralRoot, { withFileTypes: true })) {
+                if (!entry.isFile() && !entry.isSymbolicLink()) {
+                    throw new Error(`observe-only session cleanup found unexpected entry: ${entry.name}`);
+                }
+                fs.unlinkSync(path.join(ephemeralRoot, entry.name));
+            }
+            fs.rmdirSync(ephemeralRoot);
+        }
+    }
+}