@love-moon/ai-sdk 0.8.0 → 0.10.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

@@ -53,6 +53,7 @@ export class CodexAppServerSession extends EventEmitter<[never]> {
     } | null;
     bootPromise: Promise<void> | null;
     booted: boolean;
+    _contextRecoveryInFlight: boolean;
     goalMode: boolean;
     currentGoal: (import("../shared.js").GoalState & {
         raw?: unknown;
@@ -127,6 +128,22 @@ export class CodexAppServerSession extends EventEmitter<[never]> {
     }): void;
     applySessionConfigured(params: any): void;
     resolveContextUsagePercent(): number | undefined;
+    /**
+     * Whether a turn failure was caused by the provider thread outgrowing the
+     * model context window. Such failures are recoverable by rolling onto a fresh
+     * thread; ordinary failures (timeouts, closes, tool errors) are not.
+     *
+     * @param {any} error
+     * @returns {boolean}
+     */
+    isRecoverableContextOverflow(error: any): boolean;
+    /**
+     * Reset thread-bound state so the next {@link boot} starts a brand-new Codex
+     * thread, seeded with the most-recent {@link RECOVERY_HISTORY_LIMIT} history
+     * entries as a prompt preface. The oversized thread is abandoned (never
+     * resumed) so its context can no longer overflow.
+     */
+    rollOntoFreshThread(): void;
     normalizeWorkingStatusPayload(payload: any): {
         source: string;
         reply_in_progress: boolean;
@@ -223,29 +240,10 @@ 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<{
-        text: string;
-        usage: null;
-        items: never[];
-        events: never[];
-        provider?: undefined;
-        metadata?: undefined;
-    } | {
-        text: string;
-        usage: any;
-        items: any;
-        events: never[];
-        provider: string;
-        metadata: {
-            source: string;
-            threadId: any;
-            threadPath: string | undefined;
-            nativeSessionId: string | undefined;
-        };
-    }>;
+    }): any;
     /**
      * Normalize a goal payload from a codex `thread/goal/*` notification into
      * the cross-layer {@link GoalState} shape.

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);
@@ -9,6 +12,15 @@ function isTerminalGoalStatusLocal(status) {
 const DEFAULT_TURN_DEADLINE_MS = 12 * 60 * 1000;
 const MIN_TURN_DEADLINE_MS = 30 * 1000;
 const MAX_TURN_DEADLINE_MS = 30 * 60 * 1000;
+// Oversized-thread recovery: when a Codex turn fails because the provider
+// thread outgrew the model context window (and remote compaction could not
+// recover it), roll the same logical chat onto a fresh thread seeded with this
+// many most-recent history entries and retry the prompt once.
+const RECOVERY_HISTORY_LIMIT = 12;
+// Matches the various ways Codex / the underlying model report a context-window
+// overflow. Kept broad but anchored on "context"/"token" wording so ordinary
+// failures are not misclassified as recoverable.
+const CONTEXT_OVERFLOW_PATTERN = /context[ _-]?(?:length|window|limit)|context[ _-]?length[ _-]?exceeded|maximum[ _-]?context|exceed(?:s|ed)?[^.]{0,40}context|too many tokens|token[ _-]?limit|input[^.]{0,20}too long|prompt[^.]{0,20}too long/i;
 function waitForever() {
     return new Promise(() => { });
 }
@@ -35,14 +47,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 +183,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}
      */
@@ -219,6 +226,7 @@ export class CodexAppServerSession extends EventEmitter {
         this.currentTurn = null;
         this.bootPromise = null;
         this.booted = false;
+        this._contextRecoveryInFlight = false;
         this.goalMode = options.goalMode === true;
         this.currentGoal = null;
         // Goal-mode lifecycle is decoupled from `currentTurn` so that goal events
@@ -467,6 +475,61 @@ export class CodexAppServerSession extends EventEmitter {
         }
         return Math.max(0, Math.min(100, Math.round((totalTokens / contextWindow) * 100)));
     }
