@astrosheep/keiyaku 1.0.0 → 1.0.2

package/build/agents/providers/codex-app-server.js

@@ -3,22 +3,111 @@ import { z } from "zod";
 import { appendDebugLog } from "../../telemetry/debug-log.js";
 import { SUBAGENT_SESSION_VERSION } from "../session.js";
 import { createProjectionDriver } from "../harness/execution-handle.js";
+import { boundActivityExcerpt, diffstatFromUnifiedPatch } from "../harness/activity-values.js";
+import { AGENT_PLAN_ITEM_TEXT_MAX_CHARS, AGENT_PLAN_MAX_ITEMS, AGENT_THOUGHT_TEXT_MAX_CHARS, } from "../harness/events.js";
 import { buildSubagentEnv, createAbortError, emitProviderEvidence, sha256Utf8 } from "../harness/runtime.js";
-import { coerceString } from "../../agents/index.js";
+import { coerceString } from "../harness/runtime.js";
+/** Identity-only opacity boundary for codex-app-server turn/start effort. */
+function toCodexAppServerEffort(effort) {
+    return effort;
+}
+const CODEX_APP_SERVER_NOTIFICATION_ACKNOWLEDGED = new Set(["item/agentMessage/delta"]);
+const CODEX_APP_SERVER_NOTIFICATION_MAPPED = new Set([
+    "item/completed",
+    "turn/started",
+    "turn/completed",
+    "error",
+]);
+function codexAppServerNotificationDisposition(method) {
+    if (CODEX_APP_SERVER_NOTIFICATION_ACKNOWLEDGED.has(method))
+        return "acknowledged-unpersisted";
+    if (CODEX_APP_SERVER_NOTIFICATION_MAPPED.has(method))
+        return "mapped";
+    return "unknown";
+}
 /** Session handle for codex-app-server: thread id plus optional CODEX_HOME for cross-process resume. */
 export const codexAppServerSessionSchema = z.object({
     threadId: z.string().trim().min(1),
     codexHome: z.string().trim().min(1).optional(),
 });
+function appServerRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+const CODEX_APP_SERVER_ACTIVITY_ITEM_TYPES = [
+    "commandExecution",
+    "fileChange",
+    "webSearch",
+    "mcpToolCall",
+];
+function isCodexAppServerActivityItemType(value) {
+    return CODEX_APP_SERVER_ACTIVITY_ITEM_TYPES.includes(value);
+}
+function appServerActivityCall(itemType, item) {
+    switch (itemType) {
+        case "commandExecution":
+            return typeof item.command === "string"
+                ? {
+                    kind: "run",
+                    command: item.command,
+                    ...(typeof item.description === "string" && item.description ? { description: item.description } : {}),
+                }
+                : { kind: "other", display: itemType };
+        case "fileChange": {
+            const changes = Array.isArray(item.changes)
+                ? item.changes.flatMap((entry) => {
+                    const change = appServerRecord(entry);
+                    if (!change || typeof change.path !== "string")
+                        return [];
+                    if (change.kind !== "add" && change.kind !== "update" && change.kind !== "delete")
+                        return [];
+                    const op = change.kind;
+                    return [{ op, path: change.path }];
+                })
+                : [];
+            if (changes.length > 0)
+                return { kind: "fileChange", changes };
+            return { kind: "other", display: typeof item.path === "string" ? `fileChange ${item.path}` : itemType };
+        }
+        case "webSearch":
+            return typeof item.query === "string" ? { kind: "search", query: item.query } : { kind: "other", display: itemType };
+        case "mcpToolCall":
+            return typeof item.server === "string" && typeof item.tool === "string"
+                ? { kind: "other", display: `${item.server}.${item.tool}` }
+                : { kind: "other", display: itemType };
+    }
+}
+function appServerActivityResult(item) {
+    const exitCode = typeof item.exitCode === "number" && Number.isFinite(item.exitCode) ? item.exitCode : undefined;
+    const message = typeof item.aggregatedOutput === "string" && item.aggregatedOutput
+        ? boundActivityExcerpt(item.aggregatedOutput)
+        : typeof item.output === "string" && item.output
+            ? boundActivityExcerpt(item.output)
+            : typeof item.error === "string" && item.error
+                ? boundActivityExcerpt(item.error)
+                : undefined;
+    const details = item.details !== null && typeof item.details === "object" && !Array.isArray(item.details)
+        ? item.details
+        : undefined;
+    const patch = typeof details?.patch === "string" ? details.patch : undefined;
+    const diffstat = patch ? diffstatFromUnifiedPatch(patch) : undefined;
+    return {
+        status: item.status === "failed" || (exitCode !== undefined && exitCode !== 0) ? "error" : "ok",
+        ...(message ? { message } : {}),
+        ...(exitCode === undefined ? {} : { exitCode }),
+        ...(diffstat ? { diffstat } : {}),
+    };
+}
 const CODEX_APP_SERVER_PROVIDER = "codex-app-server";
 const MINIMUM_CODEX_APP_SERVER_VERSION = { major: 0, minor: 143, patch: 0 };
 /** Non-interactive defaults for turn/start (faye #316 policy A). */
 export const CODEX_APP_SERVER_TURN_APPROVAL_POLICY = "never";
