@zq-silk/yui 0.6.16 → 0.7.1

package/dist/runtime/processExitObservation.js

@@ -0,0 +1,60 @@
+export const RUNTIME_PROCESS_EXIT_SCHEMA_VERSION = 1;
+export function validateRuntimeProcessExitObservation(observation) {
+    if (observation.schemaVersion !== RUNTIME_PROCESS_EXIT_SCHEMA_VERSION) {
+        throw new Error("Runtime process-exit observation version is invalid.");
+    }
+    identity(observation.observationId, "observationId");
+    identity(observation.hostInstanceId, "hostInstanceId");
+    optionalIdentity(observation.providerProcessInstanceId, "providerProcessInstanceId");
+    optionalIdentity(observation.taskId, "taskId");
+    identity(observation.roleName, "roleName");
+    optionalIdentity(observation.runId, "runId");
+    identity(observation.launchId, "launchId");
+    optionalIdentity(observation.nativeSessionId, "nativeSessionId");
+    if (observation.processKind !== "agent-host" && observation.processKind !== "provider-child") {
+        throw new Error("Runtime process kind is invalid.");
+    }
+    if (!Number.isSafeInteger(observation.hostSequence) || observation.hostSequence < 1) {
+        throw new Error("Runtime host sequence is invalid.");
+    }
+    if (observation.exitCode !== undefined
+        && (!Number.isSafeInteger(observation.exitCode) || observation.exitCode < 0)) {
+        throw new Error("Runtime process exit code is invalid.");
+    }
+    optionalIdentity(observation.signal, "signal");
+    if (!Number.isFinite(Date.parse(observation.observedAt))) {
+        throw new Error("Runtime process observedAt is invalid.");
+    }
+    optionalIdentity(observation.stopReceiptId, "stopReceiptId");
+    optionalIdentity(observation.lastProviderEventId, "lastProviderEventId");
+    optionalIdentity(observation.diagnosticTailRef, "diagnosticTailRef");
+    return Object.freeze({ ...observation });
+}
+export function classifyRuntimeProcessExit(observation, input) {
+    validateRuntimeProcessExitObservation(observation);
+    if (observation.stopReceiptId !== undefined)
+        return "yui-requested-stop";
+    if (observation.processKind === "provider-child" && input.turnFailureObserved === true) {
+        return "provider-turn-failed";
+    }
+    if (observation.processKind === "provider-child"
+        && input.childLifecycle === "per-turn"
+        && observation.exitCode === 0
+        && input.turnTerminalObserved === true) {
+        return "expected-per-turn-exit";
+    }
+    if ((observation.exitCode !== undefined && observation.exitCode !== 0)
+        || observation.signal !== undefined) {
+        return "host-abnormal";
+    }
+    return "unknown";
+}
+function identity(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0 || value.includes("\0")) {
+        throw new Error(`Runtime process ${label} is invalid.`);
+    }
+}
+function optionalIdentity(value, label) {
+    if (value !== undefined)
+        identity(value, label);
+}

package/dist/runtime/runtimeBinding.js

