@north-light/crouter 0.3.250 → 0.3.252

package/dist/pi-extensions/canvas-inbox-watcher.js

@@ -10,7 +10,10 @@
 // Context sends never trigger a turn: the visible human delivery is the sole
 // trigger, so the agent cannot run on context alone before hearing the person.
 // A context-only batch keeps its wake by triggering on its LAST card while idle,
-// and rides the running turn while streaming.
+// and rides the running turn while streaming. A deferred-only idle batch stays
+// held until either durable mail wakes a turn or the broker prepends it to an
+// already-admitted live human prompt; that bridge still commits only at
+// agent_settled.
 import { envNodeId, envProfileId, envWatcherDebounceMs, envWatcherTickMs } from '../shared/env.js';
 import { coalesceBrokerInbox, entryCards, readBrokerCanceledEntryIds, readBrokerCursor, readBrokerInboxSince, reportRefNodeId, } from '../core/runtime/broker/inbox.js';
 import { advanceBrokerInboxCursor, brokerExtensionState } from '../core/runtime/broker/daemon-ops.js';
@@ -20,6 +23,7 @@ import { errorClassFromError } from '../core/events/errors.js';
 import { operationIdContext } from '../core/events/operation-id.js';
 import { situationalContextEnvelope, SITUATIONAL_CONTEXT_CUSTOM_TYPE } from '../core/runtime/situational-context.js';
 import { isProfilePaused } from '../core/profiles/manifest.js';
+import { brokerIdleTurnStart, HELD_DEFERRED_INBOX_PROMPT_JOIN, } from '../core/runtime/broker/held-deferred-inbox.js';
 const MAX_PENDING_HANDOFFS = 64;
 const MAX_SOURCE_OPERATION_IDS = 16;
 let currentWatcher;
