@love-moon/ai-sdk 0.7.7 → 0.9.0

package/dist/media-input.d.ts

@@ -0,0 +1,21 @@
+export function normalizeMediaInputs(value: any): {
+    kind: any;
+    path: any;
+    mimeType: any;
+    name: string;
+    sizeBytes: number;
+}[];
+export function resolveTurnMedia(sessionOptions: any, turnOptions?: {}): {
+    kind: any;
+    path: any;
+    mimeType: any;
+    name: string;
+    sizeBytes: number;
+}[];
+export function assertMediaCapabilities(media: any, backend: any, capabilities: any): void;
+export function fileMediaToDataUri(media: any): string;
+export function fileMediaToBase64(media: any): string;
+export function createMediaInputError(message: any, extras?: {}): Error;
+export function defaultPromptForMedia(media: any): string;
+export const MEDIA_CAPABILITY_NATIVE: "native";
+export const MEDIA_CAPABILITY_UNSUPPORTED: "unsupported";

package/dist/media-input.js

@@ -0,0 +1,197 @@
+import fs from "node:fs";
+import path from "node:path";
+const SUPPORTED_KINDS = new Set(["image"]);
+const SUPPORTED_MIME_TYPES = new Set([
+    "image/gif",
+    "image/jpeg",
+    "image/png",
+    "image/webp",
+]);
+const MAX_MEDIA_ITEMS = 20;
+const MAX_IMAGE_BYTES = 20 * 1024 * 1024;
+const MAX_TOTAL_MEDIA_BYTES = 100 * 1024 * 1024;
+export const MEDIA_CAPABILITY_NATIVE = "native";
+export const MEDIA_CAPABILITY_UNSUPPORTED = "unsupported";
+function inferKind(mimeType) {
+    if (mimeType.startsWith("image/"))
+        return "image";
+    return "";
+}
+function inferMimeType(filePath, kind) {
+    const extension = path.extname(filePath).toLowerCase();
+    const known = {
+        ".bmp": "image/bmp",
+        ".gif": "image/gif",
+        ".heic": "image/heic",
+        ".jpeg": "image/jpeg",
+        ".jpg": "image/jpeg",
+        ".png": "image/png",
+        ".webp": "image/webp",
+    };
+    return known[extension] || `${kind}/unknown`;
+}
+function hasExpectedSignature(filePath, mimeType) {
+    const handle = fs.openSync(filePath, "r");
+    try {
+        const header = Buffer.alloc(12);
+        const bytesRead = fs.readSync(handle, header, 0, header.length, 0);
+        if (bytesRead < 4)
+            return false;
+        if (mimeType === "image/png")
+            return header.subarray(0, 8).equals(Buffer.from("89504e470d0a1a0a", "hex"));
+        if (mimeType === "image/jpeg")
+            return header[0] === 0xff && header[1] === 0xd8 && header[2] === 0xff;
+        if (mimeType === "image/gif")
+            return header.subarray(0, 6).toString("ascii") === "GIF87a" || header.subarray(0, 6).toString("ascii") === "GIF89a";
+        if (mimeType === "image/webp")
+            return header.subarray(0, 4).toString("ascii") === "RIFF" && header.subarray(8, 12).toString("ascii") === "WEBP";
+        return false;
+    }
+    finally {
+        fs.closeSync(handle);
+    }
+}
+export function normalizeMediaInputs(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        throw createMediaInputError("media must be an array", { reason: "invalid_media_input" });
+    }
+    if (value.length > MAX_MEDIA_ITEMS) {
+        throw createMediaInputError(`media cannot contain more than ${MAX_MEDIA_ITEMS} files`, {
+            reason: "media_limit_exceeded",
+        });
+    }
+    let totalBytes = 0;
+    return value.map((item, index) => {
+        if (!item || typeof item !== "object" || Array.isArray(item)) {
+            throw createMediaInputError(`media[${index}] must be an object`, {
+                reason: "invalid_media_input",
+                mediaIndex: index,
+            });
+        }
+        const filePath = typeof item.path === "string" ? item.path.trim() : "";
+        const mimeType = typeof item.mimeType === "string" ? item.mimeType.trim().toLowerCase() : "";
+        const explicitKind = typeof item.kind === "string" ? item.kind.trim().toLowerCase() : "";
+        const kind = explicitKind || inferKind(mimeType);
+        if (!SUPPORTED_KINDS.has(kind)) {
+            throw createMediaInputError(`media[${index}] kind must be image`, {
+                reason: "invalid_media_input",
+                mediaIndex: index,
+            });
+        }
+        if (!filePath || !path.isAbsolute(filePath)) {
+            throw createMediaInputError(`media[${index}] path must be absolute`, {
+                reason: "invalid_media_input",
+                mediaIndex: index,
+            });
+        }
+        let stat;
+        try {
+            const linkStat = fs.lstatSync(filePath);
+            if (linkStat.isSymbolicLink()) {
+                throw new Error("symbolic links are not allowed");
+            }
+            stat = fs.statSync(filePath);
+        }
+        catch {
+            throw createMediaInputError(`media[${index}] file does not exist`, {
+                reason: "invalid_media_input",
+                mediaIndex: index,
+            });
+        }
+        if (!stat.isFile()) {
+            throw createMediaInputError(`media[${index}] path must reference a file`, {
+                reason: "invalid_media_input",
+                mediaIndex: index,
+            });
+        }
+        const normalizedMimeType = mimeType || inferMimeType(filePath, kind);
+        if (!SUPPORTED_MIME_TYPES.has(normalizedMimeType) || inferKind(normalizedMimeType) !== kind) {
+            throw createMediaInputError(`media[${index}] kind does not match mimeType`, {
+                reason: "invalid_media_input",
+                mediaIndex: index,
+            });
+        }
+        if (!hasExpectedSignature(filePath, normalizedMimeType)) {
+            throw createMediaInputError(`media[${index}] content does not match mimeType`, {
+                reason: "invalid_media_input",
+                mediaIndex: index,
+            });
+        }
+        const itemLimit = MAX_IMAGE_BYTES;
+        if (stat.size > itemLimit) {
+            throw createMediaInputError(`media[${index}] exceeds the ${kind} size limit`, {
+                reason: "media_limit_exceeded",
+                mediaIndex: index,
+                maxBytes: itemLimit,
+            });
+        }
+        totalBytes += stat.size;
+        if (totalBytes > MAX_TOTAL_MEDIA_BYTES) {
+            throw createMediaInputError("media exceeds the total size limit", {
+                reason: "media_limit_exceeded",
+                maxBytes: MAX_TOTAL_MEDIA_BYTES,
+            });
+        }
+        return {
+            kind,
+            path: filePath,
+            mimeType: normalizedMimeType,
+            name: typeof item.name === "string" && item.name.trim()
+                ? path.basename(item.name.trim())
+                : path.basename(filePath),
+            sizeBytes: stat.size,
+        };
+    });
+}
+export function resolveTurnMedia(sessionOptions, turnOptions = {}) {
+    const media = normalizeMediaInputs(turnOptions.media);
+    if (!turnOptions.useInitialImages || !Array.isArray(sessionOptions?.initialImages)) {
+        return media;
+    }
+    const legacy = sessionOptions.initialImages
+        .filter((item) => typeof item === "string" && item.trim())
+        .map((filePath) => ({
+        kind: "image",
+        path: path.resolve(sessionOptions?.cwd || process.cwd(), filePath.trim()),
+        mimeType: inferMimeType(filePath.trim(), "image"),
+    }));
+    const combined = [...normalizeMediaInputs(legacy), ...media];
+    const seen = new Set();
+    return combined.filter((item) => {
+        const key = `${item.kind}:${item.path}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+export function assertMediaCapabilities(media, backend, capabilities) {
+    for (const [index, item] of media.entries()) {
+        if (capabilities?.[item.kind] !== MEDIA_CAPABILITY_NATIVE) {
+            throw createMediaInputError(`${backend} does not support ${item.kind} input`, {
+                reason: "unsupported_media",
+                backend,
+                mediaKind: item.kind,
+                mediaIndex: index,
+            });
+        }
+    }
+}
+export function fileMediaToDataUri(media) {
+    return `data:${media.mimeType};base64,${fs.readFileSync(media.path).toString("base64")}`;
+}
+export function fileMediaToBase64(media) {
+    return fs.readFileSync(media.path).toString("base64");
+}
+export function createMediaInputError(message, extras = {}) {
+    const error = new Error(message);
+    for (const [key, value] of Object.entries(extras)) {
+        error[key] = value;
+    }
+    return error;
+}
+export function defaultPromptForMedia(media) {
+    return "Analyze the attached images.";
+}

package/dist/providers/chat-web-session.d.ts

@@ -109,6 +109,11 @@ export class ChatWebSession extends EventEmitter<[never]> {
             session_file_path: undefined;
             updated_at: string;
         } | null;
+        capabilities: {
+            media: Readonly<{
+                image: "unsupported";
+            }>;
+        };
         chatWebProvider: string;
         providerConversationId: any;
         providerUrl: string | undefined;
@@ -173,7 +178,8 @@ export class ChatWebSession extends EventEmitter<[never]> {
      * render "open in ChatGPT" / "open in AI Studio" links.
      */
     providerConversationUrl(): string | undefined;
-    runTurn(promptText: any, { onProgress }?: {
+    runTurn(promptText: any, { useInitialImages, media: mediaInput, contextFiles, onProgress }?: {
+        useInitialImages?: boolean | undefined;
         onProgress?: null | undefined;
     }): Promise<{
         text: string;

package/dist/providers/chat-web-session.js

@@ -1,5 +1,8 @@
 import { EventEmitter } from "node:events";
 import { CHAT_WEB_SESSION_VARIANT } from "../built-in-backends.js";
+import { PROVIDER_MEDIA_CAPABILITIES } from "../media-adapters.js";
+import { assertMediaCapabilities, resolveTurnMedia } from "../media-input.js";
+import { normalizeContextFiles } from "../context-files.js";
 import { emitLog, normalizeLogger } from "../shared.js";
 const SUPPORTED_CHAT_WEB_PROVIDERS = new Set(["chatgpt", "gemini"]);
 const DEFAULT_CHAT_WEB_PROVIDER = "chatgpt";
@@ -209,6 +212,7 @@ export class ChatWebSession extends EventEmitter {
                 ? { ready: true, command: this.providerConversationUrl() }
                 : null,
             currentTurnStatus: this.getCurrentTurnStatus(),
+            capabilities: { media: PROVIDER_MEDIA_CAPABILITIES[CHAT_WEB_SESSION_VARIANT] },
             chatWebProvider: this.chatWebProvider,
             providerConversationId: this.providerConversationId,
             providerUrl: this.providerConversationUrl(),
@@ -401,7 +405,14 @@ export class ChatWebSession extends EventEmitter {
                 return undefined;
         }
     }
-    async runTurn(promptText, { onProgress = null } = {}) {
+    async runTurn(promptText, { useInitialImages = false, media: mediaInput, contextFiles, onProgress = null } = {}) {
+        if (normalizeContextFiles(contextFiles).length > 0) {
+            const error = new Error("chat-web does not support context file input");
+            error.reason = "unsupported_context_files";
+            throw error;
+        }
+        const media = resolveTurnMedia(this.options, { useInitialImages, media: mediaInput });
+        assertMediaCapabilities(media, this.backend, PROVIDER_MEDIA_CAPABILITIES[CHAT_WEB_SESSION_VARIANT]);
         const prompt = String(promptText || "").trim();
         if (!prompt) {
             return {

package/dist/providers/claude-agent-sdk-session.d.ts

@@ -1,10 +1,16 @@
 export class ClaudeAgentSdkSession extends EventEmitter<[never]> {
     static capabilities: Readonly<{
         goal: true;
+        media: Readonly<{
+            image: "native";
+        }>;
     }>;
     constructor(backend: any, options?: {});
     getCapabilities(): {
         goal: true;
+        media: Readonly<{
+            image: "native";
+        }>;
     };
     backend: string;
     options: {};
@@ -68,6 +74,9 @@ export class ClaudeAgentSdkSession extends EventEmitter<[never]> {
         currentTurnStatus: any;
         capabilities: {
             goal: true;
+            media: Readonly<{
+                image: "native";
+            }>;
         };
     };
     getSessionInfo(): {
@@ -131,7 +140,7 @@ export class ClaudeAgentSdkSession extends EventEmitter<[never]> {
         onProgress: any;
     }): Promise<void>;
     interruptCurrentTurn(): Promise<boolean>;
-    runTurn(promptText: any, { useInitialImages, onProgress, jsonSchema }?: {
+    runTurn(promptText: any, { useInitialImages, media: mediaInput, contextFiles, onProgress, jsonSchema }?: {
         useInitialImages?: boolean | undefined;
         onProgress?: null | undefined;
         jsonSchema?: null | undefined;

package/dist/providers/claude-agent-sdk-session.js

@@ -1,5 +1,8 @@
 import { EventEmitter } from "node:events";
 import { CLAUDE_AGENT_SDK_VARIANT as CLAUDE_PROVIDER_VARIANT } from "../built-in-backends.js";
+import { appendContextFilesToPrompt } from "../context-files.js";
+import { PROVIDER_MEDIA_CAPABILITIES, buildClaudeContent } from "../media-adapters.js";
+import { assertMediaCapabilities, defaultPromptForMedia, resolveTurnMedia, } from "../media-input.js";
 import { emitLog, extractLongFlagFromCommandLine, getBoundedEnvInt, isGoalStatus, loadEnvConfig, normalizeLogger, proxyToEnv, sanitizeForLog, } from "../shared.js";
 const DEFAULT_TURN_DEADLINE_MS = 12 * 60 * 1000;
 const MIN_TURN_DEADLINE_MS = 30 * 1000;
@@ -8,6 +11,16 @@ const DEFAULT_SETTING_SOURCES = ["user", "project", "local"];
 function waitForever() {
     return new Promise(() => { });
 }
+async function* buildClaudeInput(promptText, media) {
+    yield {
+        type: "user",
+        message: {
+            role: "user",
+            content: buildClaudeContent(promptText, media),
+        },
+        parent_tool_use_id: null,
+    };
+}
 function createTurnError(message, extras = {}) {
     const error = new Error(message);
     for (const [key, value] of Object.entries(extras)) {
@@ -129,7 +142,10 @@ export class ClaudeAgentSdkSession extends EventEmitter {
     // Capability advertised via getSnapshot().capabilities so worker proxies
     // can short-circuit runGoal without an IPC round trip. Claude exposes
     // native `/goal` slash command, so this is true.
-    static capabilities = Object.freeze({ goal: true });
+    static capabilities = Object.freeze({
+        goal: true,
+        media: PROVIDER_MEDIA_CAPABILITIES[CLAUDE_PROVIDER_VARIANT],
+    });
     getCapabilities() {
         return { ...ClaudeAgentSdkSession.capabilities };
     }
@@ -722,11 +738,15 @@ export class ClaudeAgentSdkSession extends EventEmitter {
         }
         return true;
     }
-    async runTurn(promptText, { useInitialImages = false, onProgress = null, jsonSchema = null } = {}) {
+    async runTurn(promptText, { useInitialImages = false, media: mediaInput, contextFiles, onProgress = null, jsonSchema = null } = {}) {
         if (this.closeRequested) {
             throw this.createSessionClosedError();
         }
-        const effectivePrompt = this.buildPrompt(promptText, { useInitialImages });
+        const media = resolveTurnMedia(this.options, { useInitialImages, media: mediaInput });
+        assertMediaCapabilities(media, this.backend, PROVIDER_MEDIA_CAPABILITIES[CLAUDE_PROVIDER_VARIANT]);
+        let effectivePrompt = this.buildPrompt(promptText, { useInitialImages: false }) ||
+            (media.length ? defaultPromptForMedia(media) : "");
+        effectivePrompt = appendContextFilesToPrompt(effectivePrompt, contextFiles).prompt;
         if (!effectivePrompt) {
             return {
                 text: "",
@@ -776,7 +796,7 @@ export class ClaudeAgentSdkSession extends EventEmitter {
                 status_line: "claude is working",
             }, onProgress);
             const query = sdkModule.query({
-                prompt: effectivePrompt,
+                prompt: media.length ? buildClaudeInput(effectivePrompt, media) : effectivePrompt,
                 options: this.buildSdkOptions(abortController),
             });
             currentTurn.query = query;

package/dist/providers/codex-app-server-session.d.ts

@@ -139,6 +139,17 @@ export class CodexAppServerSession extends EventEmitter<[never]> {
         thread_id: any;
     };
     emitWorkingStatus(payload: any): Promise<void>;
+    /**
+     * Idempotent terminal working-status clear (see BUG-R6-01 lesson). The
+     * "reply_in_progress:false" signal that unsticks the composer must be emitted
+     * from a reliable, always-arriving path, and multiple paths emitting it must
+     * be a safe no-op. A one-time guard on the turn object ensures we clear
+     * exactly once regardless of how many code paths reach here.
+     */
+    emitTurnCompletedStatus(currentTurn: any, { phase, status_done_line }?: {
+        phase?: string | undefined;
+        status_done_line?: string | undefined;
+    }): Promise<void>;
     emitAssistantMessage(text: any): Promise<void>;
     finalizeActiveAssistantMessage(currentTurn?: {
         turnId: string;
@@ -212,7 +223,7 @@ export class CodexAppServerSession extends EventEmitter<[never]> {
     handleTransportExit(payload: any): void;
     maybeEmitAuthRequired(error: any): void;
     interruptCurrentTurn(): Promise<boolean>;
-    runTurn(promptText: any, { useInitialImages, jsonSchema }?: {
+    runTurn(promptText: any, { useInitialImages, media: mediaInput, contextFiles, jsonSchema }?: {
         useInitialImages?: boolean | undefined;
         jsonSchema?: null | undefined;
     }): Promise<{

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

@@ -1,5 +1,8 @@
 import { EventEmitter } from "node:events";
 import { CODEX_APP_SERVER_VARIANT } from "../built-in-backends.js";
+import { appendContextFilesToPrompt } from "../context-files.js";
+import { PROVIDER_MEDIA_CAPABILITIES, buildCodexAppServerInput } from "../media-adapters.js";
+import { assertMediaCapabilities, defaultPromptForMedia, resolveTurnMedia, } from "../media-input.js";
 import { CodexAppServerTransport } from "../transports/codex-app-server-transport.js";
 import { TERMINAL_GOAL_STATUSES, emitLog, getBoundedEnvInt, loadEnvConfig, normalizeLogger, proxyToEnv, sanitizeForLog, } from "../shared.js";
 const TERMINAL_GOAL_STATUSES_LOCAL = new Set(TERMINAL_GOAL_STATUSES);
@@ -35,14 +38,6 @@ function extractSessionConfiguredValue(params, ...keys) {
     }
     return undefined;
 }
-function buildTurnInput(promptText) {
-    return [
-        {
-            type: "text",
-            text: promptText,
-        },
-    ];
-}
 function injectJsonSchemaPrompt(promptText, jsonSchema) {
     const schemaText = typeof jsonSchema === "string" ? jsonSchema : JSON.stringify(jsonSchema, null, 2);
     return `You must respond with valid JSON that strictly conforms to the following JSON Schema. Do not include any markdown formatting or explanation outside the JSON object.
@@ -179,7 +174,10 @@ export class CodexAppServerSession extends EventEmitter {
      * Treat as read-only.
      * @type {Readonly<import("../shared.js").SessionCapabilities>}
      */
-    static capabilities = Object.freeze({ goal: true });
+    static capabilities = Object.freeze({
+        goal: true,
+        media: PROVIDER_MEDIA_CAPABILITIES[CODEX_APP_SERVER_VARIANT],
+    });
     /**
      * @returns {import("../shared.js").SessionCapabilities}
      */
@@ -489,6 +487,26 @@ export class CodexAppServerSession extends EventEmitter {
         }
         this.emit("working_status", snapshot);
     }
+    /**
+     * Idempotent terminal working-status clear (see BUG-R6-01 lesson). The
+     * "reply_in_progress:false" signal that unsticks the composer must be emitted
+     * from a reliable, always-arriving path, and multiple paths emitting it must
+     * be a safe no-op. A one-time guard on the turn object ensures we clear
+     * exactly once regardless of how many code paths reach here.
+     */
+    async emitTurnCompletedStatus(currentTurn, { phase = "turn_completed", status_done_line = "codex finished" } = {}) {
+        if (currentTurn && currentTurn.terminalStatusEmitted) {
+            return;
+        }
+        if (currentTurn) {
+            currentTurn.terminalStatusEmitted = true;
+        }
+        await this.emitWorkingStatus({
+            phase,
+            reply_in_progress: false,
+            status_done_line,
+        });
+    }
     async emitAssistantMessage(text) {
         this.touchTurnActivity();
         const payload = {
@@ -869,7 +887,15 @@ export class CodexAppServerSession extends EventEmitter {
                 return;
             }
             case "turn/completed": {
-                const currentTurn = this.ensureCurrentTurn(params);
+                let currentTurn = this.ensureCurrentTurn(params);
+                if (!currentTurn && this.currentTurn && !this.currentTurn.goalMode) {
+                    // Defense-in-depth (BUG-R6-01 class): a non-goal session has exactly
+                    // one active turn. If turn matching fails (missing `turn/started`, a
+                    // turnId mismatch, or an id carried on a different field), we must NOT
+                    // strand the terminal clear here — otherwise the composer stays on
+                    // "codex composing reply" until the 12-min idle deadline or a reload.
+                    currentTurn = this.currentTurn;
+                }
                 if (!currentTurn) {
                     return;
                 }
@@ -887,9 +913,8 @@ export class CodexAppServerSession extends EventEmitter {
                         turnStatus: status,
                         turnError,
                     });
-                    await this.emitWorkingStatus({
+                    await this.emitTurnCompletedStatus(currentTurn, {
                         phase: "turn_failed",
-                        reply_in_progress: false,
                         status_done_line: `codex failed (${status})`,
                     });
                     if (currentTurn.goalMode) {
@@ -927,11 +952,7 @@ export class CodexAppServerSession extends EventEmitter {
                     currentTurn.activeAssistantMessageText = "";
                     return;
                 }
-                await this.emitWorkingStatus({
-                    phase: "turn_completed",
-                    reply_in_progress: false,
-                    status_done_line: "codex finished",
-                });
+                await this.emitTurnCompletedStatus(currentTurn);
                 currentTurn.resolve({
                     turn,
                     usage: this.tokenUsage ? { ...this.tokenUsage } : null,
@@ -1006,11 +1027,15 @@ export class CodexAppServerSession extends EventEmitter {
         }
         return false;
     }
-    async runTurn(promptText, { useInitialImages = false, jsonSchema = null } = {}) {
+    async runTurn(promptText, { useInitialImages = false, media: mediaInput, contextFiles, jsonSchema = null } = {}) {
         if (this.closeRequested) {
             throw this.createSessionClosedError();
         }
-        let effectivePrompt = this.buildPrompt(promptText, { useInitialImages });
+        const media = resolveTurnMedia(this.options, { useInitialImages, media: mediaInput });
+        assertMediaCapabilities(media, this.backend, PROVIDER_MEDIA_CAPABILITIES[CODEX_APP_SERVER_VARIANT]);
+        let effectivePrompt = this.buildPrompt(promptText, { useInitialImages: false }) ||
+            (media.length ? defaultPromptForMedia(media) : "");
+        effectivePrompt = appendContextFilesToPrompt(effectivePrompt, contextFiles).prompt;
         if (jsonSchema && typeof jsonSchema === "object" && effectivePrompt) {
             effectivePrompt = injectJsonSchemaPrompt(effectivePrompt, jsonSchema);
         }
@@ -1058,7 +1083,7 @@ export class CodexAppServerSession extends EventEmitter {
                 threadId: this.sessionId,
                 cwd: this.cwd,
                 approvalPolicy: "never",
-                input: buildTurnInput(effectivePrompt),
+                input: buildCodexAppServerInput(effectivePrompt, media),
             });
             const turnResult = await Promise.race([
                 (async () => {
@@ -1075,6 +1100,10 @@ export class CodexAppServerSession extends EventEmitter {
             await this.finalizeActiveAssistantMessage(currentTurn, {
                 messageId: currentTurn.activeAssistantMessageId,
             });
+            // Belt-and-suspenders terminal clear. Idempotent (guarded on the turn),
+            // so when the wire `turn/completed` already cleared this is a no-op; it
+            // only fires if the turn resolved without the wire clear reaching here.
+            await this.emitTurnCompletedStatus(currentTurn);
             if (currentTurn.fullText) {
                 this.history.push({ role: "assistant", content: currentTurn.fullText });
             }

package/dist/providers/codex-exec-session.d.ts

@@ -52,6 +52,11 @@ export class CodexExecSession extends EventEmitter<[never]> {
         resumeReady: boolean;
         manualResume: null;
         currentTurnStatus: any;
+        capabilities: {
+            media: Readonly<{
+                image: "native";
+            }>;
+        };
         pid: any;
     };
     getSessionInfo(): {
@@ -85,13 +90,13 @@ export class CodexExecSession extends EventEmitter<[never]> {
     emitWorkingStatus(payload: any, onProgress?: null): Promise<any>;
     emitAssistantMessage(text: any): Promise<void>;
     buildPrompt(promptText: any): string;
-    buildExecArgs({ useInitialImages, schemaFilePath, lastMessageFilePath }?: {
-        useInitialImages?: boolean | undefined;
+    buildExecArgs({ media, schemaFilePath, lastMessageFilePath }?: {
+        media?: never[] | undefined;
         schemaFilePath?: string | undefined;
         lastMessageFilePath?: string | undefined;
     }): string[];
     maybeEmitAuthRequired(stderrTail: any): void;
-    runTurn(promptText: any, { useInitialImages, onProgress, jsonSchema }?: {
+    runTurn(promptText: any, { useInitialImages, media: mediaInput, contextFiles, onProgress, jsonSchema }?: {
         useInitialImages?: boolean | undefined;
         onProgress?: null | undefined;
         jsonSchema?: null | undefined;

package/dist/providers/codex-exec-session.js

@@ -6,6 +6,9 @@ import { randomUUID } from "node:crypto";
 import { EventEmitter } from "node:events";
 import readline from "node:readline";
 import { CODEX_EXEC_VARIANT as CODEX_EXEC_PROVIDER_VARIANT } from "../built-in-backends.js";
+import { appendContextFilesToPrompt } from "../context-files.js";
+import { PROVIDER_MEDIA_CAPABILITIES } from "../media-adapters.js";
+import { assertMediaCapabilities, defaultPromptForMedia, resolveTurnMedia, } from "../media-input.js";
 import { emitLog, getBoundedEnvInt, loadEnvConfig, normalizeLogger, parseCommandParts, proxyToEnv, sanitizeForLog, } from "../shared.js";
 const DEFAULT_TURN_DEADLINE_MS = 12 * 60 * 1000;
 const MIN_TURN_DEADLINE_MS = 30 * 1000;
@@ -239,6 +242,7 @@ export class CodexExecSession extends EventEmitter {
             resumeReady: false,
             manualResume: null,
             currentTurnStatus: this.getCurrentTurnStatus(),
+            capabilities: { media: PROVIDER_MEDIA_CAPABILITIES[CODEX_EXEC_PROVIDER_VARIANT] },
             pid: this.currentTurn?.child?.pid || undefined,
         };
     }
@@ -338,7 +342,7 @@ export class CodexExecSession extends EventEmitter {
     buildPrompt(promptText) {
         return buildHistoryPrompt(this.history, promptText);
     }
-    buildExecArgs({ useInitialImages = false, schemaFilePath = "", lastMessageFilePath = "" } = {}) {
+    buildExecArgs({ media = [], schemaFilePath = "", lastMessageFilePath = "" } = {}) {
         const args = [...this.baseArgs];
         args.push("exec");
         args.push("--json");
@@ -354,11 +358,8 @@ export class CodexExecSession extends EventEmitter {
         if (typeof this.options.model === "string" && this.options.model.trim()) {
             args.push("--model", this.options.model.trim());
         }
-        const images = useInitialImages && Array.isArray(this.options.initialImages)
-            ? this.options.initialImages.filter((item) => typeof item === "string" && item.trim())
-            : [];
-        for (const imagePath of images) {
-            args.push("--image", imagePath);
+        for (const image of media.filter((item) => item.kind === "image")) {
+            args.push("--image", image.path);
         }
         return args;
     }
@@ -376,7 +377,7 @@ export class CodexExecSession extends EventEmitter {
             message: lastMessage || "Codex authentication required",
         });
     }
-    async runTurn(promptText, { useInitialImages = false, onProgress = null, jsonSchema = null } = {}) {
+    async runTurn(promptText, { useInitialImages = false, media: mediaInput, contextFiles, onProgress = null, jsonSchema = null } = {}) {
         if (this.closeRequested || this.closed) {
             throw this.createSessionClosedError();
         }
@@ -385,12 +386,11 @@ export class CodexExecSession extends EventEmitter {
                 reason: "turn_already_running",
             });
         }
+        const media = resolveTurnMedia(this.options, { useInitialImages, media: mediaInput });
+        assertMediaCapabilities(media, this.backend, PROVIDER_MEDIA_CAPABILITIES[CODEX_EXEC_PROVIDER_VARIANT]);
         const effectivePrompt = this.buildPrompt(promptText);
-        const imagePaths = useInitialImages && Array.isArray(this.options.initialImages)
-            ? this.options.initialImages.filter((item) => typeof item === "string" && item.trim())
-            : [];
-        const stdinPrompt = effectivePrompt || (imagePaths.length > 0 ? "Analyze the attached image." : "");
-        if (!stdinPrompt && imagePaths.length === 0) {
+        const stdinPrompt = appendContextFilesToPrompt(effectivePrompt || (media.length > 0 ? defaultPromptForMedia(media) : ""), contextFiles).prompt;
+        if (!stdinPrompt && media.length === 0) {
             return buildEmptyTurnResult();
         }
         const normalizedSchema = normalizeJsonSchema(jsonSchema);
@@ -416,7 +416,7 @@ export class CodexExecSession extends EventEmitter {
                 status_line: statusLineForPhase("turn_started"),
             }, onProgress);
             const args = this.buildExecArgs({
-                useInitialImages,
+                media,
                 schemaFilePath,
                 lastMessageFilePath,
             });

package/dist/providers/copilot-sdk-session.d.ts

@@ -83,6 +83,11 @@ export class CopilotSdkSession extends EventEmitter<[never]> {
             command: string;
         } | null;
         currentTurnStatus: any;
+        capabilities: {
+            media: Readonly<{
+                image: "native";
+            }>;
+        };
     };
     getSessionInfo(): {
         backend: string;
@@ -165,7 +170,7 @@ export class CopilotSdkSession extends EventEmitter<[never]> {
     handleCopilotEventFailure(error: any): void;
     handleCopilotEvent(event: any): Promise<void>;
     interruptCurrentTurn(): Promise<void>;
-    runTurn(promptText: any, { useInitialImages, onProgress }?: {
+    runTurn(promptText: any, { useInitialImages, media: mediaInput, contextFiles, onProgress }?: {
         useInitialImages?: boolean | undefined;
         onProgress?: null | undefined;
     }): Promise<{