@@ -10,6 +10,9 @@ export function createRuntimeBinding(input) {
     if (initialPromptRunId !== undefined && hostCreated !== true) {
         throw new TypeError("An initial prompt Run id requires a newly-created runtime host.");
     }
+    const launchPromptUncertainRunId = input.launchPromptUncertainRunId === undefined
+        ? undefined
+        : requireSafeIdentity(input.launchPromptUncertainRunId, "Uncertain launch prompt Run id");
     return {
         id: requireSafeIdentity(input.id, "Runtime binding id"),
         launchId: requireSafeIdentity(input.launchId, "Launch id"),
@@ -19,6 +22,9 @@ export function createRuntimeBinding(input) {
         hostRef: requireText(input.hostRef, "Session host reference"),
         ...(hostCreated === undefined ? {} : { hostCreated }),
         ...(initialPromptRunId === undefined ? {} : { initialPromptRunId }),
+        ...(launchPromptUncertainRunId === undefined
+            ? {}
+            : { launchPromptUncertainRunId }),
         ...(input.nativeSessionId === undefined
             ? {}
             : { nativeSessionId: requireText(input.nativeSessionId, "Native session id") })

package/dist/runtime/runtimeObservation.js

@@ -274,8 +274,12 @@ function normalizePayload(kind, input) {
         if (!["model", "tool", "subagent", "provider", "resource"].includes(input.activity ?? "")) {
             throw new Error("activity.observed requires an activity kind.");
         }
-        if (input.usage !== undefined)
-            validateUsage(input.usage);
+        if (input.usage !== undefined) {
+            const usage = input.usage;
+            validateUsage(usage.semantics === undefined
+                ? { ...usage, semantics: "cumulative-session" }
+                : usage);
+        }
     }
     if (kind === "observer.health") {
         requireIdentity(input.sourceId, "Runtime observer source id");
@@ -339,7 +343,12 @@ function normalizePayload(kind, input) {
         ...(input.activityId === undefined
             ? {}
             : { activityId: requireIdentity(input.activityId, "Runtime activity id") }),
-        ...(input.usage === undefined ? {} : { usage: Object.freeze({ ...input.usage }) }),
+        ...(input.usage === undefined
+            ? {}
+            : { usage: Object.freeze({
+                    ...input.usage,
+                    semantics: input.usage.semantics ?? "cumulative-session"
+                }) }),
         ...(observerSource === undefined ? {} : { observerSource }),
         ...(input.sourceId === undefined
             ? {}
@@ -468,7 +477,10 @@ function normalizeFailure(input) {
             : { lastOutput: requireText(input.lastOutput, "Runtime failure last output") }),
         ...(input.runTerminal === undefined
             ? {}
-            : { runTerminal: requireBoolean(input.runTerminal, "Runtime failure runTerminal") })
+            : { runTerminal: requireBoolean(input.runTerminal, "Runtime failure runTerminal") }),
+        ...(input.retryAfterMs === undefined
+            ? {}
+            : { retryAfterMs: requirePositiveMilliseconds(input.retryAfterMs) })
     });
 }
 function requireBoolean(value, label) {
@@ -476,9 +488,18 @@ function requireBoolean(value, label) {
         throw new Error(`${label} must be boolean.`);
     return value;
 }
+function requirePositiveMilliseconds(value) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new Error("Runtime failure retryAfterMs must be a positive safe integer.");
+    }
+    return value;
+}
 function validateUsage(input) {
-    for (const [name, value] of Object.entries(input)) {
-        if (!Number.isSafeInteger(value) || value < 0) {
+    if (!["cumulative-session", "request-context", "remaining-context"].includes(input.semantics)) {
+        throw new Error("Runtime usage semantics are invalid.");
+    }
+    for (const [name, value] of Object.entries(input).filter(([name]) => name !== "semantics")) {
+        if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
             throw new Error(`Runtime usage ${name} must be a non-negative safe integer.`);
         }
     }

package/dist/runtime/runtimeProjection.js

@@ -489,10 +489,13 @@ function next(current, patch) {
     });
 }
 function usageAdvanced(previous, current) {
+    if (current.semantics === "remaining-context")
+        return false;
+    if (current.semantics === "request-context")
+        return usageTotal(current) > 0;
     // A first cumulative snapshot may contain history from a resumed native
-    // Session. It establishes the generation baseline but cannot prove that
-    // tokens were consumed during the current observation window.
-    if (previous === undefined)
+    // Session. It establishes a baseline but cannot prove current progress.
+    if (previous === undefined || previous.semantics !== "cumulative-session")
         return false;
     return usageTotal(current) > usageTotal(previous);
 }

package/dist/runtime/runtimeStopReceipt.js

@@ -0,0 +1,42 @@
+import { createHash } from "node:crypto";
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+export function writeRuntimeStopReceipt(home, launchId, requestedAt) {
+    const receipt = Object.freeze({
+        schemaVersion: 1,
+        receiptId: `runtime-stop-${createHash("sha256")
+            .update(`${launchId}\0${requestedAt.toISOString()}`)
+            .digest("hex")}`,
+        launchId,
+        requestedAt: requestedAt.toISOString()
+    });
+    const path = stopReceiptPath(home, launchId);
+    mkdirSync(resolve(join(home, "runtime", "stop-receipts")), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.tmp-${process.pid}`;
+    writeFileSync(temporary, `${JSON.stringify(receipt)}\n`, { mode: 0o600 });
+    renameSync(temporary, path);
+    chmodSync(path, 0o600);
+    return receipt;
+}
+export function readRuntimeStopReceipt(home, launchId) {
+    try {
+        const value = JSON.parse(readFileSync(stopReceiptPath(home, launchId), "utf8"));
+        if (value.schemaVersion !== 1 || value.launchId !== launchId
+            || typeof value.receiptId !== "string" || !Number.isFinite(Date.parse(value.requestedAt))) {
+            throw new Error("Runtime stop receipt is invalid.");
+        }
+        return Object.freeze({ ...value });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+export function removeRuntimeStopReceipt(home, launchId) {
+    rmSync(stopReceiptPath(home, launchId), { force: true });
+}
+function stopReceiptPath(home, launchId) {
+    const name = createHash("sha256").update(launchId).digest("hex");
+    return resolve(join(home, "runtime", "stop-receipts", `${name}.json`));
+}

package/dist/runtime/sessionTerminationGuard.js

@@ -20,6 +20,19 @@ export async function terminateSessionOwners(owner, records, ports, options = {}
     const pollMs = positiveDuration(options.pollMs, DEFAULT_TERMINATION_POLL_MS, "pollMs");
     const now = ports.now();
     ports.emit({ stage: "stop-requested", owner, at: now });
+    // Persist one exact launch receipt before any graceful stop can kill the
+    // Host. The owner-wide event remains for compatibility and summary display.
+    for (const record of records) {
+        ports.emit({
+            stage: "stop-requested",
+            owner,
+            launchId: record.launchId,
+            ...(record.nativeSessionId === undefined
+                ? {}
+                : { nativeSessionId: record.nativeSessionId }),
+            at: now
+        });
+    }
     // A launch-fence scan is a point-in-time observation, not a durable owner
     // inventory: /proc entries can disappear between the directory and
     // environment reads. Retain every exact child identity observed during the