@zq-silk/yui 0.15.11 → 0.16.0

package/dist/runtime/providerRetry.js

@@ -0,0 +1,198 @@
+export const PROVIDER_RETRY_LIMIT = 5;
+export const PROVIDER_RETRY_BUDGET_MS = 600_000;
+export function providerRetryPending(binding) {
+    return binding?.retry?.status === "waiting" || binding?.retry?.status === "in-flight";
+}
+/** Called only in the transaction recording the exact failed/rejected input. */
+export function recordProviderFailure(binding, input) {
+    let turn = binding.run;
+    const previous = binding.retry;
+    if (turn === null || !["failed", "rejected", "delivery-unknown"].includes(turn.status))
+        return binding;
+    turn = { ...turn, failure: { error: input.error, ref: input.failureRef } };
+    binding = { ...binding, run: turn };
+    if (turn.status === "delivery-unknown")
+        return binding;
+    if (previous?.currentAttemptId === turn.attemptId
+        && ["cancelled", "exhausted", "needs-attention"].includes(previous.status))
+        return binding;
+    if (previous?.failedAttemptId === turn.attemptId && previous.status !== "in-flight")
+        return binding;
+    if (input.error.retryable !== true || input.error.inputDisposition === "unknown"
+        || input.error.sessionDisposition !== "recoverable"
+        || binding.authority.owner !== "controller" || binding.retryDisabled === true
+        || turn.status === "failed" && (turn.nativeTurnId === undefined || input.error.inputDisposition !== "accepted")) {
+        return providerRetryPending(binding)
+            ? cancelProviderRetry(binding, "failure-not-safely-retryable", input.at) : binding;
+    }
+    const continuing = previous?.status === "in-flight" && previous.currentAttemptId === turn.attemptId;
+    const originalInput = continuing ? previous.input : turn.input;
+    if (originalInput === undefined)
+        return binding; // no owned input: never replay arbitrary native chat
+    const current = {
+        policyVersion: 1,
+        chainId: continuing ? previous.chainId : turn.attemptId,
+        status: "waiting",
+        input: originalInput,
+        nativeSessionId: binding.conversations.find(c => c.epoch === binding.currentConversationEpoch).conversationId,
+        authorityEpoch: binding.authority.epoch,
+        attempts: continuing ? previous.attempts - (input.noProviderWrite && previous.successorAutomatic !== false ? 1 : 0) : 0,
+        transportSequence: continuing ? previous.transportSequence : 0,
+        startedAt: continuing ? previous.startedAt : iso(input.at),
+        intentAt: continuing ? previous.intentAt : turn.submittedAt,
+        deadline: continuing ? previous.deadline : iso(input.at + PROVIDER_RETRY_BUDGET_MS),
+        nextEligibleAt: iso(input.at),
+        updatedAt: iso(input.at),
+        failedAttemptId: turn.attemptId,
+        failureAttemptId: turn.nativeTurnId !== undefined || !continuing ? turn.attemptId : previous.failureAttemptId,
+        ...((turn.nativeTurnId ?? (continuing ? previous.failedNativeTurnId : undefined)) === undefined ? {}
+            : { failedNativeTurnId: turn.nativeTurnId ?? previous.failedNativeTurnId }),
+        ...(turn.runId === undefined ? {} : { previousRunId: turn.runId }),
+        failureRef: input.failureRef,
+        error: input.error
+    };
+    const random = unitRandom(input.random ?? Math.random);
+    const window = Math.min(60_000, 5_000 * 2 ** current.attempts);
+    const backoff = Math.ceil(window * (0.5 + random / 2));
+    const serverWait = input.error.retryAfterMs;
+    const delay = serverWait === undefined ? backoff
+        : Math.max(backoff, serverWait + 1 + Math.ceil(random * 1_000));
+    const eligible = input.at + delay;
+    const exhausted = current.attempts >= PROVIDER_RETRY_LIMIT || eligible >= Date.parse(current.deadline);
+    return {
+        ...binding,
+        ...(!continuing && previous !== undefined
+            ? { retryHistory: [...(binding.retryHistory ?? []), previous] } : {}),
+        retry: {
+            // A terminal chain has no next submission. Keep its bounded deadline
+            // representable even for huge hints; the unshortened hint stays in error.
+            ...current, nextEligibleAt: iso(exhausted ? Math.min(eligible, Date.parse(current.deadline)) : eligible),
+            ...(turn.retrySupported !== true ? { status: "needs-attention", reason: "host-safe-retry-unsupported" }
+                : exhausted ? { status: "exhausted", reason: current.attempts >= PROVIDER_RETRY_LIMIT
+                        ? "automatic-attempt-limit" : "retry-after-exceeds-deadline" } : {})
+        }
+    };
+}
+/** Atomically called at the shared native write admission, never by a timer alone. */
+export function admitProviderRetry(binding, input) {
+    const retry = binding.retry;
+    if (retry?.status === "in-flight" && retry.currentAttemptId === input.attemptId)
+        return binding;
+    if (retry?.status !== "waiting"
+        || input.at < Date.parse(retry.nextEligibleAt)
+        || retry.successorAutomatic !== false && (binding.retryDisabled === true
+            || input.at >= Date.parse(retry.deadline) || retry.attempts >= PROVIDER_RETRY_LIMIT)
+        || binding.authority.owner !== "controller" || binding.authority.epoch !== retry.authorityEpoch
+        || binding.conversations.find(c => c.epoch === binding.currentConversationEpoch)?.conversationId !== retry.nativeSessionId
+        || binding.run?.attemptId !== retry.failedAttemptId
+        || !["failed", "rejected", "deferred"].includes(binding.run.status)) {
+        throw new Error("Provider retry is not eligible under the current input, Session, authority or budget.");
+    }
+    return { ...binding, retry: {
+            ...retry, status: "in-flight", attempts: retry.attempts + (retry.successorAutomatic === false ? 0 : 1),
+            transportSequence: retry.transportSequence + 1,
+            currentAttemptId: input.attemptId, updatedAt: iso(input.at)
+        } };
+}
+/** Busy/preflight refusal is not a model attempt. Keep its exact receipt visible. */
+export function deferProviderRetry(binding, at, reason) {
+    const retry = binding.retry;
+    if (retry?.status !== "in-flight" || retry.currentAttemptId !== binding.run?.attemptId)
+        return binding;
+    const { currentAttemptId: _attempt, successorRunId, ...remaining } = retry;
+    return { ...binding, retry: {
+            ...remaining, attempts: retry.attempts - (retry.successorAutomatic === false ? 0 : 1),
+            failedAttemptId: binding.run.attemptId,
+            ...(reason === undefined && successorRunId !== undefined ? { successorRunId } : {}),
+            ...(reason !== undefined && binding.run?.runId !== undefined ? { previousRunId: binding.run.runId } : {}),
+            status: reason === undefined ? "waiting" : "needs-attention",
+            nextEligibleAt: iso(Math.min(at + 1_000, Date.parse(retry.deadline))),
+            updatedAt: iso(at), ...(reason === undefined ? {} : { reason })
+        } };
+}
+export function cancelProviderRetry(binding, reason, at) {
+    return !providerRetryPending(binding) ? binding : {
+        ...binding, retry: { ...binding.retry, status: "cancelled", reason, updatedAt: iso(at) }
+    };
+}
+export function completeProviderRetry(binding, turn) {
+    const retry = binding.retry;
+    return retry === undefined || !["in-flight", "cancelled", "needs-attention"].includes(retry.status)
+        || retry.currentAttemptId !== turn.attemptId
+        || turn.status !== "completed" ? binding : {
+        ...binding, retry: { ...retry, status: "recovered", updatedAt: turn.updatedAt }
+    };
+}
+export function providerRetryAttemptId(retry) {
+    return `provider-retry:${retry.chainId}/${retry.transportSequence + 1}`;
+}
+export function providerRetryPrompt(retry, original) {
+    if (retry.failedNativeTurnId === undefined)
+        return original;
+    return [
+        "Yui infrastructure recovery, not new user authorization.",
+        `Continue the existing input after failed attempt ${retry.failureAttemptId}`,
+        `(native Turn ${retry.failedNativeTurnId}; failure ${retry.failureRef}).`,
+        "Read current authorized context and the original input. Inspect existing work and receipts first;",
+        "continue only unfinished work. Preserve local changes and do not repeat confirmed side effects.",
+        original
+    ].join("\n");
+}
+/** The same presentation is consumed by CLI, Context and Web. */
+export function providerRetryProjection(binding) {
+    const retry = binding?.retry;
+    if (retry === undefined)
+        return null;
+    return {
+        chainId: retry.chainId,
+        status: retry.status === "in-flight" && binding?.run?.status === "delivery-unknown"
+            ? "delivery-unknown" : retry.status,
+        attempts: retry.status === "recovered" ? 0 : retry.attempts,
+        limit: PROVIDER_RETRY_LIMIT, nextEligibleAt: retry.nextEligibleAt, deadline: retry.deadline,
+        category: retry.error.category, preservesWork: true, nativeSessionId: retry.nativeSessionId,
+        ...(retry.reason === undefined ? {} : { reason: retry.reason }),
+        failureRef: retry.failureRef,
+        ...(retry.previousRunId === undefined ? {} : { previousRunId: retry.previousRunId }),
+        ...(retry.successorRunId === undefined ? {} : { successorRunId: retry.successorRunId })
+    };
+}
+export function controlProviderRetry(binding, action, at) {
+    if (action === "enable")
+        return { ...binding, retryDisabled: false };
+    return { ...cancelProviderRetry(binding, `user-${action}`, at),
+        ...(action === "disable" ? { retryDisabled: true } : {}) };
+}
+export function renderProviderRetry(binding) {
+    const view = providerRetryProjection(binding);
+    return view === null ? `Provider retry: ${binding?.retryDisabled ? "disabled" : "none"}`
+        : `Provider retry: ${view.category}/${view.status}; ${view.attempts}/${view.limit}; next=${view.nextEligibleAt}; `
+            + `deadline=${view.deadline}; existing work preserved${view.reason === undefined ? "" : `; ${view.reason}`}`;
+}
+export function validateProviderRetry(retry) {
+    if (retry.policyVersion !== 1 || !["waiting", "in-flight", "recovered", "cancelled", "exhausted", "needs-attention"].includes(retry.status)
+        || !Number.isSafeInteger(retry.attempts) || retry.attempts < 0 || retry.attempts > PROVIDER_RETRY_LIMIT
+        || !Number.isSafeInteger(retry.transportSequence) || retry.transportSequence < retry.attempts
+        || !Number.isSafeInteger(retry.authorityEpoch) || retry.authorityEpoch < 1
+        || [retry.chainId, retry.nativeSessionId, retry.failedAttemptId, retry.failureRef].some(v => typeof v !== "string" || v.length === 0)
+        || [retry.startedAt, retry.intentAt, retry.deadline, retry.nextEligibleAt, retry.updatedAt].some(v => !Number.isFinite(Date.parse(v)))
+        || Date.parse(retry.deadline) - Date.parse(retry.startedAt) !== PROVIDER_RETRY_BUDGET_MS
+        || retry.status === "in-flight" && !retry.currentAttemptId)
+        throw new Error("Invalid Provider retry record.");
+    validateProviderInput(retry.input);
+}
+export function validateProviderInput(input) {
+    const fields = input.kind === "run" ? [input.taskId, input.runId]
+        : input.kind === "wake" ? [input.taskId, input.wakeId]
+            : input.kind === "message" ? [input.roleName, input.messageId]
+                : input.kind === "text" ? [input.text] : [];
+    if (fields.length === 0 || fields.some(v => typeof v !== "string" || !v.trim())) {
+        throw new Error("Invalid owned Provider input.");
+    }
+}
+function iso(at) { return new Date(at).toISOString(); }
+function unitRandom(random) {
+    const value = random();
+    if (!Number.isFinite(value) || value < 0 || value > 1)
+        throw new Error("Retry RNG must return a unit fraction.");
+    return value;
+}

