@junctionpanel/server 0.1.29 → 0.1.31

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

@@ -218,6 +218,9 @@ function parseUpdatedQuestionAnswers(updatedInput) {
     }
     return parsed;
 }
+function toPendingPermissionId(requestId) {
+    return `permission-${String(requestId)}`;
+}
 async function listCodexCustomPrompts() {
     const codexHome = resolveCodexHomeDir();
     const promptsDir = path.join(codexHome, "prompts");
@@ -524,7 +527,7 @@ class CodexAppServerClient {
                 const request = msg;
                 const handler = this.requestHandlers.get(request.method);
                 try {
-                    const result = handler ? await handler(request.params) : {};
+                    const result = handler ? await handler(request.params, request.id) : {};
                     const response = { id: request.id, result };
                     this.child.stdin.write(`${JSON.stringify(response)}\n`);
                 }
@@ -581,12 +584,73 @@ function parsePlanTextToTodoItems(text) {
         completed: false,
     }));
 }
+function formatProposedPlanBlock(text) {
+    return `<proposed_plan>\n${text}\n</proposed_plan>`;
+}
+function formatProposedPlanChunk(text, options) {
+    const parts = [];
+    if (options?.open) {
+        parts.push("<proposed_plan>\n");
+    }
+    parts.push(text);
+    if (options?.close) {
+        parts.push("\n</proposed_plan>");
+    }
+    return parts.join("");
+}
 function planStepsToTodoItems(steps) {
     return steps.map((entry) => ({
         text: entry.step,
         completed: entry.status === "completed",
     }));
 }
+function supportsPlanCollaborationMode(response) {
+    const candidateArrays = [
+        Array.isArray(response) ? response : null,
+        Array.isArray(response?.data)
+            ? (response.data)
+            : null,
+        Array.isArray(response?.modes)
+            ? (response.modes)
+            : null,
+        Array.isArray(response?.collaborationModes)
+            ? (response.collaborationModes)
+            : null,
+        Array.isArray(response?.items)
+            ? (response.items)
+            : null,
+    ];
+    for (const entries of candidateArrays) {
+        if (!entries)
+            continue;
+        for (const entry of entries) {
+            const record = toRecord(entry);
+            const modeName = (typeof record?.mode === "string" ? record.mode : null) ??
+                (typeof record?.name === "string" ? record.name : null) ??
+                (typeof record?.id === "string" ? record.id : null) ??
+                (typeof entry === "string" ? entry : null);
+            if (modeName?.trim().toLowerCase() === "plan") {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+function shouldRetryInitializeWithoutExperimentalApi(error) {
+    const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+    return (message.includes("experimentalapi") ||
+        message.includes("experimental api") ||
+        message.includes("capabilities") ||
+        message.includes("unknown field") ||
+        message.includes("invalid params"));
+}
+function shouldRetryTurnStartWithoutCollaborationMode(error) {
+    const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+    return (message.includes("collaborationmode") ||
+        message.includes("collaboration mode") ||
+        message.includes("experimentalapi") ||
+        message.includes("experimental api"));
+}
 function extractPatchLikeText(value) {
     if (!value || typeof value !== "object") {
         return undefined;
@@ -896,8 +960,11 @@ function threadItemToTimeline(item, options) {
         }
         case "plan": {
             const text = normalizedItem.text ?? "";
+            if (typeof text === "string" && text.trim().length > 0) {
+                return { type: "assistant_message", text: formatProposedPlanBlock(text) };
+            }
             const items = parsePlanTextToTodoItems(text);
-            return { type: "todo", items };
+            return items.length > 0 ? { type: "todo", items } : null;
         }
         case "reasoning": {
             const summary = Array.isArray(normalizedItem.summary)
@@ -958,6 +1025,13 @@ const TurnPlanUpdatedNotificationSchema = z.object({
     })
         .passthrough()),
 }).passthrough();
+const ItemPlanDeltaNotificationSchema = z.object({
+    itemId: z.string(),
+    delta: z.string(),
+}).passthrough();
+const ServerRequestResolvedNotificationSchema = z.object({
+    requestId: z.union([z.string(), z.number()]),
+}).passthrough();
 const TurnDiffUpdatedNotificationSchema = z.object({
     diff: z.string(),
 }).passthrough();
@@ -1097,6 +1171,12 @@ const CodexNotificationSchema = z.union([
         })),
     })),
     z.object({ method: z.literal("turn/plan/updated"), params: z.unknown() }).transform(({ method, params }) => ({ kind: "invalid_payload", method, params })),
