@zq-silk/yui 0.14.0 → 0.14.2

package/dist/controller/structuredProviderObservation.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { callController } from "../core/controllerClient.js";
 import { builtinAgentDriverRegistry } from "../runtime/builtinAgentDrivers.js";
 import { standardAgentError } from "../runtime/agentError.js";
+import { transportAgentResult } from "../domain/agentResultTransport.js";
 import { createRuntimeObservation, runtimeObservationSemanticKey } from "../runtime/runtimeObservation.js";
 import { runtimeLifecycleSignalKey } from "../runtime/lifecycleReservation.js";
 import { isForeignHandoverLockHeld } from "../release/runtimeRelease.js";
@@ -28,8 +29,7 @@ export async function publishStructuredProviderStarted(input) {
             roleName: fence.roleName,
             agentId: fence.agentId,
             driverId: driver.id,
-            launchId: fence.launchId,
-            sessionGenerationId: fence.launchId,
+            runtimeGenerationId: fence.runtimeGenerationId,
             conversationId: input.started.conversationId,
             activationId: requireIdentity(input.activationId, "Provider Activation id"),
             nativeSessionId: input.started.nativeSessionId,
@@ -56,8 +56,7 @@ export async function publishStructuredProviderAccepted(input) {
         ...(fence.turnId === undefined ? {} : { turnId: fence.turnId }),
         agentId: fence.agentId,
         driverId: driver.id,
-        launchId: fence.launchId,
-        sessionGenerationId: fence.launchId,
+        runtimeGenerationId: fence.runtimeGenerationId,
         conversationId: input.receipt.conversationId,
         activationId: requireIdentity(input.activationId, "Provider Activation id"),
         nativeSessionId: input.receipt.nativeSessionId,
@@ -107,8 +106,7 @@ export async function publishStructuredProviderOpened(input) {
         ...(fence.turnId === undefined ? {} : { turnId: fence.turnId }),
         agentId: fence.agentId,
         driverId: driver.id,
-        launchId: fence.launchId,
-        sessionGenerationId: fence.launchId,
+        runtimeGenerationId: fence.runtimeGenerationId,
         conversationId: input.conversationId,
         activationId: requireIdentity(input.activationId, "Provider Activation id"),
         nativeSessionId: input.nativeSessionId,
@@ -153,8 +151,7 @@ export async function publishStructuredProviderGoal(input) {
             roleName: fence.roleName,
             agentId: fence.agentId,
             driverId: driver.id,
-            launchId: fence.launchId,
-            sessionGenerationId: fence.launchId,
+            runtimeGenerationId: fence.runtimeGenerationId,
             conversationId: input.conversationId,
             activationId: requireIdentity(input.activationId, "Provider Activation id"),
             nativeSessionId: input.conversationId
@@ -180,8 +177,7 @@ export async function publishStructuredConversationRecoverability(input) {
         ...(fence.turnId === undefined ? {} : { turnId: fence.turnId }),
         agentId: fence.agentId,
         driverId: driver.id,
-        launchId: fence.launchId,
-        sessionGenerationId: fence.launchId,
+        runtimeGenerationId: fence.runtimeGenerationId,
         conversationId: input.conversationId,
         activationId: requireIdentity(input.activationId, "Provider Activation id"),
         nativeSessionId: input.conversationId,
@@ -224,10 +220,13 @@ export async function publishStructuredProviderTerminal(input) {
     const kind = input.terminal.status === "completed"
         ? "turn.completed"
         : input.terminal.status === "cancelled" ? "turn.cancelled" : "turn.failed";
+    const transported = transportAgentResult(input.terminal.output);
     const payload = kind === "turn.completed"
         ? {
             ...(input.terminal.input === undefined ? {} : { input: input.terminal.input }),
-            ...(input.terminal.summary === undefined ? {} : { summary: input.terminal.summary })
+            ...(transported.status === "completed"
+                ? { output: transported.output }
+                : { resultTransportDiagnostic: transported.diagnostic })
         }
         : kind === "turn.failed"
             ? {
@@ -263,8 +262,7 @@ export async function publishStructuredProviderTerminal(input) {
             ...(fence.turnId === undefined ? {} : { turnId: fence.turnId }),
             agentId: fence.agentId,
             driverId: driver.id,
-            launchId: fence.launchId,
-            sessionGenerationId: fence.launchId,
+            runtimeGenerationId: fence.runtimeGenerationId,
             conversationId: input.terminal.conversationId,
             activationId: requireIdentity(input.activationId, "Provider Activation id"),
             nativeSessionId: input.terminal.nativeSessionId,
@@ -290,8 +288,7 @@ export async function publishStructuredProviderActivationTerminal(input) {
             ...(fence.turnId === undefined ? {} : { turnId: fence.turnId }),
             agentId: fence.agentId,
             driverId: driver.id,
-            launchId: fence.launchId,
-            sessionGenerationId: fence.launchId,
+            runtimeGenerationId: fence.runtimeGenerationId,
             conversationId: requireIdentity(input.conversationId, "Provider Conversation id"),
             activationId: requireIdentity(input.activationId, "Provider Activation id"),
             nativeSessionId: requireIdentity(input.nativeSessionId, "native Session id"),
@@ -311,7 +308,7 @@ function observation(input) {
         payload: input.payload ?? {}
     };
     return createRuntimeObservation({
-        schemaVersion: 2,
+        schemaVersion: 4,
         eventId,
         semanticKey: runtimeObservationSemanticKey(partial),
         kind: input.kind,

package/dist/coordination/workMailboxQueue.js

@@ -1,4 +1,11 @@
 import { completeProcessing, consumePendingBatch, createWorkMailbox, enqueueSignal, mailboxBatches, mailboxEntityRefKey } from "./workMailbox.js";
+const LEGACY_ROLE_TURN_DISPATCH_REASONS = new Set([
+    "turn-dispatched",
+    "turn-retried",
+    "review-requested",
+    "workitem-synthesis-ready",
+    "review-synthesis-ready"
+]);
 /** Atomically useful when called inside the caller's TaskStore transaction. */
 export function enqueueWork(store, target, reason, occurredAt, refs = [], metadata = {}) {
     const mailbox = store.getWorkMailbox(target) ?? createWorkMailbox(target);
@@ -11,6 +18,106 @@ export function enqueueWork(store, target, reason, occurredAt, refs = [], metada
     store.saveWorkMailbox(queued);
     return queued;
 }
+/**
+ * The sole ordinary Role Turn wake shape. The Turn is durable execution
+ * authority; this signal only asks the Controller to deliver that exact Turn.
+ * Leader is deliberately excluded because its Role mailbox is reserved for
+ * semantic event wakes and force-steer batches. A Leader active Turn is
+ * selected directly from durable state by its targeted Controller pass.
+ */
+export function enqueueRoleTurnDispatch(store, input) {
+    if (input.roleName === "leader")
+        return null;
+    return enqueueWork(store, roleTurnTarget(input), input.reason, input.occurredAt, [roleTurnRef(input)], {
+        source: "turn-dispatch",
+        dedupeKey: roleTurnDispatchDedupeKey(input)
+    });
+}
+/**
+ * Captures only the mailbox prefix that contains one exact Role Turn dispatch.
+ * A later signal may append while Provider delivery is in flight; its suffix
+ * remains pending when this token is settled.
+ */
+export function captureRoleTurnDispatch(mailbox, input) {
+    if (input.roleName === "leader"
+        || mailbox === null
+        || mailbox.target.kind !== "role"
+        || mailbox.target.taskId !== input.taskId
+        || mailbox.target.roleName !== input.roleName) {
+        return null;
+    }
+    const exactRef = roleTurnRef(input);
+    if (mailbox.processing?.executionRef !== undefined
+        && mailboxEntityRefKey(mailbox.processing.executionRef) === mailboxEntityRefKey(exactRef)) {
+        return {
+            kind: "processing",
+            batchId: mailbox.processing.batchId
+        };
+    }
+    const pending = mailbox.pending;
+    if (pending === null)
+        return null;
+    const dedupeKey = roleTurnDispatchDedupeKey(input);
+    if (mailbox.recentDedupeKeys.includes(dedupeKey))
+        return null;
+    const keyIndex = pending.dedupeKeys.indexOf(dedupeKey);
+    if (keyIndex >= 0 && pending.dedupeKeys.length === pending.requestCount) {
+        const turnSequence = pending.fromSequence + keyIndex;
+        if (turnSequence <= pending.toSequence) {
+            return {
+                kind: "pending",
+                fromSequence: pending.fromSequence,
+                toSequence: turnSequence
+            };
+        }
+    }
+    // Valid earlier dispatches used sequence-generated dedupe keys and could
+    // include a companion WorkItem ref. Consume that complete legacy batch once
+    // the exact Turn reaches an accepted or terminal boundary.
+    if (pending.requestCount === 1
+        && pending.sources.length === 1
+        && pending.sources[0] === "yui"
+        && pending.reasons.some((reason) => LEGACY_ROLE_TURN_DISPATCH_REASONS.has(reason))
+        && pending.refs.some((ref) => (mailboxEntityRefKey(ref) === mailboxEntityRefKey(exactRef)))) {
+        return {
+            kind: "pending",
+            fromSequence: pending.fromSequence,
+            toSequence: pending.toSequence
+        };
+    }
+    return null;
+}
+/**
+ * Settles one exact ordinary Role Turn dispatch. Provider acceptance is the
+ * normal boundary; terminalization calls the same operation for conclusively
+ * unaccepted and valid earlier dispatches.
+ */
+export function settleRoleTurnDispatch(store, input, expected) {
+    if (expected === null)
+        return "absent";
+    const target = roleTurnTarget(input);
+    const mailbox = store.getWorkMailbox(target);
+    const current = captureRoleTurnDispatch(mailbox, input);
+    if (current === null || mailbox === null)
+        return "absent";
+    if (expected !== undefined && !sameRoleTurnDispatchToken(current, expected)) {
+        return "state-changed";
+    }
+    const token = expected ?? current;
+    if (token.kind === "processing") {
+        if (mailbox.processing?.batchId !== token.batchId)
+            return "state-changed";
+        store.saveWorkMailbox(completeProcessing(mailbox, token.batchId));
+        return "settled";
+    }
+    if (mailbox.pending === null
+        || mailbox.pending.fromSequence !== token.fromSequence
+        || mailbox.pending.toSequence < token.toSequence) {
+        return "state-changed";
+    }
+    store.saveWorkMailbox(consumePendingBatch(mailbox, token));
+    return "settled";
+}
 /** Completes only the batch owned by the matching durable execution. */
 export function completeWorkExecution(store, target, executionRef) {
     const mailbox = store.getWorkMailbox(target);
@@ -76,6 +183,31 @@ export function settleExactWorkExecution(store, target, executionRef) {
 function timestamp(value) {
     return value instanceof Date ? value.toISOString() : value;
 }
+function roleTurnTarget(input) {
+    return {
+        kind: "role",
+        taskId: input.taskId,
+        roleName: input.roleName
+    };
+}
+function roleTurnRef(input) {
+    return {
+        type: "turn",
+        taskId: input.taskId,
+        id: input.turnId
+    };
+}
+function roleTurnDispatchDedupeKey(input) {
+    return `role-turn:${input.taskId}:${input.roleName}:${input.turnId}`;
+}
+function sameRoleTurnDispatchToken(left, right) {
+    return left.kind === right.kind
+        && (left.kind === "pending"
+            ? right.kind === "pending"
+                && left.fromSequence === right.fromSequence
+                && left.toSequence === right.toSequence
+            : right.kind === "processing" && left.batchId === right.batchId);
+}
 function targetLabel(target) {
     switch (target.kind) {
         case "operator": return "operator";

package/dist/core/controllerServer.js

@@ -593,6 +593,7 @@ function parseBeginHandoverParams(value) {
     }
     const fromReleaseId = record.fromReleaseId;
     if (fromReleaseId !== undefined
+        && fromReleaseId !== null
         && (typeof fromReleaseId !== "string" || fromReleaseId.length > 256)) {
         return null;
     }

package/dist/domain/agentResultTransport.js

@@ -0,0 +1,60 @@
+export const MAX_TURN_RESULT_OUTPUT_BYTES = 512 * 1024;
+export const MAX_TURN_FAILURE_DIAGNOSTIC_BYTES = 16 * 1024;
+/**
+ * Validate only the transport envelope of an Agent result. The accepted text
+ * remains byte-for-byte unchanged; missing or untransportable text becomes a
+ * Core-owned failed outcome so the exact Turn can still terminalize.
+ */
+export function transportAgentResult(value) {
+    if (typeof value !== "string") {
+        return {
+            status: "failed",
+            diagnostic: "Provider terminal event did not include an Agent result.",
+            failureReason: "missing-result"
+        };
+    }
+    if (value.includes("\0")) {
+        return {
+            status: "failed",
+            diagnostic: "Provider terminal event included an Agent result with an invalid NUL byte.",
+            failureReason: "missing-result"
+        };
+    }
+    if (value.trim().length === 0) {
+        return {
+            status: "failed",
+            diagnostic: "Provider terminal event included an empty Agent result.",
+            failureReason: "missing-result"
+        };
+    }
+    const bytes = Buffer.byteLength(value, "utf8");
+    if (bytes > MAX_TURN_RESULT_OUTPUT_BYTES) {
+        return {
+            status: "failed",
+            diagnostic: `Provider Agent result is ${bytes} bytes and exceeds the ${MAX_TURN_RESULT_OUTPUT_BYTES}-byte durable result limit; the result was not stored.`,
+            failureReason: "missing-result"
+        };
+    }
+    return { status: "completed", output: value };
+}
+/**
+ * Bound Core-owned failure diagnostics without rejecting a terminal event.
+ * This is intentionally separate from Agent result transport: successful
+ * Agent text is either retained exactly or rejected as a whole, never
+ * truncated. Provider/Core diagnostics may be clipped because they are only
+ * operational context for a failed Turn.
+ */
+export function boundedTurnFailureDiagnostic(value, fallback = "Provider reported a failed Agent Turn.") {
+    const candidate = typeof value === "string" && value.trim().length > 0
+        ? value
+        : fallback;
+    const safe = candidate.replaceAll("\0", "\uFFFD");
+    if (Buffer.byteLength(safe, "utf8") <= MAX_TURN_FAILURE_DIAGNOSTIC_BYTES) {
+        return safe;
+    }
+    const prefix = Buffer
+        .from(safe, "utf8")
+        .subarray(0, MAX_TURN_FAILURE_DIAGNOSTIC_BYTES)
+        .toString("utf8");
+    return prefix.endsWith("\uFFFD") ? prefix.slice(0, -1) : prefix;
+}