@zq-silk/yui 0.6.16 → 0.7.0

package/dist/runtime/agentHost.js

@@ -0,0 +1,327 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { appendFileSync, chmodSync, closeSync, fsyncSync, mkdirSync, openSync, rmSync } from "node:fs";
+import { readdir, readFile, rename, unlink } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { createServer, createConnection } from "node:net";
+import { callController } from "../core/controllerClient.js";
+import { validateAgentHostLaunchPayload } from "./launchBroker.js";
+import { validateRuntimeProcessExitObservation } from "./processExitObservation.js";
+import { readRuntimeStopReceipt, removeRuntimeStopReceipt } from "./runtimeStopReceipt.js";
+export const AGENT_HOST_CONTROL_PROTOCOL = "yui-agent-host/v1";
+const HOST_CONTROL_TIMEOUT_MS = 5_000;
+const HOST_CONTROL_MAX_BYTES = 8 * 1024;
+export function serializeAgentHostLaunchControl(control) {
+    return JSON.stringify(validateControl(control));
+}
+export async function runAgentHost(input) {
+    const hostInstanceId = randomUUID();
+    let hostSequence = 0;
+    let payload = await redeem(input.home, input.launchId, input.ticket);
+    await replayExitOutbox(input.home);
+    const control = await openHostControl(input.home, payload);
+    try {
+        for (;;) {
+            while (payload.startMode === "idle") {
+                const next = await control.next();
+                payload = await redeem(input.home, next.launchId, next.ticket);
+            }
+            control.setActive(true, payload.launchId);
+            const result = await runAgentHostProviderChild(payload);
+            control.setActive(false);
+            hostSequence += 1;
+            const stopReceipt = readRuntimeStopReceipt(input.home, payload.launchId);
+            await persistAndSubmitExit(input.home, validateRuntimeProcessExitObservation({
+                schemaVersion: 1,
+                observationId: `${hostInstanceId}-${hostSequence}`,
+                hostSequence,
+                hostInstanceId,
+                providerProcessInstanceId: result.processInstanceId,
+                ...(payload.environment.YUI_TASK_ID === undefined
+                    ? {}
+                    : { taskId: payload.environment.YUI_TASK_ID }),
+                roleName: payload.environment.YUI_ROLE ?? "unknown-role",
+                ...(payload.environment.YUI_RUN_ID === undefined
+                    ? {}
+                    : { runId: payload.environment.YUI_RUN_ID }),
+                launchId: payload.launchId,
+                ...(payload.environment.YUI_NATIVE_SESSION_ID === undefined
+                    ? {}
+                    : { nativeSessionId: payload.environment.YUI_NATIVE_SESSION_ID }),
+                processKind: "provider-child",
+                ...(result.code === null ? {} : { exitCode: result.code }),
+                ...(result.signal === null ? {} : { signal: result.signal }),
+                ...(stopReceipt === null ? {} : { stopReceiptId: stopReceipt.receiptId }),
+                observedAt: new Date().toISOString()
+            }));
+            if (stopReceipt !== null)
+                removeRuntimeStopReceipt(input.home, payload.launchId);
+            if (result.hostStopRequested)
+                return 0;
+            // The Agent Host is the durable pane owner. Provider-child exit only
+            // moves it to idle; an exact resume launch may arrive over the private
+            // control socket without replacing the Host or native conversation.
+            const next = await control.next();
+            payload = await redeem(input.home, next.launchId, next.ticket);
+        }
+    }
+    finally {
+        await control.close();
+    }
+}
+export function agentHostControlSocketPath(input) {
+    const owner = input.scope === "task" ? input.taskId ?? "missing-task" : "global";
+    const digest = Buffer.from(`${input.scope}\0${owner}\0${input.roleName}`, "utf8")
+        .toString("base64url")
+        .slice(0, 80);
+    return resolve(join(input.home, "runtime", "agent-host-control", `${digest}.sock`));
+}
+export async function sendAgentHostLaunchControl(input) {
+    const path = agentHostControlSocketPath(input);
+    return await new Promise((resolvePromise, reject) => {
+        const client = createConnection(path);
+        let response = "";
+        const timer = setTimeout(() => {
+            client.destroy();
+            reject(new Error("Agent Host control request timed out."));
+        }, HOST_CONTROL_TIMEOUT_MS);
+        const settle = (callback, value) => {
+            clearTimeout(timer);
+            callback(value);
+        };
+        client.setEncoding("utf8");
+        client.once("connect", () => client.end(`${serializeAgentHostLaunchControl(input.control)}\n`));
+        client.on("data", (chunk) => {
+            response += chunk;
+            if (Buffer.byteLength(response, "utf8") > HOST_CONTROL_MAX_BYTES) {
+                client.destroy(new Error("Agent Host control response exceeds its bound."));
+            }
+        });
+        client.once("error", (error) => settle(reject, error));
+        client.once("close", () => {
+            const value = response.trim();
+            if (value === "accepted" || value === "active-same-launch"
+                || value === "active-other-launch")
+                settle(resolvePromise, value);
+            else
+                settle(reject, new Error(`Agent Host control response is invalid: ${value || "empty"}.`));
+        });
+    });
+}
+async function redeem(home, launchId, ticket) {
+    const result = await callController(home, "runtime.launch-redeem", {
+        launchId,
+        ticket,
+        hostPid: process.pid
+    });
+    return validateAgentHostLaunchPayload(result);
+}
+export async function runAgentHostProviderChild(payload) {
+    const processInstanceId = randomUUID();
+    const child = spawn(payload.command, [...payload.args], {
+        cwd: payload.cwd,
+        env: { ...payload.environment },
+        stdio: payload.providerInput === undefined ? "inherit" : ["pipe", "inherit", "inherit"],
+        detached: true
+    });
+    if (payload.providerInput !== undefined) {
+        if (child.stdin === null)
+            throw new Error("Provider input pipe is unavailable.");
+        const providerInput = `${JSON.stringify({
+            type: "user",
+            message: {
+                role: "user",
+                content: [{ type: "text", text: payload.providerInput.boundedText }]
+            }
+        })}\n`;
+        child.stdin.end(providerInput, "utf8");
+    }
+    const forward = (signal) => {
+        if (child.pid === undefined)
+            return;
+        try {
+            process.kill(-child.pid, signal);
+        }
+        catch (error) {
+            if (error.code !== "ESRCH")
+                throw error;
+        }
+    };
+    const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+    const handlers = new Map();
+    let hostStopRequested = false;
+    let forceKillTimer;
+    for (const signal of signals) {
+        const handler = () => {
+            hostStopRequested = true;
+            forward(signal);
+            forceKillTimer ??= setTimeout(() => forward("SIGKILL"), 10_000);
+            forceKillTimer.unref();
+        };
+        handlers.set(signal, handler);
+        process.on(signal, handler);
+    }
+    try {
+        return await new Promise((resolve, reject) => {
+            child.once("error", reject);
+            child.once("close", (code, signal) => {
+                resolve({ code, signal, processInstanceId, hostStopRequested });
+            });
+        });
+    }
+    finally {
+        for (const [signal, handler] of handlers)
+            process.removeListener(signal, handler);
+        if (forceKillTimer !== undefined)
+            clearTimeout(forceKillTimer);
+    }
+}
+async function persistAndSubmitExit(home, observation) {
+    const directory = resolve(join(home, "runtime", "agent-host-outbox"));
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const path = join(directory, `${observation.hostInstanceId}.jsonl`);
+    const descriptor = openSync(path, "a", 0o600);
+    try {
+        appendFileSync(descriptor, `${JSON.stringify(observation)}\n`, "utf8");
+        fsyncSync(descriptor);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+    chmodSync(path, 0o600);
+    await callController(home, "runtime.process-exit-observe", observation);
+    rmSync(path, { force: true });
+}
+async function replayExitOutbox(home) {
+    const directory = resolve(join(home, "runtime", "agent-host-outbox"));
+    let entries;
+    try {
+        entries = await readdir(directory);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    for (const name of entries.filter((value) => value.includes(".jsonl")).sort()) {
+        const path = join(directory, name);
+        const claimed = `${path}.claim-${process.pid}-${randomUUID()}`;
+        try {
+            await rename(path, claimed);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                continue;
+            throw error;
+        }
+        const lines = (await readFile(claimed, "utf8")).split("\n").filter(Boolean);
+        for (const line of lines) {
+            const observation = validateRuntimeProcessExitObservation(JSON.parse(line));
+            await callController(home, "runtime.process-exit-observe", observation);
+        }
+        await unlink(claimed);
+    }
+}
+async function openHostControl(home, payload) {
+    const directory = resolve(join(home, "runtime", "agent-host-control"));
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const path = agentHostControlSocketPath({
+        home,
+        scope: payload.environment.YUI_SESSION_SCOPE ?? "task",
+        ...(payload.environment.YUI_TASK_ID === undefined
+            ? {}
+            : { taskId: payload.environment.YUI_TASK_ID }),
+        roleName: payload.environment.YUI_ROLE ?? "unknown-role"
+    });
+    if (await hostControlSocketIsLive(path)) {
+        throw new Error(`Agent Host control socket is already owned: ${path}.`);
+    }
+    rmSync(path, { force: true });
+    let active = false;
+    let activeLaunchId;
+    const queued = [];
+    const waiters = [];
+    const server = createServer((socket) => {
+        socket.setEncoding("utf8");
+        let body = "";
+        socket.on("data", (chunk) => {
+            body += chunk;
+            if (Buffer.byteLength(body, "utf8") > HOST_CONTROL_MAX_BYTES) {
+                socket.destroy(new Error("Agent Host control request exceeds its bound."));
+            }
+        });
+        socket.once("end", () => {
+            try {
+                const control = validateControl(JSON.parse(body.trim()));
+                if (active || queued.length > 0) {
+                    socket.end(activeLaunchId === control.launchId
+                        ? "active-same-launch\n"
+                        : "active-other-launch\n");
+                    return;
+                }
+                const waiter = waiters.shift();
+                if (waiter === undefined)
+                    queued.push(control);
+                else
+                    waiter(control);
+                socket.end("accepted\n");
+            }
+            catch (error) {
+                socket.destroy(error);
+            }
+        });
+    });
+    await new Promise((resolvePromise, reject) => {
+        server.once("error", reject);
+        server.listen(path, () => resolvePromise());
+    });
+    chmodSync(path, 0o600);
+    return Object.freeze({
+        setActive(value, launchId) {
+            active = value;
+            activeLaunchId = value ? launchId : undefined;
+        },
+        next() {
+            const available = queued.shift();
+            if (available !== undefined)
+                return Promise.resolve(available);
+            return new Promise((resolvePromise) => waiters.push(resolvePromise));
+        },
+        close: async () => {
+            await new Promise((resolvePromise) => server.close(() => resolvePromise()));
+            rmSync(path, { force: true });
+        }
+    });
+}
+async function hostControlSocketIsLive(path) {
+    return await new Promise((resolvePromise, reject) => {
+        const client = createConnection(path);
+        const timer = setTimeout(() => finish(false), 1_000);
+        const finish = (value) => {
+            clearTimeout(timer);
+            client.removeAllListeners();
+            client.destroy();
+            resolvePromise(value);
+        };
+        client.once("connect", () => finish(true));
+        client.once("error", (error) => {
+            if (error.code === "ENOENT" || error.code === "ECONNREFUSED")
+                finish(false);
+            else
+                reject(error);
+        });
+    });
+}
+function validateControl(control) {
+    if (control.protocol !== AGENT_HOST_CONTROL_PROTOCOL || control.type !== "launch") {
+        throw new Error("Agent Host control protocol is invalid.");
+    }
+    if (typeof control.launchId !== "string" || control.launchId.length === 0
+        || control.launchId.length > 256 || control.launchId.includes("\0")) {
+        throw new Error("Agent Host launch control identity is invalid.");
+    }
+    if (typeof control.ticket !== "string" || !/^[a-f0-9]{64}$/u.test(control.ticket)) {
+        throw new Error("Agent Host launch control ticket is invalid.");
+    }
+    return Object.freeze({ ...control });
+}

package/dist/runtime/builtinAgentDrivers.js

@@ -8,6 +8,18 @@ export function builtinDriverIdForAdapter(adapterId) {
 }
 const STRUCTURED_CLI_CAPABILITIES = Object.freeze({
     surfaces: Object.freeze(["interactive-cli"]),
+    lifecycle: Object.freeze({
+        host: "persistent",
+        providerProcess: "persistent",
+        nativeConversationResume: "exact",
+        // Yui deliberately does not guess provider compaction behavior from token
+        // counters. A future Driver may upgrade these only with exact native facts.
+        compaction: "unknown",
+        compactionEvents: "unavailable",
+        contextUsage: "cumulative-only",
+        inSessionContinuation: true,
+        deliveryDeduplication: "unsupported"
+    }),
     control: Object.freeze({
         start: true,
         resume: true,
@@ -55,6 +67,10 @@ export const BUILTIN_AGENT_DRIVERS = Object.freeze([
         adapterId: "claude",
         capabilities: Object.freeze({
             ...STRUCTURED_CLI_CAPABILITIES,
+            lifecycle: Object.freeze({
+                ...STRUCTURED_CLI_CAPABILITIES.lifecycle,
+                providerProcess: "per-turn"
+            }),
             observation: Object.freeze({
                 ...STRUCTURED_CLI_CAPABILITIES.observation,
                 sessionBootstrap: "preallocated",
@@ -354,6 +370,11 @@ function claudeFailure(payload) {
     const details = optionalText(payload.error_details);
     const lastOutput = optionalText(payload.last_assistant_message);
     const parsed = parseClaudeError(code, details);
+    const retryAfterMs = typeof payload.retry_after_ms === "number"
+        && Number.isSafeInteger(payload.retry_after_ms)
+        && payload.retry_after_ms > 0
+        ? payload.retry_after_ms
+        : undefined;
     return {
         failure: {
             ...(parsed.code !== "unknown" ? { errorCode: parsed.code } : {}),
@@ -362,7 +383,8 @@ function claudeFailure(payload) {
             ...(lastOutput === undefined ? {} : { lastOutput }),
             ...(payload.run_terminal === true || payload.unrecoverable === true
                 ? { runTerminal: true }
-                : {})
+                : {}),
+            ...(retryAfterMs === undefined ? {} : { retryAfterMs })
         },
         summary: [
             "Agent turn failed.",

package/dist/runtime/builtinTranscriptObserver.js

@@ -199,6 +199,7 @@ function normalizedCodexUsage(usage) {
     const cachedInputTokens = integer(usage?.cached_input_tokens);
     const reasoningTokens = integer(usage?.reasoning_output_tokens);
     return Object.freeze({
+        semantics: "cumulative-session",
         inputTokens,
         outputTokens,
         ...(cachedInputTokens === undefined ? {} : { cachedInputTokens }),
@@ -214,6 +215,7 @@ function normalizedClaudeUsage(usage) {
     const cacheCreated = integer(usage?.cache_creation_input_tokens) ?? 0;
     const reasoningTokens = integer(object(usage?.output_tokens_details)?.thinking_tokens);
     return Object.freeze({
+        semantics: "cumulative-session",
         inputTokens: directInput + cacheRead + cacheCreated,
         outputTokens,
         cachedInputTokens: cacheRead + cacheCreated,
@@ -239,6 +241,7 @@ function usageFrom(value) {
     const cachedInputTokens = integer(raw?.cachedInputTokens);
     const reasoningTokens = integer(raw?.reasoningTokens);
     return Object.freeze({
+        semantics: "cumulative-session",
         inputTokens,
         outputTokens,
         ...(cachedInputTokens === undefined ? {} : { cachedInputTokens }),
@@ -259,6 +262,7 @@ function sumUsage(values) {
         reasoningTokens += usage.reasoningTokens ?? 0;
     }
     return Object.freeze({
+        semantics: "cumulative-session",
         inputTokens,
         outputTokens,
         cachedInputTokens,

package/dist/runtime/builtinTranscriptUsage.js

@@ -3,6 +3,7 @@ export function codexTranscriptUsage(transcript) {
     if (report === null)
         return null;
     return Object.freeze({
+        semantics: "cumulative-session",
         inputTokens: report.uncachedInputTokens + report.cacheReadTokens + report.cacheCreatedTokens,
         outputTokens: report.outputTokens,
         ...(report.cacheReadTokens + report.cacheCreatedTokens === 0
@@ -62,6 +63,7 @@ export function claudeTranscriptUsage(transcript) {
     if (report === null)
         return null;
     return Object.freeze({
+        semantics: "cumulative-session",
         inputTokens: report.uncachedInputTokens + report.cacheReadTokens + report.cacheCreatedTokens,
         outputTokens: report.outputTokens,
         ...(report.cacheReadTokens + report.cacheCreatedTokens === 0

package/dist/runtime/exactControlPlane.js

@@ -7,7 +7,7 @@ import { openCompatibleFileTaskStore } from "../storage/compatibleTaskStore.js";
 import { yuiVersionIdentity } from "../version.js";
 import { hasRuntimeCleanupObligation, isRuntimeLaunchReservation, runtimeLifecycleTarget } from "./lifecycleReservation.js";
 import { nativeSessionIdForLaunch } from "./preallocatedNativeSession.js";
-import { formatAgentRunReceiptId } from "../task/taskRecordReference.js";
+import { agentRunDeliveryReceiptId } from "../run/agentRun.js";
 import { writeTextFileAtomically } from "../storage/durableFile.js";
 import { readActiveReleasePointer } from "../release/runtimeRelease.js";
 export const EXACT_CONTROL_ARGUMENT = "--yui-control";
@@ -297,7 +297,7 @@ export function assertExactTaskRuntimeState(runtime, store, options = {}) {
         && (sessions?.inFlight === null || sessions?.inFlight === undefined);
     if (runtime.runId !== undefined && (sessions?.inFlight?.agentId !== runtime.agentId
         || sessions.inFlight.runId !== runtime.runId
-        || sessions.inFlight.receiptId !== formatAgentRunReceiptId(runtime.taskId, runtime.runId)) && !preallocatedBeforeInFlightProjection) {
+        || sessions.inFlight.receiptId !== agentRunDeliveryReceiptId(run)) && !preallocatedBeforeInFlightProjection) {
         throw new Error("Exact Task runtime in-flight Run fence is not current.");
     }
     if (runtime.launchId === undefined || (!reservation && !sessionLaunch)) {

package/dist/runtime/globalProcessExitStore.js

@@ -0,0 +1,38 @@
+import { appendFileSync, chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { validateRuntimeProcessExitObservation } from "./processExitObservation.js";
+/** Immutable low-volume audit for GlobalRoles, which have no Task Event family. */
+export function appendGlobalProcessExitObservation(home, observation, classification) {
+    validateRuntimeProcessExitObservation(observation);
+    if (observation.taskId !== undefined) {
+        throw new Error("Task process exits must use the Task Event store.");
+    }
+    const directory = resolve(join(home, "runtime"));
+    const path = join(directory, "global-process-exits.jsonl");
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    if (existsSync(path)) {
+        const duplicate = readFileSync(path, "utf8").split("\n").some((line) => {
+            if (line.length === 0)
+                return false;
+            try {
+                return JSON.parse(line).observationId
+                    === observation.observationId;
+            }
+            catch {
+                throw new Error("Global process-exit audit is malformed.");
+            }
+        });
+        if (duplicate)
+            return false;
+    }
+    const descriptor = openSync(path, "a", 0o600);
+    try {
+        appendFileSync(descriptor, `${JSON.stringify({ ...observation, classification })}\n`, "utf8");
+        fsyncSync(descriptor);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+    chmodSync(path, 0o600);
+    return true;
+}

package/dist/runtime/launchBroker.js

@@ -0,0 +1,95 @@
+import { randomBytes } from "node:crypto";
+import { resolve } from "node:path";
+const brokers = new Map();
+const TICKET_TTL_MS = 60_000;
+/** One Controller-process broker per canonical Home. Payloads never hit disk or tmux. */
+export function launchBrokerForHome(home) {
+    const key = resolve(home);
+    const existing = brokers.get(key);
+    if (existing !== undefined)
+        return existing;
+    const broker = new LaunchBroker();
+    brokers.set(key, broker);
+    return broker;
+}
+export class LaunchBroker {
+    #reservations = new Map();
+    reserve(payload) {
+        validatePayload(payload);
+        if (this.#reservations.has(payload.launchId)) {
+            throw new Error(`Launch payload is already reserved: ${payload.launchId}.`);
+        }
+        const ticket = randomBytes(32).toString("hex");
+        this.#reservations.set(payload.launchId, Object.freeze({
+            ticket,
+            payload,
+            createdAt: Date.now()
+        }));
+        return Object.freeze({ launchId: payload.launchId, ticket });
+    }
+    redeem(launchId, ticket) {
+        const reservation = this.#reservations.get(launchId);
+        if (reservation === undefined || reservation.ticket !== ticket) {
+            throw new Error("Launch ticket is invalid or already consumed.");
+        }
+        this.#reservations.delete(launchId);
+        if (Date.now() - reservation.createdAt > TICKET_TTL_MS) {
+            throw new Error("Launch ticket expired before redemption.");
+        }
+        return reservation.payload;
+    }
+    revoke(launchId) {
+        this.#reservations.delete(launchId);
+    }
+    pendingCount() {
+        return this.#reservations.size;
+    }
+}
+export function validateAgentHostLaunchPayload(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Agent Host launch payload must be an object.");
+    }
+    return validatePayload(value);
+}
+function validatePayload(payload) {
+    if (payload.schemaVersion !== 1)
+        throw new Error("Agent Host launch payload version is invalid.");
+    text(payload.launchId, "launchId");
+    text(payload.command, "command");
+    text(payload.cwd, "cwd");
+    if (!Array.isArray(payload.args))
+        throw new Error("Agent Host launch args must be an array.");
+    payload.args.forEach((value) => text(value, "argument"));
+    if (payload.environment === null || typeof payload.environment !== "object") {
+        throw new Error("Agent Host launch environment must be an object.");
+    }
+    for (const [key, value] of Object.entries(payload.environment)) {
+        text(key, "environment key");
+        if (typeof value !== "string" || value.includes("\0")) {
+            throw new Error("Agent Host launch environment value is invalid.");
+        }
+    }
+    if (payload.childLifecycle !== "persistent" && payload.childLifecycle !== "per-turn") {
+        throw new Error("Agent Host child lifecycle is invalid.");
+    }
+    if (payload.startMode !== "provider" && payload.startMode !== "idle") {
+        throw new Error("Agent Host start mode is invalid.");
+    }
+    if (payload.providerInput !== undefined) {
+        if (payload.providerInput.kind !== "stdin-json-user-message") {
+            throw new Error("Agent Host Provider input transport is invalid.");
+        }
+        if (typeof payload.providerInput.boundedText !== "string"
+            || payload.providerInput.boundedText.includes("\0")
+            || Buffer.byteLength(payload.providerInput.boundedText, "utf8") > 4 * 1024) {
+            throw new Error("Agent Host Provider input must be bounded bootstrap text.");
+        }
+    }
+    return payload;
+}
+function text(value, label) {
+    if (typeof value !== "string" || value.length === 0 || value.includes("\0")) {
+        throw new Error(`Agent Host ${label} is invalid.`);
+    }
+    return value;
+}

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") })