package/dist/runtime/providerRuntimeIdentity.js

@@ -1,3 +1,5 @@
+import { cancelProviderRetry, completeProviderRetry, validateProviderInput, validateProviderRetry } from "./providerRetry.js";
+import { isStandardAgentError } from "./agentError.js";
 export function createProviderRuntimeBinding(input) {
     const startedAt = timestamp(input.startedAt, "Provider Conversation startedAt");
     return validateProviderRuntimeBinding({
@@ -84,7 +86,7 @@ export function transferProviderAuthority(raw, input) {
     });
 }
 export function beginProviderTurn(raw, input) {
-    const binding = validateProviderRuntimeBinding(raw);
+    let binding = validateProviderRuntimeBinding(raw);
     const attemptId = identity(input.attemptId, "Provider input attempt id");
     const runId = input.runId === undefined ? undefined : identity(input.runId, "AgentRun id");
     const currentRun = binding.run;
@@ -104,6 +106,9 @@ export function beginProviderTurn(raw, input) {
         throw new Error("Provider Conversation already has an unsettled AgentRun.");
     }
     const submittedAt = timestamp(input.submittedAt, "Provider Turn submittedAt");
+    if (binding.retry?.currentAttemptId !== attemptId) {
+        binding = cancelProviderRetry(binding, "superseded-by-explicit-input", Date.parse(submittedAt));
+    }
     return validateProviderRuntimeBinding({
         ...binding,
         run: {
@@ -111,6 +116,8 @@ export function beginProviderTurn(raw, input) {
             attemptId,
             authorityEpoch: input.authorityEpoch,
             status: "submitting",
+            ...(input.input === undefined ? {} : { input: input.input }),
+            ...(input.retrySupported === undefined ? {} : { retrySupported: input.retrySupported }),
             submittedAt,
             updatedAt: submittedAt
         }
@@ -221,7 +228,7 @@ export function settleProviderTurn(raw, input) {
         throw new Error("Provider Turn settlement does not match the current AgentRun.");
     }
     const settledAt = orderedRunTimestamp(run, input.settledAt, "Provider Turn settledAt");
-    return validateProviderRuntimeBinding({
+    const settled = validateProviderRuntimeBinding({
         ...binding,
         run: {
             ...run,
@@ -233,6 +240,7 @@ export function settleProviderTurn(raw, input) {
                 : { terminalReason: identity(input.reason, "Provider Turn terminal reason") })
         }
     });
+    return completeProviderRetry(settled, settled.run);
 }
 /** Explicitly abandon an engineering input only after its execution resources
  * are quiescent. This does not invent native acceptance, a Turn id or success. */
@@ -367,6 +375,24 @@ export function validateProviderRuntimeBinding(value) {
         throw new Error("Provider Runtime Binding requires Goal state.");
     if (value.goal !== null)
         validateProviderGoal(value.goal);
+    if (value.retry !== undefined)
+        validateProviderRetry(value.retry);
+    if (value.retryHistory !== undefined) {
+        if (!Array.isArray(value.retryHistory))
+            throw new Error("Provider retry audit must be an array.");
+        for (const retry of value.retryHistory) {
+            validateProviderRetry(retry);
+            if (retry.status === "waiting" || retry.status === "in-flight")
+                throw new Error("Provider retry audit cannot schedule work.");
+        }
+    }
+    if (value.retryDisabled !== undefined && typeof value.retryDisabled !== "boolean")
+        throw new Error("Provider retry switch must be boolean.");
+    if (value.run?.input !== undefined)
+        validateProviderInput(value.run.input);
+    if (value.run?.failure !== undefined
+        && (!isStandardAgentError(value.run.failure.error) || !value.run.failure.ref))
+        throw new Error("Invalid Provider input failure.");
     return value;
 }
 function validateProviderGoal(goal) {

package/dist/runtime/runtimeObservation.js

@@ -547,11 +547,6 @@ 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/runtimeSessionCandidate.js

@@ -18,11 +18,10 @@ export function projectRuntimeSessionCandidate(sessions) {
         sessionUpdatedAt: active.updatedAt
     };
 }
-/** Deterministic owner order shared by all storage backends. */
+/** Deterministic owner order for current runtime discovery. */
 export function compareRuntimeSessionCandidates(left, right) {
     if (left.owner.scope !== right.owner.scope) {
-        // Preserve the historical adapter contract: Task owners precede the
-        // bounded global Role set.
+        // Task owners precede the bounded global Role set.
         return left.owner.scope === "task" ? -1 : 1;
     }
     if (left.owner.scope === "task" && right.owner.scope === "task") {

package/dist/runtime/sessionOwnerIdentity.js

@@ -17,7 +17,7 @@ export function createSessionOwnerIdentity(input) {
         throw new TypeError("Global session owner must not carry a task id.");
     }
     const providerRoot = input.providerRoot;
-    if (!["launch-env", "pane-pid", "owned-child"].includes(providerRoot.attribution)) {
+    if (!["pane-pid", "owned-child"].includes(providerRoot.attribution)) {
         throw new TypeError("Session owner process attribution is invalid.");
     }
     if (!Number.isSafeInteger(providerRoot.pid) || providerRoot.pid <= 0) {

package/dist/runtime/sessionTokenMetrics.js

@@ -26,11 +26,21 @@ export function resolveSessionTokenIdentity(input) {
 export function projectSessionTokenMetrics(events, identity) {
     if (identity === null)
         return unobservedSessionTokenMetrics();
-    const observations = events
-        .map(runtimeObservationFromTaskEvent)
-        .filter((observation) => (observation !== null
-        && isRuntimeTokenEvidence(observation)
-        && matchesSessionIdentity(observation, identity)))
+    return projectSessionTokenObservations(events.flatMap((event) => {
+        const observation = runtimeObservationFromTaskEvent(event);
+        return observation === null ? [] : [observation];
+    }), identity);
+}
+/** Shared reducer for authorized, already decoded canonical observations. */
+export function projectSessionTokenObservations(input, identity) {
+    const observations = input
+        .filter((observation) => (isRuntimeTokenEvidence(observation)
+        && matchesSessionIdentity(observation, identity)
+        && (observation.authority === "provider-structured" || observation.authority === "driver-inferred")
+        // Child counters have no declared inclusion relationship with the
+        // Session's parent counter. They must never be added as extra requests.
+        && observation.fence.continuationId === undefined
+        && observation.fence.parentContinuationId === undefined))
         .sort(compareObservations);
     const incompleteBoundaries = observations.filter(({ payload }) => (payload.usage === undefined));
     const request = observations.filter(({ payload }) => (payload.usage?.semantics === "request-context"));

package/dist/runtime/structuredProviderHost.js

@@ -2,13 +2,14 @@ import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { Duplex } from "node:stream";
 import { fileURLToPath } from "node:url";
+import { ProviderConversationMissingError, ProviderDeliveryUnknownError, ProviderTurnBusyError, ProviderTurnRejectedError } from "./providerErrors.js";
 import WebSocket from "ws";
-import { CodexAppServerRequestError, CodexAppServerRuntime, codexClientInitialization, codexGoalNotification, codexAppServerErrorIsMissing, codexTurnInput, codexTurnOutput } from "./codexAppServerRuntime.js";
-import { serializeAgentErrorRaw } from "./agentError.js";
+import { YUI_VERSION } from "../version.js";
 import { AcpStructuredProviderSession } from "./acpSession.js";
 import { acpDesiredSessionConfiguration } from "./acpSessionConfiguration.js";
+import { serializeAgentErrorRaw } from "./agentError.js";
 import { unsupportedAgentRunConfiguration } from "./agentRunConfiguration.js";
-import { YUI_VERSION } from "../version.js";
+import { codexAppServerErrorIsMissing, CodexAppServerRequestError, CodexAppServerRuntime, codexClientInitialization, codexGoalNotification, codexTurnInput, codexTurnOutput } from "./codexAppServerRuntime.js";
 import { JsonLineChannel, PROVIDER_MESSAGE_MAX_BYTES, terminateProcessGroup } from "./jsonLineChannel.js";
 import { PROVIDER_ACCEPT_TIMEOUT_MS } from "./runtimeDeadlines.js";
 const CODEX_PROXY_HANDSHAKE_TIMEOUT_MS = 10_000;
@@ -18,44 +19,6 @@ const CODEX_PROXY_HANDSHAKE_TIMEOUT_MS = 10_000;
  */
 const CODEX_RUN_CONFIGURATION = unsupportedAgentRunConfiguration("The Codex app-server protocol");
 const CLAUDE_RUN_CONFIGURATION = unsupportedAgentRunConfiguration("Claude Code's stream-json interface");
-export class ProviderDeliveryUnknownError extends Error {
-    attemptId;
-    name = "ProviderDeliveryUnknownError";
-    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, options) {
-        super(message, options);
-        this.attemptId = attemptId;
-    }
-}
-/** Another ordinary client currently owns the thread's active Turn. */
-export class ProviderTurnBusyError extends Error {
-    attemptId;
-    activeTurnId;
-    name = "ProviderTurnBusyError";
-    constructor(message, attemptId, activeTurnId) {
-        super(message);
-        this.attemptId = attemptId;
-        this.activeTurnId = activeTurnId;
-    }
-}
-export class ProviderConversationMissingError extends Error {
-    conversationId;
-    name = "ProviderConversationMissingError";
-    constructor(conversationId, message) {
-        super(message);
-        this.conversationId = conversationId;
-    }
-}
 export async function startStructuredProviderSession(payload, input = {}) {
     const control = payload.providerControl;
     if (control === undefined) {
@@ -462,7 +425,7 @@ class CodexStructuredProviderSession {
                         ? {}
                         : {
                             error: recovered.error ?? "Provider Turn failed.",
-                            rawError: serializeAgentErrorRaw(recovered)
+                            ...(recovered.rawError === undefined ? {} : { rawError: recovered.rawError })
                         })
                 };
                 session.#clientOwnedTurnId = undefined;
@@ -594,7 +557,11 @@ class CodexStructuredProviderSession {
                 conversationId: this.conversationId,
                 attemptId: turn.attemptId,
                 text: turn.boundedText,
-                expectedNoActiveTurn: true
+                expectedNoActiveTurn: true,
+                ...(turn.requireQuiescent ? { requireQuiescent: true } : {}),
+                ...(turn.expectedFailedNativeTurnId === undefined ? {} : {
+                    expectedFailedNativeTurnId: turn.expectedFailedNativeTurnId
+                })
             });
             if (acceptance.status === "unknown") {
                 throw new ProviderDeliveryUnknownError(acceptance.reason, turn.attemptId);