@zq-silk/yui 0.6.2 → 0.6.4

package/dist/runtime/builtinAgentDrivers.js

@@ -0,0 +1,235 @@
+import { AgentDriverRegistry } from "./agentDriver.js";
+import { claudeTranscriptObserver, codexTranscriptObserver, transcriptObserverSource } from "./builtinTranscriptObserver.js";
+export const CODEX_DRIVER_ID = "openai/codex";
+export const CLAUDE_CODE_DRIVER_ID = "anthropic/claude-code";
+export function builtinDriverIdForAdapter(adapterId) {
+    return builtinAgentDriverRegistry().requireByAdapterId(adapterId).id;
+}
+const STRUCTURED_CLI_CAPABILITIES = Object.freeze({
+    surfaces: Object.freeze(["interactive-cli"]),
+    control: Object.freeze({
+        start: true,
+        resume: true,
+        sendTurn: true,
+        interrupt: true,
+        stop: true
+    }),
+    observation: Object.freeze({
+        sessionIdentity: "exact",
+        sessionBootstrap: "discovered",
+        preInputReadiness: "unavailable",
+        promptAcceptance: "exact",
+        turnLifecycle: "exact",
+        // Model activity is inferred from usage deltas; these are the operation
+        // boundaries the current Hook surfaces actually expose.
+        operations: Object.freeze(["tool", "subagent"]),
+        waiting: Object.freeze(["permission"]),
+        usage: "streaming-cumulative",
+        delivery: "ordered-best-effort"
+    })
+});
+export const BUILTIN_AGENT_DRIVERS = Object.freeze([
+    Object.freeze({
+        id: CLAUDE_CODE_DRIVER_ID,
+        label: "Claude Code",
+        protocolVersion: 1,
+        adapterId: "claude",
+        capabilities: Object.freeze({
+            ...STRUCTURED_CLI_CAPABILITIES,
+            observation: Object.freeze({
+                ...STRUCTURED_CLI_CAPABILITIES.observation,
+                sessionBootstrap: "preallocated",
+                preInputReadiness: "exact"
+            })
+        }),
+        runtime: Object.freeze({
+            nativeSessionId: ({ payload }) => (optionalIdentityFrom(payload, ["session_id"])),
+            nativeTurnId: ({ payload }) => (optionalIdentityFrom(payload, ["prompt_id", "turn_id"])),
+            mapHook: ({ hookEventName, payload, occurrenceId }) => (mapClaudeHook(hookEventName, payload, occurrenceId)),
+            classifyHook: ({ hookEventName, payload }) => Object.freeze({
+                ...(hookEventName === "SessionStart" && payload.source === "startup"
+                    ? { startupSession: "preallocated" }
+                    : {}),
+                terminal: isTerminalHook(hookEventName)
+            }),
+            observer: Object.freeze({
+                source: (input) => transcriptObserverSource(CLAUDE_CODE_DRIVER_ID, input),
+                sample: claudeTranscriptObserver
+            })
+        })
+    }),
+    Object.freeze({
+        id: CODEX_DRIVER_ID,
+        label: "Codex",
+        protocolVersion: 1,
+        adapterId: "codex",
+        capabilities: STRUCTURED_CLI_CAPABILITIES,
+        runtime: Object.freeze({
+            nativeSessionId: ({ payload }) => (optionalIdentityFrom(payload, ["session_id"])),
+            nativeTurnId: ({ payload }) => (optionalIdentityFrom(payload, ["turn_id", "prompt_id"])),
+            mapHook: ({ hookEventName, payload, occurrenceId }) => (mapCodexHook(hookEventName, payload, occurrenceId)),
+            classifyHook: ({ hookEventName }) => Object.freeze({
+                ...(hookEventName === "SessionStart"
+                    ? { startupSession: "discovered" }
+                    : {}),
+                terminal: isTerminalHook(hookEventName)
+            }),
+            observer: Object.freeze({
+                source: (input) => transcriptObserverSource(CODEX_DRIVER_ID, input),
+                sample: codexTranscriptObserver
+            })
+        })
+    })
+]);
+export function builtinAgentDriverRegistry() {
+    const registry = new AgentDriverRegistry();
+    for (const descriptor of BUILTIN_AGENT_DRIVERS)
+        registry.register(descriptor);
+    return registry;
+}
+function mapClaudeHook(name, payload, occurrenceId) {
+    switch (name) {
+        case "SessionStart":
+            return payload.source === "startup"
+                ? mapped("session.ready")
+                : mapped("session.started");
+        case "UserPromptSubmit":
+            return mapped("turn.accepted");
+        case "PreToolUse":
+            return operation("operation.started", "tool", toolId(payload));
+        case "PostToolUse":
+            return operation("operation.completed", "tool", toolId(payload));
+        case "PostToolUseFailure":
+            return operation("operation.failed", "tool", toolId(payload));
+        case "PermissionRequest":
+            return mapped("turn.waiting", {
+                reason: "permission",
+                waitId: optionalIdentityFrom(payload, ["tool_use_id", "call_id"]) ?? requireOccurrence(occurrenceId)
+            });
+        case "MessageDisplay": {
+            const messageId = optionalIdentityFrom(payload, ["message_id"]);
+            const index = typeof payload.index === "number" && Number.isSafeInteger(payload.index)
+                ? String(payload.index)
+                : undefined;
+            return mapped("activity.observed", {
+                activity: "model",
+                activityId: messageId === undefined
+                    ? requireOccurrence(occurrenceId)
+                    : `${messageId}:${index ?? "message"}`
+            });
+        }
+        case "SubagentStart":
+            return operation("operation.started", "subagent", subagentId(payload));
+        case "SubagentStop":
+            return operation("operation.completed", "subagent", subagentId(payload));
+        case "Stop":
+            return mapped("turn.completed", optionalSummary(payload));
+        case "StopFailure":
+            return mapped("turn.failed", claudeFailure(payload));
+        case "SessionEnd":
+            return mapped("session.ended");
+        default:
+            throw new Error(`Claude Code Driver does not support Hook event: ${name}.`);
+    }
+}
+function mapCodexHook(name, payload, occurrenceId) {
+    switch (name) {
+        case "SessionStart":
+            return mapped("session.started");
+        case "UserPromptSubmit":
+            return mapped("turn.accepted");
+        case "PreToolUse":
+            return operation("operation.started", "tool", toolId(payload));
+        case "PostToolUse":
+            return operation("operation.completed", "tool", toolId(payload));
+        case "PostToolUseFailure":
+            return operation("operation.failed", "tool", toolId(payload));
+        case "PermissionRequest":
+            return mapped("turn.waiting", {
+                reason: "permission",
+                waitId: optionalIdentityFrom(payload, ["tool_use_id", "call_id", "tool_call_id"])
+                    ?? requireOccurrence(occurrenceId)
+            });
+        case "SubagentStart":
+            return operation("operation.started", "subagent", subagentId(payload));
+        case "SubagentStop":
+            return operation("operation.completed", "subagent", subagentId(payload));
+        case "Stop":
+            return mapped("turn.completed", optionalSummary(payload));
+        case "SessionEnd":
+            return mapped("session.ended");
+        default:
+            throw new Error(`Codex Driver does not support Hook event: ${name}.`);
+    }
+}
+function mapped(kind, payload = {}) {
+    return Object.freeze({ kind, payload: Object.freeze({ ...payload }) });
+}
+function operation(kind, operationKind, operationId) {
+    return mapped(kind, { operationId, operation: operationKind });
+}
+function toolId(payload) {
+    return firstIdentity(payload, ["tool_use_id", "call_id", "tool_call_id"], "Tool operation id");
+}
+function subagentId(payload) {
+    return firstIdentity(payload, ["agent_id", "subagent_id"], "Subagent operation id");
+}
+function firstIdentity(payload, fields, label) {
+    for (const field of fields) {
+        const value = payload[field];
+        if (typeof value === "string" && value.trim().length > 0 && !value.includes("\0")) {
+            return value.trim();
+        }
+    }
+    throw new Error(`${label} is required.`);
+}
+function optionalIdentityFrom(payload, fields) {
+    for (const field of fields) {
+        const value = payload[field];
+        if (typeof value === "string" && value.trim().length > 0 && !value.includes("\0")) {
+            return value.trim();
+        }
+    }
+    return undefined;
+}
+function optionalSummary(payload, preferred = "last_assistant_message") {
+    for (const field of [preferred, "summary", "message"]) {
+        const value = payload[field];
+        if (typeof value === "string" && value.trim().length > 0) {
+            return { summary: value.trim() };
+        }
+    }
+    return {};
+}
+function claudeFailure(payload) {
+    const code = firstIdentity(payload, ["error"], "Claude StopFailure error");
+    const details = optionalText(payload.error_details);
+    const lastOutput = optionalText(payload.last_assistant_message);
+    return {
+        failure: {
+            code,
+            ...(details === undefined ? {} : { details }),
+            ...(lastOutput === undefined ? {} : { lastOutput })
+        },
+        summary: [
+            "Agent turn failed.",
+            `error: ${code}`,
+            ...(details === undefined ? [] : [`details: ${details}`]),
+            ...(lastOutput === undefined ? [] : [`last_output: ${lastOutput}`])
+        ].join("\n")
+    };
+}
+function optionalText(value) {
+    return typeof value === "string" && value.trim().length > 0
+        ? value.trim()
+        : undefined;
+}
+function isTerminalHook(name) {
+    return name === "Stop" || name === "StopFailure" || name === "SessionEnd";
+}
+function requireOccurrence(value) {
+    if (value === undefined || value.trim().length === 0) {
+        throw new Error("Agent Driver Hook occurrence id is required.");
+    }
+    return value;
+}

