@zq-silk/yui 0.2.0 → 0.4.2

package/dist/runtime/exactControlPlane.js

@@ -0,0 +1,472 @@
+import { createHash } from "node:crypto";
+import { readFileSync, realpathSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { callController as defaultCallController } from "../core/controllerClient.js";
+import { inspectStorageSchema } from "../storage/storageSchema.js";
+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 { writeTextFileAtomically } from "../storage/durableFile.js";
+export const EXACT_CONTROL_ARGUMENT = "--yui-control";
+export const YUI_CONTROL_PLANE_DESCRIPTOR = "YUI_CONTROL_PLANE_DESCRIPTOR";
+export const YUI_TASK_RUNTIME_DESCRIPTOR = "YUI_TASK_RUNTIME_DESCRIPTOR";
+export function createExactControlPlaneDescriptor(input) {
+    const identity = validateVersionIdentity(input.identity ?? yuiVersionIdentity());
+    return Object.freeze({
+        schemaVersion: 1,
+        kind: "yui-control-plane",
+        executable: canonicalPath(input.executable),
+        cliEntry: canonicalPath(input.cliEntry),
+        yuiHome: canonicalPath(input.yuiHome),
+        identity: Object.freeze({ ...identity })
+    });
+}
+export function createExactTaskRuntimeDescriptor(input) {
+    return Object.freeze({
+        schemaVersion: 1,
+        kind: "yui-task-runtime",
+        controlPlaneDigest: requireDigest(input.controlPlaneDigest),
+        taskId: requireIdentity(input.taskId, "Task id"),
+        roleName: requireIdentity(input.roleName, "Role name"),
+        agentId: requireIdentity(input.agentId, "Agent id"),
+        adapterId: requireAdapter(input.adapterId),
+        workspace: canonicalPath(input.workspace),
+        ...(input.runId === undefined ? {} : { runId: requireIdentity(input.runId, "Run id") }),
+        ...(input.launchId === undefined
+            ? {}
+            : { launchId: requireIdentity(input.launchId, "Launch id") }),
+        ...(input.nativeSessionId === undefined
+            ? {}
+            : { nativeSessionId: requireIdentity(input.nativeSessionId, "Native session id") })
+    });
+}
+export function serializeExactDescriptor(descriptor) {
+    return JSON.stringify(descriptor);
+}
+export function parseExactControlPlaneDescriptor(value) {
+    const record = parseDescriptorRecord(value);
+    assertDescriptorKind(record, "yui-control-plane");
+    if (record.schemaVersion !== 1) {
+        throw new Error("Exact control-plane descriptor schema version is invalid.");
+    }
+    return createExactControlPlaneDescriptor({
+        executable: requireText(record.executable, "Control-plane executable"),
+        cliEntry: requireText(record.cliEntry, "Control-plane CLI entry"),
+        yuiHome: requireText(record.yuiHome, "Control-plane YUI_HOME"),
+        identity: validateVersionIdentity(record.identity)
+    });
+}
+export function parseExactTaskRuntimeDescriptor(value) {
+    const record = parseDescriptorRecord(value);
+    assertDescriptorKind(record, "yui-task-runtime");
+    if (record.schemaVersion !== 1) {
+        throw new Error("Exact Task runtime descriptor schema version is invalid.");
+    }
+    return createExactTaskRuntimeDescriptor({
+        controlPlaneDigest: requireText(record.controlPlaneDigest, "Control-plane digest"),
+        taskId: requireText(record.taskId, "Task id"),
+        roleName: requireText(record.roleName, "Role name"),
+        agentId: requireText(record.agentId, "Agent id"),
+        adapterId: requireAdapter(record.adapterId),
+        workspace: requireText(record.workspace, "Task runtime workspace"),
+        ...(record.runId === undefined ? {} : { runId: requireText(record.runId, "Run id") }),
+        ...(record.launchId === undefined
+            ? {}
+            : { launchId: requireText(record.launchId, "Launch id") }),
+        ...(record.nativeSessionId === undefined
+            ? {}
+            : { nativeSessionId: requireText(record.nativeSessionId, "Native session id") })
+    });
+}
+export function exactControlPlaneDigest(descriptor) {
+    return createHash("sha256").update(serializeExactDescriptor(descriptor)).digest("hex");
+}
+/** Stable per Task/Role/Agent location; volatile Run/launch/native fields are content. */
+export function exactTaskRuntimeDescriptorPath(home, descriptor) {
+    const validated = createExactTaskRuntimeDescriptor(descriptor);
+    const digest = createHash("sha256").update(JSON.stringify([
+        validated.controlPlaneDigest,
+        validated.taskId,
+        validated.roleName,
+        validated.agentId,
+        validated.adapterId,
+        validated.workspace
+    ])).digest("hex");
+    return join(canonicalPath(home), "runtime", "exact-task-runtime", `${digest}.json`);
+}
+export function readExactTaskRuntimeDescriptorSource(source, home) {
+    return readTaskRuntimeSource(source, home).descriptor;
+}
+export function exactControlPlaneCommandPrefix(descriptor) {
+    return [
+        descriptor.executable,
+        descriptor.cliEntry,
+        EXACT_CONTROL_ARGUMENT,
+        exactControlPlaneDigest(descriptor)
+    ].map(shellQuote).join(" ");
+}
+export function extractExactControlArgument(args) {
+    const later = args.indexOf(EXACT_CONTROL_ARGUMENT);
+    if (later < 0)
+        return { args: [...args] };
+    if (later !== 0) {
+        return {
+            args: [...args],
+            error: `${EXACT_CONTROL_ARGUMENT} must be the first CLI argument.`
+        };
+    }
+    const digest = args[1];
+    if (digest === undefined || !/^[a-f0-9]{64}$/u.test(digest)) {
+        return {
+            args: args.slice(2),
+            error: "Exact control-plane digest is invalid."
+        };
+    }
+    return { digest, args: args.slice(2) };
+}
+/**
+ * One read-only gate shared by every managed Task control command. It verifies
+ * the frozen executable/CLI/Home/digest, protocol and scalar-storage identity,
+ * on-disk schema, and any live Controller before command routing may construct
+ * a writable store. Package version alone may advance at the same managed path
+ * so an existing Session can cross an explicitly compatible in-place update.
+ */
+export async function assertExactControlPlanePreflight(input, options = {}) {
+    const descriptor = parseExactControlPlaneDescriptor(input.serializedDescriptor);
+    if (exactControlPlaneDigest(descriptor) !== requireDigest(input.digest)) {
+        throw new Error("Exact control-plane digest does not match its frozen descriptor.");
+    }
+    assertSamePath(descriptor.executable, input.actualExecutable, "Control-plane executable");
+    assertSamePath(descriptor.cliEntry, input.actualCliEntry, "Control-plane CLI entry");
+    assertSamePath(descriptor.yuiHome, input.actualHome, "Control-plane YUI_HOME");
+    const localIdentity = validateVersionIdentity(options.identity ?? yuiVersionIdentity());
+    assertContinuityIdentity("Local CLI", descriptor.identity, localIdentity);
+    const storage = (options.inspectStorage ?? inspectStorageSchema)(descriptor.yuiHome);
+    if (storage.status !== "current") {
+        const exactRecordOnlyOlder = storage.status === "unsupported"
+            && storage.incompatibleComponent === "record"
+            && storage.direction === "older"
+            && storage.currentLayoutVersion === descriptor.identity.storageLayoutVersion
+            && storage.currentAggregateSchemaVersion === descriptor.identity.aggregateSchemaVersion;
+        if (!exactRecordOnlyOlder) {
+            throw new Error(`Exact control-plane storage is not current: ${storage.status}.`);
+        }
+        (options.openCompatibleStore ?? openCompatibleFileTaskStore)(descriptor.yuiHome).getConfig();
+    }
+    if (storage.currentLayoutVersion !== descriptor.identity.storageLayoutVersion) {
+        throw new Error("Exact control-plane storage layout does not match its frozen descriptor "
+            + `(expected ${descriptor.identity.storageLayoutVersion}, found `
+            + `${storage.currentLayoutVersion ?? "unknown"}).`);
+    }
+    if (storage.currentAggregateSchemaVersion !== descriptor.identity.aggregateSchemaVersion) {
+        throw new Error("Exact control-plane aggregate schema does not match its frozen descriptor "
+            + `(expected ${descriptor.identity.aggregateSchemaVersion}, found `
+            + `${storage.currentAggregateSchemaVersion ?? "unknown"}).`);
+    }
+    if (options.checkController !== false) {
+        const call = options.callController ?? defaultCallController;
+        try {
+            const status = await call(descriptor.yuiHome, "controller.status", {});
+            assertControllerContinuityIdentity(status, descriptor.identity);
+        }
+        catch (error) {
+            if (!isDefinitelyNotRunning(error))
+                throw error;
+        }
+    }
+    return descriptor;
+}
+export function assertControllerStatusIdentity(status, expected = yuiVersionIdentity()) {
+    if (!isRecord(status) || status.running !== true) {
+        throw new Error("Controller status does not describe a running Controller.");
+    }
+    assertControllerField(status.protocolVersion, expected.controllerProtocolVersion, "protocol");
+    assertControllerField(status.version, expected.version, "version");
+    assertControllerField(status.storageLayoutVersion, expected.storageLayoutVersion, "storage layout");
+    assertControllerField(status.aggregateSchemaVersion, expected.aggregateSchemaVersion, "aggregate schema");
+}
+export function assertExactTaskRuntimeEnvironment(runtimeSource, environment, expectedControlDigest, expectedHome = requireText(environment.YUI_HOME, "YUI_HOME")) {
+    const resolved = readTaskRuntimeSource(runtimeSource, expectedHome);
+    const runtime = resolved.descriptor;
+    if (runtime.controlPlaneDigest !== requireDigest(expectedControlDigest)) {
+        throw new Error("Task runtime descriptor belongs to another exact control plane.");
+    }
+    assertEnvironment(runtime.taskId, environment.YUI_TASK_ID, "Task id");
+    assertEnvironment(runtime.roleName, environment.YUI_ROLE, "Role name");
+    assertEnvironment(runtime.agentId, environment.YUI_AGENT_ID, "Agent id");
+    assertEnvironment(runtime.adapterId, environment.YUI_ADAPTER_ID, "Agent adapter id");
+    assertSamePath(runtime.workspace, requireText(environment.YUI_WORKSPACE, "YUI_WORKSPACE"), "Task runtime workspace");
+    // A reused native pane retains its original process environment. Volatile
+    // identity therefore comes only from the atomically published descriptor
+    // plus durable state, never from stale ambient Run/launch/native variables.
+    if (!resolved.fromFile) {
+        assertOptionalEnvironment(runtime.runId, environment.YUI_RUN_ID, "Run id");
+        assertOptionalEnvironment(runtime.launchId, environment.YUI_LAUNCH_ID, "Launch id");
+        assertOptionalEnvironment(runtime.nativeSessionId, environment.YUI_NATIVE_SESSION_ID, "Native session id");
+    }
+    return runtime;
+}
+/** Fences a descriptor to the one currently active durable Task runtime. */
+export function assertExactTaskRuntimeState(runtime, store, options = {}) {
+    const task = store.getTask(runtime.taskId);
+    if (task === null || task.status !== "active") {
+        throw new Error("Exact Task runtime Task is not current and active.");
+    }
+    const role = store.getRole(runtime.taskId, runtime.roleName);
+    if (role === null || role.activeAgentId !== runtime.agentId) {
+        throw new Error("Exact Task runtime Role or Agent is not current.");
+    }
+    const run = store.getActiveAgentRun(runtime.taskId, runtime.roleName);
+    if (runtime.runId === undefined) {
+        if (run !== null)
+            throw new Error("Exact Task runtime Run is not current.");
+    }
+    else if (run === null
+        || run.id !== runtime.runId
+        || run.status !== "active"
+        || run.effective.agentId !== runtime.agentId
+        || run.effective.adapterId !== runtime.adapterId
+        || canonicalPath(run.effective.workspace.root) !== runtime.workspace) {
+        throw new Error("Exact Task runtime Run is not current.");
+    }
+    const sessions = store.getTaskRoleSessionSet(runtime.taskId, runtime.roleName);
+    const session = sessions?.sessions[runtime.agentId];
+    if (sessions !== null && sessions.activeAgentId !== runtime.agentId) {
+        throw new Error("Exact Task runtime Session Agent is not current.");
+    }
+    const lifecycleMailbox = store.getWorkMailbox(runtimeLifecycleTarget({
+        scope: "task",
+        taskId: runtime.taskId,
+        roleName: runtime.roleName
+    }));
+    const reservation = runtime.launchId !== undefined
+        && isRuntimeLaunchReservation(lifecycleMailbox?.processing, runtime.launchId);
+    const sessionLaunch = runtime.launchId !== undefined
+        && session?.launchId === runtime.launchId;
+    const executionRef = lifecycleMailbox?.processing?.executionRef;
+    const preallocated = options.preallocatedNativeSessionReservation;
+    const exactPreallocatedReservation = preallocated !== undefined
+        && runtime.adapterId === "claude"
+        && runtime.runId !== undefined
+        && runtime.launchId !== undefined
+        && runtime.nativeSessionId !== undefined
+        && session === undefined
+        && reservation
+        && !hasRuntimeCleanupObligation(lifecycleMailbox)
+        && executionRef?.type === "run"
+        && executionRef.taskId === runtime.taskId
+        && executionRef.id === runtime.runId
+        && runtime.nativeSessionId === nativeSessionIdForLaunch(preallocated.yuiHome, runtime.launchId, runtime.agentId, runtime.adapterId);
+    const preallocatedBeforeInFlightProjection = exactPreallocatedReservation
+        && (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) {
+        throw new Error("Exact Task runtime in-flight Run fence is not current.");
+    }
+    if (runtime.launchId === undefined || (!reservation && !sessionLaunch)) {
+        throw new Error("Exact Task runtime launch fence is not current.");
+    }
+    if (runtime.nativeSessionId === undefined) {
+        if (session !== undefined) {
+            throw new Error("Exact Task runtime native Session fence is missing.");
+        }
+    }
+    else if (session === undefined) {
+        if (!exactPreallocatedReservation) {
+            throw new Error("Exact Task runtime native Session fence is not current.");
+        }
+    }
+    else if (session.agentId !== runtime.agentId
+        || session.adapterId !== runtime.adapterId
+        || session.nativeSessionId !== runtime.nativeSessionId
+        || session.launchId !== runtime.launchId
+        || session.status === "stopped"
+        || session.status === "broken"
+        || session.effective.agentId !== runtime.agentId
+        || session.effective.adapterId !== runtime.adapterId
+        || canonicalPath(session.effective.workspace.root) !== runtime.workspace) {
+        throw new Error("Exact Task runtime native Session fence is not current.");
+    }
+}
+/** Publishes provider-discovered native identity without changing the stable source path. */
+export function refreshExactTaskRuntimeDescriptorSource(source, home, store) {
+    const resolved = readTaskRuntimeSource(source, home);
+    if (!resolved.fromFile) {
+        throw new Error("A managed Task runtime descriptor must use its stable file source.");
+    }
+    const current = resolved.descriptor;
+    const session = store.getTaskRoleSessionSet(current.taskId, current.roleName)
+        ?.sessions[current.agentId];
+    if (session === undefined) {
+        throw new Error("Exact Task runtime native Session is not available for refresh.");
+    }
+    const refreshed = createExactTaskRuntimeDescriptor({
+        ...current,
+        nativeSessionId: session.nativeSessionId
+    });
+    if (exactTaskRuntimeDescriptorPath(home, refreshed) !== resolve(source)) {
+        throw new Error("Refreshed Task runtime descriptor changed its stable identity.");
+    }
+    assertExactTaskRuntimeState(refreshed, store);
+    writeTextFileAtomically(resolve(source), `${serializeExactDescriptor(refreshed)}\n`);
+    return refreshed;
+}
+function readTaskRuntimeSource(source, home) {
+    const value = requireText(source, "Exact Task runtime descriptor source");
+    if (value.trimStart().startsWith("{")) {
+        return { descriptor: parseExactTaskRuntimeDescriptor(value), fromFile: false };
+    }
+    const requested = resolve(value);
+    const root = resolve(canonicalPath(home), "runtime", "exact-task-runtime");
+    if (dirname(requested) !== root) {
+        throw new Error("Exact Task runtime descriptor path is outside its control plane.");
+    }
+    let actual;
+    try {
+        actual = realpathSync(requested);
+    }
+    catch (error) {
+        throw new Error("Exact Task runtime descriptor file is unavailable.", { cause: error });
+    }
+    if (actual !== requested) {
+        throw new Error("Exact Task runtime descriptor file must not be a symbolic link.");
+    }
+    const descriptor = parseExactTaskRuntimeDescriptor(readFileSync(actual, "utf8"));
+    if (exactTaskRuntimeDescriptorPath(home, descriptor) !== requested) {
+        throw new Error("Exact Task runtime descriptor path does not match its stable identity.");
+    }
+    return { descriptor, fromFile: true };
+}
+function validateVersionIdentity(value) {
+    if (!isRecord(value))
+        throw new Error("Yui version identity is invalid.");
+    const version = requireText(value.version, "Yui version");
+    const controllerProtocolVersion = requireVersion(value.controllerProtocolVersion, "Controller protocol version");
+    const storageLayoutVersion = requireVersion(value.storageLayoutVersion, "Storage layout version");
+    const aggregateSchemaVersion = requireVersion(value.aggregateSchemaVersion, "Aggregate schema version");
+    return {
+        version,
+        controllerProtocolVersion,
+        storageLayoutVersion,
+        aggregateSchemaVersion
+    };
+}
+/** Managed continuity is a protocol/storage contract, not a package pin. */
+function assertContinuityIdentity(label, expected, actual) {
+    for (const field of [
+        "controllerProtocolVersion",
+        "storageLayoutVersion",
+        "aggregateSchemaVersion"
+    ]) {
+        if (expected[field] !== actual[field]) {
+            throw new Error(`${label} ${field} does not match the frozen control plane `
+                + `(expected ${expected[field]}, found ${actual[field]}).`);
+        }
+    }
+}
+function assertControllerContinuityIdentity(status, expected) {
+    if (!isRecord(status) || status.running !== true) {
+        throw new Error("Controller status does not describe a running Controller.");
+    }
+    if (typeof status.version !== "string" || status.version.trim().length === 0) {
+        throw new Error("Controller version is invalid at the managed continuity gate.");
+    }
+    assertControllerField(status.protocolVersion, expected.controllerProtocolVersion, "protocol");
+    assertControllerField(status.storageLayoutVersion, expected.storageLayoutVersion, "storage layout");
+    assertControllerField(status.aggregateSchemaVersion, expected.aggregateSchemaVersion, "aggregate schema");
+}
+function assertControllerField(actual, expected, label) {
+    if (actual !== expected) {
+        throw new Error(`Controller ${label} is incompatible with the exact control plane `
+            + `(expected ${expected}, found ${typeof actual === "string" || typeof actual === "number" ? actual : "unknown"}). `
+            + "Run controller restart through the matching exact control-plane invocation "
+            + "before writing new Task records.");
+    }
+}
+function assertSamePath(expected, actual, label) {
+    const normalized = canonicalPath(actual);
+    if (expected !== normalized) {
+        throw new Error(`${label} does not match the frozen control plane (expected ${expected}, found ${normalized}).`);
+    }
+}
+function assertEnvironment(expected, actual, label) {
+    if (actual !== expected) {
+        throw new Error(`${label} does not match the exact Task runtime descriptor.`);
+    }
+}
+function assertOptionalEnvironment(expected, actual, label) {
+    if (actual !== expected) {
+        throw new Error(`${label} does not match the exact Task runtime descriptor.`);
+    }
+}
+function parseDescriptorRecord(value) {
+    let parsed;
+    try {
+        parsed = JSON.parse(requireText(value, "Exact descriptor"));
+    }
+    catch (error) {
+        throw new Error("Exact descriptor is not valid JSON.", { cause: error });
+    }
+    if (!isRecord(parsed))
+        throw new Error("Exact descriptor must be an object.");
+    return parsed;
+}
+function assertDescriptorKind(value, expected) {
+    if (value.kind !== expected) {
+        throw new Error(`Exact descriptor kind is invalid: expected ${expected}, found `
+            + `${typeof value.kind === "string" ? value.kind : "unknown"}.`);
+    }
+}
+function requireAdapter(value) {
+    if (value !== "codex" && value !== "claude") {
+        throw new Error("Agent adapter id is invalid.");
+    }
+    return value;
+}
+function requireIdentity(value, label) {
+    const text = requireText(value, label).trim();
+    if (text.length === 0 || text.length > 1_024 || text.includes("\0")) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return text;
+}
+function requireText(value, label) {
+    if (typeof value !== "string" || value.length === 0 || value.includes("\0")) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return value;
+}
+function requireDigest(value) {
+    const digest = requireText(value, "Control-plane digest");
+    if (!/^[a-f0-9]{64}$/u.test(digest)) {
+        throw new Error("Control-plane digest is invalid.");
+    }
+    return digest;
+}
+function requireVersion(value, label) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return value;
+}
+function canonicalPath(value) {
+    const absolute = resolve(requireText(value, "Path"));
+    try {
+        return realpathSync(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\"'\"'")}'`;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isDefinitelyNotRunning(error) {
+    return isRecord(error) && error.code === "CONTROLLER_NOT_RUNNING";
+}

