@zq-silk/yui 0.6.9 → 0.6.11

package/dist/runtime/runtimeObservation.js

@@ -6,6 +6,10 @@ const KINDS = [
     "session.ready",
     "session.ended",
     "session.failed",
+    "conversation.observed",
+    "activation.started",
+    "activation.ended",
+    "activation.failed",
     "turn.accepted",
     "turn.waiting",
     "turn.completed",
@@ -14,6 +18,12 @@ const KINDS = [
     "operation.started",
     "operation.completed",
     "operation.failed",
+    "native-work.snapshot",
+    "continuation.started",
+    "continuation.reported",
+    "continuation.settled",
+    "input.accepted",
+    "input.delivery-unknown",
     "activity.observed",
     "observer.health"
 ];
@@ -37,6 +47,11 @@ const RUN_SCOPED = new Set([
     "activity.observed",
     "observer.health"
 ]);
+const CONTINUATION_SCOPED = new Set([
+    "continuation.started",
+    "continuation.reported",
+    "continuation.settled"
+]);
 const PROVIDER_STATE = new Set([
     "session.started",
     "session.ready",
@@ -52,8 +67,8 @@ const PROVIDER_STATE = new Set([
     "operation.failed"
 ]);
 export function createRuntimeObservation(input) {
-    if (input.schemaVersion !== 1)
-        throw new Error("Runtime observation schemaVersion must be 1.");
+    if (input.schemaVersion !== 2)
+        throw new Error("Runtime observation schemaVersion must be 2.");
     if (!KINDS.includes(input.kind))
         throw new Error("Runtime observation kind is invalid.");
     if (!AUTHORITIES.includes(input.authority))
@@ -76,6 +91,22 @@ export function createRuntimeObservation(input) {
     if (RUN_SCOPED.has(input.kind) && fence.nativeTurnId === undefined) {
         throw new Error(`${input.kind} requires nativeTurnId.`);
     }
+    if ((input.kind.startsWith("activation.") || CONTINUATION_SCOPED.has(input.kind)
+        || input.kind === "native-work.snapshot")
+        && fence.activationId === undefined) {
+        throw new Error(`${input.kind} requires activationId.`);
+    }
+    if ((input.kind === "conversation.observed" || input.kind.startsWith("activation.")
+        || CONTINUATION_SCOPED.has(input.kind) || input.kind === "native-work.snapshot")
+        && fence.conversationId === undefined) {
+        throw new Error(`${input.kind} requires conversationId.`);
+    }
+    if (CONTINUATION_SCOPED.has(input.kind) && fence.continuationId === undefined) {
+        throw new Error(`${input.kind} requires continuationId.`);
+    }
+    if (CONTINUATION_SCOPED.has(input.kind) && fence.continuationGeneration === undefined) {
+        throw new Error(`${input.kind} requires continuationGeneration.`);
+    }
     const payload = normalizePayload(input.kind, input.payload);
     const sequence = input.sequence;
     if (sequence !== undefined && (!Number.isSafeInteger(sequence) || sequence < 0)) {
@@ -86,8 +117,9 @@ export function createRuntimeObservation(input) {
         throw new Error("Runtime observation ordinal must be a non-negative safe integer.");
     }
     return Object.freeze({
-        schemaVersion: 1,
+        schemaVersion: 2,
         eventId: requireIdentity(input.eventId, "Runtime observation event id"),
+        semanticKey: requireIdentity(input.semanticKey, "Runtime observation semantic key"),
         kind: input.kind,
         authority: input.authority,
         receivedAt: requireTimestamp(input.receivedAt, "Runtime observation receivedAt"),
@@ -109,6 +141,11 @@ export function runtimeObservationFenceMatches(expected, actual) {
         "driverId",
         "launchId",
         "sessionGenerationId",
+        "conversationId",
+        "activationId",
+        "continuationId",
+        "continuationGeneration",
+        "parentContinuationId",
         "nativeSessionId",
         "nativeTurnId",
         "receiptId"
@@ -121,7 +158,9 @@ export function runtimeObservationFenceMatches(expected, actual) {
 /**
  * Matches observations that belong to one durable Run/session generation.
  * A provider may advance its native Turn while background subagents from an
- * earlier Turn are still active, so nativeTurnId is intentionally excluded.
+ * earlier Turn are still active and later mailbox activations use their own
+ * exactly-once receipt, so nativeTurnId and receiptId are intentionally
+ * excluded. Exact acceptance still validates both fields before persistence.
  */
 export function runtimeObservationRunFenceMatches(expected, actual) {
     for (const field of [
@@ -132,8 +171,7 @@ export function runtimeObservationRunFenceMatches(expected, actual) {
         "driverId",
         "launchId",
         "sessionGenerationId",
-        "nativeSessionId",
-        "receiptId"
+        "nativeSessionId"
     ]) {
         if (expected[field] !== actual[field])
             return false;
@@ -145,6 +183,7 @@ export function runtimeObservationTaskEventPayload(input) {
     const observation = createRuntimeObservation(input);
     return Object.freeze({
         eventId: observation.eventId,
+        semanticKey: observation.semanticKey,
         roleName: observation.fence.roleName,
         agentId: observation.fence.agentId,
         driverId: observation.fence.driverId,
@@ -187,7 +226,26 @@ function normalizeFence(input) {
             : { nativeTurnId: requireIdentity(input.nativeTurnId, "Native Turn id") }),
         ...(input.receiptId === undefined
             ? {}
-            : { receiptId: requireIdentity(input.receiptId, "Receipt id") })
+            : { receiptId: requireIdentity(input.receiptId, "Receipt id") }),
+        ...(input.conversationId === undefined
+            ? {}
+            : { conversationId: requireIdentity(input.conversationId, "Provider Conversation id") }),
+        ...(input.activationId === undefined
+            ? {}
+            : { activationId: requireIdentity(input.activationId, "Provider Activation id") }),
+        ...(input.continuationId === undefined
+            ? {}
+            : { continuationId: requireIdentity(input.continuationId, "Provider Continuation id") }),
+        ...(input.continuationGeneration === undefined
+            ? {}
+            : {
+                continuationGeneration: requireNonNegativeInteger(input.continuationGeneration, 1, "Provider Continuation generation")
+            }),
+        ...(input.parentContinuationId === undefined
+            ? {}
+            : {
+                parentContinuationId: requireIdentity(input.parentContinuationId, "Parent Provider Continuation id")
+            })
     });
 }
 function normalizePayload(kind, input) {
@@ -230,6 +288,41 @@ function normalizePayload(kind, input) {
     if (kind === "turn.failed" && input.failure === undefined) {
         throw new Error("turn.failed requires normalized failure evidence.");
     }
+    if (kind === "conversation.observed"
+        && !["unknown", "recoverable", "unrecoverable"].includes(input.recoverability ?? "")) {
+        throw new Error("conversation.observed requires recoverability.");
+    }
+    if (kind === "native-work.snapshot") {
+        if (typeof input.snapshotComplete !== "boolean"
+            || !["exact", "partial", "unavailable"].includes(input.observationQuality ?? "")) {
+            throw new Error("native-work.snapshot requires completeness and observation quality.");
+        }
+        if (input.snapshotComplete && input.observationQuality !== "exact") {
+            throw new Error("A complete native-work.snapshot requires exact observation quality.");
+        }
+    }
+    if (kind.startsWith("continuation.")) {
+        if (!["active", "quiescent", "unknown"].includes(input.execution ?? "")) {
+            throw new Error(`${kind} requires continuation execution.`);
+        }
+        if (!["pending", "succeeded", "failed", "cancelled", "unknown"].includes(input.outcome ?? "")) {
+            throw new Error(`${kind} requires continuation outcome.`);
+        }
+        if (input.attachment !== "attached" && input.attachment !== "detached") {
+            throw new Error(`${kind} requires continuation attachment.`);
+        }
+        if (!["exact", "partial", "unavailable"].includes(input.observationQuality ?? "")) {
+            throw new Error(`${kind} requires continuation observation quality.`);
+        }
+        if (typeof input.mayWriteWorkspace !== "boolean") {
+            throw new Error(`${kind} requires mayWriteWorkspace.`);
+        }
+        if (kind === "continuation.reported")
+            requireIdentity(input.reportId, "Provider report id");
+        if (kind === "continuation.settled" && input.observationQuality !== "exact") {
+            throw new Error("continuation.settled requires exact observation quality.");
+        }
+    }
     const failure = input.failure === undefined
         ? undefined
         : normalizeFailure(input.failure);
@@ -255,9 +348,92 @@ function normalizePayload(kind, input) {
             ? {}
             : { observerDetail: requireText(input.observerDetail, "Runtime observer detail") }),
         ...(failure === undefined ? {} : { failure }),
-        ...(input.summary === undefined ? {} : { summary: requireText(input.summary, "Runtime summary") })
+        ...(input.summary === undefined ? {} : { summary: requireText(input.summary, "Runtime summary") }),
+        ...(input.execution === undefined ? {} : { execution: input.execution }),
+        ...(input.outcome === undefined ? {} : { outcome: input.outcome }),
+        ...(input.attachment === undefined ? {} : { attachment: input.attachment }),
+        ...(input.observationQuality === undefined
+            ? {}
+            : { observationQuality: input.observationQuality }),
+        ...(input.mayWriteWorkspace === undefined
+            ? {}
+            : { mayWriteWorkspace: input.mayWriteWorkspace }),
+        ...(input.resultRef === undefined
+            ? {}
+            : { resultRef: requireIdentity(input.resultRef, "Provider result ref") }),
+        ...(input.reportId === undefined
+            ? {}
+            : { reportId: requireIdentity(input.reportId, "Provider report id") }),
+        ...(input.providerDeliveryRef === undefined
+            ? {}
+            : {
+                providerDeliveryRef: requireIdentity(input.providerDeliveryRef, "Provider delivery ref")
+            }),
+        ...(input.snapshotComplete === undefined
+            ? {}
+            : { snapshotComplete: input.snapshotComplete }),
+        ...(input.recoverability === undefined
+            ? {}
+            : { recoverability: input.recoverability })
     });
 }
+export function runtimeObservationSemanticKey(input) {
+    const fence = input.fence;
+    const continuationIdentity = [
+        fence.driverId,
+        fence.agentId,
+        fence.conversationId ?? fence.nativeSessionId ?? fence.launchId,
+        fence.activationId ?? fence.launchId,
+        fence.continuationId ?? "none",
+        fence.continuationGeneration ?? "none"
+    ];
+    // Terminal boundaries are semantic facts. Providers may replay them with a
+    // fresh transport sequence after reconnect, so terminal identity must win
+    // over occurrence ordering or one SessionEnd storm becomes many facts.
+    if (["session.ended", "session.failed", "activation.ended", "activation.failed",
+        "turn.completed", "turn.failed", "turn.cancelled", "continuation.settled"].includes(input.kind)) {
+        return [
+            "terminal",
+            ...continuationIdentity,
+            fence.continuationId ?? fence.nativeTurnId ?? "none",
+            input.kind,
+            input.payload?.outcome ?? input.payload?.failure?.code ?? "terminal",
+            input.kind === "continuation.settled" ? input.payload?.resultRef ?? "none" : "none",
+            input.kind === "turn.failed" && input.payload?.failure?.runTerminal === true
+                ? "run-terminal"
+                : "turn-terminal"
+        ].join(":");
+    }
+    if (input.kind === "continuation.reported") {
+        return ["continuation-report", ...continuationIdentity, input.payload?.reportId ?? "missing"]
+            .join(":");
+    }
+    if (input.kind === "continuation.started") {
+        return [
+            "continuation-state",
+            ...continuationIdentity,
+            input.payload?.execution ?? "unknown",
+            input.payload?.attachment ?? "unknown",
+            input.payload?.observationQuality ?? "unknown",
+            input.payload?.mayWriteWorkspace === true ? "writer" : "read-only",
+            input.payload?.outcome ?? "unknown",
+            input.payload?.resultRef ?? "none"
+        ].join(":");
+    }
+    if (input.sequence !== undefined) {
+        return [
+            "provider-sequence",
+            fence.driverId,
+            fence.conversationId ?? fence.nativeSessionId ?? fence.launchId,
+            fence.activationId ?? fence.launchId,
+            fence.continuationId ?? fence.nativeTurnId ?? "none",
+            fence.continuationGeneration ?? "none",
+            input.sequence,
+            input.kind
+        ].join(":");
+    }
+    return `provider-event:${requireIdentity(input.eventId, "Runtime observation event id")}`;
+}
 function normalizeObserverSource(input) {
     if (input === null || typeof input !== "object" || Array.isArray(input)) {
         throw new Error("Runtime observer source must be an object.");
@@ -283,9 +459,17 @@ function normalizeFailure(input) {
             : { details: requireText(input.details, "Runtime failure details") }),
         ...(input.lastOutput === undefined
             ? {}
-            : { lastOutput: requireText(input.lastOutput, "Runtime failure last output") })
+            : { lastOutput: requireText(input.lastOutput, "Runtime failure last output") }),
+        ...(input.runTerminal === undefined
+            ? {}
+            : { runTerminal: requireBoolean(input.runTerminal, "Runtime failure runTerminal") })
     });
 }
+function requireBoolean(value, label) {
+    if (typeof value !== "boolean")
+        throw new Error(`${label} must be boolean.`);
+    return value;
+}
 function validateUsage(input) {
     for (const [name, value] of Object.entries(input)) {
         if (!Number.isSafeInteger(value) || value < 0) {
@@ -302,6 +486,11 @@ function requireTimestamp(value, label) {
         throw new Error(`${label} is invalid.`);
     return timestamp;
 }
+function requireNonNegativeInteger(value, minimum, label) {
+    if (!Number.isSafeInteger(value) || value < minimum)
+        throw new Error(`${label} is invalid.`);
+    return value;
+}
 function requireIdentity(value, label) {
     const identity = requireText(value, label);
     if (identity.includes("/../") || identity === "__proto__")

package/dist/runtime/runtimeProjection.js

@@ -6,6 +6,14 @@ export function createRuntimeProjection(fence, createdAt) {
         host: "unknown",
         session: "unknown",
         turn: "none",
+        conversation: "unknown",
+        activation: "none",
+        continuations: Object.freeze({}),
+        inputDelivery: "none",
+        runActivity: "starting",
+        health: "reconciling",
+        waitingOn: Object.freeze([]),
+        attention: Object.freeze([]),
         operations: Object.freeze({}),
         activity: Object.freeze({ kind: "none" }),
         observer: Object.freeze({ status: "unknown" }),
@@ -40,24 +48,36 @@ export function projectRuntimeObservation(current, raw) {
                 stateSince: at
             });
         case "session.started":
-            return next(current, { session: "started", stateSince: at });
+            return next(current, {
+                session: "started",
+                conversation: "recoverable",
+                activation: "active",
+                stateSince: at
+            });
         case "session.ready":
             return next(current, { session: "ready", stateSince: at });
         case "session.ended":
             return next(current, {
                 session: "ended",
+                activation: "ended",
                 turn: terminalTurn(current.turn),
-                operations: Object.freeze({}),
+                // A parent provider Session ending is independent from native child
+                // operations already observed under the Run. Keep those children
+                // visible until their own terminal facts arrive; host/session loss is
+                // health evidence, not proof that child work or the Yui Run ended.
+                operations: activeSubagentOperations(current.operations),
                 stateSince: at
             });
         case "session.failed":
             return next(current, {
                 session: "failed",
+                activation: "failed",
                 turn: current.turn === "none" ? "failed" : terminalTurn(current.turn, "failed"),
-                operations: Object.freeze({}),
+                operations: activeSubagentOperations(current.operations),
                 stateSince: at
             });
         case "turn.accepted":
+        case "input.accepted":
             return withActivity(next(current, {
                 session: "active",
                 turn: "accepted",
@@ -107,7 +127,9 @@ export function projectRuntimeObservation(current, raw) {
             const operationId = event.payload.operationId;
             const operation = event.payload.operation;
             return withActivity(next(current, {
-                session: "active",
+                session: current.session === "ended" || current.session === "failed"
+                    ? current.session
+                    : "active",
                 turn: current.turn === "waiting" ? "accepted" : current.turn,
                 waitingReason: undefined,
                 waitId: undefined,
@@ -123,7 +145,9 @@ export function projectRuntimeObservation(current, raw) {
             const operations = { ...current.operations };
             delete operations[event.payload.operationId];
             return withActivity(next(current, {
-                session: "active",
+                session: current.session === "ended" || current.session === "failed"
+                    ? current.session
+                    : "active",
                 turn: current.turn === "waiting" ? "accepted" : current.turn,
                 waitingReason: undefined,
                 waitId: undefined,
@@ -154,6 +178,82 @@ export function projectRuntimeObservation(current, raw) {
                         : { detail: event.payload.observerDetail })
                 })
             });
+        case "conversation.observed":
+            return next(current, {
+                conversation: event.payload.recoverability === "unrecoverable"
+                    ? "unrecoverable"
+                    : event.payload.recoverability === "recoverable" ? "recoverable" : "unknown"
+            });
+        case "activation.started":
+            return next(current, { activation: "active", stateSince: at });
+        case "activation.ended":
+            return next(current, { activation: "ended", stateSince: at });
+        case "activation.failed":
+            return next(current, { activation: "failed", stateSince: at });
+        case "continuation.started":
+        case "continuation.reported":
+        case "continuation.settled": {
+            const id = [
+                event.fence.activationId,
+                event.fence.continuationId,
+                event.fence.continuationGeneration
+            ].join("/");
+            const existing = current.continuations[id];
+            if (event.kind === "continuation.reported") {
+                // A report is an attachment, not lifecycle evidence. When it races
+                // ahead of continuation.started, retain a conservative writer-owned
+                // stub until structured start/settlement metadata arrives.
+                const reported = existing ?? Object.freeze({
+                    execution: "unknown",
+                    outcome: "pending",
+                    attachment: event.payload.attachment ?? "detached",
+                    observation: "unavailable",
+                    mayWriteWorkspace: true,
+                    identityConflict: false
+                });
+                return next(current, {
+                    continuations: Object.freeze({
+                        ...current.continuations,
+                        [id]: Object.freeze({
+                            ...reported,
+                            ...(event.payload.resultRef === undefined
+                                ? {}
+                                : { resultRef: event.payload.resultRef })
+                        })
+                    }),
+                    stateSince: at
+                });
+            }
+            const settled = existing?.execution === "quiescent" && existing.observation === "exact";
+            const conflicts = settled && (event.payload.execution !== "quiescent"
+                || event.payload.outcome !== existing.outcome);
+            return next(current, {
+                continuations: Object.freeze({
+                    ...current.continuations,
+                    [id]: Object.freeze(conflicts
+                        ? { ...existing, identityConflict: true }
+                        : {
+                            execution: event.payload.execution,
+                            outcome: event.payload.outcome,
+                            attachment: event.payload.attachment,
+                            observation: event.payload.observationQuality,
+                            mayWriteWorkspace: event.payload.observationQuality === "exact"
+                                ? event.payload.mayWriteWorkspace
+                                : (existing?.mayWriteWorkspace ?? false)
+                                    || event.payload.mayWriteWorkspace,
+                            identityConflict: existing?.identityConflict ?? false,
+                            ...(event.payload.resultRef === undefined
+                                ? existing?.resultRef === undefined ? {} : { resultRef: existing.resultRef }
+                                : { resultRef: event.payload.resultRef })
+                        })
+                }),
+                stateSince: at
+            });
+        }
+        case "input.delivery-unknown":
+            return next(current, { inputDelivery: "delivery-unknown", stateSince: at });
+        case "native-work.snapshot":
+            return next(current, {});
         default:
             return current;
     }
@@ -176,12 +276,27 @@ export function completeRuntimeWorkflow(current, completedAt) {
         })
     });
 }
+export function projectRuntimeMailbox(current, mailbox) {
+    if (mailbox?.inputDelivery === undefined || mailbox.inputDelivery === null) {
+        return next(current, { inputDelivery: "none" });
+    }
+    return next(current, {
+        inputDelivery: mailbox.inputDelivery.status === "delivery-unknown"
+            ? "delivery-unknown"
+            : "dispatching"
+    });
+}
 export function runtimeDisplayStatus(current) {
     if (current.session === "failed")
         return "broken";
+    const operation = dominantOperation(current.operations);
+    // Provider-owned child work can outlive the parent Session. Surface the
+    // child as active while retaining host/session health orthogonally in the
+    // projection instead of collapsing both facts into "stopped".
+    if (operation === "subagent")
+        return "subagent-active";
     if (current.host === "exited" || current.session === "ended")
         return "stopped";
-    const operation = dominantOperation(current.operations);
     if (operation !== null)
         return `${operation}-active`;
     if (current.turn === "waiting")
@@ -239,7 +354,47 @@ function next(current, patch) {
     }
     if (patch.waitId === undefined && Object.hasOwn(patch, "waitId"))
         delete copy.waitId;
-    return Object.freeze(copy);
+    const continuations = Object.entries(copy.continuations);
+    const waitingNative = continuations.filter(([, continuation]) => (continuation.execution === "active" || continuation.execution === "unknown"));
+    const activeNativeOperations = Object.entries(copy.operations).filter(([, operation]) => (operation.kind === "subagent"));
+    const waitingOn = [
+        ...waitingNative.map(([id]) => `native:${id}`),
+        ...activeNativeOperations.map(([id]) => `native-operation:${id}`)
+    ];
+    const attention = [
+        ...(copy.inputDelivery === "delivery-unknown" ? ["delivery-unknown"] : []),
+        ...continuations.flatMap(([id, continuation]) => (continuation.identityConflict ? [`identity-conflict:${id}`]
+            : continuation.observation === "unavailable" ? [`continuation-unresolved:${id}`]
+                : [])),
+        ...(copy.conversation === "unrecoverable" ? ["leader-decision-needed"] : []),
+        ...(copy.host === "exited" || copy.session === "ended" || copy.session === "failed"
+            ? ["runtime-unobservable"]
+            : [])
+    ];
+    const health = copy.observer.status === "unavailable"
+        || waitingNative.some(([, continuation]) => continuation.observation === "unavailable")
+        || copy.host === "exited"
+        || copy.session === "ended"
+        || copy.session === "failed"
+        ? "unobservable"
+        : copy.inputDelivery === "dispatching"
+            || (copy.activation !== "active" && waitingNative.length > 0)
+            ? "reconciling"
+            : "healthy";
+    const runActivity = copy.inputDelivery === "dispatching"
+        || copy.turn === "accepted"
+        || copy.session === "active"
+        ? "running"
+        : waitingNative.length > 0 || activeNativeOperations.length > 0 ? "waiting"
+            : copy.session === "unknown" || copy.session === "started" ? "starting"
+                : "parked";
+    return Object.freeze({
+        ...copy,
+        waitingOn: Object.freeze(waitingOn),
+        attention: Object.freeze([...new Set(attention)]),
+        health,
+        runActivity
+    });
 }
 function usageAdvanced(previous, current) {
     // A first cumulative snapshot may contain history from a resumed native