@getpaseo/server 0.1.69 → 0.1.71

package/dist/server/server/agent/providers/codex-app-server-agent.js

@@ -1,5 +1,6 @@
 import { homedir } from "node:os";
 import { randomUUID } from "node:crypto";
+import * as fsSync from "node:fs";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -10,12 +11,21 @@ import { curateAgentActivity } from "../activity-curator.js";
 import { mapCodexRolloutToolCall, mapCodexToolCallFromThreadItem, } from "./codex/tool-call-mapper.js";
 import { createProviderEnv, createProviderEnvSpec, resolveProviderCommandPrefix, } from "../provider-launch-config.js";
 import { findExecutable, isCommandAvailable } from "../../../utils/executable.js";
-import { terminateProcessTree } from "../../../utils/process-tree.js";
+import { terminateWithTreeKill } from "../../../utils/tree-kill.js";
 import { spawnProcess } from "../../../utils/spawn.js";
 import { extractCodexTerminalSessionId, nonEmptyString } from "./tool-call-mapper-utils.js";
 import { buildCodexFeatures, codexModelSupportsFastMode } from "./codex-feature-definitions.js";
+import { renderProviderImageOutputAsAssistantMarkdown, } from "./provider-image-output.js";
 import { formatDiagnosticStatus, formatProviderDiagnostic, formatProviderDiagnosticError, resolveBinaryVersion, toDiagnosticErrorMessage, } from "./diagnostic-utils.js";
 import { runProviderTurn } from "./provider-runner.js";
+function assertChildWithPipes(child) {
+    if (!child.stdin || !child.stdout || !child.stderr) {
+        throw new Error("Child process did not expose stdio pipes");
+    }
+}
+function isRecord(value) {
+    return value != null && typeof value === "object" && !Array.isArray(value);
+}
 const DEFAULT_TIMEOUT_MS = 14 * 24 * 60 * 60 * 1000;
 const TURN_START_TIMEOUT_MS = 90 * 1000;
 const INTERRUPT_TIMEOUT_MS = 2000;
@@ -24,7 +34,52 @@ const APP_SERVER_FORCE_SHUTDOWN_TIMEOUT_MS = 1000;
 const CODEX_PROVIDER = "codex";
 const CODEX_IMAGE_ATTACHMENT_DIR = "paseo-attachments";
 const ASSISTANT_MESSAGE_BOUNDARY_MARKDOWN = "\n\n---\n\n";
+const CODEX_TOOL_THREAD_ITEM_TYPES = new Set([
+    "commandExecution",
+    "fileChange",
+    "mcpToolCall",
+    "webSearch",
+    "collabAgentToolCall",
+]);
 const CODEX_PLAN_IMPLEMENTATION_PROMPT_PREFIX = "The user approved the plan. Implement it now. Do not restate or revise the plan unless blocked.";
+// Codex's experimental `goals` feature ships in 0.128.0+. Older binaries reject
+// `--enable goals` at launch, so we gate by version and silently skip the flag
+// (and the /goal slash command) when the binary is too old.
+const CODEX_GOALS_MIN_VERSION = [0, 128, 0];
+function parseCodexVersion(versionOutput) {
+    const match = versionOutput.match(/(\d+)\.(\d+)\.(\d+)/);
+    if (!match)
+        return null;
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function codexVersionAtLeast(versionOutput, min) {
+    const parsed = parseCodexVersion(versionOutput);
+    if (!parsed)
+        return false;
+    for (let i = 0; i < 3; i += 1) {
+        if (parsed[i] > min[i])
+            return true;
+        if (parsed[i] < min[i])
+            return false;
+    }
+    return true;
+}
+function parseGoalSubcommand(args) {
+    const trimmed = (args ?? "").trim();
+    if (!trimmed)
+        return { kind: "usage" };
+    const lower = trimmed.toLowerCase();
+    if (lower === "pause")
+        return { kind: "pause" };
+    if (lower === "resume")
+        return { kind: "resume" };
+    if (lower === "clear")
+        return { kind: "clear" };
+    return { kind: "set", objective: trimmed };
+}
+function formatOutOfBandStatusMessage(text) {
+    return `${text.replace(/\n+$/u, "")}\n\n`;
+}
 const CODEX_APP_SERVER_CAPABILITIES = {
     supportsStreaming: true,
     supportsSessionPersistence: true,
@@ -397,8 +452,60 @@ function toCodexMcpConfig(config) {
                 url: config.url,
                 http_headers: config.headers,
             };
+        default: {
+            const _exhaustive = config;
+            throw new Error(`Unsupported MCP config type: ${String(_exhaustive.type)}`);
+        }
     }
 }