+    /**
+     * Whether a turn failure was caused by the provider thread outgrowing the
+     * model context window. Such failures are recoverable by rolling onto a fresh
+     * thread; ordinary failures (timeouts, closes, tool errors) are not.
+     *
+     * @param {any} error
+     * @returns {boolean}
+     */
+    isRecoverableContextOverflow(error) {
+        if (!error || error.reason === "session_closed" || error.reason === "turn_timeout") {
+            return false;
+        }
+        const parts = [];
+        if (typeof error.message === "string")
+            parts.push(error.message);
+        if (typeof error.turnStatus === "string")
+            parts.push(error.turnStatus);
+        const turnError = error.turnError;
+        if (typeof turnError === "string") {
+            parts.push(turnError);
+        }
+        else if (turnError && typeof turnError === "object") {
+            for (const key of ["message", "code", "type", "reason"]) {
+                if (typeof turnError[key] === "string")
+                    parts.push(turnError[key]);
+            }
+            try {
+                parts.push(JSON.stringify(turnError));
+            }
+            catch {
+                // Ignore non-serializable provider payloads.
+            }
+        }
+        return CONTEXT_OVERFLOW_PATTERN.test(parts.join(" | "));
+    }
+    /**
+     * Reset thread-bound state so the next {@link boot} starts a brand-new Codex
+     * thread, seeded with the most-recent {@link RECOVERY_HISTORY_LIMIT} history
+     * entries as a prompt preface. The oversized thread is abandoned (never
+     * resumed) so its context can no longer overflow.
+     */
+    rollOntoFreshThread() {
+        const recent = this.history.slice(-RECOVERY_HISTORY_LIMIT);
+        this.history = recent;
+        this.pendingHistorySeed = recent.length > 0;
+        this.sessionId = "";
+        this.threadPath = "";
+        this.nativeSessionId = "";
+        this.resumeSessionId = "";
+        this.manualResumeReady = false;
+        this.sessionInfo = null;
+        this.tokenUsage = null;
+        this.booted = false;
+        this.bootPromise = null;
+    }
     normalizeWorkingStatusPayload(payload) {
         return {
             source: CODEX_APP_SERVER_VARIANT,
@@ -1029,11 +1092,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);
         }
@@ -1081,7 +1148,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 () => {
@@ -1123,6 +1190,51 @@ export class CodexAppServerSession extends EventEmitter {
             if (error?.reason === "turn_timeout") {
                 await this.interruptCurrentTurn();
             }
+            // Oversized-thread recovery: the provider thread outgrew the context
+            // window and remote compaction could not save it. Roll the same logical
+            // chat onto a fresh thread seeded with bounded recent history and retry
+            // the prompt exactly once, rather than surfacing a dead turn. The
+            // in-flight guard ensures a single retry: if the fresh thread also
+            // overflows, the recursive call skips recovery and fails normally.
+            if (!this._contextRecoveryInFlight &&
+                !this.closeRequested &&
+                !currentTurn.goalMode &&
+                this.isRecoverableContextOverflow(error)) {
+                // Drop the user message pushed for the failed attempt; the retry
+                // re-adds it (and folds prior history in as a preface via buildPrompt).
+                if (this.history.length > 0 &&
+                    String(this.history[this.history.length - 1]?.role || "").toLowerCase() === "user") {
+                    this.history.pop();
+                }
+                if (this.currentTurn === currentTurn) {
+                    this.currentTurn = null;
+                }
+                this._contextRecoveryInFlight = true;
+                // Release the outer turn's guards before recursing so their timers do
+                // not linger for the duration of the retry. Both cleanups are
+                // idempotent; the outer `finally` calls them again harmlessly.
+                closeGuard.cleanup();
+                turnTimeoutGuard.cleanup();
+                try {
+                    this.rollOntoFreshThread();
+                    this.trace("context overflow; rolling onto a fresh thread and retrying the turn");
+                    await this.emitWorkingStatus({
+                        phase: "working",
+                        reply_in_progress: true,
+                        status_line: "codex context full; retrying on a fresh thread",
+                    });
+                    this.emit("thread_recovered", { reason: "context_overflow", backend: this.backend });
+                    return await this.runTurn(promptText, {
+                        useInitialImages,
+                        media: mediaInput,
+                        contextFiles,
+                        jsonSchema,
+                    });
+                }
+                finally {
+                    this._contextRecoveryInFlight = false;
+                }
+            }
             if (!this.closeRequested && error?.reason !== "session_closed") {
                 await this.emitWorkingStatus({
                     phase: "turn_failed",

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;