@zq-silk/yui 2.3.0 → 2.5.0

package/dist/resources/resourceGc.js

@@ -16,6 +16,7 @@
  * - `restoreAllResourceGc` is the explicit rollback entry point.
  */
 import { execFileSync } from "node:child_process";
+import { supportedGit } from "../repository/gitCompatibility.js";
 import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve, relative, isAbsolute } from "node:path";
 import { isDeepStrictEqual } from "node:util";
@@ -384,13 +385,14 @@ function quarantineResource(home, record, now) {
     const receiptPath = `${quarantinePath}.receipt.json`;
     try {
         if (isGitWorktreePath(record.path)) {
+            const program = supportedGit();
             // Move the linked worktree, including its exact checkout and Git
             // metadata, into the Home-local quarantine. Restore is the inverse
             // move, so the recorded HEAD cannot drift with a branch.
             mkdirSync(quarantineRoot, { recursive: true, mode: 0o700 });
             // Keep the existing SQLite writer fence through this bounded move, so a
             // Task reopen or new durable owner cannot commit between check and move.
-            execFileSync("git", ["-C", record.path, "worktree", "move", "--", record.path, quarantinePath], { timeout: 30_000 });
+            execFileSync(program.path, ["-C", record.path, "worktree", "move", "--", record.path, quarantinePath], { timeout: 30_000 });
             writeQuarantineReceipt(home, record, now, "move", receiptPath);
             return {
                 ok: true,
@@ -496,9 +498,10 @@ function restoreQuarantinedRecord(record, liveRefs, now) {
                 updatedAt: now.toISOString()
             };
         }
+        const program = isGitWorktreePath(quarantine.path) ? supportedGit() : undefined;
         mkdirSync(dirname(quarantine.originalPath), { recursive: true });
-        if (isGitWorktreePath(quarantine.path)) {
-            execFileSync("git", ["-C", quarantine.path, "worktree", "move", "--", quarantine.path, quarantine.originalPath], { timeout: 30_000 });
+        if (program !== undefined) {
+            execFileSync(program.path, ["-C", quarantine.path, "worktree", "move", "--", quarantine.path, quarantine.originalPath], { timeout: 30_000 });
         }
         else {
             renameSync(quarantine.path, quarantine.originalPath);
@@ -604,7 +607,7 @@ export async function purgeResourceQuarantine(home, options, store) {
             try {
                 if (existsSync(quarantine.path)) {
                     if (isGitWorktreePath(quarantine.path)) {
-                        execFileSync("git", ["-C", quarantine.path, "worktree", "remove", "--force", "--", quarantine.path], { timeout: 30_000 });
+                        execFileSync(supportedGit().path, ["-C", quarantine.path, "worktree", "remove", "--force", "--", quarantine.path], { timeout: 30_000 });
                     }
                     rmSync(quarantine.path, { recursive: true, force: true });
                 }

package/dist/resources/resourceRegistrar.js

@@ -9,6 +9,7 @@
 import { execFileSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { basename, dirname, resolve } from "node:path";
+import { gitOutputLine, supportedGit } from "../repository/gitCompatibility.js";
 import { upsertResourceRecord } from "./resourceRegistry.js";
 import { createResourceRegistryStore } from "./resourceRegistryStore.js";
 import { createResourceRecord, isReleaseNamespacePath, resourceId } from "./resourceTypes.js";
@@ -212,7 +213,7 @@ function ownerFromManagedWorkspace(home, owner, projectId) {
     };
 }
 function readGitWorktreeMetadata(path) {
-    const commonDir = execFileSync("git", ["-C", path, "rev-parse", "--path-format=absolute", "--git-common-dir"], { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+    const commonDir = resolve(path, gitOutputLine(execFileSync(supportedGit().path, ["-C", path, "rev-parse", "--git-common-dir"], { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] })));
     const repositoryPath = basename(commonDir) === ".git" ? dirname(commonDir) : commonDir;
     let branch;
     try {

package/dist/runtime/agentEndpoint.js

@@ -41,6 +41,12 @@ export function createAgentEndpointFactory(start = startStructuredProviderSessio
                 endpoint.observe(event);
         };
         const opened = await start(payload, {
+            // The native TUI owns rendering while attached. Raw JSON mirroring into
+            // its inherited PTY would corrupt its screen on every Provider event.
+            mirrorOutput: (stream, text) => {
+                if (!endpoint?.nativeAccess?.attached)
+                    (stream === "stdout" ? process.stdout : process.stderr).write(text);
+            },
             onAccepted: (value) => emit({ type: "accepted", value }),
             onActivity: (value) => emit({ type: "activity", value }),
             onStarted: (value) => emit({ type: "started", value }),
@@ -74,6 +80,7 @@ function freezeConfiguration(value) {
 class BuiltinAgentEndpoint {
     driver;
     configuration;
+    get nativeAccess() { return this.driver.nativeAccess; }
     get ownedProcessId() { return this.driver.ownedProcessId; }
     get nativeAccountHome() { return this.driver.nativeAccountHome; }
     capabilities;
@@ -118,6 +125,7 @@ class BuiltinAgentEndpoint {
     get nativeSessionId() { return this.driver.nativeSessionId; }
     get conversationId() { return this.driver.conversationId; }
     get processInstanceId() { return this.driver.processInstanceId; }
+    get publicReply() { return this.driver.publicReply; }
     /**
      * Delegated rather than copied at construction: the Session reads its own
      * current state, and a value captured here would freeze the configuration as

package/dist/runtime/agentHost.js

@@ -18,6 +18,7 @@ import { closeAgentHostEndpoints } from "./agentHostCleanup.js";
 import { readAgentRunConfigurationObservation, unknownAgentRunConfiguration } from "./agentRunConfiguration.js";
 import { CodexPreSubmissionError } from "./codexAppServerRuntime.js";
 import { runCodexInteractiveHost } from "./codexInteractiveHost.js";
+import { openControlledCodexTui } from "./controlledCodexTui.js";
 import { validateAgentHostLaunchPayload } from "./launchBroker.js";
 import { validateRuntimeProcessExitObservation } from "./processExitObservation.js";
 import { persistRuntimeProcessExitObservation, replayRuntimeProcessExitOutbox } from "./processExitOutbox.js";
@@ -108,6 +109,10 @@ export async function runAgentHost(input) {
     let snapshot = hostSnapshot("idle");
     let dispatchTail = Promise.resolve();
     let promptHuman = () => { };
+    let humanConsole;
+    let nativeTui;
+    let nativeOpening;
+    let modelChanging = false;
     const recentSteerAttempts = new Map();
     await replayExitOutbox(input.home);
     const updateSnapshot = (next) => {
@@ -444,6 +449,8 @@ export async function runAgentHost(input) {
                 && providerSession.adapterId === "codex"
                 && !hostStopRequested;
             if (reconnectableCodexClient) {
+                nativeTui?.close();
+                nativeTui = undefined;
                 session = undefined;
                 if (codexClientAttachedAt !== undefined
                     && Date.now() - codexClientAttachedAt >= CODEX_CLIENT_STABLE_MS) {
@@ -1028,7 +1035,128 @@ export async function runAgentHost(input) {
         promptHuman();
         return snapshot;
     };
-    const control = await openAgentHostControl(input.home, payload, () => snapshot, async (request) => {
+    const nativeMutation = async (expected, method, params) => {
+        if (session !== expected || params.threadId !== expected.nativeSessionId || !authority
+            || (sessionPayload?.environment.YUI_SESSION_SCOPE === "task" && sessionPayload.environment.YUI_ROLE !== "leader")) {
+            throw new Error("Native input targets a replaced or unsupported Session.");
+        }
+        if (method === "turn/interrupt") {
+            if (!activeRunAttemptId || params.turnId !== activeNativeTurnId)
+                throw new Error("Native stop targets a different Turn.");
+            const cancelled = await expected.cancel(activeRunAttemptId);
+            if (cancelled.status !== "requested")
+                throw new Error(`Native stop is ${cancelled.status}; do not replay.`);
+            return {};
+        }
+        if (!Array.isArray(params.input) || params.input.length === 0
+            || params.input.some(part => !part || typeof part !== "object"
+                || part.type !== "text" || typeof part.text !== "string")) {
+            throw new Error("Managed native access currently supports text input only.");
+        }
+        const boundedText = params.input.map(part => part.text).join("\n");
+        if (!boundedText.trim() || boundedText.includes("\0") || Buffer.byteLength(boundedText) > 12000)
+            throw new Error("Native input exceeds its text bound.");
+        const run = { attemptId: `human:${authority.holderId}:${randomUUID()}`, boundedText };
+        if (method === "turn/steer") {
+            const turnId = activeNativeTurnId;
+            if (params.expectedTurnId !== turnId || !turnId)
+                throw new Error("Native steer targets a different Turn.");
+            if (!sessionPayload)
+                throw new Error("Native Session launch context is unavailable.");
+            // Persist human intent and the existing steer receipt before Provider
+            // write. A fresh human turn id is not an additional-input binding.
+            const prepared = await callControllerIdempotently(input.home, "runtime.native-steer-prepare", {
+                ...hostRunControlParams(sessionPayload, expected.nativeSessionId, authority, run.attemptId),
+                nativeTurnId: turnId, boundedText
+            });
+            const result = await handleControl({ protocol: AGENT_HOST_CONTROL_PROTOCOL, type: "steer-turn",
+                nativeSessionId: expected.nativeSessionId, nativeTurnId: turnId, authority, run: prepared });
+            if (result.outcome !== "accepted")
+                throw new Error("Native steer acceptance is unconfirmed; do not resubmit.");
+            return { turnId };
+        }
+        const result = await handleControl({ protocol: AGENT_HOST_CONTROL_PROTOCOL, type: "submit-turn",
+            nativeSessionId: expected.nativeSessionId, authority, run });
+        const accepted = result.snapshot;
+        if (result.outcome !== "accepted" || accepted.inputAcceptance !== "provider" || !accepted.nativeTurnId) {
+            throw new Error("Native acceptance is unconfirmed; do not resubmit.");
+        }
+        return { turn: { id: accepted.nativeTurnId, items: [], status: "inProgress", error: null } };
+    };
+    const handleControl = async (request) => {
+        if (request.type === "native-model") {
+            return enqueueSerialized(async () => {
+                const current = session;
+                if (!current?.nativeAccess || current.nativeSessionId !== request.nativeSessionId
+                    || !sessionPayload || activeNativeTurnId || authority?.owner !== "controller"
+                    || (sessionPayload.environment.YUI_SESSION_SCOPE === "task" && sessionPayload.environment.YUI_ROLE !== "leader")
+                    || (sessionPayload.environment.YUI_SESSION_SCOPE === "global" && sessionPayload.environment.YUI_ROLE !== "operator")) {
+                    throw new Error("Model switching requires the idle current controlled Codex Session, without a native terminal writer.");
+                }
+                if (nativeTui || nativeOpening) {
+                    throw new Error("Exit the native TUI before changing the Session model. Closing a browser terminal viewer only detaches it; the Host-owned TUI remains open.");
+                }
+                modelChanging = true;
+                try {
+                    await assertHostExecutionEnvironment(input.home, sessionPayload, current.nativeSessionId);
+                    try {
+                        await current.nativeAccess.setModel(request.model);
+                    }
+                    catch (error) {
+                        if (error instanceof CodexPreSubmissionError)
+                            throw error;
+                        throw new ProviderDeliveryUnknownError(`Native model adoption is unconfirmed: ${errorText(error)}`, `model:${current.nativeSessionId}`, { cause: error });
+                    }
+                    return controlResult("accepted", { ...snapshot, runConfiguration: current.runConfiguration });
+                }
+                finally {
+                    modelChanging = false;
+                }
+            });
+        }
+        if (request.type === "native-open" || request.type === "native-respond") {
+            const current = session;
+            if (!current?.nativeAccess || current.nativeSessionId !== request.nativeSessionId
+                || !sessionPayload || (sessionPayload.environment.YUI_SESSION_SCOPE === "task"
+                && sessionPayload.environment.YUI_ROLE !== "leader"))
+                throw new Error("Native access requires the current controlled Codex Operator/Leader.");
+            if (request.type === "native-respond") {
+                await assertHostExecutionEnvironment(input.home, sessionPayload, current.nativeSessionId);
+                await current.nativeAccess.respond(request.requestId, request.nativeSessionId, request.nativeTurnId ?? null, request.result);
+            }
+            else if (!nativeTui) {
+                if (modelChanging)
+                    throw new Error("Wait for model adoption before attaching native input.");
+                if (!process.stdin.isTTY)
+                    throw new Error("Native TUI requires the Host's owned terminal.");
+                humanConsole?.close();
+                humanConsole = undefined;
+                nativeOpening ??= openControlledCodexTui(sessionPayload, current.nativeSessionId, current.nativeAccess, {
+                    mutate: (method, params) => nativeMutation(current, method, params),
+                    respond: async (requestId, nativeTurnId, result) => {
+                        await handleControl({ protocol: AGENT_HOST_CONTROL_PROTOCOL, type: "native-respond",
+                            nativeSessionId: current.nativeSessionId, requestId, nativeTurnId, result });
+                    },
+                    onExit: () => {
+                        nativeTui = undefined;
+                        process.stdout.write("\r\nNative TUI detached. Reattach the terminal to reopen this same Thread; the Agent Host remains running.\r\n");
+                    },
+                    onError: error => process.stderr.write(`Native TUI: ${errorText(error)}\n`)
+                });
+                try {
+                    nativeTui = await nativeOpening;
+                }
+                finally {
+                    nativeOpening = undefined;
+                }
+                if (session !== current) {
+                    nativeTui.close();
+                    nativeTui = undefined;
+                    throw new Error("Session changed while opening native access.");
+                }
+            }
+            return controlResult("accepted", { ...snapshot, nativeTui: !!nativeTui });
+        }
         if (request.type === "status") {
             // Read the Agent's configuration at answer time, not from the stored
             // snapshot. The Agent may have changed it since the last state
@@ -1036,10 +1164,20 @@ export async function runAgentHost(input) {
             // current reading rather than the one that was true at launch. Nothing is
             // sent to the Agent to obtain it: this reads what the Session has already
             // been told.
+            let requestBytes = 0;
+            const nativeRequests = session?.nativeAccess?.requests.filter(request => {
+                requestBytes += Buffer.byteLength(JSON.stringify(request));
+                return requestBytes <= 8000;
+            }).slice(0, 8);
             return controlResult("status", session === undefined
                 ? snapshot
                 : validateSnapshot({
                     ...snapshot,
+                    nativeTui: !!nativeTui,
+                    ...(nativeRequests === undefined ? {} : { nativeRequests,
+                        nativeRequestsOmitted: nativeRequests.length !== session.nativeAccess.requests.length }),
+                    ...(session.publicReply === undefined ? {} : { publicReply: session.publicReply }),
+                    ...(session.adapterId === "codex" ? { publicReplyObservation: "supported" } : {}),
                     runConfiguration: session.runConfiguration
                 }));
         }
@@ -1138,6 +1276,8 @@ export async function runAgentHost(input) {
             const accepted = await enqueueSerialized(async () => setAuthority(request));
             return controlResult("accepted", accepted);
         }
+        if (request.type !== "launch")
+            throw new Error("Unsupported Host request.");
         const redeemed = await redeem(input.home, request.ticket);
         if (activeRunPayload !== undefined
             || ["starting", "ready", "settling", "delivery-unknown"].includes(snapshot.state)) {
@@ -1149,8 +1289,9 @@ export async function runAgentHost(input) {
         }
         const accepted = await enqueueDispatch(redeemed);
         return controlResult("accepted", accepted);
-    });
-    const humanConsole = process.stdin.isTTY
+    };
+    const control = await openAgentHostControl(input.home, payload, () => snapshot, handleControl);
+    humanConsole = process.stdin.isTTY
         ? createInterface({ input: process.stdin, output: process.stdout, terminal: true })
         : undefined;
     promptHuman = () => {
@@ -1231,6 +1372,7 @@ export async function runAgentHost(input) {
         if (forceKillTimer !== undefined)
             clearTimeout(forceKillTimer);
         humanConsole?.close();
+        nativeTui?.close();
         await closeAgentHostEndpoints({
             owner: endpointOwner, session, lease: endpointLease, adapterId: endpointAdapterId,
             attemptId: activeRunAttemptId ?? lastTerminal?.attemptId,
@@ -1309,6 +1451,9 @@ export async function sendAgentHostAuthorityControl(input) {
 export async function sendAgentHostCancelControl(input) {
     return await sendAgentHostControl(input);
 }
+export async function sendAgentHostNativeControl(input) {
+    return sendAgentHostControl(input);
+}
 export async function inspectAgentHost(input) {
     const result = await sendAgentHostControl({
         ...input,
@@ -1550,6 +1695,12 @@ function boundControlResponse(result) {
     };
     if (withinControlBound(result))
         return result;
+    if (result.snapshot.publicReply !== undefined) {
+        const { publicReply: _omitted, ...snapshot } = result.snapshot;
+        result = { ...result, snapshot };
+        if (withinControlBound(result))
+            return result;
+    }
     const clip = (text, chars) => {
         if (text.length <= chars)
             return text;
@@ -1613,6 +1764,22 @@ function validateControl(control) {
     }
     if (control.type === "status")
         return Object.freeze({ ...control });
+    if (control.type === "native-open" || control.type === "native-respond" || control.type === "native-model") {
+        validateIdentity(control.nativeSessionId, "native Session id");
+        if (control.type === "native-model" && (typeof control.model !== "string"
+            || !control.model.trim() || control.model.length > 200 || control.model.includes("\0"))) {
+            throw new Error("Invalid native model.");
+        }
+        if (control.type === "native-respond") {
+            if (control.nativeTurnId !== null)
+                validateIdentity(control.nativeTurnId, "native Turn id");
+            if ((typeof control.requestId !== "string" && typeof control.requestId !== "number")
+                || control.result === null || typeof control.result !== "object" || Array.isArray(control.result)) {
+                throw new Error("Invalid native request response.");
+            }
+        }
+        return Object.freeze({ ...control });
+    }
     if (control.type === "cancel") {
         if (control.nativeOnly !== undefined && typeof control.nativeOnly !== "boolean") {
             throw new Error("Native-only cancellation flag is invalid.");

package/dist/runtime/codexAppServerRuntime.js

@@ -42,7 +42,7 @@ export class CodexAppServerRuntime {
             cwd: text(input.cwd, "Codex thread cwd"),
             ...threadOptions(input)
         });
-        return { conversationId: threadId(result) };
+        return { conversationId: threadId(result), raw: result };
     }
     async resumeConversation(conversationId, options = {}) {
         const id = text(conversationId, "Codex thread id");

package/dist/runtime/codexNativeAccess.js

@@ -0,0 +1,175 @@
+import { isDeepStrictEqual } from "node:util";
+import { unknownAgentRunConfiguration } from "./agentRunConfiguration.js";
+import { CodexPreSubmissionError } from "./codexAppServerRuntime.js";
+const READS = new Set([
+    "config/read", "configRequirements/read", "model/list", "collaborationMode/list",
+    "experimentalFeature/list", "skills/list", "hooks/list", "mcpServerStatus/list", "account/read",
+    "account/rateLimits/read", "modelProvider/capabilities/read", "permissionProfile/list",
+    "thread/read", "thread/turns/list", "thread/items/list", "thread/goal/get"
+]);
+const REQUESTS = new Set([
+    "item/commandExecution/requestApproval", "item/fileChange/requestApproval",
+    "item/tool/requestUserInput", "item/permissions/requestApproval", "mcpServer/elicitation/request"
+]);
+/** A view of one existing connection, never another Thread or durable input queue.
+ * Both the native TUI and Web answer the original server request on this transport. */
+export function createCodexNativeAccess(threadId, initialized, channel, openingMessages = [], initialConfiguration) {
+    const pending = new Map();
+    const listeners = new Set();
+    let configuration = initialConfiguration;
+    let observedAt = new Date().toISOString();
+    const observed = () => typeof configuration?.model !== "string"
+        ? unknownAgentRunConfiguration("No confirmed native model response. Reconnect to restore the fixed launch configuration.")
+        : {
+            status: "observed", observedAt,
+            handshake: { status: "unsupported", reason: "Model reported by Codex thread/start or thread/resume; not a capability handshake." },
+            requested: [],
+            axes: [{ key: "model", category: "model", current: { status: "observed", value: configuration.model }, offered: [] }]
+        };
+    const observe = (message) => {
+        const params = message.params;
+        if (params?.threadId !== threadId)
+            return;
+        if ((typeof message.id === "string" || typeof message.id === "number")
+            && typeof message.method === "string" && REQUESTS.has(message.method)
+            && (typeof params.turnId === "string"
+                || (message.method === "mcpServer/elicitation/request" && params.turnId == null))) {
+            pending.set(message.id, { id: message.id, method: message.method,
+                threadId, turnId: typeof params.turnId === "string" ? params.turnId : null, params });
+        }
+        if (message.method === "serverRequest/resolved")
+            pending.delete(params.requestId);
+        if (message.method === "turn/completed") {
+            const turn = params.turn;
+            for (const [id, request] of pending)
+                if (request.turnId === turn?.id)
+                    pending.delete(id);
+        }
+        for (const listener of listeners)
+            listener(message);
+    };
+    for (const message of openingMessages)
+        observe(message);
+    channel.onMessage(observe);
+    return {
+        initialized,
+        get attached() { return listeners.size > 0; },
+        get requests() { return [...pending.values()]; },
+        get runConfiguration() { return observed(); },
+        async setModel(model) {
+            try {
+                if (!model.trim() || model.length > 200 || model.includes("\0"))
+                    throw new Error("Invalid model.");
+                const read = await channel.request("thread/read", { threadId, includeTurns: false });
+                const thread = read.thread;
+                if (thread?.id !== threadId || thread.status?.type !== "idle") {
+                    throw new Error("Model switching requires a confirmed idle Thread.");
+                }
+            }
+            catch (error) {
+                throw new CodexPreSubmissionError(error instanceof Error ? error.message : "Native idle state is unavailable.");
+            }
+            // No fork/start, account, permission or Role-default mutation. Do not
+            // preserve an old observation if the native mutation becomes uncertain.
+            configuration = undefined;
+            const result = await channel.request("thread/resume", { threadId, model, excludeTurns: true });
+            if (result.thread?.id !== threadId || result.model !== model) {
+                throw new Error("Native model adoption was not confirmed; inspect before another change.");
+            }
+            configuration = result;
+            observedAt = new Date().toISOString();
+        },
+        async read(method, params) {
+            // TUI startup attaches to the already opened Thread without resuming it
+            // with new options or changing the Host's configured execution boundary.
+            if (method === "thread/resume") {
+                if (params.threadId !== threadId)
+                    throw new Error("Select the existing Session; new/forked Threads are not supported here.");
+                const page = params.initialTurnsPage;
+                configuration = await channel.request("thread/resume", { threadId,
+                    ...(typeof params.excludeTurns === "boolean" ? { excludeTurns: params.excludeTurns } : {}),
+                    ...(page ? { initialTurnsPage: { ...page, limit: Math.min(40, typeof page.limit === "number" && page.limit > 0 ? page.limit : 40) } } : {}) });
+                observedAt = new Date().toISOString();
+                return configuration;
+            }
+            if (!READS.has(method))
+                throw new Error(`Native operation is not available in managed access: ${method}.`);
+            if (method.startsWith("thread/") && params.threadId !== threadId) {
+                throw new Error("Native read targets a different Thread.");
+            }
+            // Native TUI owns its hydration protocol (legacy TUI can explicitly ask
+            // for full turns). Web history remains independently bounded/paginated.
+            return channel.request(method, method === "thread/turns/list" || method === "thread/items/list"
+                ? { ...params, limit: Math.min(40, typeof params.limit === "number" && params.limit > 0 ? params.limit : 40) }
+                : params);
+        },
+        validateTurn(params) {
+            if (!configuration)
+                throw new Error("Native TUI has not attached to the existing Thread.");
+            for (const [key, source] of Object.entries({
+                model: "model", cwd: "cwd", runtimeWorkspaceRoots: "runtimeWorkspaceRoots",
+                approvalPolicy: "approvalPolicy", approvalsReviewer: "approvalsReviewer",
+                effort: "reasoningEffort", collaborationMode: "collaborationMode"
+            })) {
+                if (params[key] != null && !isDeepStrictEqual(params[key], configuration[source])) {
+                    throw new Error(`Native ${key} differs from the managed Session; change it through Yui configuration.`);
+                }
+            }
+            for (const key of ["sandboxPolicy", "permissions", "environments", "toolOutput", "additionalContext", "outputSchema", "disabledPluginIds", "serviceTierForTurn", "summary", "personality", "cyberAccessProgram"]) {
+                if (params[key] != null)
+                    throw new Error(`Native ${key} overrides are not supported in managed access.`);
+            }
+            if (params.serviceTier != null && params.serviceTier !== (configuration.serviceTier ?? "default")) {
+                throw new Error("Native service tier differs from the managed Session.");
+            }
+        },
+        async respond(id, expectedThread, turnId, result) {
+            const request = pending.get(id);
+            if (!request || request.threadId !== expectedThread || request.turnId !== turnId) {
+                throw new Error("Native request is no longer pending for this exact Thread and Turn.");
+            }
+            validateNativeResponse(request, result);
+            // Claim before awaiting transport. A lost send acknowledgement is unknown,
+            // not permission for another entry to repeat a possibly applied answer.
+            pending.delete(id);
+            await channel.send({ id, result });
+        },
+        events(listener) { listeners.add(listener); return () => { listeners.delete(listener); }; }
+    };
+}
+function validateNativeResponse(request, result) {
+    if (!result || typeof result !== "object" || Array.isArray(result))
+        throw new Error("Missing native response.");
+    if (request.method === "mcpServer/elicitation/request") {
+        if (!["accept", "decline", "cancel"].includes(String(result.action))
+            || (result.action !== "accept" && result.content != null)) {
+            throw new Error("Invalid native MCP elicitation response.");
+        }
+    }
+    else if (request.method === "item/tool/requestUserInput") {
+        const answers = result.answers;
+        const questions = request.params.questions;
+        if (!answers || typeof answers !== "object" || Array.isArray(answers) || !Array.isArray(questions)) {
+            throw new Error("Native question requires answers keyed by question id.");
+        }
+        const ids = questions.map(q => q.id);
+        if (Object.keys(answers).some(id => !ids.includes(id))
+            || ids.some(id => {
+                if (typeof id !== "string")
+                    return true;
+                const answer = answers[id];
+                return !Array.isArray(answer?.answers) || answer.answers.some(value => typeof value !== "string");
+            })) {
+            throw new Error("Native answers do not match the original questions.");
+        }
+    }
+    else if (request.method === "item/permissions/requestApproval") {
+        // Web currently exposes decline only; richer native grants remain the TUI's
+        // protocol responsibility. Never infer broad grants from an accept button.
+        if (!result.permissions || typeof result.permissions !== "object")
+            throw new Error("Missing native permissions response.");
+    }
+    else if (!["accept", "acceptForSession", "decline", "cancel"].includes(String(result.decision))) {
+        throw new Error("Invalid native approval decision.");
+    }
+}

package/dist/runtime/controlledCodexTui.js

@@ -0,0 +1,116 @@
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { once } from "node:events";
+import WebSocket, { WebSocketServer } from "ws";
+import { localCodexTuiEnvironment } from "./codexInteractiveHost.js";
+/** The TUI is a view of the Host-owned connection. It cannot launch, fork,
+ * reconfigure, or submit outside the Host's existing input admission. */
+export async function openControlledCodexTui(payload, threadId, access, input) {
+    const baseArgs = JSON.parse(payload.environment.YUI_AGENT_BASE_ARGS ?? "[]");
+    if (!Array.isArray(baseArgs) || baseArgs.some(arg => typeof arg !== "string"))
+        throw new Error("Invalid Codex base arguments.");
+    const token = randomBytes(32).toString("hex");
+    const server = new WebSocketServer({
+        host: "127.0.0.1", port: 0, maxPayload: 1024 * 1024, perMessageDeflate: false,
+        verifyClient: (info) => info.req.headers.authorization === `Bearer ${token}`
+    });
+    let socket;
+    let closed = false;
+    let markReady;
+    let failReady;
+    const ready = new Promise((resolve, reject) => { markReady = resolve; failReady = reject; });
+    void ready.catch(() => { });
+    const unsubscribe = access.events(message => {
+        if (socket?.readyState === WebSocket.OPEN)
+            socket.send(JSON.stringify(message));
+    });
+    server.on("connection", client => {
+        if (socket || closed) {
+            client.close(1008, "TUI already attached.");
+            return;
+        }
+        socket = client;
+        client.on("error", input.onError);
+        client.on("message", (bytes, binary) => {
+            void (async () => {
+                if (binary)
+                    throw new Error("Expected native JSON request.");
+                const message = JSON.parse(bytes.toString());
+                const id = message.id;
+                if (typeof id !== "number" && typeof id !== "string")
+                    return; // notifications
+                try {
+                    if (message.method === undefined) {
+                        const request = access.requests.find(request => request.id === id);
+                        if (!request)
+                            throw new Error("Native request is no longer pending.");
+                        await input.respond(id, request.turnId, message.result);
+                        return;
+                    }
+                    const method = String(message.method), params = (message.params ?? {});
+                    if (method === "turn/start")
+                        access.validateTurn(params);
+                    const result = method === "initialize" ? access.initialized
+                        : ["turn/start", "turn/steer", "turn/interrupt"].includes(method) ? await input.mutate(method, params)
+                            : await access.read(method, params);
+                    if (client.readyState === WebSocket.OPEN)
+                        client.send(JSON.stringify({ id, result }));
+                    if (method === "thread/resume") {
+                        markReady();
+                        for (const request of access.requests)
+                            client.send(JSON.stringify({
+                                id: request.id, method: request.method, params: request.params
+                            }));
+                    }
+                }
+                catch (error) {
+                    if (client.readyState === WebSocket.OPEN)
+                        client.send(JSON.stringify({
+                            id, error: { code: -32600, message: error instanceof Error ? error.message : String(error) }
+                        }));
+                }
+            })().catch(input.onError);
+        });
+    });
+    try {
+        await once(server, "listening");
+    }
+    catch (error) {
+        unsubscribe();
+        server.close();
+        throw error;
+    }
+    const address = server.address();
+    if (!address || typeof address === "string")
+        throw new Error("Native TUI relay did not bind.");
+    const child = spawn(payload.command, [...baseArgs,
+        "--remote", `ws://127.0.0.1:${address.port}`, "--remote-auth-token-env", "YUI_CODEX_REMOTE_AUTH_TOKEN",
+        "resume", threadId], {
+        cwd: payload.cwd, stdio: "inherit",
+        env: { ...localCodexTuiEnvironment(payload.environment), YUI_CODEX_REMOTE_AUTH_TOKEN: token }
+    });
+    const close = () => {
+        if (closed)
+            return;
+        closed = true;
+        unsubscribe();
+        socket?.terminate();
+        server.close();
+        child.kill("SIGTERM");
+    };
+    server.on("error", input.onError);
+    child.on("error", error => { failReady(error); input.onError(error); close(); input.onExit(); });
+    child.once("exit", () => { failReady(new Error("Native TUI exited before attachment.")); close(); input.onExit(); });
+    const deadline = setTimeout(() => failReady(new Error("Native TUI did not attach to the selected Thread.")), 10_000);
+    try {
+        await ready;
+    }
+    catch (error) {
+        close();
+        throw error;
+    }
+    finally {
+        clearTimeout(deadline);
+    }
+    return { close };
+}