+function isJsonRpcResponse(msg) {
+    if (!isRecord(msg))
+        return false;
+    if (typeof msg.id !== "number")
+        return false;
+    return msg.result !== undefined || !!msg.error;
+}
+function isJsonRpcRequest(msg) {
+    if (!isRecord(msg))
+        return false;
+    return typeof msg.id === "number" && typeof msg.method === "string";
+}
+function isJsonRpcNotification(msg) {
+    if (!isRecord(msg))
+        return false;
+    return typeof msg.method === "string" && typeof msg.id !== "number";
+}
+function toObjectRecord(value) {
+    return isRecord(value) ? value : undefined;
+}
+const CodexModelListResponseSchema = z.object({
+    data: z
+        .array(z.object({
+        id: z.string(),
+        displayName: z.string().optional(),
+        description: z.string().optional(),
+        isDefault: z.boolean().optional(),
+        model: z.string().optional(),
+        defaultReasoningEffort: z.string().optional(),
+        supportedReasoningEfforts: z
+            .array(z.object({
+            reasoningEffort: z.string().optional(),
+            description: z.string().optional(),
+        }))
+            .optional(),
+    }))
+        .optional(),
+});
+function filterCodexThreadsByCwd(threads, cwd) {
+    if (!cwd) {
+        return threads;
+    }
+    // thread/list rows carry an optional cwd. The descriptor builder later
+    // falls back to process.cwd() if the field is missing, so we only match
+    // here when the row genuinely carries a cwd string — otherwise threads
+    // with no cwd would falsely match the daemon's own cwd.
+    return threads.filter((thread) => typeof thread.cwd === "string" && thread.cwd === cwd);
+}
 class CodexAppServerClient {
     constructor(child, logger) {
         this.child = child;
@@ -490,7 +597,7 @@ class CodexAppServerClient {
         catch {
             // ignore
         }
-        const result = await terminateProcessTree(this.child, {
+        const result = await terminateWithTreeKill(this.child, {
             gracefulTimeoutMs: APP_SERVER_GRACEFUL_SHUTDOWN_TIMEOUT_MS,
             forceTimeoutMs: APP_SERVER_FORCE_SHUTDOWN_TIMEOUT_MS,
             onForceSignal: () => {
@@ -504,33 +611,30 @@ class CodexAppServerClient {
     async handleLine(line) {
         if (!line.trim())
             return;
-        let msg;
-        try {
-            msg = JSON.parse(line);
-        }
-        catch (error) {
-            this.logger.warn({ error, line }, "Failed to parse Codex app-server JSON");
+        const raw = JSON.parse(line);
+        if (!isRecord(raw)) {
+            this.logger.warn({ line }, "Parsed JSON is not an object");
             return;
         }
-        if (typeof msg.id === "number") {
-            const id = msg.id;
-            if (msg.result !== undefined || msg.error) {
+        if (isJsonRpcResponse(raw)) {
+            const id = raw.id;
+            if (raw.result !== undefined || raw.error) {
                 const pending = this.pending.get(id);
                 if (!pending)
                     return;
                 clearTimeout(pending.timer);
                 this.pending.delete(id);
-                if (msg.error) {
-                    pending.reject(new Error(msg.error?.message ?? "Unknown error"));
+                if (raw.error) {
+                    pending.reject(new Error(raw.error.message ?? "Unknown error"));
                 }
                 else {
-                    pending.resolve(msg.result);
+                    pending.resolve(raw.result);
                 }
                 return;
             }
             // Server-initiated request
-            if (typeof msg.method === "string") {
-                const request = msg;
+            if (isJsonRpcRequest(raw)) {
+                const request = raw;
                 const handler = this.requestHandlers.get(request.method);
                 try {
                     const result = handler ? await handler(request.params) : {};
@@ -545,22 +649,22 @@ class CodexAppServerClient {
                 return;
             }
         }
-        if (typeof msg.method === "string") {
-            const notification = msg;
-            this.notificationHandler?.(notification.method, notification.params);
+        if (isJsonRpcNotification(raw)) {
+            this.notificationHandler?.(raw.method, raw.params);
         }
     }
 }
 function toAgentUsage(tokenUsage) {
-    if (!tokenUsage || typeof tokenUsage !== "object")
+    const usage = toObjectRecord(tokenUsage);
+    if (!usage)
         return undefined;
-    const usage = tokenUsage;
+    const last = toObjectRecord(usage.last);
     const contextWindowMaxTokens = firstPositiveFiniteNumber(usage.model_context_window, usage.modelContextWindow);
-    const contextWindowUsedTokens = firstPositiveFiniteNumber(usage.last?.total_tokens, usage.last?.totalTokens);
+    const contextWindowUsedTokens = firstPositiveFiniteNumber(last?.total_tokens, last?.totalTokens);
     return {
-        inputTokens: usage.last?.inputTokens,
-        cachedInputTokens: usage.last?.cachedInputTokens,
-        outputTokens: usage.last?.outputTokens,
+        inputTokens: typeof last?.inputTokens === "number" ? last.inputTokens : undefined,
+        cachedInputTokens: typeof last?.cachedInputTokens === "number" ? last.cachedInputTokens : undefined,
+        outputTokens: typeof last?.outputTokens === "number" ? last.outputTokens : undefined,
         ...(contextWindowMaxTokens !== undefined ? { contextWindowMaxTokens } : {}),
         ...(contextWindowUsedTokens !== undefined ? { contextWindowUsedTokens } : {}),
     };
@@ -570,11 +674,12 @@ function extractUserText(content) {
         return null;
     const parts = [];
     for (const item of content) {
-        if (item && typeof item === "object") {
-            const obj = item;
-            if (obj.type === "text" && typeof obj.text === "string") {
-                parts.push(obj.text);
-            }
+        const record = toObjectRecord(item);
+        if (!record) {
+            continue;
+        }
+        if (record.type === "text" && typeof record.text === "string") {
+            parts.push(record.text);
         }
     }
     return parts.length > 0 ? parts.join("\n") : null;
@@ -661,10 +766,10 @@ function normalizeCodexQuestionPrompts(raw) {
     }
     const questions = [];
     for (const item of raw) {
-        if (!item || typeof item !== "object") {
+        const record = toObjectRecord(item);
+        if (!record) {
             continue;
         }
-        const record = item;
         const id = nonEmptyString(record.id);
         const header = nonEmptyString(record.header);
         const question = nonEmptyString(record.question);
@@ -673,10 +778,10 @@ function normalizeCodexQuestionPrompts(raw) {
         }
         const options = Array.isArray(record.options)
             ? record.options.flatMap((option) => {
-                if (!option || typeof option !== "object") {
+                const optionRecord = toObjectRecord(option);
+                if (!optionRecord) {
                     return [];
                 }
-                const optionRecord = option;
                 const label = nonEmptyString(optionRecord.label);
                 if (!label) {
                     return [];
@@ -771,10 +876,9 @@ function mapCodexQuestionResponseByHeader(params) {
     if (params.response.behavior !== "allow") {
         return null;
     }
-    const answersRecord = params.response.updatedInput && typeof params.response.updatedInput === "object"
-        ? params.response.updatedInput.answers
-        : undefined;
-    if (!answersRecord || typeof answersRecord !== "object") {
+    const updatedInputRecord = toObjectRecord(params.response.updatedInput);
+    const answersRecord = toObjectRecord(updatedInputRecord?.answers);
+    if (!answersRecord) {
         return null;
     }
     const answers = {};
@@ -800,10 +904,10 @@ function mapCodexQuestionResponseByHeader(params) {
     return Object.keys(answers).length > 0 ? answers : null;
 }
 function extractPatchLikeText(value) {
-    if (!value || typeof value !== "object") {
+    const record = toObjectRecord(value);
+    if (!record) {
         return undefined;
     }
-    const record = value;
     const candidates = [
         record.diff,
         record.patch,
@@ -842,6 +946,10 @@ function normalizeCodexThreadItemType(rawType) {
             return "webSearch";
         case "CollabAgentToolCall":
             return "collabAgentToolCall";
+        case "ImageView":
+            return "imageView";
+        case "ImageGeneration":
+            return "imageGeneration";
         default:
             return rawType;
     }
@@ -900,10 +1008,10 @@ function parseCodexPatchChanges(changes) {
     if (Array.isArray(changes)) {
         return changes
             .map((entry) => {
-            if (!entry || typeof entry !== "object") {
+            const record = toObjectRecord(entry);
+            if (!record) {
                 return null;
             }
-            const record = entry;
             const pathValue = resolvePathFromRecord(record);
             if (!pathValue) {
                 return null;
@@ -918,7 +1026,10 @@ function parseCodexPatchChanges(changes) {
         })
             .filter((entry) => entry !== null);
     }
-    const recordChanges = changes;
+    const recordChanges = toObjectRecord(changes);
+    if (!recordChanges) {
+        return [];
+    }
     const directPathValue = resolvePathFromRecord(recordChanges);
     if (directPathValue) {
         return [
@@ -1118,16 +1229,81 @@ function mapCodexThreadUserMessageItem(normalizedItem, includeUserMessage) {
     const text = extractUserText(normalizedItem.content) ?? "";
     return { type: "user_message", text };
 }
+function firstStringField(record, fields) {
+    for (const field of fields) {
+        const value = record[field];
+        if (typeof value === "string") {
+            return value;
+        }
+    }
+    return null;
+}
+function codexImageOutputFromResult(result) {
+    if (typeof result === "string") {
+        const trimmed = result.trim();
+        if (trimmed.toLowerCase().startsWith("data:image/") ||
+            (/^[A-Za-z0-9+/]+={0,2}$/.test(trimmed) && trimmed.length > 64)) {
+            return { data: trimmed };
+        }
+        return { url: trimmed };
+    }
+    const resultRecord = toObjectRecord(result);
+    if (!resultRecord) {
+        return null;
+    }
+    return {
+        path: firstStringField(resultRecord, ["path", "savedPath", "saved_path"]),
+        url: firstStringField(resultRecord, ["url"]),
+        data: firstStringField(resultRecord, ["data"]),
+        mimeType: firstStringField(resultRecord, ["mimeType", "mime_type"]),
+    };
+}
+function writeImageAttachmentSync(mimeType, data) {
+    const attachmentsDir = path.join(os.tmpdir(), CODEX_IMAGE_ATTACHMENT_DIR);
+    fsSync.mkdirSync(attachmentsDir, { recursive: true });
+    const normalized = normalizeImageData(mimeType, data);
+    const extension = getImageExtension(normalized.mimeType);
+    const filename = `${randomUUID()}.${extension}`;
+    const filePath = path.join(attachmentsDir, filename);
+    fsSync.writeFileSync(filePath, Buffer.from(normalized.data, "base64"));
+    return filePath;
+}
+function materializeCodexImageOutput(image) {
+    return {
+        path: writeImageAttachmentSync(image.mimeType ?? "image/png", image.data),
+    };
+}
+function mapCodexThreadImageItem(normalizedType, normalizedItem) {
+    if (normalizedType === "imageView") {
+        return renderProviderImageOutputAsAssistantMarkdown({
+            path: firstStringField(normalizedItem, ["path"]),
+        });
+    }
+    const savedPath = firstStringField(normalizedItem, ["savedPath", "saved_path"]);
+    const result = codexImageOutputFromResult(normalizedItem.result);
+    return renderProviderImageOutputAsAssistantMarkdown({
+        path: savedPath ?? result?.path ?? null,
+        url: result?.url ?? null,
+        data: result?.data ?? null,
+        mimeType: result?.mimeType ?? null,
+    }, { materialize: materializeCodexImageOutput });
+}
 function threadItemToTimeline(item, options) {
-    if (!item || typeof item !== "object")
+    const itemRecord = toObjectRecord(item);
+    if (!itemRecord)
         return null;
-    const itemRecord = item;
     const includeUserMessage = options?.includeUserMessage ?? true;
     const cwd = options?.cwd ?? null;
     const normalizedType = normalizeCodexThreadItemType(typeof itemRecord.type === "string" ? itemRecord.type : undefined);
     const normalizedItem = normalizedType && normalizedType !== itemRecord.type
         ? { ...itemRecord, type: normalizedType }
         : itemRecord;
+    if (normalizedType === "imageView" || normalizedType === "imageGeneration") {
+        return mapCodexThreadImageItem(normalizedType, normalizedItem);
+    }
+    if (normalizedType && CODEX_TOOL_THREAD_ITEM_TYPES.has(normalizedType)) {
+        return mapCodexToolCallFromThreadItem(normalizedItem, { cwd });
+    }
     switch (normalizedType) {
         case "userMessage":
             return mapCodexThreadUserMessageItem(normalizedItem, includeUserMessage);
@@ -1140,12 +1316,6 @@ function threadItemToTimeline(item, options) {
             return mapCodexThreadPlanItem(normalizedItem);
         case "reasoning":
             return mapCodexThreadReasoningItem(normalizedItem);
-        case "commandExecution":
-        case "fileChange":
-        case "mcpToolCall":
-        case "webSearch":
-        case "collabAgentToolCall":
-            return mapCodexToolCallFromThreadItem(normalizedItem, { cwd });
         default:
             return null;
     }
@@ -1816,10 +1986,13 @@ async function writeImageAttachment(mimeType, data) {
 async function readCodexConfiguredDefaults(client, logger) {
     let savedConfigDefaults = {};
     try {
-        const response = (await client.request("getUserSavedConfig", {}));
+        const response = toObjectRecord(await client.request("getUserSavedConfig", {}));
+        const config = toObjectRecord(response?.config);
+        const modelValue = typeof config?.model === "string" ? config.model : undefined;
+        const thinkingOptionValue = typeof config?.modelReasoningEffort === "string" ? config.modelReasoningEffort : null;
         savedConfigDefaults = {
-            model: normalizeCodexModelId(response?.config?.model),
-            thinkingOptionId: normalizeCodexThinkingOptionId(response?.config?.modelReasoningEffort ?? null),
+            model: normalizeCodexModelId(modelValue),
+            thinkingOptionId: normalizeCodexThinkingOptionId(thinkingOptionValue),
         };
     }
     catch (error) {
@@ -1830,10 +2003,13 @@ async function readCodexConfiguredDefaults(client, logger) {
     }
     let configReadDefaults = {};
     try {
-        const response = (await client.request("config/read", {}));
+        const response = toObjectRecord(await client.request("config/read", {}));
+        const config = toObjectRecord(response?.config);
+        const modelValue = typeof config?.model === "string" ? config.model : undefined;
+        const thinkingOptionValue = typeof config?.model_reasoning_effort === "string" ? config.model_reasoning_effort : null;
         configReadDefaults = {
-            model: normalizeCodexModelId(response?.config?.model),
-            thinkingOptionId: normalizeCodexThinkingOptionId(response?.config?.model_reasoning_effort ?? null),
+            model: normalizeCodexModelId(modelValue),
+            thinkingOptionId: normalizeCodexThinkingOptionId(thinkingOptionValue),
         };
     }
     catch (error) {
@@ -1905,11 +2081,12 @@ function buildCodexAppServerInitializeParams() {
     };
 }
 class CodexAppServerAgentSession {
-    constructor(config, resumeHandle, logger, spawnAppServer, deps = {}, ephemeral = false) {
+    constructor(config, resumeHandle, logger, spawnAppServer, deps = {}, ephemeral = false, goalsEnabled = false) {
         this.resumeHandle = resumeHandle;
         this.spawnAppServer = spawnAppServer;
         this.deps = deps;
         this.ephemeral = ephemeral;
+        this.goalsEnabled = goalsEnabled;
         this.provider = CODEX_PROVIDER;
         this.capabilities = CODEX_APP_SERVER_CAPABILITIES;
         this.currentThreadId = null;
@@ -1999,15 +2176,20 @@ class CodexAppServerAgentSession {
         if (!this.client)
             return;
         try {
-            const response = (await this.client.request("collaborationMode/list", {}));
+            const response = toObjectRecord(await this.client.request("collaborationMode/list", {}));
             const data = Array.isArray(response?.data) ? response.data : [];
-            this.collaborationModes = data.map((entry) => ({
-                name: typeof entry.name === "string" ? entry.name : "",
-                mode: typeof entry.mode === "string" ? entry.mode : null,
-                model: typeof entry.model === "string" ? entry.model : null,
-                reasoning_effort: typeof entry.reasoning_effort === "string" ? entry.reasoning_effort : null,
-                developer_instructions: typeof entry.developer_instructions === "string" ? entry.developer_instructions : null,
-            }));
+            this.collaborationModes = data.map((entry) => {
+                const record = toObjectRecord(entry);
+                return {
+                    name: typeof record?.name === "string" ? record.name : "",
+                    mode: typeof record?.mode === "string" ? record.mode : null,
+                    model: typeof record?.model === "string" ? record.model : null,
+                    reasoning_effort: typeof record?.reasoning_effort === "string" ? record.reasoning_effort : null,
+                    developer_instructions: typeof record?.developer_instructions === "string"
+                        ? record.developer_instructions
+                        : null,
+                };
+            });
         }
         catch (error) {
             this.logger.trace({ error }, "Failed to load collaboration modes");
@@ -2019,22 +2201,22 @@ class CodexAppServerAgentSession {
         if (!this.client)
             return;
         try {
-            const response = (await this.client.request("skills/list", {
+            const response = toObjectRecord(await this.client.request("skills/list", {
                 cwd: [this.config.cwd],
             }));
             const entries = Array.isArray(response?.data) ? response.data : [];
             const skills = [];
             for (const entry of entries) {
-                const list = Array.isArray(entry.skills)
-                    ? entry.skills
-                    : [];
+                const entryRecord = toObjectRecord(entry);
+                const list = Array.isArray(entryRecord?.skills) ? entryRecord.skills : [];
                 for (const skill of list) {
-                    if (typeof skill?.name !== "string" || typeof skill?.path !== "string")
+                    const skillRecord = toObjectRecord(skill);
+                    if (typeof skillRecord?.name !== "string" || typeof skillRecord?.path !== "string")
                         continue;
                     skills.push({
-                        name: skill.name,
-                        description: resolveSkillDescription(skill),
-                        path: skill.path,
+                        name: skillRecord.name,
+                        description: resolveSkillDescription(skillRecord),
+                        path: skillRecord.path,
                     });
                 }
             }
@@ -2183,7 +2365,7 @@ class CodexAppServerAgentSession {
         if (!this.client || !this.currentThreadId)
             return;
         try {
-            const loaded = (await this.client.request("thread/loaded/list", {}));
+            const loaded = toObjectRecord(await this.client.request("thread/loaded/list", {}));
             const ids = Array.isArray(loaded?.data) ? loaded.data : [];
             if (ids.includes(this.currentThreadId)) {
                 return;
@@ -2622,7 +2804,86 @@ class CodexAppServerAgentSession {
         const fallbackSkills = appServerSkills.length === 0
             ? await listCodexSkills(this.config.cwd, this.deps.workspaceGitService)
             : [];
-        return [...appServerSkills, ...fallbackSkills, ...prompts].sort((a, b) => a.name.localeCompare(b.name));
+        const builtin = [];
+        if (this.goalsEnabled) {
+            builtin.push({
+                name: "goal",
+                description: "Set, pause, resume, or clear the agent's goal",
+                argumentHint: "[<objective>|pause|resume|clear]",
+            });
+        }
+        return [...builtin, ...appServerSkills, ...fallbackSkills, ...prompts].sort((a, b) => a.name.localeCompare(b.name));
+    }
+    tryHandleOutOfBand(prompt) {
+        if (!this.goalsEnabled)
+            return null;
+        if (typeof prompt !== "string")
+            return null;
+        const parsed = this.parseSlashCommandInput(prompt);
+        if (!parsed || parsed.commandName !== "goal")
+            return null;
+        const subcommand = parseGoalSubcommand(parsed.args);
+        return {
+            run: async ({ emit }) => {
+                const text = formatOutOfBandStatusMessage(await this.executeGoalSubcommand(subcommand));
+                emit({
+                    type: "timeline",
+                    provider: CODEX_PROVIDER,
+                    item: { type: "assistant_message", text },
+                });
+            },
+        };
+    }
+    async executeGoalSubcommand(subcommand) {
+        if (subcommand.kind === "usage") {
+            return "Usage: /goal <objective>|pause|resume|clear";
+        }
+        try {
+            await this.connect();
+            if (this.currentThreadId) {
+                await this.ensureThreadLoaded();
+            }
+            else {
+                await this.ensureThread();
+            }
+            if (!this.client || !this.currentThreadId) {
+                throw new Error("Codex thread is not available");
+            }
+            switch (subcommand.kind) {
+                case "set": {
+                    await this.client.request("thread/goal/set", {
+                        threadId: this.currentThreadId,
+                        objective: subcommand.objective,
+                        status: "active",
+                    });
+                    return `Goal set: ${subcommand.objective}`;
+                }
+                case "pause": {
+                    await this.client.request("thread/goal/set", {
+                        threadId: this.currentThreadId,
+                        status: "paused",
+                    });
+                    return "Goal paused.";
+                }
+                case "resume": {
+                    await this.client.request("thread/goal/set", {
+                        threadId: this.currentThreadId,
+                        status: "active",
+                    });
+                    return "Goal resumed.";
+                }
+                case "clear": {
+                    await this.client.request("thread/goal/clear", {
+                        threadId: this.currentThreadId,
+                    });
+                    return "Goal cleared.";
+                }
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "unknown error";
+            return `Failed to update goal: ${message}`;
+        }
     }
     async resolveModelAndThinking() {
         if (!this.client) {
@@ -2641,8 +2902,20 @@ class CodexAppServerAgentSession {
             thinkingOptionId = configuredDefaults.thinkingOptionId;
         }
         if (!model || !thinkingOptionId) {
-            const modelResponse = (await this.client.request("model/list", {}));
-            const models = modelResponse?.data ?? [];
+            const modelResponse = toObjectRecord(await this.client.request("model/list", {}));
+            const modelData = Array.isArray(modelResponse?.data) ? modelResponse.data : [];
+            const models = modelData
+                .map((m) => {
+                const record = toObjectRecord(m);
+                return {
+                    id: typeof record?.id === "string" ? record.id : "",
+                    isDefault: !!record?.isDefault,
+                    defaultReasoningEffort: typeof record?.defaultReasoningEffort === "string"
+                        ? record.defaultReasoningEffort
+                        : undefined,
+                };
+            })
+                .filter((m) => m.id);
             const defaultModel = models.find((m) => m.isDefault) ?? models[0];
             if (!defaultModel) {
                 throw new Error("No models available from Codex app-server");
@@ -2672,7 +2945,7 @@ class CodexAppServerAgentSession {
         const approvalPolicy = this.config.approvalPolicy ?? preset.approvalPolicy;
         const sandbox = this.config.sandboxMode ?? preset.sandbox;
         const innerConfig = this.buildCodexInnerConfig();
-        const response = (await this.client.request("thread/start", {
+        const rawResponse = await this.client.request("thread/start", {
             model,
             cwd: this.config.cwd ?? null,
             approvalPolicy,
@@ -2682,8 +2955,10 @@ class CodexAppServerAgentSession {
                 : {}),
             ...(innerConfig ? { config: innerConfig } : {}),
             ...(this.ephemeral ? { ephemeral: true } : {}),
-        }));
-        const threadId = response?.thread?.id;
+        });
+        const response = toObjectRecord(rawResponse);
+        const threadRecord = toObjectRecord(response?.thread);
+        const threadId = typeof threadRecord?.id === "string" ? threadRecord.id : undefined;
         if (!threadId) {
             throw new Error("Codex app-server did not return thread id");
         }
@@ -3367,7 +3642,16 @@ class CodexAppServerAgentSession {
         }, "Codex edit tool call is missing diff/content fields");
     }
     handleCommandApprovalRequest(params) {
-        const parsed = params;
+        const parsed = z
+            .object({
+            itemId: z.string(),
+            threadId: z.string(),
+            turnId: z.string(),
+            command: z.string().nullable().optional(),
+            cwd: z.string().nullable().optional(),
+            reason: z.string().nullable().optional(),
+        })
+            .parse(params);
         const commandPreview = mapCodexExecNotificationToToolCall({
             callId: parsed.itemId,
             command: parsed.command,
@@ -3408,7 +3692,14 @@ class CodexAppServerAgentSession {
         });
     }
     handleFileChangeApprovalRequest(params) {
-        const parsed = params;
+        const parsed = z
+            .object({
+            itemId: z.string(),
+            threadId: z.string(),
+            turnId: z.string(),
+            reason: z.string().nullable().optional(),
+        })
+            .parse(params);
         const requestId = `permission-${parsed.itemId}`;
         const request = {
             id: requestId,
@@ -3437,7 +3728,14 @@ class CodexAppServerAgentSession {
         });
     }
     handleToolApprovalRequest(params) {
-        const parsed = params;
+        const parsed = z
+            .object({
+            itemId: z.string(),
+            threadId: z.string(),
+            turnId: z.string(),
+            questions: z.array(z.unknown()),
+        })
+            .parse(params);
         const requestId = `permission-${parsed.itemId}`;
         const questions = normalizeCodexQuestionPrompts(parsed.questions);
         const request = {
@@ -3487,13 +3785,37 @@ export class CodexAppServerAgentClient {
         this.deps = deps;
         this.provider = CODEX_PROVIDER;
         this.capabilities = CODEX_APP_SERVER_CAPABILITIES;
+        this.goalsEnabledPromise = null;
+    }
+    resolveGoalsEnabled() {
+        if (!this.goalsEnabledPromise) {
+            this.goalsEnabledPromise = (async () => {
+                try {
+                    const launchPrefix = await resolveCodexLaunchPrefix(this.runtimeSettings);
+                    const versionOutput = await resolveBinaryVersion(launchPrefix.command);
+                    const enabled = codexVersionAtLeast(versionOutput, CODEX_GOALS_MIN_VERSION);
+                    this.logger.trace({ versionOutput, enabled }, "Resolved codex goals feature gate");
+                    return enabled;
+                }
+                catch (error) {
+                    this.logger.warn({ err: error }, "Failed to probe codex version for goals gate");
+                    return false;
+                }
+            })();
+        }
+        return this.goalsEnabledPromise;
     }
-    async spawnAppServer(launchEnv) {
+    async spawnAppServer(launchEnv, options) {
         const launchPrefix = await resolveCodexLaunchPrefix(this.runtimeSettings);
+        const args = [...launchPrefix.args, "app-server"];
+        if (options?.goalsEnabled) {
+            args.push("--enable", "goals");
+        }
         this.logger.trace({
             launchPrefix,
+            goalsEnabled: options?.goalsEnabled === true,
         }, "Spawning Codex app server");
-        return spawnProcess(launchPrefix.command, [...launchPrefix.args, "app-server"], {
+        const child = spawnProcess(launchPrefix.command, args, {
             detached: process.platform !== "win32",
             stdio: ["pipe", "pipe", "pipe"],
             ...createProviderEnvSpec({
@@ -3501,10 +3823,18 @@ export class CodexAppServerAgentClient {
                 overlays: [launchEnv],
             }),
         });
+        assertChildWithPipes(child);
+        return child;
     }
     async createSession(config, launchContext, options) {
+        if (options?.persistSession === false) {
+            this.logger.debug("Codex app-server does not expose an ephemeral-session option; persistSession=false is currently a no-op");
+            // TODO: Honor persistSession=false if app-server adds support, or route
+            // utility generations through `codex exec --ephemeral` in a larger change.
+        }
         const sessionConfig = { ...config, provider: CODEX_PROVIDER };
-        const session = new CodexAppServerAgentSession(sessionConfig, null, this.logger, () => this.spawnAppServer(launchContext?.env), this.deps, options?.persistSession === false);
+        const goalsEnabled = await this.resolveGoalsEnabled();
+        const session = new CodexAppServerAgentSession(sessionConfig, null, this.logger, () => this.spawnAppServer(launchContext?.env, { goalsEnabled }), this.deps, options?.persistSession === false, goalsEnabled);
         await session.connect();
         return session;
     }
@@ -3516,19 +3846,27 @@ export class CodexAppServerAgentClient {
             provider: CODEX_PROVIDER,
             cwd: overrides?.cwd ?? storedConfig.cwd ?? process.cwd(),
         };
-        const session = new CodexAppServerAgentSession(merged, handle, this.logger, () => this.spawnAppServer(launchContext?.env), this.deps);
+        const goalsEnabled = await this.resolveGoalsEnabled();
+        const session = new CodexAppServerAgentSession(merged, handle, this.logger, () => this.spawnAppServer(launchContext?.env, { goalsEnabled }), this.deps, false, goalsEnabled);
         await session.connect();
         return session;
     }
     async listPersistedAgents(options) {
         const child = await this.spawnAppServer();
-        const client = new CodexAppServerClient(child, this.logger);
+        const client = this.deps._createCodexClient?.(child, this.logger) ??
+            new CodexAppServerClient(child, this.logger);
         try {
             await client.request("initialize", buildCodexAppServerInitializeParams());
             client.notify("initialized", {});
             const limit = options?.limit ?? 20;
-            const response = (await client.request("thread/list", { limit }));
-            const threads = Array.isArray(response?.data) ? response.data : [];
+            // thread/list returns the cheap `cwd` field. When the caller supplied
+            // a cwd hint we filter here so the per-thread `thread/read includeTurns`
+            // hydration below only runs for matching threads. Fetch a wider window
+            // when filtering since most threads will be from other cwds.
+            const listLimit = options?.cwd ? Math.max(limit, 50) : limit;
+            const response = toObjectRecord(await client.request("thread/list", { limit: listLimit }));
+            const allThreads = Array.isArray(response?.data) ? response.data.filter(isRecord) : [];
+            const threads = filterCodexThreadsByCwd(allThreads, options?.cwd);
             const descriptors = await Promise.all(threads.slice(0, limit).map(async (thread) => {
                 const threadId = typeof thread.id === "string" ? thread.id : "";
                 const cwd = typeof thread.cwd === "string" ? thread.cwd : process.cwd();
@@ -3581,8 +3919,9 @@ export class CodexAppServerAgentClient {
         try {
             await client.request("initialize", buildCodexAppServerInitializeParams());
             client.notify("initialized", {});
-            const response = (await client.request("model/list", {}));
-            const models = Array.isArray(response?.data) ? response.data : [];
+            const rawResponse = await client.request("model/list", {});
+            const parsedResponse = CodexModelListResponseSchema.safeParse(rawResponse);
+            const models = parsedResponse.success ? (parsedResponse.data.data ?? []) : [];
             const configuredDefaults = await readCodexConfiguredDefaults(client, this.logger);
             const configuredDefaultModelId = configuredDefaults.model;
             const configuredDefaultThinkingOptionId = configuredDefaults.thinkingOptionId;
@@ -3599,6 +3938,21 @@ export class CodexAppServerAgentClient {
             await client.dispose();
         }
     }
+    async archiveNativeSession(handle) {
+        const threadId = handle.nativeHandle ?? handle.sessionId;
+        if (!threadId)
+            return;
+        const child = await this.spawnAppServer();
+        const client = new CodexAppServerClient(child, this.logger);
+        try {
+            await client.request("initialize", buildCodexAppServerInitializeParams());
+            client.notify("initialized", {});
+            await client.request("thread/archive", { threadId });
+        }
+        finally {
+            await client.dispose();
+        }
+    }
     async isAvailable() {
         const command = this.runtimeSettings?.command;
         if (command?.mode === "replace") {