@zq-silk/yui 0.15.3 → 0.15.6

package/dist/runtime/builtinAgentDrivers.js

@@ -70,6 +70,11 @@ export const BUILTIN_AGENT_DRIVERS = Object.freeze([
         adapterId: "claude",
         capabilities: Object.freeze({
             ...STRUCTURED_CLI_CAPABILITIES,
+            input: Object.freeze({
+                ...STRUCTURED_CLI_CAPABILITIES.input,
+                // Serialized stream input is not exact native steering.
+                steer: "unavailable"
+            }),
             observation: Object.freeze({
                 ...STRUCTURED_CLI_CAPABILITIES.observation,
                 sessionBootstrap: "preallocated",

package/dist/runtime/index.js

@@ -5,7 +5,7 @@ export { createRuntimeBinding } from "./runtimeBinding.js";
 export { normalizeRuntimeOwner } from "./runtimeOwner.js";
 export { createSessionLaunchRequest } from "./sessionLaunchRequest.js";
 export { DEFAULT_RECENT_TURN_ID_LIMIT, hasRecentTurnId, rememberRecentTurnId, validateRecentTurnIds } from "./recentTurnIds.js";
-export { RuntimeGenerationMismatchError, RuntimeHostContentionError, RuntimeLaunchError } from "./ports.js";
+export { promptPushOutcome, RuntimeGenerationMismatchError, RuntimeHostContentionError, RuntimeHostUnavailableError, RuntimeLaunchError } from "./ports.js";
 export { AgentHostPromptPushAdapter, TmuxSessionHost } from "./tmuxAdapters.js";
 export { FileTaskRuntimeIsolation, YUI_TASK_RUNTIME_ISOLATION_DESCRIPTOR, YUI_TASK_RUNTIME_SERVICE_NAMESPACE, assertTaskRuntimeIsolationPreflight, createTaskRuntimeIsolationDescriptor, parseTaskRuntimeIsolationDescriptor, planTaskRuntimeCleanup, taskRuntimeIsolationEnvironment, taskRuntimeIsolationFingerprint } from "./taskRuntimeIsolation.js";
 export { createSessionOwnerIdentity, discoverProviderRootByLaunchEnv, isLinuxProcessLive, listLaunchFencedProcesses, listOwnedProcessTree, readLinuxProcessIdentity } from "./sessionOwnerIdentity.js";

package/dist/runtime/ports.js

@@ -4,8 +4,8 @@ export class RuntimeLaunchError extends Error {
     runtimeGenerationId;
     reason;
     name = "RuntimeLaunchError";
-    constructor(retryable, runtimeGenerationId, message, reason) {
-        super(message);
+    constructor(retryable, runtimeGenerationId, message, reason, options) {
+        super(message, options);
         this.retryable = retryable;
         this.runtimeGenerationId = runtimeGenerationId;
         this.reason = reason;
@@ -33,3 +33,17 @@ export class RuntimeGenerationMismatchError extends Error {
         this.hostState = hostState;
     }
 }
+/** A reused Host reported an unusable state; this operation did not create it. */
+export class RuntimeHostUnavailableError extends RuntimeLaunchError {
+    hostState;
+    constructor(runtimeGenerationId, hostState, message, options) {
+        super(false, runtimeGenerationId, message, undefined, options);
+        this.hostState = hostState;
+    }
+}
+export function promptPushOutcome(result, failure) {
+    return Object.freeze({
+        result,
+        ...(failure === undefined ? {} : { failure })
+    });
+}

package/dist/runtime/providerRuntimeIdentity.js

@@ -186,6 +186,7 @@ export function beginProviderTurn(raw, input) {
         turn: {
             ...(turnId === undefined ? {} : { turnId }),
             attemptId,
+            activationId: currentProviderActivation(binding).activationId,
             authorityEpoch: input.authorityEpoch,
             status: "submitting",
             submittedAt,
@@ -207,7 +208,9 @@ export function acceptProviderTurn(raw, input) {
         turn: {
             ...turn,
             status: "accepted",
-            nativeTurnId: identity(input.nativeTurnId, "Provider native Turn id"),
+            ...(input.nativeTurnId === undefined
+                ? {}
+                : { nativeTurnId: identity(input.nativeTurnId, "Provider native Turn id") }),
             updatedAt: acceptedAt
         }
     });
@@ -273,8 +276,14 @@ export function settleProviderTurnSubmission(raw, input) {
 export function settleProviderTurn(raw, input) {
     const binding = validateProviderRuntimeBinding(raw);
     const turn = binding.turn;
-    const nativeTurnId = identity(input.nativeTurnId, "Provider native Turn id");
-    if (turn === null || turn.nativeTurnId !== nativeTurnId
+    const nativeTurnId = input.nativeTurnId === undefined
+        ? undefined : identity(input.nativeTurnId, "Provider native Turn id");
+    if (turn === null
+        || (input.attemptId === undefined
+            ? nativeTurnId === undefined || turn.nativeTurnId !== nativeTurnId
+            : turn.attemptId !== input.attemptId)
+        || (turn.nativeTurnId !== undefined && nativeTurnId !== undefined
+            && turn.nativeTurnId !== nativeTurnId)
         || turn.status !== "accepted") {
         throw new Error("Provider Turn settlement does not match the current Turn.");
     }
@@ -283,6 +292,7 @@ export function settleProviderTurn(raw, input) {
         ...binding,
         turn: {
             ...turn,
+            ...(nativeTurnId === undefined ? {} : { nativeTurnId }),
             status: input.status,
             updatedAt: settledAt,
             ...(input.reason === undefined
@@ -301,33 +311,25 @@ export function updateProviderConversationRecoverability(raw, recoverability) {
             : entry)
     });
 }
+/** Shared pre-start and commit guard for explicit native Conversation replacement. */
+export function assertProviderConversationReplaceable(raw) {
+    const binding = validateProviderRuntimeBinding(raw);
+    if (currentProviderActivation(binding) !== null || binding.authority.owner !== "none") {
+        throw new Error("Provider Conversation replacement requires its prior Activation to be ended and unowned.");
+    }
+    if (providerTurnIsActive(binding.turn)) {
+        throw new Error(`Provider Conversation replacement cannot discard unsettled input attempt ${binding.turn.attemptId} (${binding.turn.status}). Resolve its actual outcome before selecting a new Conversation.`);
+    }
+}
 export function supersedeProviderConversation(raw, input) {
     const binding = validateProviderRuntimeBinding(raw);
     const current = currentProviderConversation(binding);
-    const basis = input.basis;
-    if (basis !== "terminal-session") {
+    if (input.basis !== "terminal-session") {
         throw new Error("Provider Conversation replacement basis is invalid.");
     }
+    assertProviderConversationReplaceable(binding);
     const switchedAt = timestamp(input.switchedAt, "Provider Conversation replacement timestamp");
     const epoch = current.epoch + 1;
-    const terminalReason = "terminal-session-replaced";
-    const activations = binding.activations.map((entry) => entry.status === "active"
-        ? {
-            ...entry,
-            status: "failed",
-            endedAt: switchedAt,
-            terminalReason
-        }
-        : entry);
-    const turn = binding.turn !== null
-        && ["submitting", "accepted", "delivery-unknown"].includes(binding.turn.status)
-        ? {
-            ...binding.turn,
-            status: binding.turn.nativeTurnId === undefined ? "rejected" : "failed",
-            updatedAt: switchedAt,
-            terminalReason
-        }
-        : binding.turn;
     return validateProviderRuntimeBinding({
         ...binding,
         currentConversationEpoch: epoch,
@@ -343,7 +345,7 @@ export function supersedeProviderConversation(raw, input) {
                 createdAt: switchedAt
             }
         ],
-        activations: [...activations, {
+        activations: [...binding.activations, {
                 activationId: identity(input.activationId, "Provider Activation id"),
                 conversationId: input.conversationId,
                 generation: 1,
@@ -356,7 +358,6 @@ export function supersedeProviderConversation(raw, input) {
             holderId: input.activationId,
             changedAt: switchedAt
         },
-        turn,
         goal: null
     });
 }
@@ -464,8 +465,12 @@ export function validateProviderRuntimeBinding(value) {
     }
     if (!Object.hasOwn(value, "turn"))
         throw new Error("Provider Runtime Binding requires Turn state.");
-    if (value.turn !== null)
+    if (value.turn !== null) {
         validateProviderTurn(value.turn, value.authority.epoch);
+        if (value.turn.activationId !== undefined && !activationIds.has(value.turn.activationId)) {
+            throw new Error("Provider Turn references an unknown original Activation.");
+        }
+    }
     if (!Object.hasOwn(value, "goal"))
         throw new Error("Provider Runtime Binding requires Goal state.");
     if (value.goal !== null)
@@ -515,9 +520,10 @@ function validateProviderTurn(turn, currentAuthorityEpoch) {
     }
     const hasAcceptedIdentity = turn.status === "accepted"
         || turn.status === "completed" || turn.status === "failed" || turn.status === "cancelled";
-    if (hasAcceptedIdentity)
+    if (hasAcceptedIdentity && turn.nativeTurnId !== undefined) {
         identity(turn.nativeTurnId, "Provider native Turn id");
-    else if (turn.nativeTurnId !== undefined) {
+    }
+    else if (!hasAcceptedIdentity && turn.nativeTurnId !== undefined) {
         throw new Error("Unaccepted Provider Turn cannot have a native Turn id.");
     }
 }

package/dist/runtime/runtimeCoherence.js

@@ -0,0 +1,91 @@
+import { resolve } from "node:path";
+import { callController as defaultCallController } from "../core/controllerClient.js";
+import { inspectStorageSchema } from "../storage/storageSchema.js";
+import { yuiVersionIdentity } from "../version.js";
+export async function assertRuntimeCoherence(input, options = {}) {
+    const home = resolve(input.actualHome);
+    const identity = validateVersionIdentity(options.identity ?? yuiVersionIdentity());
+    const storage = (options.inspectStorage ?? inspectStorageSchema)(home);
+    if (storage.status !== "current") {
+        throw new Error(`Managed control-plane storage is not current: ${storage.status}.`);
+    }
+    if (storage.currentVersion !== identity.storageVersion) {
+        throw new Error("Managed control-plane storage version is incompatible "
+            + `(expected ${identity.storageVersion}, found `
+            + `${storage.currentVersion ?? "unknown"}).`);
+    }
+    if (options.checkController !== false) {
+        const call = options.callController ?? defaultCallController;
+        try {
+            const status = await call(home, "controller.status", {});
+            assertControllerContinuityIdentity(status, identity);
+        }
+        catch (error) {
+            if (!isDefinitelyNotRunning(error))
+                throw error;
+        }
+    }
+    return identity;
+}
+export function assertControllerStatusIdentity(status, expected = yuiVersionIdentity()) {
+    if (!isRecord(status) || status.running !== true) {
+        throw new Error("Controller status does not describe a running Controller.");
+    }
+    assertControllerField(status.protocolVersion, expected.controllerProtocolVersion, "protocol");
+    assertControllerField(status.version, expected.version, "version");
+    assertControllerField(status.storageVersion, expected.storageVersion, "storage version");
+    assertControllerField(status.minimumStorageVersion, expected.minimumStorageVersion, "minimum storage migration version");
+}
+function validateVersionIdentity(value) {
+    if (!isRecord(value))
+        throw new Error("Yui version identity is invalid.");
+    const version = requireText(value.version, "Yui version");
+    const controllerProtocolVersion = requireVersion(value.controllerProtocolVersion, "Controller protocol version");
+    const storageVersion = requireVersion(value.storageVersion, "Storage version");
+    const minimumStorageVersion = requireVersion(value.minimumStorageVersion, "Minimum storage migration version");
+    if (minimumStorageVersion > storageVersion) {
+        throw new Error("Minimum storage migration version cannot exceed the current storage version.");
+    }
+    return {
+        version,
+        controllerProtocolVersion,
+        storageVersion,
+        minimumStorageVersion
+    };
+}
+function assertControllerContinuityIdentity(status, expected) {
+    if (!isRecord(status) || status.running !== true) {
+        throw new Error("Controller status does not describe a running Controller.");
+    }
+    if (typeof status.version !== "string" || status.version.trim().length === 0) {
+        throw new Error("Controller version is invalid at the managed continuity gate.");
+    }
+    assertControllerField(status.protocolVersion, expected.controllerProtocolVersion, "protocol");
+    assertControllerField(status.storageVersion, expected.storageVersion, "storage version");
+}
+function assertControllerField(actual, expected, label) {
+    if (actual !== expected) {
+        throw new Error(`Controller ${label} is incompatible with the exact control plane `
+            + `(expected ${expected}, found ${typeof actual === "string" || typeof actual === "number" ? actual : "unknown"}). `
+            + "Run controller restart through the matching exact control-plane invocation "
+            + "before writing new Task records.");
+    }
+}
+function requireText(value, label) {
+    if (typeof value !== "string" || value.length === 0 || value.includes("\0")) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return value;
+}
+function requireVersion(value, label) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return value;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isDefinitelyNotRunning(error) {
+    return isRecord(error) && error.code === "CONTROLLER_NOT_RUNNING";
+}

package/dist/runtime/runtimeObservation.js

@@ -97,15 +97,18 @@ export function createRuntimeObservation(input) {
     }
     if (PROVIDER_STATE.has(input.kind)
         && input.authority !== "provider-structured"
-        && input.authority !== "controller") {
+        && input.authority !== "controller"
+        && !(input.kind === "turn.accepted" && input.authority === "transport"
+            && input.fence.receiptId !== undefined)) {
         throw new Error(`${input.kind} requires provider-structured or controller authority.`);
     }
     const fence = normalizeFence(input.fence);
     if (TURN_SCOPED.has(input.kind) && fence.nativeSessionId === undefined) {
         throw new Error(`${input.kind} requires nativeSessionId.`);
     }
-    if (TURN_SCOPED.has(input.kind) && fence.nativeTurnId === undefined) {
-        throw new Error(`${input.kind} requires nativeTurnId.`);
+    if (TURN_SCOPED.has(input.kind) && fence.nativeTurnId === undefined
+        && fence.receiptId === undefined) {
+        throw new Error(`${input.kind} requires a native Turn or exact receipt identity.`);
     }
     if ((input.kind.startsWith("activation.") || CONTINUATION_SCOPED.has(input.kind)
         || input.kind === "native-work.snapshot")
@@ -473,7 +476,7 @@ export function runtimeObservationSemanticKey(input) {
         return [
             "terminal",
             ...continuationIdentity,
-            fence.continuationId ?? fence.nativeTurnId ?? "none",
+            fence.continuationId ?? fence.receiptId ?? fence.nativeTurnId ?? "none",
             input.kind,
             input.payload?.outcome ?? input.payload?.failure?.error.code ?? "terminal",
             input.kind === "continuation.settled" ? input.payload?.resultRef ?? "none" : "none",
@@ -517,7 +520,7 @@ export function runtimeObservationSemanticKey(input) {
             fence.driverId,
             fence.conversationId ?? fence.nativeSessionId ?? fence.runtimeGenerationId,
             fence.activationId ?? fence.runtimeGenerationId,
-            fence.continuationId ?? fence.nativeTurnId ?? "none",
+            fence.continuationId ?? fence.receiptId ?? fence.nativeTurnId ?? "none",
             fence.continuationGeneration ?? "none",
             input.sequence,
             input.kind

package/dist/runtime/structuredProviderHost.js

@@ -11,16 +11,19 @@ const CODEX_PROXY_HANDSHAKE_TIMEOUT_MS = 10_000;
 export class ProviderDeliveryUnknownError extends Error {
     attemptId;
     name = "ProviderDeliveryUnknownError";
-    constructor(message, attemptId) {
-        super(message);
+    constructor(message, attemptId, 
+    // Wrapping must not become the end of the causal chain: the original
+    // transport or Controller failure is the reason a reader needs.
+    options) {
+        super(message, options);
         this.attemptId = attemptId;
     }
 }
 export class ProviderTurnRejectedError extends Error {
     attemptId;
     name = "ProviderTurnRejectedError";
-    constructor(message, attemptId) {
-        super(message);
+    constructor(message, attemptId, options) {
+        super(message, options);
         this.attemptId = attemptId;
     }
 }
@@ -381,6 +384,7 @@ class CodexStructuredProviderSession {
     adapterId = "codex";
     #activeTurnId;
     #clientOwnedTurnId;
+    #clientOwnedAttemptId;
     #submissionPending = false;
     #bufferedStarts = [];
     #bufferedTerminals = [];
@@ -443,6 +447,7 @@ class CodexStructuredProviderSession {
         session.#activeTurnId = resumedActiveTurnId;
         const ownedTurn = control.kind === "restore" ? control.ownedTurn : undefined;
         session.#clientOwnedTurnId = ownedTurn?.turnId;
+        session.#clientOwnedAttemptId = ownedTurn?.attemptId;
         stopOpeningBuffer();
         let recoveredTerminal;
         for (const message of openingMessages) {
@@ -463,6 +468,7 @@ class CodexStructuredProviderSession {
                     conversationId,
                     nativeSessionId: conversationId,
                     nativeTurnId: ownedTurn.turnId,
+                    attemptId: ownedTurn.attemptId,
                     clientOwned: true,
                     status: recovered.status === "failed"
                         ? "failed"
@@ -477,6 +483,7 @@ class CodexStructuredProviderSession {
                         })
                 };
                 session.#clientOwnedTurnId = undefined;
+                session.#clientOwnedAttemptId = undefined;
             }
             else {
                 throw new ProviderDeliveryUnknownError(`Codex resume could not recover the persisted Yui Turn ${ownedTurn.turnId}.`, ownedTurn.attemptId);
@@ -579,12 +586,14 @@ class CodexStructuredProviderSession {
             }
             this.#activeTurnId = acceptance.turnId;
             this.#clientOwnedTurnId = acceptance.turnId;
+            this.#clientOwnedAttemptId = turn.attemptId;
             return Object.freeze({
                 attemptId: turn.attemptId,
                 conversationId: this.conversationId,
                 nativeSessionId: this.conversationId,
                 nativeTurnId: acceptance.turnId,
-                acceptedAt: new Date().toISOString()
+                acceptedAt: new Date().toISOString(),
+                acceptance: "provider"
             });
         }
         finally {
@@ -619,7 +628,8 @@ class CodexStructuredProviderSession {
             conversationId: this.conversationId,
             nativeSessionId: this.conversationId,
             nativeTurnId,
-            acceptedAt: new Date().toISOString()
+            acceptedAt: new Date().toISOString(),
+            acceptance: "provider"
         });
     }
     #emitTerminal(terminal) {
@@ -632,12 +642,20 @@ class CodexStructuredProviderSession {
         });
     }
     #completeTerminal(terminal, emit) {
-        const clientOwned = terminal.nativeTurnId === this.#clientOwnedTurnId;
+        const clientOwned = terminal.nativeTurnId !== undefined
+            && terminal.nativeTurnId === this.#clientOwnedTurnId;
+        const attemptId = clientOwned ? this.#clientOwnedAttemptId : undefined;
         if (terminal.nativeTurnId === this.#activeTurnId)
             this.#activeTurnId = undefined;
-        if (clientOwned)
+        if (clientOwned) {
             this.#clientOwnedTurnId = undefined;
-        const completed = { ...terminal, clientOwned };
+            this.#clientOwnedAttemptId = undefined;
+        }
+        const completed = {
+            ...terminal,
+            clientOwned,
+            ...(attemptId === undefined ? {} : { attemptId })
+        };
         if (emit)
             this.onTerminal?.(completed);
         return completed;
@@ -657,7 +675,8 @@ class ClaudeStructuredProviderSession {
     channel;
     onGoal;
     adapterId = "claude";
-    #activeTurnId;
+    #activeAttemptId;
+    #resultAttempts = new Map();
     #lastGoalKey;
     constructor(child, exit, processInstanceId, conversationId, channel, onGoal) {
         this.child = child;
@@ -681,12 +700,16 @@ class ClaudeStructuredProviderSession {
         return this.conversationId;
     }
     get activeTurnId() {
-        return this.#activeTurnId;
+        // stream-json result.uuid is a message identity, not an execution identity.
+        return undefined;
     }
     async submitTurn(turn) {
-        if (this.#activeTurnId !== undefined) {
+        if (this.#activeAttemptId !== undefined) {
             throw new ProviderTurnRejectedError("Provider Conversation already has an unsettled Turn.", turn.attemptId);
         }
+        // Reserve before the pipe write: a fast result can precede its callback.
+        // A failed write is ambiguous and must retain the same occupancy.
+        this.#activeAttemptId = turn.attemptId;
         try {
             await this.channel.send({
                 type: "user",
@@ -697,47 +720,23 @@ class ClaudeStructuredProviderSession {
             });
         }
         catch (error) {
-            throw new ProviderDeliveryUnknownError(`Claude input write did not complete: ${error instanceof Error ? error.message : String(error)}`, turn.attemptId);
+            throw new ProviderDeliveryUnknownError(`Claude input write did not complete: ${error instanceof Error ? error.message : String(error)}`, turn.attemptId, { cause: error });
         }
         // AgentHost is the sole writer to this dedicated stream-json process.
         // A completed pipe write is the smallest reliable acceptance boundary;
         // Claude's later `result` is the matching terminal for this serialized
         // Turn. Requiring an echoed user-message creates a second, brittle
         // protocol without improving delivery safety.
-        const nativeTurnId = `claude-stream:${turn.attemptId}`;
-        this.#activeTurnId = nativeTurnId;
         return Object.freeze({
             attemptId: turn.attemptId,
             conversationId: this.conversationId,
             nativeSessionId: this.conversationId,
-            nativeTurnId,
-            acceptedAt: new Date().toISOString()
+            acceptedAt: new Date().toISOString(),
+            acceptance: "transport"
         });
     }
     async steerTurn(turn) {
-        const nativeTurnId = this.#activeTurnId;
-        if (nativeTurnId === undefined) {
-            throw new ProviderTurnRejectedError("Provider Conversation has no active Turn to steer.", turn.attemptId);
-        }
-        try {
-            await this.channel.send({
-                type: "user",
-                message: {
-                    role: "user",
-                    content: [{ type: "text", text: turn.boundedText }]
-                }
-            });
-        }
-        catch (error) {
-            throw new ProviderDeliveryUnknownError(`Claude steer write did not complete: ${error instanceof Error ? error.message : String(error)}`, turn.attemptId);
-        }
-        return Object.freeze({
-            attemptId: turn.attemptId,
-            conversationId: this.conversationId,
-            nativeSessionId: this.conversationId,
-            nativeTurnId,
-            acceptedAt: new Date().toISOString()
-        });
+        throw new ProviderTurnRejectedError("Claude stream-json does not expose an exact native Turn identity for steering.", turn.attemptId);
     }
     waitForExit() {
         return this.exit;
@@ -760,11 +759,21 @@ class ClaudeStructuredProviderSession {
         }
         if (message.type === "user")
             return;
-        if (message.type !== "result" || this.#activeTurnId === undefined
+        if (message.type !== "result"
             || optionalId(message.session_id) !== this.conversationId)
             return;
-        const nativeTurnId = this.#activeTurnId;
-        this.#activeTurnId = undefined;
+        // A result UUID identifies this message, not the Provider execution.
+        // Retain its local association so a delayed duplicate cannot be assigned
+        // to a successor request on the same long-lived process.
+        const resultId = optionalId(message.uuid);
+        const priorAttempt = resultId === undefined ? undefined : this.#resultAttempts.get(resultId);
+        const attemptId = priorAttempt ?? this.#activeAttemptId;
+        if (attemptId === undefined)
+            return;
+        if (resultId !== undefined)
+            this.#resultAttempts.set(resultId, attemptId);
+        if (attemptId === this.#activeAttemptId)
+            this.#activeAttemptId = undefined;
         const failed = message.is_error === true || message.subtype === "error_during_execution";
         const result = typeof message.result === "string" && message.result.length > 0
             ? message.result
@@ -772,7 +781,7 @@ class ClaudeStructuredProviderSession {
         onTerminal?.({
             conversationId: this.conversationId,
             nativeSessionId: this.conversationId,
-            nativeTurnId,
+            attemptId,
             clientOwned: true,
             status: failed ? "failed" : "completed",
             observedAt: new Date().toISOString(),