@zq-silk/yui 0.13.8 → 0.13.9

package/dist/observability/executionAudit.js

@@ -86,26 +86,6 @@ function roleBucket(roleName) {
     }
     return "other";
 }
-/** Maps a provider-retry lifecycle event to its last recorded decision. */
-function providerRetryDecision(event) {
-    if (event.type === "runtime.provider-retry-waiting")
-        return "waiting";
-    if (event.type === "runtime.provider-retry-resume")
-        return "resume";
-    if (event.type === "runtime.provider-retry-session-dead")
-        return "session-dead";
-    if (event.type === "runtime.provider-retry-budget-exhausted")
-        return "budget-exhausted";
-    if (event.payload.note === "native-turn-completion-durable")
-        return "suppressed:completion-durable";
-    if (event.payload.note === "retry-budget-exhausted")
-        return "budget-exhausted";
-    if (event.payload.wouldRetry === "true")
-        return "retrying";
-    if (event.payload.shadow === "true")
-        return "shadow";
-    return "not-retried";
-}
 function durationMs(run) {
     if (run.endedAt === undefined)
         return 0;
@@ -205,7 +185,7 @@ export function runExecutionAudit(home, options = {}, ports = createProductionEx
             integrations: section,
             publications: section,
             events: section,
-            providerRetries: section,
+            agentErrors: section,
             workItems: section,
             orchestration: section,
             storage: section,
@@ -378,13 +358,13 @@ export function runExecutionAudit(home, options = {}, ports = createProductionEx
                     const history = Array.isArray(set.history) ? set.history : [];
                     for (const session of [...history, ...Object.values(set.sessions)]) {
                         generations += 1;
-                        if (session.status === "broken")
+                        if (session.status === "ended" && session.endReason === "failed")
                             broken += 1;
-                        else if (session.status === "stopped")
+                        else if (session.status === "ended")
                             stopped += 1;
                         else
                             other += 1;
-                        if (session.status === "broken" || session.status === "stopped") {
+                        if (session.status === "ended") {
                             classifyTerminalSessionRunRelation(runs, set.owner.roleName, session, terminalByRunRelation);
                         }
                     }
@@ -608,51 +588,38 @@ export function runExecutionAudit(home, options = {}, ports = createProductionEx
             return failed(error);
         }
     })();
-    const providerRetries = (() => {
+    const agentErrors = (() => {
         try {
-            const entries = new Map();
+            const entries = [];
+            const categories = new Map();
             for (const taskId of taskIds) {
                 for (const event of store.listEvents(taskId)) {
-                    if (!inWindow(event.createdAt, options))
-                        continue;
-                    if (!event.type.startsWith("runtime.provider-retry-"))
-                        continue;
-                    const runId = event.payload.runId;
-                    if (typeof runId !== "string")
+                    if (!inWindow(event.createdAt, options) || event.type !== "runtime.agent-error") {
                         continue;
-                    const key = `${taskId}/${runId}`;
-                    const previous = entries.get(key);
-                    const attempt = Number(event.payload.attempt ?? "0");
-                    const decision = providerRetryDecision(event);
-                    const terminal = decision === "session-dead" || decision === "budget-exhausted";
-                    const next = {
+                    }
+                    const category = event.payload.category ?? "unknown";
+                    categories.set(category, (categories.get(category) ?? 0) + 1);
+                    entries.push({
                         taskId,
-                        runId,
-                        roleName: typeof event.payload.roleName === "string"
-                            ? event.payload.roleName
-                            : previous?.roleName ?? "",
-                        attempts: Number.isFinite(attempt) ? Math.max(previous?.attempts ?? 0, attempt) : (previous?.attempts ?? 0),
-                        errorClass: typeof event.payload.errorClass === "string"
-                            ? event.payload.errorClass
-                            : previous?.errorClass ?? "",
-                        firstFailureAt: previous?.firstFailureAt ?? event.createdAt,
-                        lastFailureAt: event.createdAt,
-                        ...(typeof event.payload.nextAttemptAt === "string"
-                            ? { lastBackoffAt: event.payload.nextAttemptAt }
-                            : previous?.lastBackoffAt !== undefined
-                                ? { lastBackoffAt: previous.lastBackoffAt }
-                                : {}),
-                        decision,
-                        terminal: (previous?.terminal ?? false) || terminal
-                    };
-                    entries.set(key, next);
+                        eventId: event.id,
+                        runId: event.payload.runId ?? "",
+                        roleName: event.payload.roleName ?? "",
+                        source: event.payload.source ?? "unknown",
+                        phase: event.payload.phase ?? "unknown",
+                        category,
+                        code: event.payload.code ?? "unknown",
+                        message: event.payload.message ?? "",
+                        raw: event.payload.raw ?? "",
+                        inputDisposition: event.payload.inputDisposition ?? "unknown",
+                        sessionDisposition: event.payload.sessionDisposition ?? "unknown",
+                        createdAt: event.createdAt
+                    });
                 }
             }
-            const list = [...entries.values()];
             return ok({
-                total: list.length,
-                terminal: list.filter((entry) => entry.terminal).length,
-                entries: list.map(({ terminal: _terminal, ...entry }) => entry)
+                total: entries.length,
+                byCategory: Object.fromEntries(categories),
+                entries
             });
         }
         catch (error) {
@@ -748,16 +715,10 @@ export function runExecutionAudit(home, options = {}, ports = createProductionEx
         try {
             const protocolVersions = new Map();
             const manifestDigests = new Set();
-            const retryStates = new Map();
+            const agentErrorCategories = new Map();
             const exitClassifications = new Map();
             const usageSemantics = new Map();
-            let activeRetryEpisodes = 0;
-            let activeConsecutiveFailures = 0;
-            let activeDispatchedRetries = 0;
-            let retryClassifiedEvents = 0;
-            let retryDispatchedEvents = 0;
-            let retryRecoveredEvents = 0;
-            let retryExhaustedEvents = 0;
+            let agentErrors = 0;
             let contextCapacityFailures = 0;
             let processExitObservations = 0;
             let compactionEvents = 0;
@@ -770,26 +731,17 @@ export function runExecutionAudit(home, options = {}, ports = createProductionEx
                     if (run.effective.sessionManifestCompatibilityDigest !== undefined) {
                         manifestDigests.add(run.effective.sessionManifestCompatibilityDigest);
                     }
-                    if (run.providerRetry !== undefined) {
-                        activeRetryEpisodes += 1;
-                        retryStates.set(run.providerRetry.state, (retryStates.get(run.providerRetry.state) ?? 0) + 1);
-                        activeConsecutiveFailures += run.providerRetry.consecutiveFailures;
-                        activeDispatchedRetries += run.providerRetry.dispatchedRetries;
-                    }
                 }
                 for (const event of store.listEvents(taskId)) {
                     if (!inWindow(event.createdAt, options))
                         continue;
-                    if (event.type === "runtime.provider-retry-classified")
-                        retryClassifiedEvents += 1;
-                    else if (event.type === "runtime.provider-retry-dispatched")
-                        retryDispatchedEvents += 1;
-                    else if (event.type === "runtime.provider-retry-recovered")
-                        retryRecoveredEvents += 1;
-                    else if (event.type === "runtime.provider-retry-exhausted")
-                        retryExhaustedEvents += 1;
-                    else if (event.type === "runtime.context-capacity-failure")
-                        contextCapacityFailures += 1;
+                    if (event.type === "runtime.agent-error") {
+                        agentErrors += 1;
+                        const category = event.payload.category ?? "unknown";
+                        agentErrorCategories.set(category, (agentErrorCategories.get(category) ?? 0) + 1);
+                        if (category === "context")
+                            contextCapacityFailures += 1;
+                    }
                     else if (event.type === "runtime.process-exit-observed") {
                         processExitObservations += 1;
                         const classification = event.payload.classification ?? "unknown";
@@ -808,14 +760,8 @@ export function runExecutionAudit(home, options = {}, ports = createProductionEx
             return ok({
                 contextProtocolVersions: Object.fromEntries(protocolVersions),
                 manifestCompatibilityDigests: manifestDigests.size,
-                activeRetryEpisodes,
-                activeRetryStates: Object.fromEntries(retryStates),
-                activeConsecutiveFailures,
-                activeDispatchedRetries,
-                retryClassifiedEvents,
-                retryDispatchedEvents,
-                retryRecoveredEvents,
-                retryExhaustedEvents,
+                agentErrors,
+                agentErrorCategories: Object.fromEntries(agentErrorCategories),
                 contextCapacityFailures,
                 processExitObservations,
                 processExitClassifications: Object.fromEntries(exitClassifications),
@@ -870,7 +816,7 @@ export function runExecutionAudit(home, options = {}, ports = createProductionEx
         integrations,
         publications,
         events,
-        providerRetries,
+        agentErrors,
         workItems,
         orchestration,
         storage,

package/dist/operator/operatorSessionHistory.js

@@ -25,7 +25,7 @@ export function projectOperatorStatus(sessions, activeAgentId, activeAdapterId)
     }
     return Object.freeze({
         writer: {
-            state: matchingActive.status === "stopped" || matchingActive.status === "broken" ? "inactive" : "active",
+            state: matchingActive.status === "ended" ? "inactive" : "active",
             agentId: matchingActive.agentId,
             adapterId: matchingActive.adapterId,
             sessionRef: activeRef,
@@ -42,7 +42,7 @@ export function listOperatorSessions(sessions) {
     if (sessions === null)
         return [];
     validateRoleSessionSet(sessions);
-    const current = Object.values(sessions.sessions).map((session) => (listItem(session, session.status === "stopped" || session.status === "broken"
+    const current = Object.values(sessions.sessions).map((session) => (listItem(session, session.status === "ended"
         ? "current"
         : "running")));
     const history = Object.values(sessions.history ?? {}).map((session) => (listItem(session, "history")));
@@ -92,7 +92,8 @@ export function prepareOperatorResumeSession(sessions, ref, now) {
     delete history[normalizedRef];
     nextSessions[selected.agentId] = {
         ...selected,
-        status: "stopped",
+        status: "ended",
+        endReason: "stopped",
         updatedAt: requireDate(now)
     };
     return validateRoleSessionSet({
@@ -104,12 +105,13 @@ export function prepareOperatorResumeSession(sessions, ref, now) {
     });
 }
 function archiveCurrent(history, session) {
-    if (session.status !== "stopped" && session.status !== "broken") {
+    if (session.status !== "ended") {
         throw new Error(`Cannot replace Operator session while its native process is ${session.status}.`);
     }
     const archived = {
         ...session,
-        status: "stopped"
+        status: "ended",
+        endReason: session.endReason ?? "stopped"
     };
     return {
         ...history,

package/dist/role/role.js

@@ -130,7 +130,7 @@ export function unbindRoleAgent(role, sessions, agentId, now) {
             throw new Error(`Cannot unbind Role Agent with an active Run: ${normalizedAgentId}.`);
         }
         const targetSession = sessions.sessions[normalizedAgentId];
-        if (targetSession !== undefined && targetSession.status !== "stopped") {
+        if (targetSession !== undefined && targetSession.status === "active") {
             throw new Error(`Cannot unbind Role Agent while its native session is ${targetSession.status}: `
                 + `${normalizedAgentId}.`);
         }

package/dist/run/agentRun.js

@@ -1,6 +1,5 @@
 import { validateEffectiveLaunchSnapshot } from "../executor/effectiveLaunch.js";
 import { formatAgentRunReceiptId, validateTaskRecordReference } from "../task/taskRecordReference.js";
-import { prepareProviderRetryDispatch, validateAgentRunProviderRetry } from "./providerRetry.js";
 import { validateYieldReceipt } from "./yieldReceipt.js";
 import { validateAgentRunControlRequest } from "./runControlRequest.js";
 import { validateManagedWorkspace } from "../worktree/managedWorkspace.js";
@@ -30,7 +29,7 @@ export function createAgentRun(id, taskId, roleName, mode, assignment, now, cont
         })
         : validateRunAssignment(assignment);
     return {
-        schemaVersion: 9,
+        schemaVersion: 10,
         id: requireSafeIdentity(id, "Agent run id"),
         taskId: requireSafeIdentity(taskId, "Task id"),
         roleName: requireSafeIdentity(roleName, "Role name"),
@@ -104,8 +103,8 @@ export function markAgentRunDelivered(run, now) {
     };
 }
 export function validateAgentRun(run) {
-    if (run.schemaVersion !== 9)
-        throw new Error("Agent run must use schemaVersion 9.");
+    if (run.schemaVersion !== 10)
+        throw new Error("Agent run must use schemaVersion 10.");
     validateTaskRecordReference({ taskId: run.taskId, localId: run.id }, "agentRun");
     requireSafeIdentity(run.roleName, "Role name");
     if (run.mode !== "new" && run.mode !== "resume") {
@@ -266,12 +265,6 @@ export function validateAgentRun(run) {
             }
         }
     }
-    if (run.providerRetry !== undefined) {
-        validateAgentRunProviderRetry(run.providerRetry);
-        if (run.status !== "active") {
-            throw new Error("A terminal Agent run cannot carry a providerRetry projection.");
-        }
-    }
     if (run.controlRequest !== undefined) {
         validateAgentRunControlRequest(run.controlRequest);
         if (run.status !== "active") {
@@ -304,60 +297,17 @@ function finishAgentRun(run, status, summary, now) {
         updatedAt: timestamp,
         endedAt: timestamp
     };
-    // A terminal Run no longer waits for a retry; the projection is cleared so
-    // old and new readers agree the Run is settled.
-    if (terminal.providerRetry !== undefined) {
-        delete terminal.providerRetry;
-    }
     if (terminal.controlRequest !== undefined)
         delete terminal.controlRequest;
     return terminal;
 }
-/**
- * Attaches (or advances) the Issue 04 in-place retry projection on an active
- * Run. The Run stays `active`; only the projection changes.
- */
-export function withProviderRetry(run, retry) {
-    if (run.status !== "active") {
-        throw new Error(`Cannot schedule provider retry on a terminal Agent run: ${run.id}.`);
-    }
-    return validateAgentRun({ ...run, providerRetry: retry });
-}
-/**
- * Reopens an active retry-waiting Run for another in-place attempt on its
- * original Native Session. The original Run transport/acceptance timestamps
- * remain historical facts; the new delivery receipt and `dispatching` retry
- * state make the delivery path send only the short continuation envelope.
- */
-export function reopenRunForProviderRetry(run, receiptId, now, mode = "resume") {
-    if (run.status !== "active" || run.providerRetry === undefined) {
-        throw new Error(`Agent run is not waiting for a provider retry: ${run.id}.`);
-    }
-    const timestamp = now.toISOString();
-    const { providerRetry, ...rest } = run;
-    return validateAgentRun({
-        ...rest,
-        mode,
-        deliveryReceiptId: receiptId,
-        updatedAt: timestamp,
-        providerRetry: prepareProviderRetryDispatch(providerRetry, receiptId, now)
-    });
-}
-/** Any exact correlated provider progress ends the active consecutive-failure episode. */
-export function clearProviderRetryOnProgress(run) {
-    if (run.providerRetry === undefined)
-        return run;
-    const { providerRetry: _providerRetry, ...rest } = run;
-    return validateAgentRun(rest);
-}
 export function agentRunDeliveryReceiptId(run) {
     return run.deliveryReceiptId
         ?? run.controlRequest?.receiptId
-        ?? run.providerRetry?.lastRetryReceiptId
         ?? formatAgentRunReceiptId(run.taskId, run.id);
 }
 export function withAgentRunControlRequest(run, request, now) {
-    if (run.status !== "active" || run.providerRetry !== undefined) {
+    if (run.status !== "active") {
         throw new Error(`Agent run cannot accept a control request: ${run.id}.`);
     }
     return validateAgentRun({

package/dist/runtime/agentDriver.js

@@ -233,6 +233,7 @@ export class AgentDriverRegistry {
         }
         if (typeof input.runtime.nativeSessionId !== "function"
             || typeof input.runtime.nativeTurnId !== "function"
+            || typeof input.runtime.mapError !== "function"
             || typeof input.runtime.mapHook !== "function"
             || typeof input.runtime.classifyHook !== "function"
             || (input.runtime.observer !== undefined
@@ -249,6 +250,7 @@ export class AgentDriverRegistry {
             runtime: Object.freeze({
                 nativeSessionId: input.runtime.nativeSessionId,
                 nativeTurnId: input.runtime.nativeTurnId,
+                mapError: input.runtime.mapError,
                 mapHook: input.runtime.mapHook,
                 classifyHook: input.runtime.classifyHook,
                 ...(input.runtime.observer === undefined

package/dist/runtime/agentError.js

@@ -0,0 +1,114 @@
+/**
+ * Provider-neutral Agent failure facts.
+ *
+ * Drivers recognize provider-native failures. Core persists the resulting
+ * facts and routes them to an Agent; it does not attach a recovery policy.
+ * `unknown` is the required fallback and the complete native payload is always
+ * retained in `raw`.
+ */
+export const AGENT_ERROR_CATEGORIES = Object.freeze([
+    "availability",
+    "rate-limit",
+    "transport",
+    "access",
+    "invalid-request",
+    "context",
+    "session",
+    "runtime",
+    "conflict",
+    "cancelled",
+    "unknown"
+]);
+export function standardAgentError(input) {
+    const classification = input.classification ?? UNKNOWN_AGENT_ERROR_CLASSIFICATION;
+    const retryAfterMs = input.retryAfterMs;
+    if (retryAfterMs !== undefined
+        && (!Number.isSafeInteger(retryAfterMs) || retryAfterMs < 0)) {
+        throw new Error("Agent error retryAfterMs must be a non-negative safe integer.");
+    }
+    return Object.freeze({
+        source: input.source,
+        phase: input.phase,
+        category: classification.category,
+        code: requiredErrorText(classification.code, "Agent error code"),
+        message: requiredErrorText(input.message, "Agent error message"),
+        raw: requiredErrorText(input.raw, "Agent error raw payload"),
+        inputDisposition: input.inputDisposition
+            ?? classification.inputDisposition
+            ?? "unknown",
+        sessionDisposition: input.sessionDisposition
+            ?? classification.sessionDisposition
+            ?? "unknown",
+        ...(retryAfterMs === undefined ? {} : { retryAfterMs })
+    });
+}
+export const UNKNOWN_AGENT_ERROR_CLASSIFICATION = Object.freeze({
+    category: "unknown",
+    code: "unknown"
+});
+export function isAgentErrorCategory(value) {
+    return typeof value === "string"
+        && AGENT_ERROR_CATEGORIES.includes(value);
+}
+export function isStandardAgentError(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const error = value;
+    return ["provider", "driver", "host", "yui"].includes(error.source ?? "")
+        && [
+            "host-start",
+            "session-start",
+            "session-restore",
+            "turn-submit",
+            "turn-execute",
+            "turn-reconcile",
+            "host-stop"
+        ].includes(error.phase ?? "")
+        && isAgentErrorCategory(error.category)
+        && isErrorText(error.code)
+        && isErrorText(error.message)
+        && isErrorText(error.raw)
+        && ["accepted", "not-accepted", "unknown"].includes(error.inputDisposition ?? "")
+        && ["recoverable", "unrecoverable", "unknown"].includes(error.sessionDisposition ?? "")
+        && (error.retryAfterMs === undefined
+            || (Number.isSafeInteger(error.retryAfterMs) && error.retryAfterMs >= 0));
+}
+export function serializeAgentErrorRaw(value) {
+    if (typeof value === "string")
+        return requiredErrorText(value, "Agent error raw payload");
+    if (value === undefined)
+        return "Agent operation failed without an error payload.";
+    try {
+        const seen = new WeakSet();
+        const serialized = JSON.stringify(value, (_key, member) => {
+            if (typeof member === "bigint")
+                return member.toString();
+            if (member !== null && typeof member === "object") {
+                if (seen.has(member))
+                    return "[Circular]";
+                seen.add(member);
+                if (member instanceof Error) {
+                    return Object.fromEntries(Object.getOwnPropertyNames(member).map((name) => [
+                        name,
+                        member[name]
+                    ]));
+                }
+            }
+            return member;
+        });
+        return serialized === undefined
+            ? String(value)
+            : requiredErrorText(serialized, "Agent error raw payload");
+    }
+    catch {
+        return requiredErrorText(String(value), "Agent error raw payload");
+    }
+}
+function isErrorText(value) {
+    return typeof value === "string" && value.trim().length > 0 && !value.includes("\0");
+}
+function requiredErrorText(value, label) {
+    if (!isErrorText(value))
+        throw new Error(`${label} is required.`);
+    return value;
+}