@@ -188,6 +192,7 @@ class CanvasInboxWatcher {
     lastArrival = 0;
     pendingHandoffs = [];
     pendingCommit;
+    promptJoinInFlight = false;
     seeded = false;
     disposed = false;
     disposalReason;
@@ -250,7 +255,7 @@ class CanvasInboxWatcher {
                 // every queued continuation has drained, so hasPendingMessages() must
                 // not veto the commit here. Await crtrd before changing the in-memory
                 // durable cursor; a failed commit remains replayable after process exit.
-                const result = await this.settle(nodeId, ctx, false);
+                const result = await this.settle(nodeId, ctx, false, true);
                 if (result === 'refresh_held')
                     this.dispose('refresh', false);
             }
@@ -383,6 +388,7 @@ class CanvasInboxWatcher {
             this.reportNodes.clear();
             this.reportNodesAsked.clear();
             this.pendingCommit = undefined;
+            this.promptJoinInFlight = false;
             this.nodeId = undefined;
             this.lastCtx = undefined;
             this.lastArrival = 0;
@@ -531,6 +537,8 @@ class CanvasInboxWatcher {
             this.retryPendingCommitOnTick(nodeId);
             return;
         }
+        if (this.promptJoinInFlight)
+            return;
         // A paused profile is inert: read nothing, send nothing, leave the cursor
         // where it is, so every queued entry — critical included, since aborting the
         // live turn is exactly the punch-through pause forbids — is still there to
@@ -599,6 +607,9 @@ class CanvasInboxWatcher {
         const hiddenIds = new Set(hiddenEntries.map((entry) => entry.entry_id));
         const visibleIds = new Set(visibleEntries.map((entry) => entry.entry_id));
         const routedEntries = entries.filter((entry) => hiddenIds.has(entry.entry_id) || visibleIds.has(entry.entry_id));
+        // Deferred-only idle mail remains in this buffer until a non-deferred inbox
+        // entry starts delivery, or a live human prompt claims it through
+        // prependHeldDeferredInbox(). Neither path wakes the node on its own.
         const deferredHold = this.isIdle()
             && routedEntries.length > 0
             && routedEntries.every((entry) => entry.tier === 'deferred');
@@ -727,7 +738,10 @@ class CanvasInboxWatcher {
                 this.pi.sendMessage({ customType: SITUATIONAL_CONTEXT_CUSTOM_TYPE, content: card, display: true }, route === 'idle' ? {} : { deliverAs: route });
             }
             if (route === 'idle') {
-                this.pi.sendUserMessage(content);
+                const start = brokerIdleTurnStart();
+                if (start === undefined)
+                    throw new Error('broker idle-turn admission is unavailable');
+                start(content);
             }
             else {
                 this.pi.sendUserMessage(content, { deliverAs: route });
@@ -826,6 +840,83 @@ class CanvasInboxWatcher {
         this.requeueFromBatch(batch, execution.requeueEntryIds);
         return 'attempted';
     }
+    /** Claim the deferred-only idle batch for the human prompt already admitted
+     * by the broker. Each rendered delivery is persisted before that prompt, but
+     * no cursor may advance until the prompt's agent_settled event proves the
+     * turn consumed it. */
+    async prependHeldDeferredInbox(session) {
+        if (!this.canMutate() || this.nodeId === undefined || profilePaused())
+            return;
+        const plan = this.ordinaryPlan();
+        if (!plan.deferredHold)
+            return;
+        const deliveries = plan.visibleEntries.length === 0
+            ? []
+            : this.digest(plan.visibleEntries, 'poll');
+        const handoffCount = Number(plan.hiddenEntries.length > 0) + deliveries.length;
+        if (this.pendingHandoffs.length + handoffCount > MAX_PENDING_HANDOFFS)
+            return;
+        const batch = [...this.buffer];
+        this.promptJoinInFlight = true;
+        try {
+            if (plan.hiddenEntries.length > 0) {
+                await this.sendPromptJoinDelivery(session, 'hidden', plan.hiddenEntries, this.contextCards(this.nodeId, plan.hiddenEntries));
+            }
+            for (const delivery of deliveries) {
+                await this.sendPromptJoinDelivery(session, 'visible', delivery.entries, [...delivery.cards, delivery.text]);
+            }
+            if (!this.canMutate())
+                return;
+            this.buffer.splice(0, batch.length);
+        }
+        finally {
+            this.promptJoinInFlight = false;
+        }
+    }
+    async sendPromptJoinDelivery(session, channel, entries, messages) {
+        let facts;
+        try {
+            facts = deliveryFacts(entries, channel);
+        }
+        catch (error) {
+            this.raiseReadFatal('poll', error);
+        }
+        let operationId;
+        try {
+            await operationIdContext.fresh(async (freshOperationId) => {
+                operationId = freshOperationId;
+                emitBestEffort({
+                    level: 'info',
+                    event: 'inbox.delivery.started',
+                    operation_id: freshOperationId,
+                    fields: deliveryFields(facts),
+                });
+                for (const content of messages) {
+                    await session.sendCustomMessage({
+                        customType: SITUATIONAL_CONTEXT_CUSTOM_TYPE,
+                        content,
+                        display: true,
+                    });
+                }
+            });
+        }
+        catch (error) {
+            if (operationId === undefined)
+                this.raiseReadFatal('poll', error);
+            emitDeliveryFailure(operationId, facts, 'send', error);
+            throw error;
+        }
+        if (operationId === undefined) {
+            this.raiseReadFatal('poll', new Error(`${channel} prompt-join delivery returned without an operation id`));
+        }
+        const handoff = { operationId, ...facts, settleAtAgentSettled: true };
+        if (!this.canMutate()) {
+            if (this.disposed && this.disposalReason !== undefined)
+                emitDeliveryAbandoned(handoff, this.disposalReason);
+            return;
+        }
+        this.pendingHandoffs.push(handoff);
+    }
     coveredEntryIds(channel) {
         const covered = new Set();
         for (const handoff of this.pendingHandoffs) {
@@ -883,7 +974,7 @@ class CanvasInboxWatcher {
             emitDeliveryCompleted(handoff);
         return 'settled';
     }
-    async settle(nodeId, ctx, holdPendingMessages) {
+    async settle(nodeId, ctx, holdPendingMessages, atAgentSettled = false) {
         if (holdPendingMessages) {
             try {
                 if (ctx?.hasPendingMessages?.() === true)
@@ -903,9 +994,17 @@ class CanvasInboxWatcher {
             for (const handoff of alreadyDurable)
                 emitDeliveryCompleted(handoff);
         }
+        const agentSettledBlock = atAgentSettled
+            ? undefined
+            : this.pendingHandoffs
+                .filter((handoff) => handoff.settleAtAgentSettled === true)
+                .map((handoff) => physical.throughIndexes.get(handoff))
+                .reduce((first, index) => first === undefined ? index : Math.min(first, index), undefined);
         const eligible = this.pendingHandoffs.filter((handoff) => {
             const throughIndex = physical.throughIndexes.get(handoff);
-            return physical.blockedIndex === undefined || throughIndex < physical.blockedIndex;
+            return (handoff.settleAtAgentSettled !== true || atAgentSettled)
+                && (physical.blockedIndex === undefined || throughIndex < physical.blockedIndex)
+                && (agentSettledBlock === undefined || throughIndex < agentSettledBlock);
         });
         if (eligible.length === 0)
             return 'settled';
@@ -1006,6 +1105,11 @@ function installWatcher(pi, cadence) {
     currentWatcher?.dispose('reload', false);
     const watcher = new CanvasInboxWatcher(pi, cadence, ++nextGeneration);
     currentWatcher = watcher;
+    // Pi loads this extension through Jiti while the broker driver is native ESM,
+    // so their module-level singletons differ. Register the bound watcher on the
+    // process-global key that the broker reads immediately before a human prompt.
+    const promptJoin = (session) => watcher.prependHeldDeferredInbox(session);
+    globalThis[HELD_DEFERRED_INBOX_PROMPT_JOIN] = promptJoin;
     try {
         watcher.start();
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.250",
+  "version": "0.3.252",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.250",
+  "version": "0.3.252",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.250",
+      "version": "0.3.252",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {