@ouro.bot/cli 0.1.0-alpha.943 → 0.1.0-alpha.944

package/changelog.json

@@ -1,6 +1,12 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.944",
+      "changes": [
+        "The Butler sends at most one Telegram warning for a batch of health events from one sweep, records the rest as covered by it, and settles a retry of an already-sent warning without sending it again."
+      ]
+    },
     {
       "version": "0.1.0-alpha.943",
       "changes": [

package/deploy/unraid/sanctuary.ouro/bundle-meta.json

@@ -1,5 +1,5 @@
 {
-  "runtimeVersion": "0.1.0-alpha.943",
+  "runtimeVersion": "0.1.0-alpha.944",
   "bundleSchemaVersion": 3,
   "lastUpdated": "2026-09-03T00:00:00.000Z"
 }

package/deploy/unraid/sanctuary.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <Container version="2">
   <Name>ouro-butler</Name>
-  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.943</Repository>
+  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.944</Repository>
   <Registry>https://github.com/ourostack/ouroboros/pkgs/container/ouroboros-butler</Registry>
   <Network>host</Network>
   <Shell>sh</Shell>

package/dist/heart/external-events/router.js

@@ -1313,6 +1313,13 @@ function validateDisposition(disposition) {
         assertBoundedText(ref, "disposition reference", 512);
     if (disposition.nextWake.kind === "at")
         assertBoundedText(disposition.nextWake.at, "wake time", 64);
+    if (disposition.ownerMessage) {
+        if (!["sent", "already_sent", "covered"].includes(disposition.ownerMessage.status))
+            throw new Error("External event owner message status is invalid");
+        if (!disposition.ownerMessage.effectKey)
+            throw new Error("External event owner message key is missing");
+        assertBoundedText(disposition.ownerMessage.effectKey, "owner message key", 1_024);
+    }
 }
 function commitExternalEventDisposition(recordPath, input) {
     return withRecordLock(recordPath, () => {

package/dist/repertoire/tools-continuity.js

@@ -176,12 +176,18 @@ function prepareExternalEventDisposition(a, ctx) {
     return {
         recordPath,
         finish: async () => {
+            let ownerMessage;
             if (decision === "ask" || decision === "report") {
                 if (Buffer.byteLength(reason, "utf8") > 1_200)
                     throw new Error("External event owner message must be phone-sized");
                 if (!ctx?.externalEventEffects)
                     throw new Error("External event owner delivery is unavailable");
-                await ctx.externalEventEffects.deliverOwnerDecision({ source: record.source, eventId: record.eventId, generation: record.generation, text: reason });
+                // The whole dispatched batch shares one owner message; the delivery port settles later decisions as covered by it.
+                const relatedEvents = [turnContext, ...(turnContext.relatedEvents ?? [])]
+                    .filter((event) => path.resolve(event.recordPath) !== recordPath)
+                    .map((event) => ({ source: event.source, eventId: event.eventId, generation: event.generation }));
+                const delivered = await ctx.externalEventEffects.deliverOwnerDecision({ source: record.source, eventId: record.eventId, generation: record.generation, text: reason, relatedEvents });
+                ownerMessage = { status: delivered.status, effectKey: delivered.effectKey };
             }
             const handled = (0, router_1.commitExternalEventDisposition)(recordPath, {
                 owner: turnEvent.claimOwner,
@@ -198,10 +204,11 @@ function prepareExternalEventDisposition(a, ctx) {
                     awaitId: typeof a.awaitId === "string" && a.awaitId ? a.awaitId : null,
                     actionRefs,
                     verificationRefs,
+                    ...(ownerMessage ? { ownerMessage } : {}),
                 },
             });
             ctx?.externalEventAuthority?.recordCommittedDisposition?.(turnEvent);
-            (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.external_event_disposition", message: "external event disposition recorded", meta: { agentName, eventId: record.eventId, generation: record.generation, classification, decision } });
+            (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.external_event_disposition", message: "external event disposition recorded", meta: { agentName, eventId: record.eventId, generation: record.generation, classification, decision, ...(ownerMessage ? { ownerMessage: ownerMessage.status } : {}) } });
             return handled;
         },
     };
@@ -213,7 +220,7 @@ exports.continuityToolDefinitions = [
             type: "function",
             function: {
                 name: "external_event_disposition",
-                description: "Classify the exact external-event generation I just investigated. An ask or report is the sole owner-delivery path and sends reason once for this receipt; silent and act only record the disposition.",
+                description: "Classify the exact external-event generation I just investigated. An ask or report is the sole owner-delivery path and sends reason once for this receipt; silent and act only record the disposition. In a batch, only the first ask or report sends a message and the later ones are recorded as covered by it, so write that first reason to cover every listed lease.",
                 parameters: {
                     type: "object",
                     properties: {

package/dist/senses/private-runtime.js

@@ -893,7 +893,7 @@ function buildExternalEventLeaseMessage(event) {
     const members = [event, ...(event.relatedEvents ?? [])];
     const dispositionInstruction = members.length === 1
         ? "Investigate the current observation, then call external_event_disposition once for this lease before settling."
-        : "Investigate the current observations, then call external_event_disposition once with one bounded batch containing every listed lease before settling.";
+        : "Investigate the current observations, then call external_event_disposition once with one bounded batch containing every listed lease before settling. The batch gets at most one owner message: the first ask or report sends it, so its reason must cover every lease.";
     return [
         "[current external-event disposition contract]",
         "This exact lease frame is authoritative for this turn. Ignore older receipts, failed tool arguments, held-work summaries, and checkpoints when choosing disposition arguments.",
@@ -1368,7 +1368,7 @@ async function runPrivateRuntimeTurn(options) {
                         externalEventEffects: {
                             deliverOwnerDecision: async (input) => {
                                 const { sendTelegramExternalEventDecision } = await Promise.resolve().then(() => __importStar(require("./telegram")));
-                                await sendTelegramExternalEventDecision(agentName, input);
+                                return sendTelegramExternalEventDecision(agentName, input);
                             },
                         },
                     };

package/dist/senses/telegram-effect-adapter.js

@@ -284,6 +284,10 @@ class FileTelegramEffectJournal {
         const filePath = this.artifactPath(id);
         return fs.existsSync(filePath) ? this.read(id) : null;
     }
+    /** The artifact an idempotency key already owns, if any; its existence means the journal owns that delivery. */
+    readByIdempotencyKey(idempotencyKey) {
+        return this.readIfExists(artifactId(idempotencyKey));
+    }
     quarantineInvalid(id, reason) {
         this.assertRootIdentity();
         const filePath = this.artifactPath(id);

package/dist/senses/telegram.js

@@ -1954,19 +1954,49 @@ function createTelegramSenseApp(options) {
             });
         },
         async sendExternalEventDecision(input) {
-            const source = requiredText(input.source, "external event source");
-            const eventId = requiredText(input.eventId, "external event id");
-            if (Buffer.byteLength(source) > 512 || Buffer.byteLength(eventId) > 512 || !Number.isSafeInteger(input.generation) || input.generation < 1)
+            const identities = [input, ...(input.relatedEvents ?? [])].map((event) => ({
+                source: requiredText(event.source, "external event source"),
+                eventId: requiredText(event.eventId, "external event id"),
+                generation: event.generation,
+            }));
+            if (identities.some(({ source, eventId, generation }) => Buffer.byteLength(source) > 512 || Buffer.byteLength(eventId) > 512
+                || !Number.isSafeInteger(generation) || generation < 1))
                 throw new Error("Telegram external event identity is invalid");
-            await runWithAcceptanceAuditOwner(async () => {
-                const receiptIdentity = JSON.stringify([source, eventId, input.generation]);
+            const [key, ...relatedKeys] = identities.map(({ source, eventId, generation }) => `external-event:${JSON.stringify([source, eventId, generation])}`);
+            return runWithAcceptanceAuditOwner(async () => {
                 const text = requiredText(input.text, "external event decision");
-                if (holdNoticeDuringHandoff(text, `external-event:${receiptIdentity}`))
-                    return;
-                await releaseHeldNotices(input.signal);
-                const effect = await deliverButlerEffect(text, `external-event:${receiptIdentity}`, input.signal);
                 const sessionPath = (0, shared_turn_1.getSenseSessionPath)(options.agentName, configuredOwnerFriendId, "telegram", configuredOwnerSessionKey, agentRoot);
+                const held = (0, telegram_handoff_1.readHeldNotices)(heldNoticesPath);
+                const ownerMessageExists = (candidate) => held.some((notice) => notice.key === candidate)
+                    || getEffectJournal().readByIdempotencyKey(candidate) !== null;
+                if (ownerMessageExists(key)) {
+                    // A retry after the message went out (or was held): finish the original send, never send a reworded second one.
+                    const existing = getEffectJournal().readByIdempotencyKey(key);
+                    if (existing) {
+                        await releaseHeldNotices(input.signal);
+                        await recordAcceptedEffects(sessionPath, [await executeAuthorizedEffect({
+                                idempotencyKey: key, target: existing.target, authorClass: existing.authorClass, effect: existing.effect,
+                                ...(input.signal ? { signal: input.signal } : {}),
+                            })]);
+                    }
+                    return { status: "already_sent", effectKey: key };
+                }
+                const coveredBy = relatedKeys.find(ownerMessageExists);
+                if (coveredBy) {
+                    (0, runtime_1.emitNervesEvent)({
+                        component: "senses",
+                        event: "senses.telegram_external_event_decision_covered",
+                        message: "settled an external-event decision under the owner message already sent for its batch",
+                        meta: { agentName: options.agentName, effectKey: key, coveredBy },
+                    });
+                    return { status: "covered", effectKey: coveredBy };
+                }
+                if (holdNoticeDuringHandoff(text, key))
+                    return { status: "sent", effectKey: key };
+                await releaseHeldNotices(input.signal);
+                const effect = await deliverButlerEffect(text, key, input.signal);
                 await recordAcceptedEffects(sessionPath, [effect]);
+                return { status: "sent", effectKey: key };
             });
         },
         async sendAwaitFollowUp(request) {
@@ -2315,7 +2345,7 @@ async function startTelegramSenseApp(agentName, waitForAuthority = false) {
 async function sendTelegramExternalEventDecision(agentName, input) {
     const app = await startTelegramSenseApp(agentName);
     try {
-        await app.sendExternalEventDecision(input);
+        return await app.sendExternalEventDecision(input);
     }
     finally {
         await app.stop();

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.943",
+  "version": "0.1.0-alpha.944",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@ouro.bot/cli",
-      "version": "0.1.0-alpha.943",
+      "version": "0.1.0-alpha.944",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.78.0",
         "@azure/identity": "^4.13.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.943",
+  "version": "0.1.0-alpha.944",
   "engines": {
     "node": ">=22"
   },