package/dist/runtime/index.js

@@ -0,0 +1,8 @@
+export { createPromptEnvelope } from "./promptEnvelope.js";
+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 { 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";

package/dist/runtime/lifecycleReservation.js

@@ -0,0 +1,38 @@
+export const RUNTIME_LIFECYCLE_OWNER = "runtime-lifecycle";
+export const RUNTIME_LAUNCH_RESERVED_REASON = "runtime-launch-reserved";
+export const RUNTIME_CLEANUP_REQUIRED_REASON = "runtime-cleanup-required";
+export function runtimeLifecycleTarget(owner) {
+    return owner.scope === "task"
+        ? {
+            kind: "role-runtime",
+            taskId: owner.taskId,
+            roleName: owner.roleName
+        }
+        : {
+            kind: "global-role-runtime",
+            roleName: owner.roleName
+        };
+}
+export function runtimeLifecycleSignalKey(owner) {
+    return owner.scope === "task"
+        ? `role:${encodeURIComponent(owner.taskId)}/${encodeURIComponent(owner.roleName)}`
+        : `global-role:${encodeURIComponent(owner.roleName)}`;
+}
+export function isRuntimeLaunchReservation(processing, launchId) {
+    return processing?.owner === RUNTIME_LIFECYCLE_OWNER
+        && processing.batch.reasons.length === 1
+        && processing.batch.reasons[0] === RUNTIME_LAUNCH_RESERVED_REASON
+        && (launchId === undefined || processing.batchId === launchId);
+}
+export function hasRuntimeLaunchReservation(mailbox) {
+    return isRuntimeLaunchReservation(mailbox?.processing);
+}
+export function hasRuntimeCleanupObligation(mailbox) {
+    return mailbox?.pending?.reasons.includes(RUNTIME_CLEANUP_REQUIRED_REASON) === true
+        || (!isRuntimeLaunchReservation(mailbox?.processing)
+            && mailbox?.processing?.batch.reasons.includes(RUNTIME_CLEANUP_REQUIRED_REASON) === true);
+}
+export function hasRuntimeLifecycleWork(mailbox) {
+    return mailbox !== null
+        && (mailbox.processing !== null || mailbox.pending !== null);
+}

package/dist/runtime/ports.js

@@ -0,0 +1,11 @@
+/** A persisted launch is either temporarily unavailable or permanently lost. */
+export class RuntimeLaunchError extends Error {
+    retryable;
+    launchId;
+    name = "RuntimeLaunchError";
+    constructor(retryable, launchId, message) {
+        super(message);
+        this.retryable = retryable;
+        this.launchId = launchId;
+    }
+}

package/dist/runtime/preallocatedNativeSession.js

@@ -0,0 +1,13 @@
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import { requireText } from "./validation.js";
+/** Deterministic native identity preallocated for one exact provider launch. */
+export function nativeSessionIdForLaunch(home, launchId, agentId, adapterId) {
+    const hex = createHash("sha256").update(JSON.stringify([
+        resolve(requireText(home, "YUI_HOME")),
+        requireText(launchId, "Launch id"),
+        requireText(agentId, "Agent id"),
+        requireText(adapterId, "Agent adapter id")
+    ])).digest("hex");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-4${hex.slice(13, 16)}-a${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+}

package/dist/runtime/promptEnvelope.js

@@ -0,0 +1,30 @@
+import { requireText, requireTimestamp } from "./validation.js";
+import { formatAgentRunReceiptId, formatInputRequestReceiptId, validateTaskRecordReference } from "../task/taskRecordReference.js";
+export function createPromptEnvelope(input) {
+    if (input.source.kind !== "agent-run" && input.source.kind !== "input-request") {
+        throw new Error("Prompt source kind is invalid.");
+    }
+    const source = validateTaskRecordReference({
+        taskId: input.source.taskId,
+        localId: input.source.localId
+    }, input.source.kind === "agent-run" ? "agentRun" : "inputRequest");
+    const id = requireQualifiedReceiptId(input.id, input.source.kind, source.taskId, source.localId);
+    return {
+        id,
+        source: {
+            kind: input.source.kind,
+            taskId: source.taskId,
+            localId: source.localId
+        },
+        text: requireText(input.text, "Prompt text"),
+        createdAt: requireTimestamp(input.createdAt, "Prompt createdAt")
+    };
+}
+function requireQualifiedReceiptId(value, kind, taskId, localId) {
+    const expected = kind === "agent-run"
+        ? formatAgentRunReceiptId(taskId, localId)
+        : formatInputRequestReceiptId(taskId, localId);
+    if (value !== expected)
+        throw new Error("Prompt envelope id does not match its source.");
+    return expected;
+}

package/dist/runtime/runtimeBinding.js

@@ -0,0 +1,31 @@
+import { normalizeRuntimeOwner } from "./runtimeOwner.js";
+import { requireSafeIdentity, requireText } from "./validation.js";
+export function createRuntimeBinding(input) {
+    const hostCreated = input.hostCreated === undefined
+        ? undefined
+        : requireBoolean(input.hostCreated, "Runtime host-created flag");
+    const initialPromptRunId = input.initialPromptRunId === undefined
+        ? undefined
+        : requireSafeIdentity(input.initialPromptRunId, "Initial prompt Run id");
+    if (initialPromptRunId !== undefined && hostCreated !== true) {
+        throw new TypeError("An initial prompt Run id requires a newly-created runtime host.");
+    }
+    return {
+        id: requireSafeIdentity(input.id, "Runtime binding id"),
+        launchId: requireSafeIdentity(input.launchId, "Launch id"),
+        owner: normalizeRuntimeOwner(input.owner),
+        agentId: requireSafeIdentity(input.agentId, "Agent id"),
+        adapterId: requireSafeIdentity(input.adapterId, "Agent adapter id"),
+        hostRef: requireText(input.hostRef, "Session host reference"),
+        ...(hostCreated === undefined ? {} : { hostCreated }),
+        ...(initialPromptRunId === undefined ? {} : { initialPromptRunId }),
+        ...(input.nativeSessionId === undefined
+            ? {}
+            : { nativeSessionId: requireText(input.nativeSessionId, "Native session id") })
+    };
+}
+function requireBoolean(value, label) {
+    if (typeof value !== "boolean")
+        throw new TypeError(`${label} must be boolean.`);
+    return value;
+}

package/dist/runtime/runtimeOwner.js

@@ -0,0 +1,14 @@
+import { requireSafeIdentity } from "./validation.js";
+export function normalizeRuntimeOwner(owner) {
+    const roleName = requireSafeIdentity(owner.roleName, "Role name");
+    if (owner.scope === "global")
+        return { scope: "global", roleName };
+    if (owner.scope === "task") {
+        return {
+            scope: "task",
+            taskId: requireSafeIdentity(owner.taskId, "Task id"),
+            roleName
+        };
+    }
+    throw new Error("Runtime owner scope is invalid.");
+}