@ouro.bot/cli 0.1.0-alpha.732 → 0.1.0-alpha.734

package/dist/heart/core.js

@@ -1,5 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_PROVIDER_ITERATIONS = void 0;
+exports.validateToolCallBatchAtProductionBoundary = validateToolCallBatchAtProductionBoundary;
 exports.createProviderRegistry = createProviderRegistry;
 exports.resetProviderRuntime = resetProviderRuntime;
 exports.getModel = getModel;
@@ -24,6 +26,20 @@ const friends_1 = require("@ouro.bot/friends");
 const tools_2 = require("../repertoire/tools");
 const streaming_1 = require("./streaming");
 const runtime_1 = require("../nerves/runtime");
+function validateToolCallBatchAtProductionBoundary(calls, activeTools) {
+    const callIdCounts = new Map();
+    for (const call of calls)
+        callIdCounts.set(call.id, (callIdCounts.get(call.id) ?? 0) + 1);
+    return calls.map((call) => {
+        if (callIdCounts.get(call.id) !== 1)
+            return { call, error: "duplicate tool call id" };
+        const advertised = activeTools.find((tool) => tool.function.name === call.name);
+        if (!advertised || !advertised.function.parameters || typeof advertised.function.parameters !== "object")
+            return { call, error: "tool was not advertised with a valid argument schema" };
+        const validated = (0, tool_arguments_1.validateAdvertisedToolArguments)(call.arguments, advertised.function.parameters);
+        return validated.ok ? { call, advertised, validated: validated.value } : { call, error: validated.reason };
+    });
+}
 const context_1 = require("../mind/context");
 const prompt_budget_1 = require("../mind/prompt-budget");
 const prompt_1 = require("../mind/prompt");
@@ -34,6 +50,7 @@ const azure_1 = require("./providers/azure");
 const minimax_1 = require("./providers/minimax");
 const openai_codex_1 = require("./providers/openai-codex");
 const github_copilot_1 = require("./providers/github-copilot");
+const openai_compatible_1 = require("./providers/openai-compatible");
 const orientation_frame_1 = require("./orientation-frame");
 const identity_2 = require("./identity");
 const socket_client_1 = require("./daemon/socket-client");
@@ -109,6 +126,9 @@ function createProviderRegistry() {
                     return (0, openai_codex_1.createOpenAICodexProviderRuntime)(model, providerConfig);
                 case "github-copilot":
                     return (0, github_copilot_1.createGithubCopilotProviderRuntime)(model, providerConfig);
+                case "openai-compatible":
+                case "openai-compatible-gemini":
+                    return (0, openai_compatible_1.createOpenAICompatibleProviderRuntime)(provider, model, providerConfig);
             }
         },
     };
@@ -198,6 +218,8 @@ function getProviderDisplayLabel(facing = "human") {
         "openai-codex": () => `openai codex (${model})`,
         /* v8 ignore next -- branch: tested via display label unit test @preserve */
         "github-copilot": () => `github copilot (${model})`,
+        "openai-compatible": () => `z.ai openai-compatible (${model})`,
+        "openai-compatible-gemini": () => `gemini openai-compatible (${model})`,
     };
     return providerLabelBuilders[provider]();
 }