package/dist/runtime/builtinTranscriptObserver.js

@@ -0,0 +1,290 @@
+import { createHash } from "node:crypto";
+import { open, stat } from "node:fs/promises";
+import { isAbsolute } from "node:path";
+const MAX_INITIAL_TAIL_BYTES = 1024 * 1024;
+const MAX_SAMPLE_BYTES = 1024 * 1024;
+const MAX_REMAINDER_BYTES = 64 * 1024;
+const MAX_CLAUDE_MESSAGES = 4_096;
+export function transcriptObserverSource(driverId, input) {
+    if (input.hookEventName !== "UserPromptSubmit")
+        return null;
+    const locator = input.payload.transcript_path;
+    if (typeof locator !== "string" || !isAbsolute(locator) || locator.includes("\0"))
+        return null;
+    const sessionId = identity(input.payload.session_id) ?? "session";
+    const turnId = identity(input.payload.prompt_id)
+        ?? identity(input.payload.turn_id)
+        ?? input.occurrenceId
+        ?? "turn";
+    const digest = createHash("sha256")
+        .update(JSON.stringify([driverId, sessionId, turnId, locator]))
+        .digest("hex");
+    return Object.freeze({
+        schemaVersion: 1,
+        sourceId: `transcript-${digest}`,
+        transport: "append-only-jsonl",
+        locator
+    });
+}
+export async function codexTranscriptObserver(source, cursor) {
+    return sampleJsonl(source, cursor, parseCodexLines);
+}
+export async function claudeTranscriptObserver(source, cursor) {
+    return sampleJsonl(source, cursor, parseClaudeLines);
+}
+async function sampleJsonl(source, rawCursor, parse) {
+    const previous = normalizeCursor(rawCursor);
+    let metadata;
+    try {
+        metadata = await stat(source.locator);
+    }
+    catch (error) {
+        return unavailable(previous, error);
+    }
+    if (!metadata.isFile())
+        return unavailable(previous, new Error("observer locator is not a file"));
+    const reset = previous !== undefined && metadata.size < previous.offset;
+    const initial = previous === undefined || reset;
+    const start = initial
+        ? Math.max(0, metadata.size - MAX_INITIAL_TAIL_BYTES)
+        : previous.offset;
+    const length = Math.min(MAX_SAMPLE_BYTES, Math.max(0, metadata.size - start));
+    let bytes = Buffer.alloc(0);
+    try {
+        if (length > 0) {
+            const handle = await open(source.locator, "r");
+            try {
+                bytes = Buffer.alloc(length);
+                const read = await handle.read(bytes, 0, length, start);
+                bytes = bytes.subarray(0, read.bytesRead);
+            }
+            finally {
+                await handle.close();
+            }
+        }
+    }
+    catch (error) {
+        return unavailable(previous, error);
+    }
+    let text = `${initial ? "" : previous?.remainder ?? ""}${bytes.toString("utf8")}`;
+    if (initial && start > 0) {
+        const firstLineEnd = text.indexOf("\n");
+        text = firstLineEnd < 0 ? "" : text.slice(firstLineEnd + 1);
+    }
+    const complete = text.endsWith("\n");
+    const split = text.split("\n");
+    const remainder = complete ? "" : split.pop() ?? "";
+    const boundedRemainder = Buffer.byteLength(remainder, "utf8") <= MAX_REMAINDER_BYTES
+        ? remainder
+        : "";
+    const parsed = parse(split, initial ? {} : previous?.state ?? {});
+    const nextCursor = Object.freeze({
+        offset: start + bytes.length,
+        remainder: boundedRemainder,
+        state: parsed.state
+    });
+    const fellBehind = start + bytes.length < metadata.size;
+    const detail = parsed.degraded
+        ?? (fellBehind ? "Transcript observer is catching up with a bounded read." : undefined)
+        ?? (reset ? "Transcript was truncated; observer baseline was reset." : undefined)
+        ?? (remainder !== boundedRemainder ? "Oversized partial transcript line was discarded." : undefined);
+    return Object.freeze({
+        cursor: nextCursor,
+        status: detail === undefined ? "healthy" : "degraded",
+        ...(detail === undefined ? {} : { detail }),
+        ...(parsed.usage === undefined ? {} : { usage: parsed.usage }),
+        ...(parsed.activityId === undefined ? {} : {
+            activity: "model",
+            activityId: parsed.activityId
+        })
+    });
+}
+function parseCodexLines(lines, state) {
+    let usage = usageFrom(state.usage);
+    let activityId;
+    let malformed = 0;
+    for (const line of lines) {
+        const entry = jsonObject(line);
+        if (entry === null) {
+            if (line.trim().length > 0)
+                malformed += 1;
+            continue;
+        }
+        if (entry.type !== "event_msg")
+            continue;
+        const payload = object(entry.payload);
+        if (payload?.type !== "token_count")
+            continue;
+        const candidate = normalizedCodexUsage(object(object(payload.info)?.total_token_usage));
+        if (candidate === undefined)
+            continue;
+        usage = candidate;
+        activityId = `usage:${candidate.inputTokens}:${candidate.outputTokens}`;
+    }
+    return Object.freeze({
+        state: Object.freeze({ ...(usage === undefined ? {} : { usage }) }),
+        ...(usage === undefined ? {} : { usage }),
+        ...(activityId === undefined ? {} : { activityId }),
+        ...(malformed === 0 ? {} : { degraded: `${malformed} malformed transcript line(s) ignored.` })
+    });
+}
+function parseClaudeLines(lines, state) {
+    const messages = messageState(state.messages);
+    let activityId;
+    let malformed = 0;
+    for (const line of lines) {
+        const entry = jsonObject(line);
+        if (entry === null) {
+            if (line.trim().length > 0)
+                malformed += 1;
+            continue;
+        }
+        if (entry.type !== "assistant")
+            continue;
+        const message = object(entry.message);
+        const usage = normalizedClaudeUsage(object(message?.usage));
+        if (usage === undefined)
+            continue;
+        const key = identity(message?.id) === undefined
+            ? identity(entry.uuid) === undefined ? undefined : `entry:${identity(entry.uuid)}`
+            : `message:${identity(message?.id)}`;
+        if (key === undefined)
+            continue;
+        messages[key] = usage;
+        activityId = `${key}:${usage.inputTokens}:${usage.outputTokens}`;
+    }
+    const keys = Object.keys(messages);
+    let degraded = malformed === 0 ? undefined : `${malformed} malformed transcript line(s) ignored.`;
+    if (keys.length > MAX_CLAUDE_MESSAGES) {
+        for (const key of keys.slice(0, keys.length - MAX_CLAUDE_MESSAGES))
+            delete messages[key];
+        degraded = "Claude transcript message baseline was bounded to the newest entries.";
+    }
+    const usage = sumUsage(Object.values(messages));
+    return Object.freeze({
+        state: Object.freeze({ messages: Object.freeze(messages) }),
+        ...(usage === undefined ? {} : { usage }),
+        ...(activityId === undefined ? {} : { activityId }),
+        ...(degraded === undefined ? {} : { degraded })
+    });
+}
+function normalizeCursor(input) {
+    if (input === undefined)
+        return undefined;
+    const offset = input.offset;
+    const remainder = input.remainder;
+    const state = input.state;
+    if (!Number.isSafeInteger(offset) || offset < 0
+        || typeof remainder !== "string"
+        || state === null || typeof state !== "object" || Array.isArray(state))
+        return undefined;
+    return Object.freeze({
+        offset: offset,
+        remainder,
+        state: state
+    });
+}
+function unavailable(cursor, error) {
+    return Object.freeze({
+        cursor: cursor ?? Object.freeze({ offset: 0, remainder: "", state: Object.freeze({}) }),
+        status: "unavailable",
+        detail: error instanceof Error ? error.message : String(error)
+    });
+}
+function normalizedCodexUsage(usage) {
+    const inputTokens = integer(usage?.input_tokens);
+    const outputTokens = integer(usage?.output_tokens);
+    if (inputTokens === undefined || outputTokens === undefined)
+        return undefined;
+    const cachedInputTokens = integer(usage?.cached_input_tokens);
+    const reasoningTokens = integer(usage?.reasoning_output_tokens);
+    return Object.freeze({
+        inputTokens,
+        outputTokens,
+        ...(cachedInputTokens === undefined ? {} : { cachedInputTokens }),
+        ...(reasoningTokens === undefined ? {} : { reasoningTokens })
+    });
+}
+function normalizedClaudeUsage(usage) {
+    const directInput = integer(usage?.input_tokens);
+    const outputTokens = integer(usage?.output_tokens);
+    if (directInput === undefined || outputTokens === undefined)
+        return undefined;
+    const cacheRead = integer(usage?.cache_read_input_tokens) ?? 0;
+    const cacheCreated = integer(usage?.cache_creation_input_tokens) ?? 0;
+    const reasoningTokens = integer(object(usage?.output_tokens_details)?.thinking_tokens);
+    return Object.freeze({
+        inputTokens: directInput + cacheRead + cacheCreated,
+        outputTokens,
+        cachedInputTokens: cacheRead + cacheCreated,
+        ...(reasoningTokens === undefined ? {} : { reasoningTokens })
+    });
+}
+function messageState(value) {
+    const source = object(value) ?? {};
+    const result = {};
+    for (const [key, raw] of Object.entries(source)) {
+        const usage = usageFrom(raw);
+        if (usage !== undefined)
+            result[key] = usage;
+    }
+    return result;
+}
+function usageFrom(value) {
+    const raw = object(value);
+    const inputTokens = integer(raw?.inputTokens);
+    const outputTokens = integer(raw?.outputTokens);
+    if (inputTokens === undefined || outputTokens === undefined)
+        return undefined;
+    const cachedInputTokens = integer(raw?.cachedInputTokens);
+    const reasoningTokens = integer(raw?.reasoningTokens);
+    return Object.freeze({
+        inputTokens,
+        outputTokens,
+        ...(cachedInputTokens === undefined ? {} : { cachedInputTokens }),
+        ...(reasoningTokens === undefined ? {} : { reasoningTokens })
+    });
+}
+function sumUsage(values) {
+    if (values.length === 0)
+        return undefined;
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let cachedInputTokens = 0;
+    let reasoningTokens = 0;
+    for (const usage of values) {
+        inputTokens += usage.inputTokens;
+        outputTokens += usage.outputTokens;
+        cachedInputTokens += usage.cachedInputTokens ?? 0;
+        reasoningTokens += usage.reasoningTokens ?? 0;
+    }
+    return Object.freeze({
+        inputTokens,
+        outputTokens,
+        cachedInputTokens,
+        ...(reasoningTokens === 0 ? {} : { reasoningTokens })
+    });
+}
+function jsonObject(line) {
+    if (line.trim().length === 0)
+        return null;
+    try {
+        return object(JSON.parse(line));
+    }
+    catch {
+        return null;
+    }
+}
+function object(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+function integer(value) {
+    return Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+function identity(value) {
+    return typeof value === "string" && value.trim().length > 0 && !value.includes("\0")
+        ? value.trim()
+        : undefined;
+}

package/dist/runtime/builtinTranscriptUsage.js

@@ -0,0 +1,97 @@
+export function codexTranscriptUsage(transcript) {
+    let latest = null;
+    for (const line of transcript.split("\n")) {
+        const entry = parseLine(line);
+        if (entry?.type !== "event_msg")
+            continue;
+        const payload = object(entry.payload);
+        if (payload?.type !== "token_count")
+            continue;
+        const info = object(payload.info);
+        const usage = object(info?.total_token_usage);
+        const inputTokens = integer(usage?.input_tokens);
+        const outputTokens = integer(usage?.output_tokens);
+        if (inputTokens === null || outputTokens === null)
+            continue;
+        const cachedInputTokens = integer(usage?.cached_input_tokens);
+        const reasoningTokens = integer(usage?.reasoning_output_tokens);
+        latest = Object.freeze({
+            inputTokens,
+            outputTokens,
+            ...(cachedInputTokens === null ? {} : { cachedInputTokens }),
+            ...(reasoningTokens === null ? {} : { reasoningTokens })
+        });
+    }
+    return latest;
+}
+export function claudeTranscriptUsage(transcript) {
+    const messages = new Map();
+    for (const line of transcript.split("\n")) {
+        const entry = parseLine(line);
+        if (entry?.type !== "assistant")
+            continue;
+        const message = object(entry.message);
+        const usage = object(message?.usage);
+        const directInput = integer(usage?.input_tokens);
+        const outputTokens = integer(usage?.output_tokens);
+        if (directInput === null || outputTokens === null)
+            continue;
+        const cacheRead = integer(usage?.cache_read_input_tokens) ?? 0;
+        const cacheCreated = integer(usage?.cache_creation_input_tokens) ?? 0;
+        const details = object(usage?.output_tokens_details);
+        const reasoningTokens = integer(details?.thinking_tokens);
+        const key = typeof message?.id === "string" && message.id.length > 0
+            ? `message:${message.id}`
+            : typeof entry.uuid === "string" && entry.uuid.length > 0
+                ? `entry:${entry.uuid}`
+                : null;
+        // A streaming transcript can repeat cumulative snapshots. Without a
+        // stable provider or entry identity, summing them would fabricate growth.
+        if (key === null)
+            continue;
+        messages.set(key, Object.freeze({
+            // Normalize inputTokens as the complete input total. cachedInputTokens is
+            // a breakdown and must not be added to it again by the projection.
+            inputTokens: directInput + cacheRead + cacheCreated,
+            outputTokens,
+            cachedInputTokens: cacheRead + cacheCreated,
+            ...(reasoningTokens === null ? {} : { reasoningTokens })
+        }));
+    }
+    if (messages.size === 0)
+        return null;
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let cachedInputTokens = 0;
+    let reasoningTokens = 0;
+    for (const usage of messages.values()) {
+        inputTokens += usage.inputTokens;
+        outputTokens += usage.outputTokens;
+        cachedInputTokens += usage.cachedInputTokens ?? 0;
+        reasoningTokens += usage.reasoningTokens ?? 0;
+    }
+    return Object.freeze({
+        inputTokens,
+        outputTokens,
+        cachedInputTokens,
+        ...(reasoningTokens === 0 ? {} : { reasoningTokens })
+    });
+}
+function parseLine(line) {
+    if (line.trim().length === 0)
+        return null;
+    try {
+        return object(JSON.parse(line));
+    }
+    catch {
+        return null;
+    }
+}
+function object(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+function integer(value) {
+    return Number.isSafeInteger(value) && value >= 0 ? value : null;
+}

package/dist/runtime/exactControlPlane.js

@@ -280,9 +280,9 @@ export function assertExactTaskRuntimeState(runtime, store, options = {}) {
     const sessionLaunch = runtime.launchId !== undefined
         && session?.launchId === runtime.launchId;
     const executionRef = lifecycleMailbox?.processing?.executionRef;
-    const preallocated = options.preallocatedNativeSessionReservation;
+    const preallocated = options.preallocatedDriverSessionReservation;
     const exactPreallocatedReservation = preallocated !== undefined
-        && runtime.adapterId === "claude"
+        && runtime.adapterId === preallocated.adapterId
         && runtime.runId !== undefined
         && runtime.launchId !== undefined
         && runtime.nativeSessionId !== undefined

package/dist/runtime/index.js

@@ -3,7 +3,7 @@ export { createRuntimeBinding } from "./runtimeBinding.js";
 export { normalizeRuntimeOwner } from "./runtimeOwner.js";
 export { createSessionLaunchRequest } from "./sessionLaunchRequest.js";
 export { createPendingTurnCompletion, DEFAULT_RECENT_TURN_ID_LIMIT, hasRecentTurnId, rememberRecentTurnId, validatePendingTurnCompletion, validateRecentTurnIds } from "./turnCompletion.js";
-export { RuntimeLaunchError } from "./ports.js";
+export { RuntimeHostContentionError, RuntimeLaunchError } from "./ports.js";
 export { TmuxPromptPushAdapter, 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

@@ -2,10 +2,21 @@
 export class RuntimeLaunchError extends Error {
     retryable;
     launchId;
+    reason;
     name = "RuntimeLaunchError";
-    constructor(retryable, launchId, message) {
+    constructor(retryable, launchId, message, reason) {
         super(message);
         this.retryable = retryable;
         this.launchId = launchId;
+        this.reason = reason;
+    }
+}
+/** A host-side contention check that occurs before planning or process start. */
+export class RuntimeHostContentionError extends Error {
+    reason;
+    name = "RuntimeHostContentionError";
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
     }
 }