@zq-silk/yui 2.7.1 → 2.8.0

package/dist/controller/structuredProviderObservation.js

@@ -10,10 +10,15 @@ import { FileRuntimeEventInbox } from "./runtimeEventInbox.js";
 import { AGENT_HOST_EVENT_PROTOCOL } from "../runtime/agentHostProtocol.js";
 import { redactAgentErrorText } from "../runtime/agentError.js";
 let structuredSequence = 0;
-let deliveryFailure;
+const deliveryFailures = new Map();
 // Only live diagnostics for this process's immutable files, not another queue.
 // No payload, retry, or authoritative delivery state is kept in this map.
 const emittedEvents = new Map();
+// Only facts whose immutable Inbox write has not succeeded. The original
+// process must retain these bytes during a filesystem fault: another direct
+// native turn can arrive without Yui admission and replace a last-turn cache.
+// No new durable queue or execution retry; discard only after durable enqueue.
+const unpersistedEvents = new Map();
 /** Retained in the existing Host Inbox; it never settles a Turn or a resource. */
 export async function publishStructuredProviderDiagnostic(input) {
     const diagnostic = input.diagnostic;
@@ -44,6 +49,7 @@ export async function publishStructuredProviderDiagnostic(input) {
 /** A live transport observation, independent of Provider state and Run truth. */
 export function structuredProviderEventDelivery(home, environment, nativeSessionId) {
     try {
+        const deliveryFailure = deliveryFailures.get(deliveryKey(home, environment));
         const inbox = new FileRuntimeEventInbox(home);
         const pending = [];
         for (const [id, entry] of emittedEvents) {
@@ -57,16 +63,39 @@ export function structuredProviderEventDelivery(home, environment, nativeSession
                 && (nativeSessionId === undefined || entry.nativeSessionId === nativeSessionId))
                 pending.push(entry);
         }
+        const retained = pendingPersistence(home, environment);
         return {
-            pending: pending.length,
-            pendingTerminals: pending.filter(event => event.terminal).length,
+            pending: pending.length + retained.length,
+            unpersisted: retained.length,
+            pendingTerminals: pending.filter(event => event.terminal).length
+                + retained.filter(event => ["turn.completed", "turn.failed", "turn.cancelled"].includes(event.observation.kind)).length,
             ...(deliveryFailure === undefined ? {} : { failure: deliveryFailure })
         };
     }
     catch (error) {
-        return { pending: 0, pendingTerminals: 0, failure: deliveryFault("persistence", error) };
+        const retained = pendingPersistence(home, environment);
+        return {
+            pending: retained.length, unpersisted: retained.length,
+            pendingTerminals: retained.filter(event => ["turn.completed", "turn.failed", "turn.cancelled"].includes(event.observation.kind)).length,
+            failure: deliveryFault("persistence", error)
+        };
     }
 }
+function deliveryKey(home, environment) {
+    return JSON.stringify([home, environment.YUI_TASK_ID, environment.YUI_ROLE, environment.YUI_AGENT_ID]);
+}
+function pendingPersistence(home, environment) {
+    return [...unpersistedEvents.values()].filter(event => event.home === home
+        && event.observation.fence.taskId === environment.YUI_TASK_ID
+        && event.observation.fence.roleName === environment.YUI_ROLE
+        && event.observation.fence.agentId === environment.YUI_AGENT_ID);
+}
+/** Retry only original native facts, under the original Host's control fence. */
+export async function replayStructuredProviderPersistence(home, environment) {
+    const retained = pendingPersistence(home, environment).map(event => event.observation);
+    await persistAndApply(home, [], environment);
+    return retained;
+}
 function deliveryFault(stage, error) {
     return {
         stage, detail: redactAgentErrorText(error instanceof Error ? error.message : String(error)),
@@ -412,28 +441,35 @@ function requireIdentity(value, label) {
 }
 async function persistAndApply(home, observations, environment, connection, startupRunId) {
     const inbox = new FileRuntimeEventInbox(home);
+    const key = deliveryKey(home, environment);
     const host = {
         protocol: AGENT_HOST_EVENT_PROTOCOL,
         adapterId: requireIdentity(environment.YUI_ADAPTER_ID, "Agent adapter id"),
         workspace: requireIdentity(environment.YUI_WORKSPACE, "Yui workspace"),
         ...(connection === undefined ? {} : { connection })
     };
-    let events;
+    const source = { ...host, ...(startupRunId === undefined ? {} : { startupRunId }) };
+    for (const observation of observations) {
+        unpersistedEvents.set(observation.eventId, { home, observation, host: source });
+    }
+    const events = [];
     try {
         structuredProviderEventDelivery(home, environment); // prune ACKed local diagnostics
-        events = observations.map(entry => inbox.enqueueObservation(entry, {
-            ...host,
-            ...(startupRunId === undefined ? {} : { startupRunId })
-        }).event);
-        for (const event of events)
+        for (const retained of pendingPersistence(home, environment)) {
+            const event = inbox.enqueueObservation(retained.observation, retained.host).event;
+            events.push(event);
+            unpersistedEvents.delete(retained.observation.eventId);
             emittedEvents.set(event.id, {
                 home, taskId: event.taskId, roleName: event.observation.fence.roleName,
                 nativeSessionId: event.observation.fence.nativeSessionId,
                 terminal: ["turn.completed", "turn.failed", "turn.cancelled"].includes(event.observation.kind)
             });
+        }
+        if (deliveryFailures.get(key)?.stage === "persistence")
+            deliveryFailures.delete(key);
     }
     catch (error) {
-        deliveryFailure = deliveryFault("persistence", error);
+        deliveryFailures.set(key, deliveryFault("persistence", error));
         throw error;
     }
     // The immutable inbox is authoritative. During a release/update handover the
@@ -463,7 +499,7 @@ async function persistAndApply(home, observations, environment, connection, star
                 return;
             // The native fact is already durable. An incompatible/refusing
             // Controller is a reporting fault, not Provider execution failure.
-            deliveryFailure = deliveryFault("controller", error);
+            deliveryFailures.set(key, deliveryFault("controller", error));
             return;
         }
         // A fast Provider can accept the initial AgentRun before the scheduler call
@@ -472,12 +508,12 @@ async function persistAndApply(home, observations, environment, connection, star
         // `deferred` therefore means "retained for replay", not delivery failure.
         // The signal below schedules the replay after the transport transaction.
         if (result.outcome !== "applied" && result.outcome !== "deferred") {
-            deliveryFailure = deliveryFault("controller", `Structured Provider observation was rejected: ${result.outcome ?? "unknown"}. Event: ${entry.id}`);
+            deliveryFailures.set(key, deliveryFault("controller", `Structured Provider observation was rejected: ${result.outcome ?? "unknown"}. Event: ${entry.id}`));
             return;
         }
     }
-    if (deliveryFailure?.stage === "controller")
-        deliveryFailure = undefined;
+    if (events.length > 0 && deliveryFailures.get(key)?.stage === "controller")
+        deliveryFailures.delete(key);
     await signalController(home, hostTaskId(environment), requireIdentity(environment.YUI_ROLE, "Role"));
 }
 /** Capture only identities the Host actually received; the current Controller

package/dist/controller/taskHostTerminalRecovery.js

@@ -0,0 +1,33 @@
+import { AGENT_HOST_CONTROL_PROTOCOL, reconcileAgentHostTurn } from "../runtime/agentHost.js";
+import { currentProviderConversation } from "../runtime/providerRuntimeIdentity.js";
+import { providerRetryPending } from "../runtime/providerRetry.js";
+/** Existing full reconciliation pass only; no new timer, input or Session. */
+export async function recoverTaskHostTerminals(home, store, onError, reconcile = reconcileAgentHostTurn) {
+    for (const candidate of store.listRuntimeSessionCandidates({ scope: "task" })) {
+        const owner = candidate.owner;
+        if (owner.scope !== "task")
+            continue;
+        const binding = store.getTaskRoleSessionSet(owner.taskId, owner.roleName)?.providerBinding;
+        const turn = binding?.run;
+        if (binding === undefined || binding === null || turn == null || providerRetryPending(binding)
+            || !["submitting", "accepted", "delivery-unknown"].includes(turn.status)
+            || binding.authority.owner !== "controller" || binding.authority.holderId === undefined)
+            continue;
+        try {
+            const result = await reconcile({ home, ...owner, control: {
+                    protocol: AGENT_HOST_CONTROL_PROTOCOL, type: "reconcile-turn",
+                    nativeSessionId: currentProviderConversation(binding).conversationId,
+                    attemptId: turn.attemptId, nativeTurnId: turn.nativeTurnId,
+                    authority: { epoch: binding.authority.epoch, owner: "controller", holderId: binding.authority.holderId }
+                } });
+            if (result.outcome === "rejected" || result.reconciliation === "unsupported") {
+                throw new Error(result.failure?.detail
+                    ?? "Host terminal reconciliation is unsupported; retain the original input and inspect Host/Inbox evidence.");
+            }
+        }
+        catch (error) {
+            onError(new Error(`Task Host terminal recovery ${owner.taskId}/${owner.roleName}/${turn.attemptId}: `
+                + `${error instanceof Error ? error.message : String(error)} No input was replayed.`, { cause: error }));
+        }
+    }
+}

package/dist/executor/fileRoleLaunchPlanner.js

@@ -259,15 +259,10 @@ export class FileRoleLaunchPlanner {
         const existingSession = owner.scope === "task"
             ? this.store.getTaskRoleSessionSet(owner.taskId, role.name)?.sessions[input.agentId]
             : this.store.getGlobalRoleSessionSet(role.name)?.sessions[input.agentId];
-        // A resume carries the Session's recorded generation forward unchanged. This
-        // planner runs in the Controller, which after an upgrade is already the new
-        // code, so it cannot speak for the still-running Agent Host that owns the
-        // Session: rejecting here would end live Sessions on Controller upgrade,
-        // while rewriting to current code would silently move a Session onto code it
-        // never started on. The Host that actually executes the implementation makes
-        // the decision — a reused live Host accepts its own generation, and a newly
-        // started Host running different code fails closed
-        // (`agentEndpointOwnership.pin` -> `requireBuiltinAgentEndpointImplementation`).
+        // Retain original launch provenance. The Host reports its actually loaded
+        // build separately and checks adapter/native identity, not build equality.
+        // A compatible new Host can resume this exact Session after safe release;
+        // this planner never silently replaces a live Host or native conversation.
         const endpointImplementation = input.mode === "resume"
             ? validateAgentEndpointImplementation(existingSession.endpointImplementation)
             : builtinAgentEndpointImplementation(binding.adapterId);

package/dist/message/inboxReceipt.js

@@ -1,5 +1,24 @@
 import { requireKnownFields, requireText, requireTimestamp } from "../domain/validation.js";
 import { isDeepStrictEqual } from "node:util";
+/** Semantic handling and transport delivery are independent facts. Projections
+ * must not infer handling from delivery, a native terminal, or an empty queue. */
+export function inboxHandlingState(receipt) {
+    return receipt?.ack !== undefined ? "handled" : receipt !== undefined ? "claimed-unacknowledged" : "unclaimed";
+}
+export function isGlobalInboxMessage(message) {
+    return message.inputControl !== undefined || message.interruptThen !== undefined;
+}
+/** Unhandled own-role input, including accepted and unknown delivery. This is
+ * NOT the scheduler's deliverable queue; selecting it never authorizes replay. */
+export function pendingGlobalInboxMessages(messages) {
+    return messages.filter(message => isGlobalInboxMessage(message) && inboxHandlingState(message.inbox) !== "handled");
+}
+/** Original message evidence only. A missing receipt is not proof of
+ * non-submission; admission additionally inspects the exact native attempt. */
+export function globalInboxDeliveryState(message) {
+    return message.control?.outcome ?? (message.delivery?.via === "provider" ? "accepted"
+        : message.delivery === undefined ? "unobserved" : "delivery-unknown");
+}
 export function validateInboxReceipt(receipt) {
     if (receipt === undefined)
         return;
@@ -30,3 +49,14 @@ export function assertInboxReceiptPreserved(previous, next) {
         throw new Error("Inbox handling ownership changed; reread the original instead of overwriting its receipt.");
     }
 }
+/** A receipt cannot silently acknowledge different content under the same ID.
+ * Operational delivery/Assignment fields may evolve with their existing
+ * guards, but handled originals must be submitted as new Messages to change.
+ */
+export function assertInboxOriginalPreserved(previous, next) {
+    assertInboxReceiptPreserved(previous?.inbox, next.inbox);
+    if (previous?.inbox !== undefined && (previous.body !== next.body || previous.kind !== next.kind
+        || !isDeepStrictEqual(previous.author, next.author) || !isDeepStrictEqual(previous.inputControl, next.inputControl))) {
+        throw new Error("Inbox receipt binds the exact original Message; submit changed content as a new Message.");
+    }
+}

package/dist/message/taskInboxOwnership.js

@@ -1,4 +1,19 @@
 import { operationalTaskRecords } from "../task/taskRecordRetirement.js";
+/** Pin mutable originals by their existing event identity, not wall-clock time.
+ * Both automatic notification and active consumption use the same fixed refs. */
+export function pinMessageRevisions(store, taskId, refs) {
+    const pinned = [...refs];
+    for (const ref of refs) {
+        if (ref.type !== "message" || ref.taskId !== taskId)
+            continue;
+        const message = store.listMessages(taskId).find(message => message.id === ref.id);
+        const revision = message === undefined ? undefined : latestMessageUpdate(store, message);
+        if (revision !== undefined && !pinned.some(ref => ref.type === "event" && ref.id === revision.id)) {
+            pinned.push({ type: "event", taskId, id: revision.id });
+        }
+    }
+    return pinned;
+}
 export function latestMessageUpdate(store, message) {
     return store.listEvents(message.taskId).filter(event => event.type === "message.updated" && event.payload.messageId === message.id).at(-1);
 }
@@ -9,10 +24,17 @@ export function isLeaderSteer(message) {
 }
 /** Derive ownership from original receipts, never from disposable mailboxes. */
 export function taskMessageInboxReceipt(store, message) {
+    return message.inbox ?? messageRevisionWakes(store, message).find(wake => wake.inbox !== undefined)?.inbox;
+}
+/** Delivery suppresses repeat notification of that revision, but remains
+ * distinct from handling. The original fixed window stays in the own inbox. */
+export function deliveredMessageWake(store, message) {
+    return messageRevisionWakes(store, message).find(wake => wake.status === "consumed");
+}
+function messageRevisionWakes(store, message) {
     const revision = latestMessageUpdate(store, message);
-    return message.inbox ?? store.listTaskWakes(message.taskId).find(wake => wake.inbox !== undefined
-        && (revision === undefined || wake.refs?.some(ref => ref.type === "event" && ref.taskId === message.taskId && ref.id === revision.id))
-        && wake.refs?.some(ref => ref.type === "message" && ref.taskId === message.taskId && ref.id === message.id))?.inbox;
+    return store.listTaskWakes(message.taskId).filter(wake => (revision === undefined || wake.refs?.some(ref => ref.type === "event" && ref.taskId === message.taskId && ref.id === revision.id))
+        && wake.refs?.some(ref => ref.type === "message" && ref.taskId === message.taskId && ref.id === message.id));
 }
 export function unfinishedLeaderInbox(store, taskId) {
     return store.listTaskWakes(taskId).some(wake => wake.inbox !== undefined && wake.inbox.ack === undefined)