-export function buildCodexAppServerDefaultSandboxPolicy(cwd) {
+export function buildCodexAppServerWorkspaceWriteSandboxPolicy(input) {
     return {
         type: "workspaceWrite",
-        writableRoots: [cwd],
-        networkAccess: false,
+        writableRoots: [...input.writableRoots],
+        networkAccess: input.networkAccess,
         excludeTmpdirEnvVar: false,
         excludeSlashTmp: false,
     };
@@ -43,6 +132,40 @@ export function configOwnsSandboxPolicy(config) {
     }
     return false;
 }
+function extractReasoningSummary(item) {
+    const summary = item.summary;
+    const text = typeof summary === "string"
+        ? summary
+        : Array.isArray(summary)
+            ? summary.map((part) => {
+                if (typeof part === "string")
+                    return part;
+                if (!part || typeof part !== "object")
+                    return "";
+                const record = part;
+                if (record.type !== "summary_text" && record.type !== "text")
+                    return "";
+                return typeof record.text === "string" ? record.text : "";
+            }).join("\n")
+            : "";
+    return text.trim().length > 0 ? text : undefined;
+}
+function extractPlanItems(item) {
+    if (!Array.isArray(item.items))
+        return [];
+    return item.items.slice(0, AGENT_PLAN_MAX_ITEMS).flatMap((value) => {
+        if (!value || typeof value !== "object")
+            return [];
+        const record = value;
+        if (typeof record.text !== "string" || record.text.trim().length === 0)
+            return [];
+        return [{
+                text: record.text.slice(0, AGENT_PLAN_ITEM_TEXT_MAX_CHARS),
+                done: record.completed === true || record.done === true,
+                ...(record.active === true ? { active: true } : {}),
+            }];
+    });
+}
 function parseSemver(version) {
     const match = version.trim().match(/(\d+)\.(\d+)\.(\d+)/);
     if (!match)
@@ -304,15 +427,19 @@ export async function startCodexAppServer(prompt, cwd, options = {}) {
     const resumeThreadId = options.threadId?.trim();
     let server;
     let activeTurnId;
+    const responseSeenTurnIds = new Set();
+    const completedBeforeResponseTurnIds = new Set();
     let activeTurnSource;
     let activeTurnAcceptingSteer = false;
     let activeThreadId;
     let interruptRequested = false;
     let lastAgentMessage = "";
     let builderDiagnostic;
+    let emitTurnStarted;
     const pendingTells = [];
     let drainingTells = false;
     let failActiveTurn;
+    let finishAfterTellDrain;
     const rejectPendingTells = (error) => {
         for (const pending of pendingTells.splice(0))
             pending.reject(error);
@@ -331,6 +458,15 @@ export async function startCodexAppServer(prompt, cwd, options = {}) {
         }
         return activeTurnId;
     };
+    const recordTurnStartResponse = (candidate) => {
+        const turnId = coerceString(candidate);
+        if (!turnId)
+            throw new Error(`${CODEX_APP_SERVER_PROVIDER} response omitted active turn id`);
+        if (completedBeforeResponseTurnIds.delete(turnId))
+            return turnId;
+        responseSeenTurnIds.add(turnId);
+        return recordActiveTurnId(turnId, "response");
+    };
     appendDebugLog(`startCodexAppServer: executable=${executable} model=${options.model ?? "default"} mode=${resumeThreadId ? "resume" : "fresh"}`, { cwd, section: CODEX_APP_SERVER_PROVIDER });
     const submitSteer = async (tell, turnId) => {
         // turn/steer response {turnId} = enqueue acceptance (submitted), not consumption.
@@ -346,6 +482,8 @@ export async function startCodexAppServer(prompt, cwd, options = {}) {
         if (acknowledgedTurnId !== turnId) {
             throw new Error(`${CODEX_APP_SERVER_PROVIDER} turn/steer acknowledgement mismatched active turn: expected=${turnId}, actual=${acknowledgedTurnId}`);
         }
+        // Accepted same-native-turn steer opens the next public conversation turn.
+        emitTurnStarted?.();
         if (options.onEvidence) {
             emitProviderEvidence(options.onEvidence, {
                 type: "ack",
@@ -361,14 +499,21 @@ export async function startCodexAppServer(prompt, cwd, options = {}) {
             threadId: activeThreadId,
             input: [{ type: "text", text: tell.text }],
             ...(options.model ? { model: options.model } : {}),
-            ...(tell.effort ? { effort: tell.effort } : {}),
-            ...(!configOwnsApprovalPolicy(options.config) ? { approvalPolicy: CODEX_APP_SERVER_TURN_APPROVAL_POLICY } : {}),
-            ...(!configOwnsSandboxPolicy(options.config) ? { sandboxPolicy: buildCodexAppServerDefaultSandboxPolicy(cwd) } : {}),
+            ...(tell.effort ? { effort: toCodexAppServerEffort(tell.effort) } : {}),
+            ...(!configOwnsApprovalPolicy(options.config) ? { approvalPolicy: options.approvalPolicy ?? CODEX_APP_SERVER_TURN_APPROVAL_POLICY } : {}),
+            ...(!configOwnsSandboxPolicy(options.config)
+                ? {
+                    sandboxPolicy: options.sandboxPolicy ?? buildCodexAppServerWorkspaceWriteSandboxPolicy({
+                        writableRoots: [cwd],
+                        networkAccess: false,
+                    }),
+                }
+                : {}),
         });
         const startedTurn = started && typeof started === "object"
             ? (started.turn ?? undefined)
             : undefined;
-        const newTurnId = recordActiveTurnId(startedTurn?.id, "response");
+        const newTurnId = recordTurnStartResponse(startedTurn?.id);
         if (options.onEvidence)
             emitProviderEvidence(options.onEvidence, { type: "ack", provider: CODEX_APP_SERVER_PROVIDER, fence: { kind: "turn", turnId: newTurnId }, outbound: "run" }, builderDiagnostic);
         return { fence: { kind: "turn", turnId: newTurnId } };
@@ -400,6 +545,9 @@ export async function startCodexAppServer(prompt, cwd, options = {}) {
         }
         finally {
             drainingTells = false;
+            const finish = finishAfterTellDrain;
+            finishAfterTellDrain = undefined;
+            finish?.();
         }
     };
     const enqueue = async (tell) => {
@@ -413,7 +561,9 @@ export async function startCodexAppServer(prompt, cwd, options = {}) {
     };
     return createProjectionDriver({
         steerMode: "mid-execution",
+        initialTurn: options.initialTurn,
         enqueue,
+        onIngress: options.onIngress,
         async abort() {
             interruptRequested = true;
             if (server && activeThreadId && activeTurnId) {
@@ -432,6 +582,7 @@ export async function startCodexAppServer(prompt, cwd, options = {}) {
         },
         async run(builder) {
             builderDiagnostic = (text) => builder.emit({ type: "diagnostic", text });
+            emitTurnStarted = () => builder.emit({ type: "turn", phase: "started" });
             const env = buildSubagentEnv();
             server = new CodexAppServerProcess(executable, env, options.codexHome, options.onEvidence, (text) => builder.emit({ type: "diagnostic", text }));
             const turnCompleted = new Promise((resolve, reject) => {
@@ -456,58 +607,72 @@ export async function startCodexAppServer(prompt, cwd, options = {}) {
                     failTurn(new Error(message));
                 };
                 unsubServerRequest = server.onServerRequest((request) => {
-                    failServerRequest(request);
+                    builder.ingress(CODEX_APP_SERVER_PROVIDER, request.method, request, "mapped", () => {
+                        failServerRequest(request);
+                    });
                 });
                 unsubNotifications = server.onNotification((notification) => {
                     try {
-                        builder.emit({ type: "output", value: notification });
-                        if (notification.method === "item/agentMessage/delta") {
-                            const delta = coerceString(notification.params?.delta);
-                            if (delta) {
-                                lastAgentMessage = `${lastAgentMessage}${delta}`;
-                                builder.emit({ type: "message", text: lastAgentMessage });
-                            }
-                        }
-                        if (notification.method === "item/completed") {
-                            const item = notification.params?.item;
-                            if (item && (item.type === "agentMessage" || item.type === "agent_message")) {
-                                const text = coerceString(item.text);
-                                if (text) {
-                                    lastAgentMessage = text;
-                                    builder.emit({ type: "message", text });
+                        builder.ingress(CODEX_APP_SERVER_PROVIDER, notification.method, notification, codexAppServerNotificationDisposition(notification.method), () => {
+                            if (notification.method === "item/agentMessage/delta") {
+                                const delta = coerceString(notification.params?.delta);
+                                if (delta) {
+                                    lastAgentMessage = `${lastAgentMessage}${delta}`;
                                 }
                             }
-                        }
-                        if (notification.method === "turn/started") {
-                            const turn = notification.params?.turn;
-                            const turnId = recordActiveTurnId(turn?.id, "notification");
-                            activeTurnAcceptingSteer = true;
-                            const checkpoint = { fence: { kind: "turn", turnId } };
-                            if (options.onEvidence) {
-                                emitProviderEvidence(options.onEvidence, {
-                                    type: "checkpoint",
-                                    provider: CODEX_APP_SERVER_PROVIDER,
-                                    ...checkpoint,
-                                    source: "notification",
-                                }, builderDiagnostic);
+                            if (notification.method === "item/completed") {
+                                const item = notification.params?.item;
+                                if (!item) {
+                                    throw new Error(`${CODEX_APP_SERVER_PROVIDER} item/completed lacked required item`);
+                                }
+                                const id = coerceString(item.id);
+                                const itemType = coerceString(item.type);
+                                if (!id || !itemType) {
+                                    throw new Error(`${CODEX_APP_SERVER_PROVIDER} item/completed lacked required item id or type`);
+                                }
+                                if (itemType === "agentMessage") {
+                                    const text = coerceString(item.text);
+                                    if (text) {
+                                        lastAgentMessage = text;
+                                        builder.emit({ type: "message", text });
+                                    }
+                                }
+                                else if (itemType === "reasoning") {
+                                    const text = extractReasoningSummary(item);
+                                    if (text) {
+                                        const truncated = text.length > AGENT_THOUGHT_TEXT_MAX_CHARS;
+                                        builder.emit({
+                                            type: "thought",
+                                            id,
+                                            text: text.slice(0, AGENT_THOUGHT_TEXT_MAX_CHARS),
+                                            final: true,
+                                            ...(truncated ? { truncated: true } : {}),
+                                        });
+                                    }
+                                }
+                                else if (itemType === "todo_list" || itemType === "todoList") {
+                                    builder.emit({
+                                        type: "plan",
+                                        id,
+                                        items: extractPlanItems(item),
+                                    });
+                                }
+                                else if (isCodexAppServerActivityItemType(itemType)) {
+                                    builder.emit({
+                                        type: "activity",
+                                        phase: "completed",
+                                        id,
+                                        tool: itemType,
+                                        call: appServerActivityCall(itemType, item),
+                                        result: appServerActivityResult(item),
+                                    });
+                                }
                             }
-                            // turn/start may respond before the server has installed its active
-                            // turn. The native notification is the first steer-safe boundary.
-                            options.onSyncCheckpoint?.({ enqueue }, checkpoint);
-                            void drainPendingTells();
-                        }
-                        if (notification.method === "turn/completed") {
-                            const turn = notification.params?.turn ?? {};
-                            const status = coerceString(turn.status) ?? "unknown";
-                            // Either response or notification may mint the turn fence first;
-                            // every later native source must agree with it.
-                            const turnId = recordActiveTurnId(turn.id, "notification");
-                            // This must stay in the native notification call stack: the harness
-                            // checkpoint and its observer evidence describe this exact crossing.
-                            if (status === "completed") {
-                                activeTurnAcceptingSteer = false;
-                                activeTurnId = undefined;
-                                activeTurnSource = undefined;
+                            if (notification.method === "turn/started") {
+                                const turn = notification.params?.turn;
+                                const turnId = recordActiveTurnId(turn?.id, "notification");
+                                builder.emit({ type: "turn", phase: "started" });
+                                activeTurnAcceptingSteer = true;
                                 const checkpoint = { fence: { kind: "turn", turnId } };
                                 if (options.onEvidence) {
                                     emitProviderEvidence(options.onEvidence, {
@@ -517,23 +682,63 @@ export async function startCodexAppServer(prompt, cwd, options = {}) {
                                         source: "notification",
                                     }, builderDiagnostic);
                                 }
+                                // turn/start may respond before the server has installed its active
+                                // turn. The native notification is the first steer-safe boundary.
                                 options.onSyncCheckpoint?.({ enqueue }, checkpoint);
                                 void drainPendingTells();
-                                if (pendingTells.length > 0 || drainingTells) {
-                                    return;
+                            }
+                            if (notification.method === "turn/completed") {
+                                const turn = notification.params?.turn ?? {};
+                                const status = coerceString(turn.status) ?? "unknown";
+                                // Either response or notification may mint the turn fence first;
+                                // every later native source must agree with it.
+                                const turnId = recordActiveTurnId(turn.id, "notification");
+                                if (!responseSeenTurnIds.delete(turnId)) {
+                                    completedBeforeResponseTurnIds.add(turnId);
                                 }
+                                // Public completed only for exact native status completed.
+                                if (status === "completed") {
+                                    builder.emit({ type: "turn", phase: "completed" });
+                                    // This must stay in the native notification call stack: the harness
+                                    // checkpoint and its observer evidence describe this exact crossing.
+                                    activeTurnAcceptingSteer = false;
+                                    activeTurnId = undefined;
+                                    activeTurnSource = undefined;
+                                    const checkpoint = { fence: { kind: "turn", turnId } };
+                                    if (options.onEvidence) {
+                                        emitProviderEvidence(options.onEvidence, {
+                                            type: "checkpoint",
+                                            provider: CODEX_APP_SERVER_PROVIDER,
+                                            ...checkpoint,
+                                            source: "notification",
+                                        }, builderDiagnostic);
+                                    }
+                                    options.onSyncCheckpoint?.({ enqueue }, checkpoint);
+                                    void drainPendingTells();
+                                    if (pendingTells.length > 0 || drainingTells) {
+                                        finishAfterTellDrain = () => {
+                                            if (settled || activeTurnId !== undefined || pendingTells.length > 0)
+                                                return;
+                                            settled = true;
+                                            unsubNotifications();
+                                            unsubServerRequest();
+                                            resolve({ status, turn });
+                                        };
+                                        return;
+                                    }
+                                }
+                                if (settled)
+                                    return;
+                                settled = true;
+                                unsubNotifications();
+                                unsubServerRequest();
+                                resolve({ status, turn });
                             }
-                            if (settled)
-                                return;
-                            settled = true;
-                            unsubNotifications();
-                            unsubServerRequest();
-                            resolve({ status, turn });
-                        }
-                        if (notification.method === "error") {
-                            const message = coerceString(notification.params?.message) ?? `${CODEX_APP_SERVER_PROVIDER} error`;
-                            builder.emit({ type: "diagnostic", text: message });
-                        }
+                            if (notification.method === "error") {
+                                const message = coerceString(notification.params?.message) ?? `${CODEX_APP_SERVER_PROVIDER} error`;
+                                builder.emit({ type: "diagnostic", text: message });
+                            }
+                        });
                     }
                     catch (error) {
                         // Notification listeners run outside the driver's await chain;
@@ -601,13 +806,16 @@ export async function startCodexAppServer(prompt, cwd, options = {}) {
                     threadId: activeThreadId,
                     input: [{ type: "text", text: prompt }],
                     ...(options.model ? { model: options.model } : {}),
-                    ...(options.effort ? { effort: options.effort } : {}),
+                    ...(options.effort ? { effort: toCodexAppServerEffort(options.effort) } : {}),
                 };
                 if (!configOwnsApprovalPolicy(options.config)) {
-                    turnStartParams.approvalPolicy = CODEX_APP_SERVER_TURN_APPROVAL_POLICY;
+                    turnStartParams.approvalPolicy = options.approvalPolicy ?? CODEX_APP_SERVER_TURN_APPROVAL_POLICY;
                 }
                 if (!configOwnsSandboxPolicy(options.config)) {
-                    turnStartParams.sandboxPolicy = buildCodexAppServerDefaultSandboxPolicy(cwd);
+                    turnStartParams.sandboxPolicy = options.sandboxPolicy ?? buildCodexAppServerWorkspaceWriteSandboxPolicy({
+                        writableRoots: [cwd],
+                        networkAccess: false,
+                    });
                 }
                 activeTurnId = undefined;
                 activeTurnSource = undefined;
@@ -616,9 +824,9 @@ export async function startCodexAppServer(prompt, cwd, options = {}) {
                 const turn = turnStart && typeof turnStart === "object"
                     ? (turnStart.turn ?? undefined)
                     : undefined;
-                recordActiveTurnId(turn?.id, "response");
+                const turnId = recordTurnStartResponse(turn?.id);
                 if (options.onEvidence)
-                    emitProviderEvidence(options.onEvidence, { type: "checkpoint", provider: CODEX_APP_SERVER_PROVIDER, fence: { kind: "turn", turnId: activeTurnId }, source: "response" }, builderDiagnostic);
+                    emitProviderEvidence(options.onEvidence, { type: "checkpoint", provider: CODEX_APP_SERVER_PROVIDER, fence: { kind: "turn", turnId }, source: "response" }, builderDiagnostic);
                 const completed = await turnCompleted;
                 if (completed.status === "interrupted" || interruptRequested) {
                     throw createAbortError(`${CODEX_APP_SERVER_PROVIDER} turn interrupted`);