@zq-silk/yui 0.13.7 → 0.13.9

package/dist/executor/agentExecutor.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { hasRecentTurnId, rememberRecentTurnId, validatePendingTurnCompletion, validateRecentTurnIds } from "./turnCompletion.js";
 import { effectiveLaunchSnapshotsCompatible, effectiveLaunchSnapshotsCompatibleForTaskSession, validateEffectiveLaunchSnapshot } from "./effectiveLaunch.js";
-import { currentProviderActivation, endProviderActivation, rebindProviderRuntimeRun, validateProviderRuntimeBinding } from "../runtime/providerRuntimeIdentity.js";
+import { currentProviderActivation, endProviderActivation, settleProviderTurn, settleProviderTurnSubmission, validateProviderRuntimeBinding } from "../runtime/providerRuntimeIdentity.js";
 import { builtinDriverIdForAdapter } from "../runtime/builtinAgentDrivers.js";
 export function createRoleSessionSet(owner, activeAgentId, now) {
     const base = {
@@ -11,10 +11,10 @@ export function createRoleSessionSet(owner, activeAgentId, now) {
         updatedAt: now.toISOString()
     };
     return owner.scope === "global"
-        ? { ...base, schemaVersion: 3 }
+        ? { ...base, schemaVersion: 4 }
         : {
             ...base,
-            schemaVersion: 6,
+            schemaVersion: 8,
             inFlight: null,
             providerBinding: null
         };
@@ -28,7 +28,7 @@ export function activeRoleAgentSession(set) {
 /** The immutable snapshot that remains actual until its native process terminates. */
 export function activeLiveRoleAgentSession(set) {
     const session = activeRoleAgentSession(set);
-    return session === null || session.status === "stopped" || session.status === "broken"
+    return session === null || session.status === "ended"
         ? null
         : session;
 }
@@ -73,13 +73,13 @@ export function recordRoleAgentSession(set, input, now) {
         throw new Error(`Role Agent session effective launch cannot change: ${agentId}.`);
     }
     if (existing !== undefined && existing.nativeSessionId !== nativeSessionId
-        && existing.status !== "stopped" && existing.status !== "broken") {
+        && existing.status === "active") {
         throw new Error(`Live Role Agent native session cannot be replaced: ${agentId}.`);
     }
     const timestamp = now.toISOString();
     const continuing = existing?.nativeSessionId === nativeSessionId ? existing : undefined;
     const session = {
-        schemaVersion: 3,
+        schemaVersion: 4,
         agentId,
         adapterId,
         nativeSessionId,
@@ -91,6 +91,9 @@ export function recordRoleAgentSession(set, input, now) {
         policy: input.policy,
         effective: continuing?.effective ?? effective,
         status: input.status,
+        ...(input.status === "ended"
+            ? { endReason: input.endReason ?? continuing?.endReason ?? "stopped" }
+            : {}),
         recentCompletedTurnIds: continuing?.recentCompletedTurnIds ?? [],
         createdAt: continuing?.createdAt ?? timestamp,
         updatedAt: timestamp
@@ -127,7 +130,7 @@ export function replaceTaskRoleAgentSession(set, input, now) {
     if (existing === undefined || existing.nativeSessionId === input.nativeSessionId) {
         return recordRoleAgentSession(set, input, now);
     }
-    const terminalized = updateRoleAgentSessionStatus(set, input.agentId, "stopped", now);
+    const terminalized = updateRoleAgentSessionStatus(set, input.agentId, "ended", now, "stopped");
     return recordRoleAgentSession(terminalized, input, now);
 }
 /**
@@ -147,7 +150,7 @@ export function createRoleAgentSession(input, now) {
     const set = createRoleSessionSet({ scope: "global", roleName: "session-factory" }, agentId, now);
     return recordRoleAgentSession(set, input, now).sessions[agentId];
 }
-export function updateRoleAgentSessionStatus(set, agentId, status, now) {
+export function updateRoleAgentSessionStatus(set, agentId, status, now, endReason) {
     validateRoleSessionSet(set);
     const normalizedAgentId = requireSafeIdentity(agentId, "Agent id");
     if (!isAgentSessionStatus(status)) {
@@ -162,7 +165,12 @@ export function updateRoleAgentSessionStatus(set, agentId, status, now) {
         ...set,
         sessions: {
             ...set.sessions,
-            [normalizedAgentId]: { ...existing, status, updatedAt: timestamp }
+            [normalizedAgentId]: {
+                ...existing,
+                status,
+                ...(status === "ended" ? { endReason: endReason ?? "stopped" } : { endReason: undefined }),
+                updatedAt: timestamp
+            }
         },
         updatedAt: timestamp
     };
@@ -174,7 +182,7 @@ export function retireTaskRoleSessionsForWorkspace(set, now) {
     if (set.inFlight !== null) {
         throw new Error("Cannot retire a Task Role session with unsettled Run state.");
     }
-    const live = Object.values(set.sessions).find(({ status }) => status !== "stopped" && status !== "broken");
+    const live = Object.values(set.sessions).find(({ status }) => status === "active");
     if (live !== undefined) {
         throw new Error(`Task Role session must be stopped before workspace migration: ${live.agentId}.`);
     }
@@ -205,13 +213,18 @@ export function retireConfirmedAbsentInactiveTaskRolePlaceholders(set, now) {
     const sessions = Object.fromEntries(Object.entries(set.sessions).map(([agentId, session]) => {
         const isNeverStartedInactiveClaude = agentId !== set.activeAgentId
             && session.adapterId === "claude"
-            && (session.status === "reserved" || session.status === "ready")
+            && session.status === "active"
             && session.launchId === undefined
             && session.recentCompletedTurnIds.length === 0;
         if (!isNeverStartedInactiveClaude)
             return [agentId, session];
         changed = true;
-        return [agentId, { ...session, status: "broken", updatedAt: timestamp }];
+        return [agentId, {
+                ...session,
+                status: "ended",
+                endReason: "failed",
+                updatedAt: timestamp
+            }];
     }));
     if (!changed)
         return set;
@@ -231,7 +244,7 @@ export function rememberRoleAgentCompletedTurn(set, agentId, nativeSessionId, tu
     if (session.nativeSessionId !== requireText(nativeSessionId, "Native session id")) {
         throw new Error("Completed Turn native session does not match the Role Agent session.");
     }
-    const normalizedTurnId = requireSafeIdentity(turnId, "Turn id");
+    const normalizedTurnId = requireText(turnId, "Turn id");
     if (hasRecentTurnId(session.recentCompletedTurnIds, normalizedTurnId))
         return set;
     const recentCompletedTurnIds = rememberRecentTurnId(session.recentCompletedTurnIds, normalizedTurnId);
@@ -244,9 +257,6 @@ export function rememberRoleAgentCompletedTurn(set, agentId, nativeSessionId, tu
             ...set.sessions,
             [normalizedAgentId]: {
                 ...session,
-                status: session.status === "stopped" || session.status === "broken"
-                    ? session.status
-                    : "ready",
                 recentCompletedTurnIds,
                 updatedAt: timestamp
             }
@@ -268,13 +278,13 @@ export function roleAgentSessionResumeMode(set, agentId, desired) {
     // permits the normal fresh-generation path.
     if (typeof session.nativeSessionId !== "string"
         || session.nativeSessionId.trim().length === 0) {
-        if (session.status !== "stopped" && session.status !== "broken") {
+        if (session.status === "active") {
             throw new Error(`Role Agent session has no native Session identity: ${agentId}. `
                 + "Restore the exact native Session or explicitly stop it before starting a fresh Session.");
         }
         return "new";
     }
-    if (session.status === "stopped" || session.status === "broken") {
+    if (session.status === "ended") {
         return "new";
     }
     const compatible = set.owner.scope === "task"
@@ -298,15 +308,14 @@ export function bindTaskRoleRun(set, fence, preparedAt, mode) {
         throw new Error("Task Role session set already has an in-flight Run.");
     }
     const timestamp = requireDate(preparedAt, "Task Role Run preparedAt");
-    // A fresh Session follows physical cleanup and does not inherit execution
-    // fences from the disposable old Conversation. Runtime events retain its
-    // audit evidence; the new Provider binds a fresh control identity when it is
-    // observed. Resume keeps the existing exact Conversation fence.
+    // A fresh Session follows physical cleanup and does not inherit runtime
+    // evidence from the disposable old Conversation. A resumed Session keeps
+    // that evidence unchanged here: claiming a durable Run is a workflow
+    // mutation, not a Provider operation. AgentHost binds the Conversation to
+    // this Run only when it can actually submit the next serialized Turn.
     const providerBinding = mode === "new"
         ? null
-        : set.providerBinding !== null
-            ? rebindProviderRuntimeRun(set.providerBinding, normalized.runId)
-            : null;
+        : set.providerBinding;
     const updated = {
         ...set,
         inFlight: { ...normalized, preparedAt: timestamp },
@@ -315,34 +324,9 @@ export function bindTaskRoleRun(set, fence, preparedAt, mode) {
     };
     return validateRoleSessionSet(updated);
 }
-/** Re-fences the same active Run for an exact Provider retry without losing its Conversation. */
-export function prepareTaskRoleRunRedispatch(set, fence, preparedAt) {
-    validateRoleSessionSet(set);
-    const normalized = normalizeTaskRoleRunFence(fence);
-    if (set.inFlight === null
-        || set.inFlight.agentId !== normalized.agentId
-        || set.inFlight.runId !== normalized.runId) {
-        throw new Error("Provider retry does not match the in-flight Task Run.");
-    }
-    if (set.providerBinding !== null
-        && set.providerBinding.turn !== null
-        && ["submitting", "accepted", "running", "delivery-unknown"]
-            .includes(set.providerBinding.turn.status)) {
-        throw new Error("Provider retry cannot redispatch an unsettled Turn.");
-    }
-    const timestamp = requireDate(preparedAt, "Task Role retry preparedAt");
-    return validateRoleSessionSet({
-        ...set,
-        inFlight: { ...normalized, preparedAt: timestamp },
-        updatedAt: timestamp
-    });
-}
 export function bindTaskRoleProviderRuntime(set, binding, updatedAt) {
     validateRoleSessionSet(set);
     const normalized = validateProviderRuntimeBinding(binding);
-    if (set.inFlight === null || set.inFlight.runId !== normalized.runId) {
-        throw new Error("Provider Runtime Binding does not match the in-flight Run.");
-    }
     if (set.providerBinding !== null) {
         if (JSON.stringify(set.providerBinding) === JSON.stringify(normalized))
             return set;
@@ -358,7 +342,6 @@ export function updateTaskRoleProviderRuntime(set, binding, updatedAt) {
     validateRoleSessionSet(set);
     const normalized = validateProviderRuntimeBinding(binding);
     if (set.providerBinding === null
-        || normalized.runId !== set.providerBinding.runId
         || normalized.providerNamespace !== set.providerBinding.providerNamespace
         || normalized.accountScope !== set.providerBinding.accountScope) {
         throw new Error("Provider Runtime Binding identity cannot change in place.");
@@ -370,33 +353,65 @@ export function updateTaskRoleProviderRuntime(set, binding, updatedAt) {
     });
 }
 /**
- * Records an exact local Host exit without forgetting the Provider
- * Conversation. The ended Activation releases writer authority, while the
- * current Conversation and any unsettled Turn remain durable recovery fences.
+ * Detaches a confirmed-dead local Host without ending its resumable native
+ * Session. The Host launch and Provider Activation are disposable execution
+ * facts; the native Session remains the durable continuation identity.
  */
-export function stopTaskRoleRuntimeAfterPhysicalExit(set, now) {
+export function detachRoleAgentSessionHost(set, now) {
     validateRoleSessionSet(set);
     const active = set.sessions[set.activeAgentId];
-    if (active === undefined)
-        return set;
-    const activation = set.providerBinding === null
-        ? null
-        : currentProviderActivation(set.providerBinding);
-    if (active.status === "stopped") {
-        if (activation !== null) {
-            throw new Error("Stopped Task Role Session cannot retain a live Provider Activation.");
-        }
+    if (active === undefined || active.status === "ended")
         return set;
+    const timestamp = requireDate(now, "Role Host detach timestamp");
+    const { launchId: _launchId, endReason: _endReason, ...session } = active;
+    let updated = validateRoleSessionSet({
+        ...set,
+        sessions: {
+            ...set.sessions,
+            [set.activeAgentId]: {
+                ...session,
+                status: "active",
+                updatedAt: timestamp
+            }
+        },
+        updatedAt: timestamp
+    });
+    if (updated.owner.scope !== "task")
+        return updated;
+    let taskSet = updated;
+    let binding = taskSet.providerBinding;
+    const turn = binding?.turn;
+    if (binding !== null && binding !== undefined && turn !== null && turn !== undefined
+        && ["accepted", "running"].includes(turn.status)) {
+        binding = settleProviderTurn(binding, {
+            turnId: turn.turnId,
+            status: "cancelled",
+            settledAt: timestamp,
+            reason: "runtime-physical-exit"
+        });
+        taskSet = updateTaskRoleProviderRuntime(taskSet, binding, now);
+    }
+    else if (binding !== null && binding !== undefined && turn !== null && turn !== undefined
+        && ["submitting", "delivery-unknown"].includes(turn.status)) {
+        binding = settleProviderTurnSubmission(binding, {
+            attemptId: turn.attemptId,
+            status: "rejected",
+            resolvedAt: timestamp,
+            reason: "runtime-physical-exit"
+        });
+        taskSet = updateTaskRoleProviderRuntime(taskSet, binding, now);
     }
-    let updated = updateRoleAgentSessionStatus(set, set.activeAgentId, "stopped", now);
+    const activation = binding === null
+        ? null
+        : currentProviderActivation(binding);
     if (activation !== null) {
-        updated = updateTaskRoleProviderRuntime(updated, endProviderActivation(updated.providerBinding, activation.activationId, {
+        taskSet = updateTaskRoleProviderRuntime(taskSet, endProviderActivation(binding, activation.activationId, {
             status: "ended",
             endedAt: now.toISOString(),
             reason: "runtime-physical-exit"
         }), now);
     }
-    return updated;
+    return taskSet;
 }
 export function markTaskRoleRunPushed(set, fence, pushedAt) {
     validateRoleSessionSet(set);
@@ -450,7 +465,7 @@ export function recordTaskRoleTurnBoundary(set, input, completedAt) {
     assertTaskRoleSessionSet(set);
     const agentId = requireSafeIdentity(input.agentId, "Agent id");
     const nativeSessionId = requireText(input.nativeSessionId, "Native session id");
-    const turnId = requireSafeIdentity(input.turnId, "Turn id");
+    const turnId = requireText(input.turnId, "Turn id");
     const session = set.sessions[agentId];
     if (session === undefined || session.nativeSessionId !== nativeSessionId) {
         throw new Error("Completed Turn has no matching Role Agent native session.");
@@ -461,16 +476,12 @@ export function recordTaskRoleTurnBoundary(set, input, completedAt) {
         throw new Error("Completed Turn Agent does not match the in-flight Run.");
     }
     const timestamp = requireDate(completedAt, "Turn completedAt");
-    const status = session.status === "stopped" || session.status === "broken"
-        ? session.status
-        : "ready";
     return validateRoleSessionSet({
         ...set,
         sessions: {
             ...set.sessions,
             [agentId]: {
                 ...session,
-                status,
                 recentCompletedTurnIds: rememberRecentTurnId(session.recentCompletedTurnIds, turnId),
                 updatedAt: timestamp
             }
@@ -525,28 +536,22 @@ export function clearTaskRoleRun(set, fence, clearedAt) {
     return validateRoleSessionSet(updated);
 }
 /**
- * Applies an authoritative application-level Run terminal fact to the native
- * session fence. A later native Hook is only advisory and must not be required
- * to make the next Run dispatchable.
+ * Applies an authoritative application-level Run terminal fact to its exact
+ * delivery receipt. Provider lifecycle remains independent: only the matching
+ * native Turn boundary may move the Session from running to ready. AgentHost
+ * serializes a retained next delivery while that Turn is still active.
  */
 export function terminalizeTaskRoleRunSession(set, fence, terminalAt) {
     validateRoleSessionSet(set);
     const inFlight = set.inFlight;
-    let updated = inFlight === null
-        ? set
-        : clearTaskRoleRun(set, fence, terminalAt);
-    const session = updated.sessions[updated.activeAgentId];
-    if (session?.status === "running") {
-        updated = updateRoleAgentSessionStatus(updated, updated.activeAgentId, "ready", terminalAt);
-    }
-    return updated;
+    return inFlight === null ? set : clearTaskRoleRun(set, fence, terminalAt);
 }
 export function settleTaskRoleCompletion(set, expected, settledAt) {
     validateRoleSessionSet(set);
     assertTaskRoleSessionSet(set);
     const agentId = requireSafeIdentity(expected.agentId, "Agent id");
     const runId = requireSafeIdentity(expected.runId, "Run id");
-    const turnId = requireSafeIdentity(expected.turnId, "Turn id");
+    const turnId = requireText(expected.turnId, "Turn id");
     const inFlight = set.inFlight;
     if (inFlight === null || inFlight.agentId !== agentId || inFlight.runId !== runId) {
         throw new Error("Pending Turn completion does not match the in-flight Run.");
@@ -578,7 +583,7 @@ export function validateRoleSessionSet(set) {
         validateRoleAgentSession(session, agentId);
     }
     if (set.owner.scope === "global") {
-        if (set.schemaVersion !== 3) {
+        if (set.schemaVersion !== 4) {
             throw new Error("Global Role session set schema version is invalid.");
         }
         if (Object.hasOwn(set, "inFlight")
@@ -590,14 +595,14 @@ export function validateRoleSessionSet(set) {
             for (const [ref, session] of Object.entries(history)) {
                 requireSafeIdentity(ref, "Operator session ref");
                 validateRoleAgentSession(session);
-                if (session.status !== "stopped" && session.status !== "broken") {
+                if (session.status !== "ended") {
                     throw new Error(`Operator history session must be stopped: ${ref}.`);
                 }
             }
         }
     }
     else {
-        if (set.schemaVersion !== 6) {
+        if (set.schemaVersion !== 8) {
             throw new Error("Task Role session set schema version is invalid.");
         }
         if (!Object.hasOwn(set, "inFlight")
@@ -612,7 +617,7 @@ export function validateRoleSessionSet(set) {
             const identities = new Set();
             for (const session of taskSet.history) {
                 validateRoleAgentSession(session);
-                if (session.status !== "stopped" && session.status !== "broken") {
+                if (session.status !== "ended") {
                     throw new Error("Task Role session history must be terminal.");
                 }
                 const key = taskRoleSessionIdentity(session);
@@ -637,9 +642,6 @@ export function validateRoleSessionSet(set) {
             throw new Error("Task Role in-flight Run Agent must be active.");
         }
         if (providerBinding !== null) {
-            if (inFlight !== null && providerBinding.runId !== inFlight.runId) {
-                throw new Error("Provider Runtime Binding must match the in-flight Run.");
-            }
             const session = taskSet.sessions[inFlight?.agentId ?? set.activeAgentId];
             if (session === undefined) {
                 throw new Error("Provider Runtime Binding has no active Role Agent session.");
@@ -653,7 +655,7 @@ export function validateRoleSessionSet(set) {
     return set;
 }
 export function validateRoleAgentSession(session, expectedAgentId = session.agentId) {
-    if (session.schemaVersion !== 3) {
+    if (session.schemaVersion !== 4) {
         throw new Error(`Role Agent session schema version is invalid: ${expectedAgentId}.`);
     }
     const agentId = requireSafeIdentity(session.agentId, "Agent id");
@@ -691,6 +693,14 @@ export function validateRoleAgentSession(session, expectedAgentId = session.agen
     if (!isAgentSessionStatus(session.status)) {
         throw new Error(`Role Agent session status is invalid: ${agentId}.`);
     }
+    if (session.status === "active" && session.endReason !== undefined) {
+        throw new Error(`Active Role Agent session cannot have an end reason: ${agentId}.`);
+    }
+    if (session.status === "ended"
+        && session.endReason !== "stopped"
+        && session.endReason !== "failed") {
+        throw new Error(`Ended Role Agent session requires an end reason: ${agentId}.`);
+    }
     validateRecentTurnIds(session.recentCompletedTurnIds);
     requireText(session.createdAt, "Role Agent session creation timestamp");
     requireText(session.updatedAt, "Role Agent session update timestamp");
@@ -820,7 +830,7 @@ function normalizeOwner(owner) {
         };
 }
 function isAgentSessionStatus(value) {
-    return ["reserved", "ready", "running", "stopped", "broken"].includes(value);
+    return value === "active" || value === "ended";
 }
 function requireSafeIdentity(value, label) {
     const normalized = requireText(value, label);

package/dist/executor/executorRegistry.js

@@ -82,7 +82,10 @@ export class ExecutorRegistry {
                     : {
                         ...common,
                         mode: "resume",
-                        nativeSessionId: input.nativeSessionId
+                        nativeSessionId: input.nativeSessionId,
+                        ...(input.hostActivationId === undefined
+                            ? {}
+                            : { hostActivationId: input.hostActivationId })
                     }, "deferred", undefined, input.beforeHostStart);
             }
             else {
@@ -100,7 +103,7 @@ export class ExecutorRegistry {
                     });
                 binding = request.mode === "new"
                     ? await this.runtimePorts.sessionHost.start(request, input.beforeHostStart)
-                    : await this.runtimePorts.sessionHost.resume(request, input.beforeHostStart);
+                    : await this.runtimePorts.sessionHost.restore(request, input.beforeHostStart);
             }
             sessionStarted = binding.hostCreated === true;
             session = binding.nativeSessionId === undefined
@@ -109,7 +112,7 @@ export class ExecutorRegistry {
                     agentId: binding.agentId,
                     adapterId: binding.adapterId,
                     nativeSessionId: binding.nativeSessionId,
-                    status: "ready",
+                    status: "active",
                     effective: input.effective
                 };
         }
@@ -118,22 +121,6 @@ export class ExecutorRegistry {
             ...(binding === undefined ? {} : { launchId: binding.launchId }),
             sessionStarted,
             session,
-            ...(input.runId !== undefined
-                && ((binding?.initialTurnRunId === input.runId))
-                ? { turnAcceptedDuringLaunch: true }
-                : {}),
-            ...(input.runId !== undefined
-                && binding?.initialTurnDeliveryUnknownRunId === input.runId
-                ? { turnDeliveryUnknownDuringLaunch: true }
-                : {}),
-            ...(input.runId !== undefined
-                && binding?.initialTurnBusyRunId === input.runId
-                ? { turnBusyDuringLaunch: true }
-                : {}),
-            ...(input.runId !== undefined
-                && binding?.initialTurnRejectedRunId === input.runId
-                ? { turnRejectedDuringLaunch: true }
-                : {})
         };
         this.#prepared.set(delivery.deliveryId, {
             delivery,
@@ -362,7 +349,8 @@ function preparedDeliveryId(input) {
         input.effective,
         input.mode,
         input.runId ?? null,
-        input.nativeSessionId ?? null
+        input.nativeSessionId ?? null,
+        input.hostActivationId ?? null
     ])).digest("hex");
 }
 function hasText(value) {