@zq-silk/yui 0.2.0 → 0.4.2

package/dist/controller/runtimeLaunchCoordinator.js

@@ -0,0 +1,477 @@
+import { createHash, randomUUID } from "node:crypto";
+import { runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
+import { createRuntimeBinding, RuntimeLaunchError } from "../runtime/index.js";
+import { effectiveLaunchSnapshotsCompatible, validateEffectiveLaunchSnapshot } from "../executor/effectiveLaunch.js";
+class RuntimeBindingContractError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "RuntimeBindingContractError";
+    }
+}
+/**
+ * One application service owns the reservation -> host -> persistence
+ * protocol for both foreground enter and scheduler-driven Role launches.
+ */
+export class RuntimeLaunchCoordinator {
+    reservations;
+    host;
+    #createGenerationId;
+    #now;
+    #assertCurrent;
+    #launchFingerprint;
+    #onCleanupRequired;
+    #runtimeIsolation;
+    constructor(reservations, host, options = {}) {
+        this.reservations = reservations;
+        this.host = host;
+        this.#createGenerationId = options.createGenerationId ?? randomUUID;
+        this.#now = options.now ?? (() => new Date());
+        this.#assertCurrent = options.assertCurrent;
+        this.#launchFingerprint = options.launchFingerprint
+            ?? defaultLaunchFingerprint;
+        this.#onCleanupRequired = options.onCleanupRequired;
+        this.#runtimeIsolation = options.runtimeIsolation;
+    }
+    async prepare(request, persistence, assertCurrent, beforeHostStart) {
+        const ownerKey = request.owner.scope === "task"
+            ? `task\0${request.owner.taskId}\0${request.owner.roleName}`
+            : `global\0${request.owner.roleName}`;
+        const previous = this.#launchTails.get(ownerKey) ?? Promise.resolve();
+        let release;
+        const current = new Promise((resolve) => { release = resolve; });
+        const tail = previous.then(() => current);
+        this.#launchTails.set(ownerKey, tail);
+        await previous;
+        try {
+            return await this.#prepareUnlocked(request, persistence, assertCurrent, beforeHostStart);
+        }
+        finally {
+            release();
+            if (this.#launchTails.get(ownerKey) === tail) {
+                this.#launchTails.delete(ownerKey);
+            }
+        }
+    }
+    #launchTails = new Map();
+    async #prepareUnlocked(request, persistence, assertCurrent, beforeHostStart) {
+        const effective = validateEffectiveLaunchSnapshot(request.effective);
+        if (effective.agentId !== request.agentId
+            || effective.adapterId !== request.adapterId
+            || effective.workspace.root !== request.workspace) {
+            throw new TypeError("Runtime launch request does not match its effective snapshot.");
+        }
+        if (this.#runtimeIsolation !== undefined && request.owner.scope === "task") {
+            if (request.managedWorkspace === undefined) {
+                throw new Error("An authoritative ManagedWorkspace owner is required for a Task runtime launch.");
+            }
+            if (request.managedWorkspace.owner.taskId !== request.owner.taskId
+                || request.managedWorkspace.root !== request.workspace) {
+                throw new Error("Task runtime launch does not match its authoritative ManagedWorkspace.");
+            }
+        }
+        if (request.owner.scope === "global" && request.managedWorkspace !== undefined) {
+            throw new Error("A global runtime cannot use a Task ManagedWorkspace.");
+        }
+        const expectedFingerprint = requireText(this.#launchFingerprint(request), "Launch fingerprint");
+        const assertLaunchCurrent = () => {
+            this.#assertCurrent?.(request);
+            assertCurrent?.();
+            if (this.#launchFingerprint(request) !== expectedFingerprint) {
+                throw new Error(`Role or Agent launch state changed: ${request.owner.roleName}.`);
+            }
+        };
+        const generationPrefix = `runtime-${expectedFingerprint}:generation:`;
+        const proposedGenerationId = requireText(this.#createGenerationId(), "Launch generation id");
+        const proposedLaunchId = `${generationPrefix}${proposedGenerationId}`;
+        let runtimeIsolation = this.#preflightRuntimeIsolation(request, proposedLaunchId, proposedGenerationId, false);
+        let reservation = this.reservations.reserveRuntimeLaunch({
+            owner: request.owner,
+            launchId: proposedLaunchId,
+            ...(request.runId === undefined ? {} : { runId: request.runId })
+        }, assertLaunchCurrent, this.#now());
+        let reusedConfirmedRunningHost = false;
+        let launchPromptAcknowledgementRequired = false;
+        if (reservation.status === "existing") {
+            if (!reservation.launchId.startsWith(generationPrefix)) {
+                this.#requireCleanup(request.owner);
+                throw new Error(`Runtime launch reservation belongs to stale Role or Agent state: ${request.owner.roleName}.`);
+            }
+            const sameRunReservation = request.runId !== undefined
+                && reservation.runId === request.runId;
+            const differentRunReservation = request.runId !== undefined
+                && reservation.runId !== undefined
+                && reservation.runId !== request.runId;
+            const inspection = await this.host.inspectOwner(request.owner);
+            if (inspection.state === "unavailable" || inspection.state === "starting") {
+                if (sameRunReservation) {
+                    throw new RuntimeLaunchError(true, reservation.launchId, `Runtime is temporarily ${inspection.state}: ${request.runId}/${reservation.launchId}.`);
+                }
+                throw new Error(`Runtime launch reservation cannot yet be verified: ${request.owner.roleName}.`);
+            }
+            if (inspection.state === "stopped") {
+                if (sameRunReservation) {
+                    throw new RuntimeLaunchError(false, reservation.launchId, `Exact Run launch generation stopped before delivery: ${request.runId}/${reservation.launchId}.`);
+                }
+                const taskOwner = request.owner.scope === "task"
+                    ? request.owner
+                    : undefined;
+                let exactCleanupAttempted = false;
+                let completed = false;
+                try {
+                    completed = this.reservations.completeRuntimeLaunchReservation(request.owner, reservation.launchId, differentRunReservation ? reservation.runId : undefined, taskOwner !== undefined && this.#runtimeIsolation !== undefined
+                        ? () => {
+                            exactCleanupAttempted = true;
+                            this.#cleanupTaskLaunch(taskOwner, reservation.launchId);
+                        }
+                        : undefined);
+                }
+                catch (error) {
+                    if (exactCleanupAttempted)
+                        this.#requireCleanup(request.owner);
+                    throw error;
+                }
+                if (!completed) {
+                    if (exactCleanupAttempted)
+                        this.#requireCleanup(request.owner);
+                    throw new Error("Runtime launch reservation changed during recovery.");
+                }
+                reservation = this.reservations.reserveRuntimeLaunch({
+                    owner: request.owner,
+                    launchId: proposedLaunchId,
+                    ...(request.runId === undefined ? {} : { runId: request.runId })
+                }, assertLaunchCurrent, this.#now());
+                if (reservation.status !== "reserved") {
+                    throw new Error("Runtime launch reservation could not be renewed.");
+                }
+            }
+            else {
+                if (differentRunReservation) {
+                    throw new Error(`Runtime launch reservation belongs to another Run whose host is still running: ${reservation.runId}.`);
+                }
+                reusedConfirmedRunningHost = true;
+                // Only a fresh Codex generation can carry the exact Run prompt in its
+                // launch argv. A resume request targets an existing native Session and
+                // must use the normal receipt-backed prompt push, even when the
+                // Controller is recovering the same launch reservation.
+                launchPromptAcknowledgementRequired = sameRunReservation
+                    && request.mode === "new"
+                    && request.adapterId === "codex";
+                runtimeIsolation = this.#preflightRuntimeIsolation(request, reservation.launchId, reservation.launchId.slice(generationPrefix.length), true);
+                assertLaunchCurrent();
+            }
+        }
+        const launchId = reservation.launchId;
+        let preflightObserved = beforeHostStart === undefined;
+        const observePreflight = (preflight) => {
+            if (preflightObserved) {
+                throw new Error("Runtime host reported its pre-start launch fence more than once.");
+            }
+            validateRuntimeLaunchPreflight(preflight, request, launchId);
+            preflightObserved = true;
+            beforeHostStart?.(preflight);
+        };
+        let binding;
+        try {
+            if (!reusedConfirmedRunningHost && runtimeIsolation !== undefined) {
+                // Activation is the first runtime-resource side effect and can occur
+                // only after the centralized read-only preflight and durable launch
+                // reservation have both succeeded.
+                this.#runtimeIsolation.activate(runtimeIsolation);
+            }
+            const rawBinding = request.mode === "new"
+                ? await this.host.start({
+                    mode: "new",
+                    launchId,
+                    owner: request.owner,
+                    agentId: request.agentId,
+                    adapterId: request.adapterId,
+                    effective: request.effective,
+                    workspace: request.workspace,
+                    ...(runtimeIsolation === undefined
+                        ? {}
+                        : { runtimeIsolation: runtimeIsolation.descriptor }),
+                    ...(request.runId === undefined ? {} : { runId: request.runId }),
+                    ...(request.environment === undefined
+                        ? {}
+                        : { environment: request.environment })
+                }, beforeHostStart === undefined ? undefined : observePreflight)
+                : await this.host.resume({
+                    mode: "resume",
+                    launchId,
+                    owner: request.owner,
+                    agentId: request.agentId,
+                    adapterId: request.adapterId,
+                    effective: request.effective,
+                    workspace: request.workspace,
+                    ...(runtimeIsolation === undefined
+                        ? {}
+                        : { runtimeIsolation: runtimeIsolation.descriptor }),
+                    ...(request.runId === undefined ? {} : { runId: request.runId }),
+                    ...(request.environment === undefined
+                        ? {}
+                        : { environment: request.environment }),
+                    nativeSessionId: requireText(request.nativeSessionId, "Native session id")
+                }, beforeHostStart === undefined ? undefined : observePreflight);
+            if (!preflightObserved) {
+                throw new Error("Runtime session host did not expose a pre-host-start launch fence.");
+            }
+            binding = requireMatchingRuntimeBinding(rawBinding, request, launchId, launchPromptAcknowledgementRequired, reusedConfirmedRunningHost);
+        }
+        catch (error) {
+            if (error instanceof RuntimeBindingContractError) {
+                // Never pass an untrusted hostRef to stop(). Reconcile the requested
+                // owner through the durable, owner-addressed cleanup lane instead.
+                this.#requireCleanup(request.owner);
+                throw error;
+            }
+            await this.#settleFailedStart(request, launchId, reusedConfirmedRunningHost, runtimeIsolation);
+            throw error;
+        }
+        if (reusedConfirmedRunningHost && binding.hostCreated === true) {
+            if (request.runId !== undefined && reservation.runId === request.runId) {
+                throw new RuntimeLaunchError(false, launchId, `Exact Run launch generation was unexpectedly recreated: ${request.runId}/${launchId}.`);
+            }
+            await this.#compensateStartedHost(request.owner, binding, launchId, runtimeIsolation, new Error(`Runtime host was recreated while recovering an existing generation: ${request.owner.roleName}.`));
+        }
+        let reservationConfirmation;
+        try {
+            assertLaunchCurrent();
+            if (persistence === "immediate" && binding.nativeSessionId !== undefined) {
+                this.reservations.recordReservedRuntimeNativeSession({
+                    owner: request.owner,
+                    launchId,
+                    agentId: request.agentId,
+                    adapterId: request.adapterId,
+                    nativeSessionId: binding.nativeSessionId,
+                    effective: request.effective
+                }, assertLaunchCurrent, this.#now());
+            }
+            else {
+                // Deferred scheduler persistence records a known native identity while
+                // retaining the reservation until exact Run delivery. Fresh Codex has
+                // no identity yet and keeps it until its matching generation Hook.
+                reservationConfirmation = this.reservations.confirmRuntimeLaunchReservation({
+                    owner: request.owner,
+                    launchId
+                }, assertLaunchCurrent);
+            }
+        }
+        catch (error) {
+            await this.#compensateStartedHost(request.owner, binding, launchId, runtimeIsolation, error);
+        }
+        if (request.owner.scope === "task"
+            && request.adapterId === "codex"
+            && request.runId !== undefined
+            && binding.hostCreated !== false
+            && reservationConfirmation !== "provider-bound"
+            && binding.initialPromptRunId !== request.runId) {
+            // Fresh Codex has no pre-input Provider event. It may return before its
+            // matching lifecycle Hook, but only an exact launch-carried Run marker
+            // can bridge that asynchronous interval. This is transport evidence,
+            // never Provider acceptance; the reservation remains fenced until the
+            // matching Hook binds the native Session.
+            this.#requireCleanup(request.owner);
+            throw new RuntimeBindingContractError(`Session host cannot acknowledge the exact launch-carried prompt: ${request.owner.roleName}.`);
+        }
+        return binding;
+    }
+    async #settleFailedStart(request, launchId, reusedConfirmedRunningHost, runtimeIsolation) {
+        let inspection;
+        try {
+            inspection = await this.host.inspectOwner(request.owner);
+        }
+        catch {
+            // A rebind/preflight failure did not create the already-confirmed host.
+            // Preserve its generation when the follow-up probe is merely unknown.
+            if (!reusedConfirmedRunningHost)
+                this.#requireCleanup(request.owner);
+            return;
+        }
+        if (inspection.state === "stopped") {
+            if (runtimeIsolation !== undefined) {
+                try {
+                    this.#runtimeIsolation.cleanup(runtimeIsolation, "failure");
+                }
+                catch (cleanupError) {
+                    this.#requireCleanup(request.owner);
+                    throw new Error(`Task runtime launch failed and exact resource cleanup also failed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`, { cause: cleanupError });
+                }
+            }
+            if (!this.#settleConfirmedStopped(request, launchId)) {
+                this.#requireCleanup(request.owner);
+            }
+            return;
+        }
+        if (reusedConfirmedRunningHost)
+            return;
+        this.#requireCleanup(request.owner);
+    }
+    async #compensateStartedHost(owner, binding, launchId, runtimeIsolation, cause) {
+        try {
+            await this.host.stop(binding);
+        }
+        catch (stopError) {
+            this.#requireCleanup(owner);
+            throw new Error(`Runtime launch state changed. Runtime cleanup also failed: ${stopError instanceof Error ? stopError.message : String(stopError)}`, { cause: stopError });
+        }
+        let stopped = false;
+        try {
+            stopped = (await this.host.inspectOwner(owner)).state === "stopped";
+        }
+        catch {
+            // Durable owner cleanup below is the only safe fallback.
+        }
+        if (stopped && runtimeIsolation !== undefined) {
+            try {
+                this.#runtimeIsolation.cleanup(runtimeIsolation, "failure");
+            }
+            catch (cleanupError) {
+                this.#requireCleanup(owner);
+                throw new Error(`Runtime host stopped but exact Task resource cleanup failed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`, { cause: cleanupError });
+            }
+        }
+        if (!stopped
+            || !this.reservations.settleStoppedRuntimeLaunch({
+                owner,
+                launchId,
+                agentId: binding.agentId,
+                adapterId: binding.adapterId,
+                ...(binding.nativeSessionId === undefined
+                    ? {}
+                    : { nativeSessionId: binding.nativeSessionId })
+            }, this.#now())) {
+            this.#requireCleanup(owner);
+        }
+        throw cause;
+    }
+    #preflightRuntimeIsolation(request, launchId, generationId, allowExactActive) {
+        if (this.#runtimeIsolation === undefined || request.owner.scope !== "task") {
+            return undefined;
+        }
+        return this.#runtimeIsolation.preflight({
+            workspace: request.managedWorkspace,
+            ...(request.runId === undefined ? {} : { runId: request.runId }),
+            launchId,
+            generationId: requireText(generationId, "Launch generation id"),
+            ...(request.runtimePolicy === undefined ? {} : { policy: request.runtimePolicy }),
+            ...(allowExactActive ? { allowExactActive: true } : {})
+        });
+    }
+    #cleanupTaskLaunch(owner, launchId) {
+        const cleanupTaskLaunch = this.#runtimeIsolation?.cleanupTaskLaunch;
+        if (cleanupTaskLaunch === undefined) {
+            throw new Error("Exact Task runtime launch cleanup is unavailable.");
+        }
+        cleanupTaskLaunch.call(this.#runtimeIsolation, {
+            taskId: owner.taskId,
+            launchId,
+            reason: "interruption"
+        });
+    }
+    #settleConfirmedStopped(request, launchId) {
+        return this.reservations.settleStoppedRuntimeLaunch({
+            owner: request.owner,
+            launchId,
+            agentId: request.agentId,
+            adapterId: request.adapterId,
+            ...(request.nativeSessionId === undefined
+                ? {}
+                : { nativeSessionId: request.nativeSessionId })
+        }, this.#now());
+    }
+    #requireCleanup(owner) {
+        const target = this.reservations.enqueueRuntimeCleanup(owner, this.#now())
+            ?? runtimeLifecycleTarget(owner);
+        try {
+            this.#onCleanupRequired?.(target);
+        }
+        catch {
+            // The durable cleanup lane is authoritative.
+        }
+    }
+}
+function validateRuntimeLaunchPreflight(preflight, request, launchId) {
+    const ownerMatches = preflight.owner.scope === request.owner.scope
+        && preflight.owner.roleName === request.owner.roleName
+        && (preflight.owner.scope === "global"
+            || (request.owner.scope === "task"
+                && preflight.owner.taskId === request.owner.taskId));
+    if (preflight.launchId !== launchId
+        || !ownerMatches
+        || preflight.runId !== request.runId
+        || preflight.agentId !== request.agentId
+        || preflight.adapterId !== request.adapterId
+        || !effectiveLaunchSnapshotsCompatible(preflight.effective, request.effective)
+        || (request.mode === "resume"
+            && preflight.nativeSessionId !== request.nativeSessionId)
+        || (preflight.initialPromptRunId !== undefined
+            && preflight.initialPromptRunId !== request.runId)) {
+        throw new Error(`Session host pre-start launch fence does not match the requested runtime: ${request.owner.roleName}.`);
+    }
+}
+function requireMatchingRuntimeBinding(raw, request, launchId, launchPromptAcknowledgementRequired, launchPromptUncertaintyAllowed) {
+    let binding;
+    try {
+        binding = createRuntimeBinding(raw);
+    }
+    catch (error) {
+        throw new RuntimeBindingContractError("Session host returned an invalid runtime binding.", { cause: error });
+    }
+    const ownerMatches = binding.owner.scope === request.owner.scope
+        && binding.owner.roleName === request.owner.roleName
+        && (binding.owner.scope === "global"
+            || (request.owner.scope === "task"
+                && binding.owner.taskId === request.owner.taskId));
+    if (binding.initialPromptRunId !== undefined
+        && binding.initialPromptRunId !== request.runId) {
+        throw new RuntimeBindingContractError(`Session host returned a launch-carried prompt for another Run: ${request.owner.roleName}.`);
+    }
+    if (launchPromptAcknowledgementRequired
+        && binding.initialPromptRunId !== request.runId
+        && !(launchPromptUncertaintyAllowed && binding.hostCreated === false)) {
+        throw new RuntimeBindingContractError(`Session host cannot acknowledge the exact launch-carried prompt: ${request.owner.roleName}.`);
+    }
+    if (binding.launchId !== launchId
+        || !ownerMatches
+        || binding.agentId !== request.agentId
+        || binding.adapterId !== request.adapterId
+        || (request.mode === "resume"
+            && binding.nativeSessionId !== request.nativeSessionId)) {
+        throw new RuntimeBindingContractError(`Session host returned a binding that does not match the requested runtime: ${request.owner.roleName}.`);
+    }
+    if (launchPromptAcknowledgementRequired
+        && launchPromptUncertaintyAllowed
+        && binding.hostCreated === false
+        && request.runId !== undefined
+        && binding.initialPromptRunId !== request.runId) {
+        // A Controller restart can lose only the in-memory fact that a still-
+        // running Codex generation carried this Run in its launch argv. Keep the
+        // uncertainty explicitly tied to the exact reservation/Run; the matching
+        // Provider Hook remains the sole acceptance authority.
+        return {
+            ...binding,
+            launchPromptUncertainRunId: request.runId
+        };
+    }
+    return binding;
+}
+function defaultLaunchFingerprint(request) {
+    return createHash("sha256").update(JSON.stringify([
+        request.owner,
+        request.agentId,
+        request.adapterId,
+        request.effective,
+        request.workspace,
+        request.managedWorkspace,
+        request.runtimePolicy
+    ])).digest("hex");
+}
+function requireText(value, label) {
+    if (typeof value !== "string"
+        || value.length === 0
+        || value.trim() !== value
+        || value.includes("\0")) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return value;
+}