@zq-silk/yui 0.8.1 → 0.8.2

package/dist/controller/runtime.js

@@ -17,9 +17,9 @@ import { AsyncTaskStoreClient, resolveStoreWorkerEnabledForHome } from "../stora
 import { FileTaskWorkspacePreparer } from "../repository/taskWorkspacePreparer.js";
 import { NodeCommandExecutor } from "../tmux/commandExecutor.js";
 import { TmuxManager, yuiTmuxServerName } from "../tmux/tmuxManager.js";
-import { FileTaskRuntimeIsolation, TmuxPromptPushAdapter, TmuxSessionHost, ProviderContinuationReconciliationService } from "../runtime/index.js";
+import { AgentHostPromptPushAdapter, FileTaskRuntimeIsolation, TmuxSessionHost, ProviderContinuationReconciliationService } from "../runtime/index.js";
 import { startFileTaskController } from "./controller.js";
-import { FileSchedulerStoreAdapter } from "./fileSchedulerStoreAdapter.js";
+import { AgentHostProviderTurnFenceError, FileSchedulerStoreAdapter } from "./fileSchedulerStoreAdapter.js";
 import { openSchedulerTelemetry } from "../telemetry/telemetryWiring.js";
 import { createFileArtifactPort, createLinuxProcessPort, DurableJobSupervisor } from "./jobSupervisor.js";
 import { createDurableJobControl } from "./jobControl.js";
@@ -38,7 +38,7 @@ import { launchBrokerForHome } from "../runtime/launchBroker.js";
 import { classifyRuntimeProcessExit, validateRuntimeProcessExitObservation } from "../runtime/processExitObservation.js";
 import { appendGlobalProcessExitObservation } from "../runtime/globalProcessExitStore.js";
 import { builtinAgentDriverRegistry } from "../runtime/builtinAgentDrivers.js";
-import { runtimeObservationFromTaskEvent } from "../runtime/runtimeObservation.js";
+import { createRuntimeObservation, runtimeObservationFromTaskEvent } from "../runtime/runtimeObservation.js";
 import { createTaskEvent } from "../event/taskEvent.js";
 /** Refreshes only the exact Task runtime generation folded by the event transaction. */
 export function refreshAppliedTaskRuntimeDescriptor(store, planner, input) {
@@ -198,7 +198,7 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
         }
     });
     const promptPush = options.promptPush