@@ -247,6 +269,7 @@ function createHabitCallbackBuffer(callbacks) {
 function createFinalOnlyTextBuffer(callbacks) {
     return createCallbackBuffer(callbacks, "text-only");
 }
+exports.MAX_PROVIDER_ITERATIONS = 8;
 function continuationCallbacks(callbacks, text) {
     const noop = () => undefined;
     return {
@@ -356,18 +379,6 @@ function hasFreshPendingWork(options) {
         && message.content.trim().length > 0);
 }
 const HABIT_CONTROL_TOOLS = new Set(["rest", "ponder", "observe"]);
-function habitToolArgs(call) {
-    try {
-        const parsed = JSON.parse(call.arguments);
-        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-            return { ok: false, reason: `habit tool '${call.name}' arguments must be a JSON object` };
-        }
-        return { ok: true, args: parsed };
-    }
-    catch {
-        return { ok: false, reason: `habit tool '${call.name}' has malformed JSON arguments` };
-    }
-}
 function highRiskExternalMutation(profile) {
     if (profile.risk !== "high")
         return null;
@@ -383,8 +394,8 @@ function recordBlockedHabitSurfaceAttempts(habitSession, toolCalls, reason) {
     for (const call of toolCalls) {
         if (call.name !== "send_message" && call.name !== "surface")
             continue;
-        const parsed = habitToolArgs(call);
-        const args = parsed.ok ? parsed.args : {};
+        // The canonical pre-batch schema gate guarantees object arguments here.
+        const args = JSON.parse(call.arguments);
         habitSession.recordSurfaceAttempt({
             recipient: String(args.friendId ?? args.delegationId ?? "unknown"),
             channel: String(args.channel ?? call.name),
@@ -395,10 +406,7 @@ function recordBlockedHabitSurfaceAttempts(habitSession, toolCalls, reason) {
         });
     }
 }
-async function habitToolBatchBlockReason(habitSession, toolCalls, delegatedOrigins, activeToolNames, noSend) {
-    if (noSend && toolCalls.some((call) => call.name === "ponder")) {
-        return "habit tool 'ponder' cannot create continuations under immutable no-send authority";
-    }
+async function habitToolBatchBlockReason(habitSession, toolCalls, delegatedOrigins) {
     if (!habitSession)
         return null;
     const granted = new Set(habitSession.toolPolicy.grantedTools);
@@ -406,16 +414,13 @@ async function habitToolBatchBlockReason(habitSession, toolCalls, delegatedOrigi
     for (const call of toolCalls) {
         if (denied.has(call.name))
             return `habit tool '${call.name}' is denied by this habit session`;
-        if (!activeToolNames.has(call.name))
-            return `habit tool '${call.name}' was not advertised to this model turn`;
         if (HABIT_CONTROL_TOOLS.has(call.name))
             continue;
         if (!granted.has(call.name))
             return `habit tool '${call.name}' was not granted to this habit session`;
-        const parsed = habitToolArgs(call);
-        if (!parsed.ok)
-            return parsed.reason;
-        const riskProfile = (0, tools_1.riskProfileForToolName)(call.name, parsed.args);
+        // The canonical pre-batch schema gate guarantees object arguments here.
+        const args = JSON.parse(call.arguments);
+        const riskProfile = (0, tools_1.riskProfileForToolName)(call.name, args);
         if (!riskProfile)
             return `habit tool '${call.name}' does not have a known executable risk profile`;
         const externalMutation = highRiskExternalMutation(riskProfile);
@@ -427,7 +432,7 @@ async function habitToolBatchBlockReason(habitSession, toolCalls, delegatedOrigi
                 agentRoot: (0, identity_2.getAgentRoot)(),
                 envelope: habitSession.permissionEnvelope,
                 toolName: call.name,
-                args: parsed.args,
+                args,
                 friendStore: habitSession.friendStore,
                 delegatedOrigins,
             });
@@ -441,7 +446,7 @@ async function habitToolBatchBlockReason(habitSession, toolCalls, delegatedOrigi
  *  BlueBubbles is final-only: its adapter owns one accepted visibility boundary.
  *  The private runtime has `ponder`; MCP returns synchronously; mail is batch. */
 function isChatStyleChannel(channel) {
-    return channel === "cli" || channel === "teams" || channel === "voice";
+    return (0, friends_1.getChannelCapabilities)(channel).chatStyle;
 }
 function bindCurrentIngressEvidenceLocator(toolList, evidence) {
     if (!evidence
@@ -493,13 +498,8 @@ function parseSettlePayload(argumentsText) {
     return { answer, intent };
 }
 function parsePonderPayload(argumentsText) {
-    try {
-        const parsed = JSON.parse(argumentsText);
-        return parsed && typeof parsed === "object" ? parsed : {};
-    }
-    catch {
-        return {};
-    }
+    // The canonical pre-batch schema gate guarantees a valid object payload.
+    return JSON.parse(argumentsText);
 }
 function parseSuccessCriteria(raw) {
     if (typeof raw !== "string")
@@ -885,7 +885,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
         generatedMessages.push(...structuredClone(next));
     };
     const facing = (0, friends_1.channelToFacing)(channel);
-    let providerRuntime = await getProviderRuntime(facing);
+    let providerRuntime = options?.providerRuntimeOverride ?? await getProviderRuntime(facing);
     const provider = providerRuntime.id;
     const toolChoiceRequired = options?.toolChoiceRequired ?? true;
     const traceId = options?.traceId;
@@ -1039,6 +1039,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
     // a ponder packet created the return obligation in this turn.
     let noToolCallRetries = 0;
     const NO_TOOL_CALL_MAX_RETRIES = 2;
+    let providerIterations = 0;
     const toolLoopState = (0, tool_loop_1.createToolLoopState)();
     const toolFrictionLedger = (0, tool_friction_1.createToolFrictionLedger)();
     const finishTerminalProviderError = (error, classification) => {
@@ -1126,7 +1127,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
         const filteredBaseTools = isPrivateRuntimeChannel
             ? baseTools.filter((t) => privateRuntimeHabitCanSendMessage || t.function.name !== "send_message")
             : baseTools;
-        const activeTools = [
+        const ordinaryActiveTools = [
             ...filteredBaseTools,
             ...(augmentedToolContext?.noSend === true ? [] : [tools_1.ponderTool]),
             ...(isPrivateRuntimeChannel && privateRuntimeHabitCanSurface ? [tools_2.surfaceToolDef] : []),
@@ -1135,6 +1136,15 @@ async function runAgent(messages, callbacks, channel, signal, options) {
             ...(!isPrivateRuntimeChannel ? [tools_1.settleTool] : []),
             ...(isChatStyleChannel(channel ?? "") ? [tools_1.speakTool] : []),
         ];
+        const activeTools = options?.toolProfile === "sanctuary-health-private"
+            ? (() => {
+                const sendTools = baseTools.filter((tool) => tool.function.name === "send_message");
+                if (channel !== "inner" || sendTools.length !== 1 || baseTools.length !== 1) {
+                    throw new Error("sanctuary-health-private requires inner channel with exactly one canonical send_message definition");
+                }
+                return [sendTools[0], tools_1.restTool];
+            })()
+            : ordinaryActiveTools;
         const activeToolNames = new Set(activeTools.map((tool) => tool.function.name));
         const steeringFollowUps = options?.drainSteeringFollowUps?.() ?? [];
         if (steeringFollowUps.length > 0) {
@@ -1278,6 +1288,10 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                 continue;
             }
             const result = attempt.value;
+            providerIterations += 1;
+            if (providerIterations === exports.MAX_PROVIDER_ITERATIONS && result.toolCalls.length > 0) {
+                throw new Error(`provider iteration limit exhausted at response ${exports.MAX_PROVIDER_ITERATIONS} before tool execution`);
+            }
             const streamCallbackBuffer = turnCallbackBufferRef.current;
             turnCallbackBufferRef.current = null;
             if (result.settleFinalization && !result.settleFinalization.ok) {
@@ -1454,7 +1468,54 @@ async function runAgent(messages, callbacks, channel, signal, options) {
             else {
                 // Reset the retry counter on any successful tool call.
                 noToolCallRetries = 0;
-                const habitBlockReason = await habitToolBatchBlockReason(habitSession, result.toolCalls, augmentedToolContext?.delegatedOrigins, activeToolNames, augmentedToolContext?.noSend === true);
+                const preCallMessages = structuredClone(messages.filter((message) => message.role !== "system"));
+                const validatedCalls = validateToolCallBatchAtProductionBoundary(result.toolCalls, activeTools);
+                const invalidCall = validatedCalls.find((entry) => "error" in entry);
+                if (invalidCall) {
+                    await streamCallbackBuffer?.flush();
+                    pushGenerated(msg);
+                    const unadvertisedCall = validatedCalls.find((entry) => !activeToolNames.has(entry.call.name));
+                    for (const entry of validatedCalls) {
+                        const detail = "error" in entry ? entry.error : "another call in this batch had invalid arguments";
+                        const rejection = unadvertisedCall
+                            ? `rejected: ${entry.call.name} was not advertised for this channel; no handler was executed.`
+                            : `invalid tool arguments: ${detail}`;
+                        pushGenerated({ role: "tool", tool_call_id: entry.call.id, content: rejection });
+                        providerRuntime.appendToolOutput(entry.call.id, rejection);
+                        options?.toolBoundaryObserver?.({
+                            name: entry.call.name,
+                            reason: activeToolNames.has(entry.call.name) ? "invalid_arguments" : "profile_excluded",
+                            globallyResolvable: typeof (0, tools_1.resolveToolDefinition)(entry.call.name)?.handler === "function",
+                            invoked: false,
+                            sideEffect: false,
+                        });
+                    }
+                    if (unadvertisedCall) {
+                        (0, runtime_1.emitNervesEvent)({
+                            level: "warn",
+                            component: "engine",
+                            event: "engine.unadvertised_tool_blocked",
+                            message: "blocked an unadvertised tool call before batch execution",
+                            meta: { channel: String(channel), toolName: unadvertisedCall.call.name },
+                        });
+                    }
+                    else {
+                        (0, runtime_1.emitNervesEvent)({
+                            level: "warn",
+                            component: "engine",
+                            event: "engine.tool_arguments_rejected",
+                            message: "tool batch rejected before execution because arguments were invalid",
+                            meta: { toolCallId: invalidCall.call.id, toolName: invalidCall.call.name },
+                        });
+                    }
+                    continue;
+                }
+                const validCalls = validatedCalls;
+                const validatedCallArguments = new Map(validCalls.map((entry) => [
+                    entry.call,
+                    entry.validated.arguments,
+                ]));
+                const habitBlockReason = await habitToolBatchBlockReason(habitSession, result.toolCalls, augmentedToolContext?.delegatedOrigins);
                 if (habitBlockReason) {
                     streamCallbackBuffer?.discard();
                     recordBlockedHabitSurfaceAttempts(habitSession, result.toolCalls, habitBlockReason);
@@ -1480,16 +1541,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                     ? (0, tools_1.resolveToolDefinition)(soleTerminalCall.name)?.terminalProjection
                     : undefined;
                 if (soleTerminalCall && soleTerminalProjection?.mode === "verbatim") {
-                    let terminalArgs = {};
-                    try {
-                        const parsed = JSON.parse(soleTerminalCall.arguments);
-                        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-                            terminalArgs = parsed;
-                        }
-                    }
-                    catch {
-                        // The registered handler owns exact argument validation.
-                    }
+                    const terminalArgs = validatedCallArguments.get(soleTerminalCall);
                     if (soleTerminalProjection.clearBufferedText
                         || callbacks.settleOutputMode === "final_only") {
                         streamCallbackBuffer?.discard();
@@ -1529,13 +1581,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                 }
                 // Check for settle sole call: intercept before tool execution
                 if (isSoleSettle) {
-                    /* v8 ignore next -- defensive: JSON.parse catch for malformed settle args @preserve */
-                    const settleArgs = (() => { try {
-                        return JSON.parse(result.toolCalls[0].arguments);
-                    }
-                    catch {
-                        return {};
-                    } })();
+                    const settleArgs = validatedCallArguments.get(result.toolCalls[0]);
                     callbacks.onToolStart("settle", settleArgs);
                     // Private-runtime attention queue gate: reject settle if items remain
                     const attentionQueue = augmentedToolContext?.delegatedOrigins;
@@ -1627,13 +1673,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                 const isSoleObserve = result.toolCalls.length === 1 && result.toolCalls[0].name === "observe";
                 if (isSoleObserve) {
                     streamCallbackBuffer?.discard();
-                    /* v8 ignore next -- defensive: JSON.parse catch for malformed observe args @preserve */
-                    const observeArgs = (() => { try {
-                        return JSON.parse(result.toolCalls[0].arguments);
-                    }
-                    catch {
-                        return {};
-                    } })();
+                    const observeArgs = validatedCallArguments.get(result.toolCalls[0]);
                     let reason;
                     if (typeof observeArgs?.reason === "string")
                         reason = observeArgs.reason;
@@ -1657,12 +1697,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                 const isSoleRest = result.toolCalls.length === 1 && result.toolCalls[0].name === "rest";
                 if (isSoleRest) {
                     streamCallbackBuffer?.discard();
-                    const restArgs = (() => { try {
-                        return JSON.parse(result.toolCalls[0].arguments);
-                    }
-                    catch {
-                        return {};
-                    } })();
+                    const restArgs = validatedCallArguments.get(result.toolCalls[0]);
                     callbacks.onToolStart("rest", restArgs);
                     // Attention queue gate: reject rest if items remain
                     const attentionQueue = augmentedToolContext?.delegatedOrigins;
@@ -1705,42 +1740,10 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                     done = true;
                     continue;
                 }
-                const preCallMessages = structuredClone(messages.filter((message) => message.role !== "system"));
-                const validatedCalls = options?.approvalCoordinator
-                    ? result.toolCalls.map((call) => {
-                        const advertised = activeTools.find((tool) => tool.function.name === call.name);
-                        if (!advertised || !advertised.function.parameters || typeof advertised.function.parameters !== "object") {
-                            return { call, error: "tool was not advertised with a valid argument schema" };
-                        }
-                        const validated = (0, tool_arguments_1.validateAdvertisedToolArguments)(call.arguments, advertised.function.parameters);
-                        return validated.ok
-                            ? { call, advertised, validated: validated.value }
-                            : { call, error: validated.reason };
-                    })
-                    : null;
-                const invalidApprovalCall = validatedCalls?.find((entry) => "error" in entry);
-                if (invalidApprovalCall) {
-                    await streamCallbackBuffer?.flush();
-                    pushGenerated(msg);
-                    for (const entry of validatedCalls) {
-                        const detail = "error" in entry ? entry.error : "another call in this batch had invalid arguments";
-                        const rejection = `invalid tool arguments: ${detail}`;
-                        pushGenerated({ role: "tool", tool_call_id: entry.call.id, content: rejection });
-                        providerRuntime.appendToolOutput(entry.call.id, rejection);
-                    }
-                    (0, runtime_1.emitNervesEvent)({
-                        level: "warn",
-                        component: "engine",
-                        event: "engine.tool_arguments_rejected",
-                        message: "tool batch rejected before execution because arguments were invalid",
-                        meta: { toolCallId: invalidApprovalCall.call.id, toolName: invalidApprovalCall.call.name },
-                    });
-                    continue;
-                }
-                const approvalCalls = validatedCalls?.map((entry) => ({
+                const approvalCalls = options?.approvalCoordinator ? validCalls.map((entry) => ({
                     ...entry,
                     policy: (0, tools_1.approvalPolicyForToolName)(entry.call.name, entry.validated.arguments),
-                })) ?? [];
+                })) : [];
                 const protectedCall = approvalCalls.find((entry) => entry.policy.kind === "required");
                 if (protectedCall && result.toolCalls.length !== 1) {
                     streamCallbackBuffer?.discard();
@@ -1816,21 +1819,6 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                 for (const tc of result.toolCalls) {
                     if (signal?.aborted)
                         break;
-                    if (tc.name === "speak" && !activeToolNames.has("speak")) {
-                        const rejection = "rejected: speak was not advertised for this channel; no outward message was sent.";
-                        callbacks.onToolStart(tc.name, {});
-                        callbacks.onToolEnd(tc.name, "", false);
-                        pushGenerated({ role: "tool", tool_call_id: tc.id, content: rejection });
-                        providerRuntime.appendToolOutput(tc.id, rejection);
-                        (0, runtime_1.emitNervesEvent)({
-                            level: "warn",
-                            component: "engine",
-                            event: "engine.unadvertised_speak_blocked",
-                            message: "blocked an unadvertised speak tool call",
-                            meta: { channel: String(channel) },
-                        });
-                        continue;
-                    }
                     // Reject sole-call tools when mixed with other tool calls
                     const terminalProjection = (0, tools_1.resolveToolDefinition)(tc.name)?.terminalProjection;
                     const soleCallRejection = SOLE_CALL_REJECTION[tc.name]
@@ -1842,13 +1830,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                         providerRuntime.appendToolOutput(tc.id, soleCallRejection);
                         continue;
                     }
-                    let args = {};
-                    try {
-                        args = JSON.parse(tc.arguments);
-                    }
-                    catch {
-                        /* ignore */
-                    }
+                    const args = validatedCallArguments.get(tc);
                     if (tc.name === "send_message" && args.friendId === "self") {
                         const latestUserText = latestUserMessageText(messages);
                         if (!isPrivateRuntimeChannel && looksLikePrivateReturnRequest(latestUserText)) {
@@ -1863,12 +1845,9 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                         sawSendMessageSelf = true;
                     }
                     if (tc.name === "speak") {
-                        let speakArgs = {};
-                        try {
-                            speakArgs = JSON.parse(tc.arguments);
-                        }
-                        catch { /* malformed */ }
-                        const speakMessage = typeof speakArgs.message === "string" ? speakArgs.message : "";
+                        // The canonical pre-batch schema gate guarantees a required string.
+                        const speakArgs = JSON.parse(tc.arguments);
+                        const speakMessage = speakArgs.message;
                         const argSummary = (0, tools_1.summarizeArgs)("speak", { message: speakMessage });
                         callbacks.onToolStart("speak", { message: speakMessage });
                         if (speakMessage.trim().length === 0) {
@@ -2024,7 +2003,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                                     }
                                 }
                             }
-                            else if (action === "revise") {
+                            else {
                                 const packetId = typeof parsedArgs.packet_id === "string" ? parsedArgs.packet_id.trim() : "";
                                 const kind = parsedArgs.kind;
                                 const objective = typeof parsedArgs.objective === "string" ? parsedArgs.objective.trim() : "";
@@ -2045,9 +2024,6 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                                     : null;
                                 resultAction = "revised";
                             }
-                            else {
-                                throw new Error("ponder requires action=create or revise.");
-                            }
                             if (returnObligationId) {
                                 for (const token of extractPrivateReturnHeldTokens(privateReturnSourceRequest)) {
                                     privateReturnHeldTokens.add(token);
@@ -2110,6 +2086,15 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                         success = false;
                         augmentedToolContext?.habitSession?.recordError?.(toolResult);
                     }
+                    const resolvedRiskProfile = (0, tools_1.resolveToolDefinition)(tc.name)?.riskProfile;
+                    const toolRiskProfile = typeof resolvedRiskProfile === "function" ? resolvedRiskProfile(args) : resolvedRiskProfile;
+                    options?.toolBoundaryObserver?.({
+                        name: tc.name,
+                        reason: "dispatched",
+                        globallyResolvable: typeof (0, tools_1.resolveToolDefinition)(tc.name)?.handler === "function",
+                        invoked: true,
+                        sideEffect: success && toolRiskProfile?.mutates !== "none",
+                    });
                     toolResult = (0, tool_friction_1.rewriteToolResultForModel)(tc.name, toolResult, toolFrictionLedger);
                     (0, tool_loop_1.recordToolOutcome)(toolLoopState, tc.name, args, toolResult, success);
                     callbacks.onToolEnd(tc.name, (0, tools_1.buildToolResultSummary)(tc.name, args, toolResult, success), success);

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

@@ -93,6 +93,7 @@ const background_operations_1 = require("../background-operations");
 const mail_import_discovery_1 = require("../mail-import-discovery");
 const session_activity_1 = require("../session-activity");
 const target_resolution_1 = require("../target-resolution");
+const sanctuary_scheduler_origin_1 = require("./sanctuary-scheduler-origin");
 const cli_parse_1 = require("./cli-parse");
 const cli_parse_2 = require("./cli-parse");
 const cli_help_1 = require("./cli-help");
@@ -1488,6 +1489,8 @@ function toDaemonCommand(command) {
             noSend: true,
         };
     }
+    if (command.kind === "habit.poke")
+        return (0, sanctuary_scheduler_origin_1.createSanctuarySchedulerFireCommand)(command) ?? command;
     return command;
 }
 function habitProbeJsonResponse(response) {
@@ -2217,7 +2220,7 @@ const DEFAULT_RUNTIME_APPLY_TIMEOUT_MS = 15_000;
 const DEFAULT_RUNTIME_APPLY_POLL_INTERVAL_MS = 500;
 const DEFAULT_DAEMON_STATUS_TIMEOUT_MS = 4_000;
 const DEFAULT_AGENT_RESTART_TIMEOUT_MS = 8_000;
-const CONNECT_PROVIDER_CHOICES = ["openai-codex", "anthropic", "minimax", "azure", "github-copilot"];
+const CONNECT_PROVIDER_CHOICES = ["openai-compatible", "openai-compatible-gemini", "openai-codex", "anthropic", "minimax", "azure", "github-copilot"];
 function hasRuntimeConfigValue(config, key) {
     return readRuntimeConfigString(config, key) !== null;
 }
@@ -2813,6 +2816,7 @@ function enableAgentSense(agent, sense, deps) {
         mail: senses.mail ?? { enabled: false },
         voice: senses.voice ?? { enabled: false },
         a2a: senses.a2a ?? { enabled: false },
+        telegram: senses.telegram ?? { enabled: false },
         [sense]: { ...existing, enabled: true },
     };
     fs.writeFileSync(configPath, `${JSON.stringify(raw, null, 2)}\n`, "utf-8");
@@ -4997,6 +5001,71 @@ async function executeConnectA2A(agent, deps) {
     deps.writeStdout(message);
     return message;
 }
+function parseCanonicalTelegramId(value, label) {
+    const trimmed = value.trim();
+    if (!/^[1-9][0-9]*$/u.test(trimmed)) {
+        throw new Error(`${label} must be a canonical positive decimal string`);
+    }
+    return trimmed;
+}
+async function executeConnectTelegram(agent, deps) {
+    if (agent === "SerpentGuide") {
+        throw new Error("SerpentGuide has no persistent runtime credentials. Connect Telegram on the hatchling agent instead.");
+    }
+    const promptInput = requirePromptInput(deps, "Telegram setup");
+    const promptSecret = requirePromptSecret(deps, "Telegram bot token entry");
+    const botToken = (await promptSecret("Telegram bot token: ")).trim();
+    if (!/^[0-9]+:[A-Za-z0-9_-]+$/u.test(botToken))
+        throw new Error("Telegram bot token has an invalid format");
+    const authorizedUserId = parseCanonicalTelegramId(await promptInput("Authorized Telegram user ID: "), "Telegram authorized user ID");
+    const authorizedChatId = parseCanonicalTelegramId(await promptInput("Authorized private Telegram chat ID: "), "Telegram authorized chat ID");
+    const progress = createHumanCommandProgress(deps, "connect telegram");
+    let stored;
+    try {
+        stored = await runCommandProgressPhase(progress, "saving Telegram setup", async () => {
+            progress.updateDetail("checking existing runtime config");
+            const current = await (0, runtime_credentials_1.refreshRuntimeCredentialConfig)(agent, { preserveCachedOnFailure: true });
+            if (!current.ok && current.reason !== "missing") {
+                throw new Error(`cannot read existing runtime credentials from ${current.itemPath}: ${current.error}`);
+            }
+            progress.updateDetail("storing private Telegram coordinates in the agent vault");
+            return (0, runtime_credentials_1.upsertRuntimeCredentialConfig)(agent, {
+                ...(current.ok ? current.config : {}),
+                telegramBotToken: botToken,
+                telegramAuthorizedUserId: authorizedUserId,
+                telegramAuthorizedChatId: authorizedChatId,
+            }, providerCliNow(deps));
+        }, () => "private Telegram coordinates stored");
+        progress.updateDetail("enabling Telegram in agent.json");
+        enableAgentSense(agent, "telegram", deps);
+    }
+    finally {
+        progress.end();
+    }
+    const syncSummary = pushAgentBundleAfterCliMutation(agent, deps);
+    return writeCapabilityOutcome(deps, {
+        subtitle: `${agent}'s private Telegram sense is configured.`,
+        summary: `Telegram is ready for ${agent}.`,
+        whatChanged: [
+            "Capability: private Telegram sense",
+            `Stored: ${stored.itemPath}`,
+            "agent.json: senses.telegram.enabled = true",
+            "token and numeric IDs were not printed",
+            ...(syncSummary ? [syncSummary] : []),
+        ],
+        nextMoves: ["Run ouro up so the daemon starts the Telegram long poll."],
+        fallbackLines: [
+            `Telegram connected for ${agent}`,
+            "capability: private Telegram sense",
+            `stored: ${stored.itemPath}`,
+            "agent.json: senses.telegram.enabled = true",
+            "token and numeric IDs were not printed",
+            "",
+            "Next: run `ouro up` so the daemon starts the Telegram long poll.",
+            ...(syncSummary ? [syncSummary] : []),
+        ],
+    });
+}
 async function executeConnectWorkbench(agent, deps) {
     const { workbenchMcpCommand, workbenchHasStaleBundleEntry } = readConnectBaySenseFlags(agent, deps);
     const changed = removeWorkbenchMcpRegistration(agent, deps);
@@ -5045,6 +5114,8 @@ async function executeConnect(command, deps) {
         return executeConnectVoice(command.agent, deps);
     if (command.target === "a2a")
         return executeConnectA2A(command.agent, deps);
+    if (command.target === "telegram")
+        return executeConnectTelegram(command.agent, deps);
     if (command.target === "workbench")
         return executeConnectWorkbench(command.agent, deps);
     const progress = createHumanCommandProgress(deps, "connect");
@@ -5417,6 +5488,7 @@ async function executeAuthRun(command, deps) {
             agentName: command.agent,
             provider,
             promptInput: deps.promptInput,
+            promptSecret: deps.promptSecret,
             onProgress: (message) => progress.updateDetail(message),
         });
     }
@@ -6406,7 +6478,7 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
     }
     if (command.kind === "mail.sync-cache") {
         const { runHostedMailCacheSync } = await Promise.resolve().then(() => __importStar(require("../../mailroom/cache-sync-cli")));
-        const text = await runHostedMailCacheSync(command.agent);
+        const text = await runHostedMailCacheSync(command.agent, deps.writeStdout);
         deps.writeStdout(text);
         return text;
     }

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

@@ -445,6 +445,11 @@ const SUBCOMMAND_HELP = {
         usage: "ouro connect a2a [--agent <name>]",
         example: "ouro connect a2a --agent <agent>",
     },
+    "connect telegram": {
+        description: "Connect a private Telegram bot and enable the Telegram sense",
+        usage: "ouro connect telegram [--agent <name>]",
+        example: "ouro connect telegram --agent <agent>",
+    },
     "connect workbench": {
         description: "Verify native Ouro Workbench runtime injection and clean stale bundle entries",
         usage: "ouro connect workbench [--agent <name>]",
@@ -541,7 +546,7 @@ const SUBCOMMAND_HELP = {
         example: "ouro mail backfill-indexes --agent <agent>",
     },
     "mail sync-cache": {
-        description: "Converge the local decrypted search cache against complete hosted Mailroom authority in the foreground.",
+        description: "Converge the local decrypted search cache against stable hosted Mailroom authority in up to three passes, using 20 bounded body-read workers, foreground settlement progress, a 30-second heartbeat, and durable missing-key receipts.",
         usage: "ouro mail sync-cache [--agent <name>]",
         example: "ouro mail sync-cache --agent <agent>",
     },

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

@@ -86,7 +86,7 @@ function extractLaneFlag(args) {
     return { lane: value, rest };
 }
 function isAgentProvider(value) {
-    return value === "azure" || value === "anthropic" || value === "minimax" || value === "openai-codex" || value === "github-copilot";
+    return value === "azure" || value === "anthropic" || value === "minimax" || value === "openai-codex" || value === "github-copilot" || value === "openai-compatible" || value === "openai-compatible-gemini";
 }
 function usage() {
     return [
@@ -103,7 +103,7 @@ function usage() {
         "  ouro -v|--version",
         "  ouro auth [--agent <name>] [--provider <provider>]",
         "  ouro account ensure [--agent <name>] [--owner-email <email> --source <label>|--no-delegated-source] [--rotate-missing-mail-keys]",
-        "  ouro connect [providers|perplexity|embeddings|teams|bluebubbles|mail|voice|a2a|workbench] [--agent <name>] [--owner-email <email> --source <label>|--no-delegated-source] [--rotate-missing-mail-keys]",
+        "  ouro connect [providers|perplexity|embeddings|teams|bluebubbles|mail|voice|a2a|telegram|workbench] [--agent <name>] [--owner-email <email> --source <label>|--no-delegated-source] [--rotate-missing-mail-keys]",
         "  ouro mail import-mbox --file <path> [--owner-email <email>] [--source <label>] [--agent <name>] [--foreground]",
         "  ouro mail backfill-indexes [--agent <name>] [--foreground]",
         "  ouro auth verify [--agent <name>] [--provider <provider>]",
@@ -1035,9 +1035,11 @@ function normalizeConnectTarget(value) {
         return "voice";
     if (value === "a2a" || value === "agent2agent" || value === "agent-to-agent")
         return "a2a";
+    if (value === "telegram")
+        return "telegram";
     if (value === "workbench" || value === "ouro-workbench" || value === "terminal-workbench")
         return "workbench";
-    throw new Error("Usage: ouro connect [providers|perplexity|embeddings|teams|bluebubbles|mail|voice|a2a|workbench] [--agent <name>]");
+    throw new Error("Usage: ouro connect [providers|perplexity|embeddings|teams|bluebubbles|mail|voice|a2a|telegram|workbench] [--agent <name>]");
 }
 function extractMailSourceFlags(args, usageText) {
     const rest = [];
@@ -1090,7 +1092,7 @@ function extractMailSourceFlags(args, usageText) {
     };
 }
 function parseConnectCommand(args) {
-    const usageText = "Usage: ouro connect [providers|perplexity|embeddings|teams|bluebubbles|mail|voice|a2a|workbench] [--agent <name>] [--owner-email <email> --source <label>|--no-delegated-source] [--rotate-missing-mail-keys]";
+    const usageText = "Usage: ouro connect [providers|perplexity|embeddings|teams|bluebubbles|mail|voice|a2a|telegram|workbench] [--agent <name>] [--owner-email <email> --source <label>|--no-delegated-source] [--rotate-missing-mail-keys]";
     const { agent, rest: afterAgent } = extractAgentFlag(args);
     const mailFlags = extractMailSourceFlags(afterAgent, usageText);
     if (mailFlags.rest.length > 1)