+    z.object({ method: z.literal("item/plan/delta"), params: ItemPlanDeltaNotificationSchema }).transform(({ params }) => ({
+        kind: "plan_delta",
+        itemId: params.itemId,
+        delta: params.delta,
+    })),
+    z.object({ method: z.literal("item/plan/delta"), params: z.unknown() }).transform(({ method, params }) => ({ kind: "invalid_payload", method, params })),
     z.object({ method: z.literal("turn/diff/updated"), params: TurnDiffUpdatedNotificationSchema }).transform(({ params }) => ({ kind: "diff_updated", diff: params.diff })),
     z.object({ method: z.literal("turn/diff/updated"), params: z.unknown() }).transform(({ method, params }) => ({ kind: "invalid_payload", method, params })),
     z.object({
@@ -1104,6 +1184,14 @@ const CodexNotificationSchema = z.union([
         params: ThreadTokenUsageUpdatedNotificationSchema,
     }).transform(({ params }) => ({ kind: "token_usage_updated", tokenUsage: params.tokenUsage })),
     z.object({ method: z.literal("thread/tokenUsage/updated"), params: z.unknown() }).transform(({ method, params }) => ({ kind: "invalid_payload", method, params })),
+    z.object({
+        method: z.literal("serverRequest/resolved"),
+        params: ServerRequestResolvedNotificationSchema,
+    }).transform(({ params }) => ({
+        kind: "server_request_resolved",
+        requestId: String(params.requestId),
+    })),
+    z.object({ method: z.literal("serverRequest/resolved"), params: z.unknown() }).transform(({ method, params }) => ({ kind: "invalid_payload", method, params })),
     z.object({ method: z.literal("item/agentMessage/delta"), params: ItemTextDeltaNotificationSchema }).transform(({ params }) => ({
         kind: "agent_message_delta",
         itemId: params.itemId,
@@ -1303,6 +1391,10 @@ export async function codexAppServerTurnInputFromPrompt(prompt, logger) {
 }
 export const __codexAppServerInternals = {
     mapCodexPatchNotificationToToolCall,
+    supportsPlanCollaborationMode,
+    shouldRetryInitializeWithoutExperimentalApi,
+    shouldRetryTurnStartWithoutCollaborationMode,
+    formatProposedPlanBlock,
 };
 class CodexAppServerAgentSession {
     constructor(config, resumeHandle, logger, spawnAppServer) {
@@ -1332,8 +1424,8 @@ class CodexAppServerAgentSession {
         this.warnedInvalidNotificationPayloads = new Set();
         this.warnedIncompleteEditToolCallIds = new Set();
         this.connected = false;
-        this.collaborationModes = [];
-        this.resolvedCollaborationMode = null;
+        this.nativePlanModeSupported = null;
+        this.pendingPlanTexts = new Map();
         this.cachedSkills = [];
         this.logger = logger.child({ module: "agent", provider: CODEX_PROVIDER });
         if (config.modeId === undefined) {
@@ -1358,13 +1450,26 @@ class CodexAppServerAgentSession {
         this.client = new CodexAppServerClient(child, this.logger);
         this.client.setNotificationHandler((method, params) => this.handleNotification(method, params));
         this.registerRequestHandlers();
-        await this.client.request("initialize", {
-            clientInfo: {
-                name: "junction",
-                title: "Junction",
-                version: "0.0.0",
-            },
-        });
+        const clientInfo = {
+            name: "junction",
+            title: "Junction",
+            version: "0.0.0",
+        };
+        try {
+            await this.client.request("initialize", {
+                clientInfo,
+                capabilities: {
+                    experimentalApi: true,
+                },
+            });
+        }
+        catch (error) {
+            if (!shouldRetryInitializeWithoutExperimentalApi(error)) {
+                throw error;
+            }
+            await this.client.request("initialize", { clientInfo });
+            this.nativePlanModeSupported = false;
+        }
         this.client.notify("initialized", {});
         await this.loadCollaborationModes();
         await this.loadSkills();
@@ -1377,22 +1482,17 @@ class CodexAppServerAgentSession {
     async loadCollaborationModes() {
         if (!this.client)
             return;
+        if (this.nativePlanModeSupported === false) {
+            return;
+        }
         try {
-            const response = (await this.client.request("collaborationMode/list", {}));
-            const data = Array.isArray(response?.data) ? response.data : [];
-            this.collaborationModes = data.map((entry) => ({
-                name: String(entry.name ?? ""),
-                mode: entry.mode ?? null,
-                model: entry.model ?? null,
-                reasoning_effort: entry.reasoning_effort ?? null,
-                developer_instructions: entry.developer_instructions ?? null,
-            }));
+            const response = await this.client.request("collaborationMode/list", {});
+            this.nativePlanModeSupported = supportsPlanCollaborationMode(response);
         }
         catch (error) {
             this.logger.trace({ error }, "Failed to load collaboration modes");
-            this.collaborationModes = [];
+            this.nativePlanModeSupported = false;
         }
-        this.resolvedCollaborationMode = this.resolveCollaborationMode(this.currentMode);
     }
     async loadSkills() {
         if (!this.client)
@@ -1422,59 +1522,12 @@ class CodexAppServerAgentSession {
             this.cachedSkills = [];
         }
     }
-    resolveCollaborationMode(modeId) {
-        if (this.collaborationModes.length === 0)
-            return null;
-        const normalized = modeId.toLowerCase();
-        const findByName = (predicate) => this.collaborationModes.find((entry) => predicate(entry.name.toLowerCase()));
-        let match;
-        if (normalized === "read-only") {
-            // Prefer explicit plan collaboration modes over generic read-only modes.
-            match =
-                findByName((name) => name.includes("plan")) ??
-                    findByName((name) => name.includes("read"));
-        }
-        else if (normalized === "full-access") {
-            match = findByName((name) => name.includes("full") || name.includes("exec"));
-        }
-        else {
-            match = findByName((name) => name.includes("auto") || name.includes("code"));
-        }
-        if (!match) {
-            match = this.collaborationModes[0] ?? null;
-        }
-        if (!match)
-            return null;
-        const settings = {};
-        if (match.model)
-            settings.model = match.model;
-        if (match.reasoning_effort)
-            settings.reasoning_effort = match.reasoning_effort;
-        const modeSpecificInstruction = normalized === "read-only"
-            ? "Plan mode is enabled. Do not execute commands, edit files, or perform write operations. Provide analysis and a step-by-step plan only."
-            : "";
-        const developerInstructions = [
-            modeSpecificInstruction,
-            match.developer_instructions?.trim(),
-            this.config.systemPrompt?.trim(),
-        ]
-            .filter((entry) => typeof entry === "string" && entry.length > 0)
-            .join("\n\n");
-        if (developerInstructions)
-            settings.developer_instructions = developerInstructions;
-        if (this.config.model)
-            settings.model = this.config.model;
-        const thinkingOptionId = normalizeCodexThinkingOptionId(this.config.thinkingOptionId);
-        if (thinkingOptionId)
-            settings.reasoning_effort = thinkingOptionId;
-        return { mode: match.mode ?? "code", settings, name: match.name };
-    }
     registerRequestHandlers() {
         if (!this.client)
             return;
-        this.client.setRequestHandler("item/commandExecution/requestApproval", (params) => this.handleCommandApprovalRequest(params));
-        this.client.setRequestHandler("item/fileChange/requestApproval", (params) => this.handleFileChangeApprovalRequest(params));
-        this.client.setRequestHandler("tool/requestUserInput", (params) => this.handleToolApprovalRequest(params));
+        this.client.setRequestHandler("item/commandExecution/requestApproval", (params, requestId) => this.handleCommandApprovalRequest(params, requestId));
+        this.client.setRequestHandler("item/fileChange/requestApproval", (params, requestId) => this.handleFileChangeApprovalRequest(params, requestId));
+        this.client.setRequestHandler("tool/requestUserInput", (params, requestId) => this.handleToolApprovalRequest(params, requestId));
     }
     async loadPersistedHistory() {
         if (!this.client || !this.currentThreadId)
@@ -1672,6 +1725,8 @@ class CodexAppServerAgentSession {
             const preset = MODE_PRESETS[this.currentMode] ?? MODE_PRESETS[DEFAULT_CODEX_MODE_ID];
             const approvalPolicy = this.config.approvalPolicy ?? preset.approvalPolicy;
             const sandboxPolicyType = this.config.sandboxMode ?? preset.sandbox;
+            const planModeRequested = options?.extra?.codex?.planMode === true;
+            const thinkingOptionId = normalizeCodexThinkingOptionId(this.config.thinkingOptionId);
             const params = {
                 threadId: this.currentThreadId,
                 input,
@@ -1683,16 +1738,9 @@ class CodexAppServerAgentSession {
             if (this.config.model) {
                 params.model = this.config.model;
             }
-            const thinkingOptionId = normalizeCodexThinkingOptionId(this.config.thinkingOptionId);
             if (thinkingOptionId) {
                 params.effort = thinkingOptionId;
             }
-            if (this.resolvedCollaborationMode) {
-                params.collaborationMode = {
-                    mode: this.resolvedCollaborationMode.mode,
-                    settings: this.resolvedCollaborationMode.settings,
-                };
-            }
             if (this.config.cwd) {
                 params.cwd = this.config.cwd;
             }
@@ -1706,7 +1754,38 @@ class CodexAppServerAgentSession {
             if (codexConfig) {
                 params.config = codexConfig;
             }
-            await this.client.request("turn/start", params, TURN_START_TIMEOUT_MS);
+            let downgradedFromPlanMode = false;
+            if (this.nativePlanModeSupported !== false) {
+                const collaborationMode = this.buildCollaborationModePayload(planModeRequested ? "plan" : "default");
+                if (collaborationMode) {
+                    params.collaborationMode = collaborationMode;
+                }
+            }
+            try {
+                await this.client.request("turn/start", params, TURN_START_TIMEOUT_MS);
+            }
+            catch (error) {
+                const canRetryWithoutPlanMode = Object.prototype.hasOwnProperty.call(params, "collaborationMode") &&
+                    shouldRetryTurnStartWithoutCollaborationMode(error);
+                if (!canRetryWithoutPlanMode) {
+                    throw error;
+                }
+                delete params.collaborationMode;
+                this.nativePlanModeSupported = false;
+                this.cachedRuntimeInfo = null;
+                downgradedFromPlanMode = planModeRequested;
+                await this.client.request("turn/start", params, TURN_START_TIMEOUT_MS);
+            }
+            if (downgradedFromPlanMode) {
+                this.emitEvent({
+                    type: "timeline",
+                    provider: CODEX_PROVIDER,
+                    item: {
+                        type: "assistant_message",
+                        text: "Plan mode is not supported by this Codex runtime. Sent as a normal turn instead.",
+                    },
+                });
+            }
             let sawTurnStarted = false;
             for await (const event of queue) {
                 // Drop pre-start timeline noise that can leak from the previous turn.
@@ -1763,9 +1842,9 @@ class CodexAppServerAgentSession {
             model: this.config.model ?? null,
             thinkingOptionId: normalizeCodexThinkingOptionId(this.config.thinkingOptionId) ?? null,
             modeId: this.currentMode ?? null,
-            extra: this.resolvedCollaborationMode
-                ? { collaborationMode: this.resolvedCollaborationMode.name }
-                : undefined,
+            extra: this.nativePlanModeSupported === null
+                ? undefined
+                : { planModeSupported: this.nativePlanModeSupported },
         };
         this.cachedRuntimeInfo = info;
         return { ...info };
@@ -1779,17 +1858,14 @@ class CodexAppServerAgentSession {
     async setMode(modeId) {
         validateCodexMode(modeId);
         this.currentMode = modeId;
-        this.resolvedCollaborationMode = this.resolveCollaborationMode(modeId);
         this.cachedRuntimeInfo = null;
     }
     async setModel(modelId) {
         this.config.model = modelId ?? undefined;
-        this.resolvedCollaborationMode = this.resolveCollaborationMode(this.currentMode);
         this.cachedRuntimeInfo = null;
     }
     async setThinkingOption(thinkingOptionId) {
         this.config.thinkingOptionId = normalizeCodexThinkingOptionId(thinkingOptionId);
-        this.resolvedCollaborationMode = this.resolveCollaborationMode(this.currentMode);
         this.cachedRuntimeInfo = null;
     }
     getPendingPermissions() {
@@ -2019,6 +2095,24 @@ class CodexAppServerAgentSession {
         }
         return Object.keys(innerConfig).length > 0 ? innerConfig : null;
     }
+    buildCollaborationModePayload(mode) {
+        if (this.nativePlanModeSupported !== true) {
+            return null;
+        }
+        const model = normalizeCodexModelId(this.config.model);
+        if (!model) {
+            return null;
+        }
+        const thinkingOptionId = normalizeCodexThinkingOptionId(this.config.thinkingOptionId) ?? null;
+        return {
+            mode,
+            settings: {
+                model,
+                reasoning_effort: thinkingOptionId,
+                developer_instructions: null,
+            },
+        };
+    }
     async buildUserInput(prompt) {
         if (typeof prompt === "string") {
             return [{ type: "text", text: prompt }];
@@ -2073,6 +2167,7 @@ class CodexAppServerAgentSession {
             this.emittedExecCommandCompletedCallIds.clear();
             this.pendingCommandOutputDeltas.clear();
             this.pendingFileChangeOutputDeltas.clear();
+            this.pendingPlanTexts.clear();
             this.warnedIncompleteEditToolCallIds.clear();
             this.eventQueue?.end();
             return;
@@ -2089,6 +2184,22 @@ class CodexAppServerAgentSession {
             });
             return;
         }
+        if (parsed.kind === "plan_delta") {
+            const previous = this.pendingPlanTexts.get(parsed.itemId) ?? "";
+            const next = previous + parsed.delta;
+            this.pendingPlanTexts.set(parsed.itemId, next);
+            this.emitEvent({
+                type: "timeline",
+                provider: CODEX_PROVIDER,
+                item: {
+                    type: "assistant_message",
+                    text: formatProposedPlanChunk(parsed.delta, {
+                        open: previous.length === 0,
+                    }),
+                },
+            });
+            return;
+        }
         if (parsed.kind === "diff_updated") {
             // NOTE: Codex app-server emits frequent `turn/diff/updated` notifications
             // containing a full accumulated unified diff for the *entire turn*.
@@ -2096,6 +2207,20 @@ class CodexAppServerAgentSession {
             // We intentionally do NOT store every diff update in the timeline.
             return;
         }
+        if (parsed.kind === "server_request_resolved") {
+            const pendingRequestId = toPendingPermissionId(parsed.requestId);
+            if (this.resolvedPermissionRequests.has(pendingRequestId)) {
+                return;
+            }
+            this.pendingPermissions.delete(pendingRequestId);
+            this.emitEvent({
+                type: "permission_resolved",
+                provider: CODEX_PROVIDER,
+                requestId: pendingRequestId,
+                resolution: { behavior: "allow" },
+            });
+            return;
+        }
         if (parsed.kind === "token_usage_updated") {
             this.latestUsage = toAgentUsage(parsed.tokenUsage);
             return;
@@ -2225,6 +2350,24 @@ class CodexAppServerAgentSession {
                         timelineItem.text = buffered;
                     }
                 }
+                if (timelineItem.type === "assistant_message" &&
+                    normalizedItemType === "plan" &&
+                    itemId) {
+                    const bufferedPlanText = this.pendingPlanTexts.get(itemId) ?? "";
+                    const finalPlanText = typeof parsed.item.text === "string" ? parsed.item.text : "";
+                    if (bufferedPlanText.length > 0) {
+                        const trailingText = finalPlanText.startsWith(bufferedPlanText)
+                            ? finalPlanText.slice(bufferedPlanText.length)
+                            : "";
+                        timelineItem.text = formatProposedPlanChunk(trailingText, {
+                            close: true,
+                        });
+                        this.pendingPlanTexts.delete(itemId);
+                    }
+                    else if (finalPlanText.trim().length > 0) {
+                        timelineItem.text = formatProposedPlanBlock(finalPlanText);
+                    }
+                }
                 if (timelineItem.type === "reasoning" && itemId) {
                     const buffered = this.pendingReasoning.get(itemId);
                     if (buffered && buffered.length > 0) {
@@ -2240,6 +2383,7 @@ class CodexAppServerAgentSession {
                     this.emittedItemStartedIds.delete(itemId);
                     this.pendingCommandOutputDeltas.delete(itemId);
                     this.pendingFileChangeOutputDeltas.delete(itemId);
+                    this.pendingPlanTexts.delete(itemId);
                 }
             }
             return;
@@ -2336,7 +2480,7 @@ class CodexAppServerAgentSession {
             payload,
         }, "Codex edit tool call is missing diff/content fields");
     }
-    handleCommandApprovalRequest(params) {
+    handleCommandApprovalRequest(params, rawRequestId) {
         const parsed = params;
         const commandPreview = mapCodexExecNotificationToToolCall({
             callId: parsed.itemId,
@@ -2344,7 +2488,7 @@ class CodexAppServerAgentSession {
             cwd: parsed.cwd ?? this.config.cwd ?? null,
             running: true,
         });
-        const requestId = `permission-${parsed.itemId}`;
+        const requestId = toPendingPermissionId(rawRequestId ?? parsed.itemId);
         const title = parsed.command ? `Run command: ${parsed.command}` : "Run command";
         const request = {
             id: requestId,
@@ -2377,9 +2521,9 @@ class CodexAppServerAgentSession {
             this.pendingPermissionHandlers.set(requestId, { resolve, kind: "command" });
         });
     }
-    handleFileChangeApprovalRequest(params) {
+    handleFileChangeApprovalRequest(params, rawRequestId) {
         const parsed = params;
-        const requestId = `permission-${parsed.itemId}`;
+        const requestId = toPendingPermissionId(rawRequestId ?? parsed.itemId);
         const request = {
             id: requestId,
             provider: CODEX_PROVIDER,
@@ -2406,16 +2550,19 @@ class CodexAppServerAgentSession {
             this.pendingPermissionHandlers.set(requestId, { resolve, kind: "file" });
         });
     }
-    handleToolApprovalRequest(params) {
+    handleToolApprovalRequest(params, rawRequestId) {
         const parsed = params;
-        const requestId = `permission-${parsed.itemId}`;
+        const requestId = toPendingPermissionId(rawRequestId ?? parsed.itemId);
         const request = {
             id: requestId,
             provider: CODEX_PROVIDER,
-            name: "CodexTool",
-            kind: "tool",
-            title: "Tool action requires approval",
+            name: "CodexQuestion",
+            kind: "question",
+            title: "Answer question",
             description: undefined,
+            input: {
+                questions: Array.isArray(parsed.questions) ? parsed.questions : [],
+            },
             detail: {
                 type: "unknown",
                 input: {
@@ -2435,7 +2582,7 @@ class CodexAppServerAgentSession {
         return new Promise((resolve) => {
             this.pendingPermissionHandlers.set(requestId, {
                 resolve,
-                kind: "tool",
+                kind: "question",
                 questions: Array.isArray(parsed.questions) ? parsed.questions : [],
             });
         });