-        ?? new TmuxPromptPushAdapter(tmux, agentProcessReadinessProbe);
+        ?? new AgentHostPromptPushAdapter(home);
     const runtimeIsolation = options.runtimeIsolation
         ?? new FileTaskRuntimeIsolation({
             // A sibling of the exact control Home keeps provider data/cache/tmp out
@@ -283,9 +283,6 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
         sessionHost,
         promptPush,
         launchCoordinator,
-        ...(options.providerInputRouting === undefined
-            ? {}
-            : { providerInputRouting: options.providerInputRouting }),
         roleResourceInventory: async (panes, inputs) => {
             const inventory = await scanInventory(panes);
             return inventory.resources.flatMap((resource) => {
@@ -550,6 +547,55 @@ export function createRuntimeLifecycleDispatcher(store, schedulerStore, sessionH
         });
     const lifecycleTails = new Map();
     return async (method, params) => {
+        if (method === "runtime.observation-apply") {
+            return {
+                outcome: schedulerStore.observeRuntimeObservation(createRuntimeObservation(params), new Date())
+            };
+        }
+        if (method === "runtime.provider-turn-begin") {
+            const value = providerTurnControlParams(params);
+            try {
+                schedulerStore.beginAgentHostProviderTurn({
+                    taskId: value.taskId,
+                    roleName: value.roleName,
+                    runId: value.runId,
+                    agentId: value.agentId,
+                    launchId: value.launchId,
+                    nativeSessionId: value.nativeSessionId,
+                    attemptId: value.attemptId,
+                    authorityEpoch: value.authorityEpoch,
+                    authorityOwner: value.authorityOwner,
+                    holderId: value.holderId,
+                    now: value.now
+                });
+            }
+            catch (error) {
+                if (error instanceof AgentHostProviderTurnFenceError) {
+                    throw applicationError("INVALID_PARAMS", error.message);
+                }
+                throw error;
+            }
+            return { recorded: true };
+        }
+        if (method === "runtime.provider-turn-submission-resolve") {
+            const value = providerTurnControlParams(params);
+            const status = params.status;
+            const reason = params.reason;
+            if ((status !== "rejected" && status !== "delivery-unknown")
+                || typeof reason !== "string" || reason.trim().length === 0) {
+                throw applicationError("INVALID_PARAMS", "Provider Turn resolution is invalid.");
+            }
+            schedulerStore.resolveAgentHostProviderTurnSubmission({
+                taskId: value.taskId,
+                roleName: value.roleName,
+                runId: value.runId,
+                attemptId: value.attemptId,
+                status,
+                reason,
+                now: value.now
+            });
+            return { recorded: true };
+        }
         if (method === "runtime.process-exit-observe") {
             const observation = validateRuntimeProcessExitObservation(params);
             const run = observation.taskId === undefined || observation.runId === undefined
@@ -1032,6 +1078,33 @@ function requiredParam(value) {
     }
     return value;
 }
+function providerTurnControlParams(params) {
+    if (typeof params !== "object" || params === null || Array.isArray(params)) {
+        throw applicationError("INVALID_PARAMS", "Provider Turn control params are invalid.");
+    }
+    const value = params;
+    const authorityEpoch = value.authorityEpoch;
+    const authorityOwner = value.authorityOwner;
+    const observedAt = requiredParam(value.observedAt);
+    if (!Number.isSafeInteger(authorityEpoch) || authorityEpoch < 1
+        || (authorityOwner !== "controller" && authorityOwner !== "human")
+        || !Number.isFinite(Date.parse(observedAt))) {
+        throw applicationError("INVALID_PARAMS", "Provider Turn control fence is invalid.");
+    }
+    return {
+        taskId: requiredParam(value.taskId),
+        roleName: requiredParam(value.roleName),
+        runId: requiredParam(value.runId),
+        agentId: requiredParam(value.agentId),
+        launchId: requiredParam(value.launchId),
+        nativeSessionId: requiredParam(value.nativeSessionId),
+        attemptId: requiredParam(value.attemptId),
+        authorityEpoch: authorityEpoch,
+        authorityOwner,
+        holderId: requiredParam(value.holderId),
+        now: new Date(observedAt)
+    };
+}
 function abortableDelay(milliseconds, signal) {
     return new Promise((resolve, reject) => {
         const timer = setTimeout(() => {

package/dist/controller/runtimeLaunchCoordinator.js

@@ -8,12 +8,6 @@ class RuntimeBindingContractError extends Error {
         this.name = "RuntimeBindingContractError";
     }
 }
-class LaunchSubmittedHostBusyError extends RuntimeBindingContractError {
-    constructor(message) {
-        super(message);
-        this.name = "LaunchSubmittedHostBusyError";
-    }
-}
 class RuntimeLaunchStateChangedError extends Error {
     constructor(message, options) {
         super(message, options);
@@ -103,12 +97,6 @@ export class RuntimeLaunchCoordinator {
             ...(request.runId === undefined ? {} : { runId: request.runId })
         }, assertLaunchCurrent, this.#now());
         let reusedConfirmedRunningHost = false;
-        const launchCarriesExactRunPrompt = carriesExactRunPrompt(request);
-        // Preserve the existing Codex recovery path; managed Claude is the one
-        // finite-process protocol that must never fall back to tmux key delivery
-        // when a newly-reserved Run encounters an older live pane.
-        let launchPromptAcknowledgementRequired = request.adapterId === "claude"
-            && launchCarriesExactRunPrompt;
         if (reservation.status === "existing") {
             if (!reservation.launchId.startsWith(generationPrefix)) {
                 this.#requireCleanup(request.owner);
@@ -167,12 +155,6 @@ export class RuntimeLaunchCoordinator {
                     throw new Error(`Runtime launch reservation belongs to another Run whose host is still running: ${reservation.runId}.`);
                 }
                 reusedConfirmedRunningHost = true;
-                // A fresh Codex generation carries the prompt in its launch argv. A
-                // managed Claude generation carries it through stream-json stdin for
-                // both new and native-resume modes. Only recovery of the exact same
-                // reserved Run may bridge a lost in-memory launch acknowledgement.
-                launchPromptAcknowledgementRequired = sameRunReservation
-                    && launchCarriesExactRunPrompt;
                 runtimeIsolation = this.#preflightRuntimeIsolation(request, reservation.launchId, reservation.launchId.slice(generationPrefix.length), true);
                 assertLaunchCurrent();
             }
@@ -229,11 +211,8 @@ export class RuntimeLaunchCoordinator {
                         : { environment: request.environment }),
                     nativeSessionId: requireText(request.nativeSessionId, "Native session id")
                 }, beforeHostStart === undefined ? undefined : observePreflight);
-            binding = requireMatchingRuntimeBinding(rawBinding, request, launchId, launchPromptAcknowledgementRequired, reusedConfirmedRunningHost);
-            if (!preflightObserved
-                && !(binding.hostCreated === false
-                    && request.adapterId === "claude"
-                    && launchCarriesExactRunPrompt)) {
+            binding = requireMatchingRuntimeBinding(rawBinding, request, launchId);
+            if (!preflightObserved) {
                 throw new Error("Runtime session host did not expose a pre-host-start launch fence.");
             }
         }
@@ -244,8 +223,7 @@ export class RuntimeLaunchCoordinator {
                 // terminalize that reservation.
                 throw new RuntimeLaunchError(true, launchId, error.message, error.reason);
             }
-            if ((error instanceof LaunchSubmittedHostBusyError
-                || error instanceof RuntimeHostContentionError)
+            if (error instanceof RuntimeHostContentionError
                 && !reusedConfirmedRunningHost) {
                 let exactCleanupAttempted = false;
                 let completed = false;
@@ -266,12 +244,6 @@ export class RuntimeLaunchCoordinator {
                     this.#requireCleanup(request.owner);
                     throw new Error("Busy managed runtime launch reservation changed during retry release.");
                 }
-                if (error instanceof LaunchSubmittedHostBusyError) {
-                    // A terminal Run no longer owns its finite provider process. Move
-                    // that exact Role owner through the durable cleanup lane before a
-                    // later retry creates the successor generation.
-                    this.#requireCleanup(request.owner);
-                }
                 throw new RuntimeLaunchError(true, launchId, error.message, error instanceof RuntimeHostContentionError
                     ? error.reason
                     : "previous-process");
@@ -291,7 +263,6 @@ export class RuntimeLaunchCoordinator {
             }
             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) {
@@ -308,7 +279,7 @@ export class RuntimeLaunchCoordinator {
                 // 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({
+                this.reservations.confirmRuntimeLaunchReservation({
                     owner: request.owner,
                     launchId
                 }, assertLaunchCurrent);
@@ -317,18 +288,6 @@ export class RuntimeLaunchCoordinator {
         catch (error) {
             await this.#compensateStartedHost(request.owner, binding, launchId, runtimeIsolation, error);
         }
-        if (launchCarriesExactRunPrompt
-            && binding.hostCreated !== false
-            && reservationConfirmation !== "provider-bound"
-            && binding.initialPromptRunId !== request.runId) {
-            // A launch-carried prompt may return before its matching lifecycle Hook,
-            // but only an exact 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) {
@@ -461,12 +420,12 @@ function validateRuntimeLaunchPreflight(preflight, request, launchId) {
         || !effectiveLaunchSnapshotsCompatible(preflight.effective, request.effective)
         || (request.mode === "resume"
             && preflight.nativeSessionId !== request.nativeSessionId)
-        || (preflight.initialPromptRunId !== undefined
-            && preflight.initialPromptRunId !== request.runId)) {
+        || (preflight.initialTurnRunId !== undefined
+            && preflight.initialTurnRunId !== 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) {
+function requireMatchingRuntimeBinding(raw, request, launchId) {
     let binding;
     try {
         binding = createRuntimeBinding(raw);
@@ -479,9 +438,17 @@ function requireMatchingRuntimeBinding(raw, request, launchId, launchPromptAckno
         && (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 (binding.initialTurnRunId !== undefined
+        && binding.initialTurnRunId !== request.runId) {
+        throw new RuntimeBindingContractError(`Session host returned an initial structured Turn for another Run: ${request.owner.roleName}.`);
+    }
+    if (binding.initialTurnDeliveryUnknownRunId !== undefined
+        && binding.initialTurnDeliveryUnknownRunId !== request.runId) {
+        throw new RuntimeBindingContractError(`Session host returned a delivery-unknown initial structured Turn for another Run: ${request.owner.roleName}.`);
+    }
+    if (binding.initialTurnRejectedRunId !== undefined
+        && binding.initialTurnRejectedRunId !== request.runId) {
+        throw new RuntimeBindingContractError(`Session host returned a rejected initial structured Turn for another Run: ${request.owner.roleName}.`);
     }
     if (binding.launchId !== launchId
         || !ownerMatches
@@ -491,35 +458,8 @@ function requireMatchingRuntimeBinding(raw, request, launchId, launchPromptAckno
             && binding.nativeSessionId !== request.nativeSessionId)) {
         throw new RuntimeBindingContractError(`Session host returned a binding that does not match the requested runtime: ${request.owner.roleName}.`);
     }
-    if (launchPromptAcknowledgementRequired
-        && binding.initialPromptRunId !== request.runId
-        && !(launchPromptUncertaintyAllowed && binding.hostCreated === false)) {
-        throw binding.hostCreated === false
-            ? new LaunchSubmittedHostBusyError(`An earlier managed runtime is still exiting: ${request.owner.roleName}.`)
-            : new RuntimeBindingContractError(`Session host cannot acknowledge the exact launch-carried prompt: ${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 generation carried this Run at process launch. 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 carriesExactRunPrompt(request) {
-    if (request.owner.scope !== "task" || request.runId === undefined)
-        return false;
-    return request.adapterId === "claude"
-        || (request.adapterId === "codex" && request.mode === "new");
-}
 function defaultLaunchFingerprint(request) {
     return createHash("sha256").update(JSON.stringify([
         request.owner,

package/dist/controller/structuredProviderObservation.js

@@ -0,0 +1,273 @@
+import { randomUUID } from "node:crypto";
+import { callController } from "../core/controllerClient.js";
+import { builtinAgentDriverRegistry } from "../runtime/builtinAgentDrivers.js";
+import { createRuntimeObservation, runtimeObservationSemanticKey } from "../runtime/runtimeObservation.js";
+import { runtimeLifecycleSignalKey } from "../runtime/lifecycleReservation.js";
+import { FileRuntimeEventInbox } from "./runtimeEventInbox.js";
+import { resolveRuntimeHookRunFence } from "./runtimeHookRunFence.js";
+let structuredSequence = 0;
+export async function publishStructuredProviderAccepted(input) {
+    const adapterId = requireIdentity(input.environment.YUI_ADAPTER_ID, "Agent adapter id");
+    const driver = builtinAgentDriverRegistry().requireByAdapterId(adapterId);
+    const startupSession = driver.capabilities.observation.sessionBootstrap;
+    const fence = resolveRuntimeHookRunFence(input.environment, adapterId, input.receipt.nativeSessionId, {
+        startupSession,
+        nativeTurnId: input.receipt.nativeTurnId
+    });
+    const observedAt = input.receipt.acceptedAt;
+    const commonFence = {
+        taskId: fence.taskId,
+        roleName: fence.roleName,
+        runId: fence.runId,
+        agentId: fence.agentId,
+        driverId: driver.id,
+        launchId: fence.launchId,
+        sessionGenerationId: fence.launchId,
+        conversationId: input.receipt.conversationId,
+        activationId: requireIdentity(input.activationId, "Provider Activation id"),
+        nativeSessionId: input.receipt.nativeSessionId,
+        nativeTurnId: input.receipt.nativeTurnId,
+        // The structured Host owns the exact input attempt identity. Runtime
+        // descriptor receipts name the Run bootstrap and must not overwrite a
+        // continuation or human-takeover Turn.
+        receiptId: input.receipt.attemptId
+    };
+    const baseSequence = nextStructuredSequence();
+    const observations = [observation({
+            kind: startupSession === "preallocated" ? "session.ready" : "session.started",
+            observedAt,
+            sequence: baseSequence,
+            ordinal: 0,
+            fence: commonFence
+        }), observation({
+            kind: "conversation.observed",
+            observedAt,
+            sequence: baseSequence,
+            ordinal: 1,
+            fence: commonFence,
+            payload: { recoverability: "recoverable" }
+        }), observation({
+            kind: "activation.started",
+            observedAt,
+            sequence: baseSequence,
+            ordinal: 2,
+            fence: commonFence
+        }), observation({
+            kind: "turn.accepted",
+            observedAt,
+            sequence: baseSequence,
+            ordinal: 3,
+            fence: commonFence
+        })];
+    await persistAndApply(input.home, observations, fence.taskId, fence.roleName);
+}
+export async function publishStructuredProviderOpened(input) {
+    const adapterId = requireIdentity(input.environment.YUI_ADAPTER_ID, "Agent adapter id");
+    const driver = builtinAgentDriverRegistry().requireByAdapterId(adapterId);
+    const startupSession = driver.capabilities.observation.sessionBootstrap;
+    const fence = resolveRuntimeHookRunFence(input.environment, adapterId, input.nativeSessionId, { startupSession });
+    const commonFence = {
+        taskId: fence.taskId,
+        roleName: fence.roleName,
+        runId: fence.runId,
+        agentId: fence.agentId,
+        driverId: driver.id,
+        launchId: fence.launchId,
+        sessionGenerationId: fence.launchId,
+        conversationId: input.conversationId,
+        activationId: requireIdentity(input.activationId, "Provider Activation id"),
+        nativeSessionId: input.nativeSessionId,
+        ...(fence.receiptId === undefined ? {} : { receiptId: fence.receiptId })
+    };
+    const sequence = nextStructuredSequence();
+    const observations = [observation({
+            kind: startupSession === "preallocated" ? "session.ready" : "session.started",
+            observedAt: input.observedAt,
+            sequence,
+            ordinal: 0,
+            fence: commonFence
+        }), observation({
+            kind: "conversation.observed",
+            observedAt: input.observedAt,
+            sequence,
+            ordinal: 1,
+            fence: commonFence,
+            payload: { recoverability: input.recoverability }
+        }), observation({
+            kind: "activation.started",
+            observedAt: input.observedAt,
+            sequence,
+            ordinal: 2,
+            fence: commonFence
+        })];
+    await persistAndApply(input.home, observations, fence.taskId, fence.roleName);
+}
+export async function publishStructuredConversationRecoverability(input) {
+    const adapterId = requireIdentity(input.environment.YUI_ADAPTER_ID, "Agent adapter id");
+    const driver = builtinAgentDriverRegistry().requireByAdapterId(adapterId);
+    const fence = resolveRuntimeHookRunFence(input.environment, adapterId, input.conversationId);
+    const sequence = nextStructuredSequence();
+    const observationFence = {
+        taskId: fence.taskId,
+        roleName: fence.roleName,
+        runId: fence.runId,
+        agentId: fence.agentId,
+        driverId: driver.id,
+        launchId: fence.launchId,
+        sessionGenerationId: fence.launchId,
+        conversationId: input.conversationId,
+        activationId: requireIdentity(input.activationId, "Provider Activation id"),
+        nativeSessionId: input.conversationId,
+        ...(fence.receiptId === undefined ? {} : { receiptId: fence.receiptId })
+    };
+    const observations = [observation({
+            kind: "activation.started",
+            observedAt: input.observedAt,
+            sequence,
+            ordinal: 0,
+            fence: observationFence
+        }), observation({
+            kind: "conversation.observed",
+            observedAt: input.observedAt,
+            sequence,
+            ordinal: 1,
+            fence: observationFence,
+            payload: { recoverability: input.recoverability }
+        })];
+    if (input.recoverability === "unrecoverable") {
+        observations.push(observation({
+            kind: "activation.failed",
+            observedAt: input.observedAt,
+            sequence,
+            ordinal: 2,
+            fence: observationFence,
+            payload: {}
+        }));
+    }
+    await persistAndApply(input.home, observations, fence.taskId, fence.roleName);
+}
+export async function publishStructuredProviderTerminal(input) {
+    const adapterId = requireIdentity(input.environment.YUI_ADAPTER_ID, "Agent adapter id");
+    const driver = builtinAgentDriverRegistry().requireByAdapterId(adapterId);
+    const fence = resolveRuntimeHookRunFence(input.environment, adapterId, input.terminal.nativeSessionId, { terminal: true, nativeTurnId: input.terminal.nativeTurnId });
+    const kind = input.terminal.status === "completed"
+        ? "turn.completed"
+        : input.terminal.status === "cancelled" ? "turn.cancelled" : "turn.failed";
+    const payload = kind === "turn.completed"
+        ? { ...(input.terminal.summary === undefined ? {} : { summary: input.terminal.summary }) }
+        : kind === "turn.failed"
+            ? {
+                failure: {
+                    code: "provider-structured-failure",
+                    ...(input.terminal.error === undefined
+                        ? {}
+                        : { details: input.terminal.error })
+                }
+            }
+            : {};
+    const terminalObservation = observation({
+        kind,
+        observedAt: input.terminal.observedAt,
+        sequence: nextStructuredSequence(),
+        ordinal: 0,
+        fence: {
+            taskId: fence.taskId,
+            roleName: fence.roleName,
+            runId: fence.runId,
+            agentId: fence.agentId,
+            driverId: driver.id,
+            launchId: fence.launchId,
+            sessionGenerationId: fence.launchId,
+            conversationId: input.terminal.conversationId,
+            activationId: requireIdentity(input.activationId, "Provider Activation id"),
+            nativeSessionId: input.terminal.nativeSessionId,
+            nativeTurnId: input.terminal.nativeTurnId,
+            ...(fence.receiptId === undefined ? {} : { receiptId: fence.receiptId })
+        },
+        payload
+    });
+    await persistAndApply(input.home, [terminalObservation], fence.taskId, fence.roleName);
+}
+export async function publishStructuredProviderActivationTerminal(input) {
+    const adapterId = requireIdentity(input.environment.YUI_ADAPTER_ID, "Agent adapter id");
+    const driver = builtinAgentDriverRegistry().requireByAdapterId(adapterId);
+    const fence = resolveRuntimeHookRunFence(input.environment, adapterId, input.nativeSessionId);
+    const terminal = observation({
+        kind: input.status === "failed" ? "activation.failed" : "activation.ended",
+        observedAt: input.observedAt,
+        sequence: nextStructuredSequence(),
+        ordinal: 0,
+        fence: {
+            taskId: fence.taskId,
+            roleName: fence.roleName,
+            runId: fence.runId,
+            agentId: fence.agentId,
+            driverId: driver.id,
+            launchId: fence.launchId,
+            sessionGenerationId: fence.launchId,
+            conversationId: requireIdentity(input.conversationId, "Provider Conversation id"),
+            activationId: requireIdentity(input.activationId, "Provider Activation id"),
+            nativeSessionId: requireIdentity(input.nativeSessionId, "native Session id"),
+            ...(fence.receiptId === undefined ? {} : { receiptId: fence.receiptId })
+        },
+        payload: {}
+    });
+    await persistAndApply(input.home, [terminal], fence.taskId, fence.roleName);
+}
+function observation(input) {
+    const eventId = `agent-host-${randomUUID()}`;
+    const partial = {
+        eventId,
+        kind: input.kind,
+        fence: input.fence,
+        sequence: input.sequence,
+        payload: input.payload ?? {}
+    };
+    return createRuntimeObservation({
+        schemaVersion: 2,
+        eventId,
+        semanticKey: runtimeObservationSemanticKey(partial),
+        kind: input.kind,
+        authority: "provider-structured",
+        receivedAt: new Date().toISOString(),
+        observedAt: input.observedAt,
+        sequence: input.sequence,
+        ordinal: input.ordinal,
+        fence: input.fence,
+        payload: input.payload ?? {}
+    });
+}
+async function signalController(home, taskId, roleName) {
+    await callController(home, "scheduler.signal", {
+        key: runtimeLifecycleSignalKey({ scope: "task", taskId, roleName })
+    }, { timeoutMs: 100 }).catch(() => { });
+}
+function nextStructuredSequence() {
+    structuredSequence = (structuredSequence + 1) % Number.MAX_SAFE_INTEGER;
+    return structuredSequence;
+}
+function requireIdentity(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0 || value.includes("\0")) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return value.trim();
+}
+async function persistAndApply(home, observations, taskId, roleName) {
+    const inbox = new FileRuntimeEventInbox(home);
+    for (const entry of observations)
+        inbox.enqueueObservation(entry);
+    for (const entry of observations) {
+        const result = await callController(home, "runtime.observation-apply", entry, {
+            timeoutMs: 10_000
+        });
+        // A fast Provider can accept the initial Turn before the scheduler call
+        // that launched this Host has returned and committed `run.pushed`. The
+        // immutable inbox entry already makes that exact fenced fact durable;
+        // `deferred` therefore means "retained for replay", not delivery failure.
+        // The signal below schedules the replay after the transport transaction.
+        if (result.outcome !== "applied" && result.outcome !== "deferred") {
+            throw new Error(`Structured Provider observation was not applied: ${result.outcome ?? "unknown"}.`);
+        }
+    }
+    await signalController(home, taskId, roleName);
+}

package/dist/executor/agentAdapter.js

@@ -159,6 +159,24 @@ class CodexAdapter extends BaseAdapter {
         const launch = this.compileNew(input);
         return { ...launch, argv: [...launch.argv, "resume", nativeId(input.nativeSessionId)] };
     }
+    compileManagedControl(input, _mode, _nativeSessionId) {
+        const launch = this.compileNew(input);
+        const argv = [...launch.argv];
+        if (input.config.model !== undefined) {
+            const modelFlag = argv.findIndex((value, index) => (value === "--model" && argv[index + 1] === input.config.model));
+            if (modelFlag < 0)
+                throw new Error("Managed Codex launch lost its selected model.");
+            argv.splice(modelFlag, 2);
+            // App Server thread/start reads the model from resolved configuration;
+            // the interactive --model shortcut is not inherited by new threads.
+            argv.push("--config", `model=${tomlString(input.config.model)}`);
+        }
+        return {
+            ...launch,
+            argv: [...argv, "app-server", "--stdio"],
+            transport: "codex-app-server-stdio"
+        };
+    }
 }
 class ClaudeAdapter extends BaseAdapter {
     id = "claude";
@@ -261,6 +279,28 @@ class ClaudeAdapter extends BaseAdapter {
         const launch = super.compileNew(input);
         return { ...launch, argv: [...launch.argv, "--resume", nativeId(input.nativeSessionId)] };
     }
+    compileManagedControl(input, mode, nativeSessionId) {
+        if (nativeSessionId === undefined) {
+            throw new Error("Managed Claude control requires a preallocated native Session id.");
+        }
+        const sessionId = nativeId(nativeSessionId);
+        const launch = mode === "new"
+            ? super.compileNew(input)
+            : this.compileResume({ ...input, nativeSessionId: sessionId });
+        return {
+            ...launch,
+            argv: [
+                ...launch.argv,
+                ...(mode === "new" ? ["--session-id", sessionId] : []),
+                "-p",
+                "--output-format", "stream-json",
+                "--input-format", "stream-json",
+                "--verbose",
+                "--replay-user-messages"
+            ],
+            transport: "claude-stream-json"
+        };
+    }
 }
 function driverPreInputReadiness(adapterId) {
     const capability = builtinAgentDriverRegistry().requireByAdapterId(adapterId)