@borgee/agents-host 0.2.35 → 0.2.44

package/dist/providers/claude/cli-client.d.ts

@@ -1,7 +1,7 @@
 import spawn from 'cross-spawn';
 import { PROTOCOL_VERSION, client, methods, ndJsonStream } from '@agentclientprotocol/sdk';
 import { type DebugLogger } from '../../debug.js';
-import type { PreparedProviderTurnInput, ProviderGenerateOptions } from '../../types.js';
+import type { PreparedPromptContext, PreparedProviderTurnInput, ProviderGenerateOptions } from '../../types.js';
 import type { ClaudeChannelSessionStore } from './session-store.js';
 interface ClaudeAcpRuntime {
     spawn: typeof spawn;
@@ -9,12 +9,18 @@ interface ClaudeAcpRuntime {
     ndJsonStream: typeof ndJsonStream;
     methods: typeof methods;
     protocolVersion: typeof PROTOCOL_VERSION;
+    fetch: typeof fetch;
     cwd: string;
     idleBackendShutdownMs: number;
     idleShutdownGracePeriodMs: number;
     shutdownGracePeriodMs: number;
     shutdownForceKillWaitMs: number;
 }
+interface ClaudeHostedImageInputConfig {
+    borgeeBaseUrl?: string;
+    agentApiKey?: string;
+}
+export declare function buildClaudeSessionSystemPrompt(promptContext?: PreparedPromptContext): string | undefined;
 /**
  * Persistent ACP-backed client for the Claude ACP adapter.
  *
@@ -29,6 +35,7 @@ export declare class ClaudeCliClient {
     private readonly sessionStore?;
     private readonly resolveSessionStoreAgentId;
     private readonly logger;
+    private readonly imageInputConfig;
     private readonly runtime;
     private readonly channels;
     /**
@@ -65,7 +72,7 @@ export declare class ClaudeCliClient {
     private sessionCapabilities;
     private readonly idleBackendShutdown;
     private childStderr;
-    constructor(command: string, args?: string[], runtimeOverrides?: Partial<ClaudeAcpRuntime>, sessionStore?: ClaudeChannelSessionStore | undefined, resolveSessionStoreAgentId?: () => string | undefined, logger?: DebugLogger);
+    constructor(command: string, args?: string[], runtimeOverrides?: Partial<ClaudeAcpRuntime>, sessionStore?: ClaudeChannelSessionStore | undefined, resolveSessionStoreAgentId?: () => string | undefined, logger?: DebugLogger, imageInputConfig?: ClaudeHostedImageInputConfig);
     generateReply(turn: PreparedProviderTurnInput, options?: ProviderGenerateOptions): Promise<string>;
     generateReply(channelId: string, prompt: string, options?: ProviderGenerateOptions): Promise<string>;
     dispose(): Promise<void>;
@@ -110,5 +117,7 @@ export declare class ClaudeCliClient {
     private waitForPendingSessionStarts;
     private waitForPendingSessionCloses;
     private waitForChildExit;
+    private buildPromptInput;
+    private fetchImageBlock;
 }
 export {};

package/dist/providers/claude/cli-client.js

@@ -6,6 +6,7 @@ import { assertClaudeCommandCompatibility, DEFAULT_CLAUDE_COMMAND, isLegacyClaud
 import { PROTOCOL_VERSION, client, methods, ndJsonStream, } from '@agentclientprotocol/sdk';
 import { HostLogger, summarizeChildStderr, summarizeError } from '../../debug.js';
 import { resolveCopilotPermissionResponse } from '../../policy/copilot-permission.js';
+import { buildSkillManualLines } from '../../context/skill-manual.js';
 import { IDLE_BACKEND_SHUTDOWN_DISABLED_MS, IdleBackendShutdownScheduler, } from '../idle-backend-shutdown.js';
 const SESSION_TAINTED_ERRORS = new WeakSet();
 const IDLE_BACKEND_STOPPED_MESSAGE = 'Claude ACP backend stopped after idle timeout';
@@ -30,6 +31,7 @@ const DEFAULT_RUNTIME = {
     ndJsonStream,
     methods,
     protocolVersion: PROTOCOL_VERSION,
+    fetch,
     cwd: process.cwd(),
     idleBackendShutdownMs: IDLE_BACKEND_SHUTDOWN_DISABLED_MS,
     idleShutdownGracePeriodMs: DEFAULT_IDLE_SHUTDOWN_GRACE_PERIOD_MS,
@@ -42,6 +44,25 @@ function hasVisibleText(value) {
 function normalizeError(error) {
     return error instanceof Error ? error : new Error(String(error));
 }
+function isAbsoluteHttpUrl(value) {
+    return value.startsWith('http://') || value.startsWith('https://');
+}
+function resolveHostedAttachmentUrl(rawUrl, borgeeBaseUrl) {
+    if (isAbsoluteHttpUrl(rawUrl)) {
+        return rawUrl;
+    }
+    const base = borgeeBaseUrl.replace(/\/$/, '');
+    const path = rawUrl.startsWith('/') ? rawUrl : `/${rawUrl}`;
+    return `${base}${path}`;
+}
+function isSameOrigin(left, right) {
+    try {
+        return new URL(left).origin === new URL(right).origin;
+    }
+    catch {
+        return false;
+    }
+}
 function parsePersistedSessionRecord(rawValue) {
     const trimmed = rawValue.trim();
     if (trimmed.startsWith('{')) {
@@ -168,7 +189,7 @@ class ClaudeProgressCollector {
         this.onProgress({ text });
     }
 }
-function createDeferredTurn(channelId, prompt, sessionPersistence, promptContext, options) {
+function createDeferredTurn(channelId, preparedTurn, sessionPersistence, options) {
     let settled = false;
     let resolvePromise;
     let rejectPromise;
@@ -178,9 +199,8 @@ function createDeferredTurn(channelId, prompt, sessionPersistence, promptContext
     });
     return {
         channelId,
-        prompt,
+        preparedTurn,
         sessionPersistence,
-        promptContext,
         options,
         promise,
         resolve(value) {
@@ -204,6 +224,9 @@ function resolveSessionRouting(turn) {
         persistence: turn.providerSessionRouting?.persistence ?? 'persistent',
     };
 }
+function asImagePart(part) {
+    return part.type === 'image' ? part : null;
+}
 function asObject(value) {
     return typeof value === 'object' && value !== null ? value : null;
 }
@@ -267,25 +290,18 @@ function resolveClaudeLaunch(command, args, baseCwd) {
         args: args.map((arg) => (isRelativePathLike(arg) ? resolve(baseCwd, arg) : arg)),
     };
 }
-function buildClaudeSessionSystemPrompt(promptContext) {
+export function buildClaudeSessionSystemPrompt(promptContext) {
     if (!promptContext) {
         return undefined;
     }
     const lines = [];
-    if (promptContext.channelContextPayloadPath) {
-        lines.push('Channel-scoped local context is available for this session.');
-        lines.push(`Channel context payload: ${promptContext.channelContextPayloadPath}`);
-    }
-    if (promptContext.skillRuntime) {
-        lines.push(`Skill guide: ${promptContext.skillRuntime.skillMarkdownPath}`);
-        lines.push(`Node bootstrap CLI: node ${promptContext.skillRuntime.nodeCliPath} --context ${promptContext.channelContextPayloadPath} --print-bootstrap`);
-        lines.push(`Python bootstrap CLI: python3 ${promptContext.skillRuntime.pythonCliPath} --context ${promptContext.channelContextPayloadPath} --print-bootstrap`);
+    // Every command the CLI carries needs the gateway credential file, so the session names it only
+    // when one exists; otherwise the model is handed an invocation template it cannot fill.
+    if (promptContext.skillRuntime && promptContext.gatewayCredentialPath) {
+        lines.push(...buildSkillManualLines(promptContext.skillRuntime));
     }
-    if (promptContext.localhostGateway && promptContext.gatewayAuthPath) {
-        lines.push(`Gateway auth sidecar for this session: ${promptContext.gatewayAuthPath}`);
-        if (promptContext.localhostGateway.baseUrl) {
-            lines.push(`Loopback gateway base URL: ${promptContext.localhostGateway.baseUrl}`);
-        }
+    if (promptContext.localhostGateway && promptContext.gatewayCredentialPath) {
+        lines.push(`Gateway credential file for this session: ${promptContext.gatewayCredentialPath}`);
     }
     if (promptContext.taskWorkspace) {
         lines.push(`Task-scoped writable workspace root: ${promptContext.taskWorkspace.rootPath}.`);
@@ -312,20 +328,32 @@ function resolveSessionAdditionalDirectories(promptContext) {
     if (promptContext?.channelContextPayloadPath) {
         directories.add(dirname(promptContext.channelContextPayloadPath));
     }
-    if (promptContext?.gatewayAuthPath) {
-        directories.add(dirname(promptContext.gatewayAuthPath));
+    if (promptContext?.gatewayCredentialPath) {
+        directories.add(dirname(promptContext.gatewayCredentialPath));
     }
     if (promptContext?.skillRuntime?.skillDirectoryPath) {
         directories.add(promptContext.skillRuntime.skillDirectoryPath);
     }
     return directories.size > 0 ? [...directories].sort((left, right) => left.localeCompare(right)) : undefined;
 }
+/**
+ * A session carries its scope from `session/new`: the directories it may read, plus the append that
+ * names the CLI manual and this channel's gateway credential file. The credential file sits in the
+ * channel context directory the payload already contributes, so its absence is invisible in the
+ * directory set alone — without the path itself in the key, a session opened while the credential
+ * write failed keeps an append that never names the CLI for as long as the session lives.
+ */
 function resolveSessionVisibilityKey(promptContext) {
     const additionalDirectories = resolveSessionAdditionalDirectories(promptContext);
     if (!additionalDirectories) {
         return undefined;
     }
-    return JSON.stringify({ additionalDirectories });
+    return JSON.stringify({
+        additionalDirectories,
+        ...(promptContext?.gatewayCredentialPath
+            ? { gatewayCredentialPath: promptContext.gatewayCredentialPath }
+            : {}),
+    });
 }
 function buildSessionRequest(cwd, promptContext, additionalDirectories) {
     const meta = buildClaudeSessionMeta(promptContext);
@@ -369,6 +397,7 @@ export class ClaudeCliClient {
     sessionStore;
     resolveSessionStoreAgentId;
     logger;
+    imageInputConfig;
     runtime;
     channels = new Map();
     /**
@@ -407,12 +436,13 @@ export class ClaudeCliClient {
     sessionCapabilities = DEFAULT_SESSION_CAPABILITIES;
     idleBackendShutdown;
     childStderr = '';
-    constructor(command, args = [], runtimeOverrides = {}, sessionStore, resolveSessionStoreAgentId = () => undefined, logger = new HostLogger()) {
+    constructor(command, args = [], runtimeOverrides = {}, sessionStore, resolveSessionStoreAgentId = () => undefined, logger = new HostLogger(), imageInputConfig = {}) {
         this.command = command;
         this.args = args;
         this.sessionStore = sessionStore;
         this.resolveSessionStoreAgentId = resolveSessionStoreAgentId;
         this.logger = logger;
+        this.imageInputConfig = imageInputConfig;
         this.runtime = { ...DEFAULT_RUNTIME, ...runtimeOverrides };
         assertClaudeCommandCompatibility(command, args, 'Claude provider runtime');
         this.idleBackendShutdown = new IdleBackendShutdownScheduler({
@@ -434,19 +464,26 @@ export class ClaudeCliClient {
         if (this.fatalError) {
             throw this.fatalError;
         }
-        const preparedTurn = typeof channelIdOrTurn === 'string'
+        const preparedTurnBase = typeof channelIdOrTurn === 'string'
             ? {
                 channelId: channelIdOrTurn,
+                incomingContent: '',
+                incomingParts: [],
                 prompt: typeof promptOrOptions === 'string' ? promptOrOptions : '',
             }
             : channelIdOrTurn;
+        const preparedTurn = {
+            ...preparedTurnBase,
+            incomingContent: preparedTurnBase.incomingContent ?? '',
+            incomingParts: preparedTurnBase.incomingParts ?? [],
+        };
         const options = typeof channelIdOrTurn === 'string'
             ? maybeOptions
             : promptOrOptions;
         const sessionRouting = resolveSessionRouting(preparedTurn);
         const state = this.getOrCreateChannelState(sessionRouting.key, preparedTurn.channelId, sessionRouting.persistence);
         this.idleBackendShutdown.cancel();
-        const turn = createDeferredTurn(preparedTurn.channelId, preparedTurn.prompt, sessionRouting.persistence, preparedTurn.promptContext, options);
+        const turn = createDeferredTurn(preparedTurn.channelId, preparedTurn, sessionRouting.persistence, options);
         state.queue.push(turn);
         this.processChannelQueue(sessionRouting.key, state);
         return turn.promise;
@@ -618,14 +655,15 @@ export class ClaudeCliClient {
                     }
                     state.activeTurn = turn;
                     try {
-                        state.cwd = this.resolveSessionCwd(turn.promptContext);
-                        state.visibilityKey = resolveSessionVisibilityKey(turn.promptContext);
+                        state.cwd = this.resolveSessionCwd(turn.preparedTurn.promptContext);
+                        state.visibilityKey = resolveSessionVisibilityKey(turn.preparedTurn.promptContext);
                         await this.ensureStarted();
                         await this.recycleSessionIfScopeChanged(channelId, state);
-                        const session = await this.getOrCreateSession(channelId, state, turn.promptContext);
+                        const session = await this.getOrCreateSession(channelId, state, turn.preparedTurn.promptContext);
                         let reply;
                         try {
-                            reply = await this.runTurn(session, turn.prompt, turn.options);
+                            const promptInput = await this.buildPromptInput(turn.preparedTurn);
+                            reply = await this.runTurn(session, promptInput, turn.options);
                         }
                         catch (error) {
                             if (isSessionTainted(error)) {
@@ -1199,4 +1237,37 @@ export class ClaudeCliClient {
             }
         }
     }
+    async buildPromptInput(turn) {
+        const imageParts = turn.incomingParts.map(asImagePart).filter((part) => part !== null);
+        if (imageParts.length === 0) {
+            return turn.prompt;
+        }
+        const imageBlocks = await Promise.all(imageParts.map(async (part) => this.fetchImageBlock(part.attachment.url, part.attachment.contentType)));
+        return [
+            { type: 'text', text: turn.prompt },
+            ...imageBlocks,
+        ];
+    }
+    async fetchImageBlock(rawUrl, contentType) {
+        const baseUrl = this.imageInputConfig.borgeeBaseUrl?.trim();
+        const agentApiKey = this.imageInputConfig.agentApiKey?.trim();
+        if (!baseUrl || !agentApiKey) {
+            throw new Error('Claude image input requires Borgee base URL and agent API key');
+        }
+        const resolvedUrl = resolveHostedAttachmentUrl(rawUrl, baseUrl);
+        if (!isSameOrigin(resolvedUrl, baseUrl)) {
+            throw new Error(`Claude image input only supports Borgee-origin attachments: ${resolvedUrl}`);
+        }
+        const init = { headers: { Authorization: `Bearer ${agentApiKey}` } };
+        const response = await this.runtime.fetch(resolvedUrl, init);
+        if (!response.ok) {
+            throw new Error(`Claude image fetch failed with ${response.status} ${response.statusText}`.trim());
+        }
+        const blob = Buffer.from(await response.arrayBuffer()).toString('base64');
+        return {
+            type: 'image',
+            mimeType: contentType,
+            data: blob,
+        };
+    }
 }

package/dist/providers/codex/adapter.d.ts

@@ -1,10 +1,12 @@
-import type { ProviderAdapter } from '../provider-adapter.js';
+import { type ProviderAdapter } from '../provider-adapter.js';
 import type { ProviderGenerateOptions, ProviderInput, ProviderReply } from '../../types.js';
 import { ProviderTurnPreparer } from '../../context/turn-preparation.js';
 import { CodexCliClient } from './cli-client.js';
+export declare const CODEX_HOSTED_PROVIDER_CAPABILITIES: import("../provider-adapter.js").ProviderCapabilities;
 export declare class CodexProviderAdapter implements ProviderAdapter {
     private readonly cli;
     private readonly turnPreparer;
+    readonly capabilities: import("../provider-adapter.js").ProviderCapabilities;
     constructor(cli: CodexCliClient, turnPreparer: ProviderTurnPreparer);
     generateReply(input: ProviderInput, options?: ProviderGenerateOptions): Promise<ProviderReply>;
     dispose(): Promise<void>;

package/dist/providers/codex/adapter.js

@@ -1,7 +1,17 @@
+import { createHostedProviderCapabilities } from '../provider-adapter.js';
 import { createAwaitingUserProgressHandler, parseProviderReply } from '../awaiting-user.js';
+export const CODEX_HOSTED_PROVIDER_CAPABILITIES = createHostedProviderCapabilities({
+    imageInputTransport: {
+        source: 'transport-derived',
+        support: 'supported',
+        reason: 'real-media-delivered',
+        delivery: ['blob'],
+    },
+});
 export class CodexProviderAdapter {
     cli;
     turnPreparer;
+    capabilities = CODEX_HOSTED_PROVIDER_CAPABILITIES;
     constructor(cli, turnPreparer) {
         this.cli = cli;
         this.turnPreparer = turnPreparer;

package/dist/providers/codex/cli-client.d.ts

@@ -28,6 +28,11 @@ interface CodexAcpRuntime {
         mode?: number;
     }): Promise<void>;
     unlink(path: string): Promise<void>;
+    fetch(input: string | URL, init?: RequestInit): Promise<Response>;
+}
+interface CodexHostedImageInputConfig {
+    borgeeBaseUrl?: string;
+    agentApiKey?: string;
 }
 export declare class CodexCliClient {
     private readonly command;
@@ -35,6 +40,7 @@ export declare class CodexCliClient {
     private readonly sessionStore?;
     private readonly resolveSessionStoreAgentId;
     private readonly logger;
+    private readonly imageInputConfig;
     private readonly runtime;
     private readonly channels;
     /**
@@ -70,7 +76,7 @@ export declare class CodexCliClient {
     private sessionStoreWriteQueue;
     private sessionCapabilities;
     private readonly idleBackendShutdown;
-    constructor(command: string, args?: string[], runtimeOverrides?: Partial<CodexAcpRuntime>, sessionStore?: CodexChannelSessionStore | undefined, resolveSessionStoreAgentId?: () => string | undefined, logger?: DebugLogger);
+    constructor(command: string, args?: string[], runtimeOverrides?: Partial<CodexAcpRuntime>, sessionStore?: CodexChannelSessionStore | undefined, resolveSessionStoreAgentId?: () => string | undefined, logger?: DebugLogger, imageInputConfig?: CodexHostedImageInputConfig);
     generateReply(turn: PreparedProviderTurnInput, options?: ProviderGenerateOptions): Promise<string>;
     generateReply(channelId: string, prompt: string, options?: ProviderGenerateOptions): Promise<string>;
     dispose(): Promise<void>;
@@ -90,9 +96,11 @@ export declare class CodexCliClient {
     private resolveProjectedContextDirectory;
     private buildProjectedPromptContext;
     private copyProjectedFile;
-    private pruneProjectedGatewayAuthFiles;
+    private pruneProjectedGatewayCredentials;
     private refreshProjectedPromptContextBestEffort;
     private rewritePromptContextPaths;
+    private buildPromptInput;
+    private fetchImageBlock;
     private runTurn;
     private raceWithFatal;
     private invalidateSession;

package/dist/providers/codex/cli-client.js

@@ -6,6 +6,7 @@ import spawn from 'cross-spawn';
 import { PROTOCOL_VERSION, client, methods, ndJsonStream, } from '@agentclientprotocol/sdk';
 import { HostLogger, summarizeChildStderr, summarizeError } from '../../debug.js';
 import { assertCodexProjectDocumentSize, buildCodexProjectDocument } from './project-doc.js';
+import { isGatewayCredentialSidecarBasename } from '../../context/injection.js';
 import { IDLE_BACKEND_SHUTDOWN_DISABLED_MS, IdleBackendShutdownScheduler, } from '../idle-backend-shutdown.js';
 const SESSION_TAINTED_ERRORS = new WeakSet();
 const DEFAULT_IDLE_SESSION_TTL_MS = 2 * 24 * 60 * 60 * 1000;
@@ -27,8 +28,6 @@ const DEFAULT_SESSION_CAPABILITIES = {
 const DEFAULT_CODEX_COMMAND = 'codex-acp';
 const DEFAULT_CODEX_ARGS = [];
 const CODEX_CONTEXT_ROOT_DIRNAME = 'codex-context';
-const PROJECTED_GATEWAY_AUTH_FILENAME = '.localhost-gateway-auth.json';
-const PROJECTED_GATEWAY_AUTH_PREFIX = '.localhost-gateway-auth.';
 const PROJECTION_UNAVAILABLE_PLACEHOLDER = '[codex-projection-unavailable]';
 const QUEUED_TURN_DROPPED_MESSAGE = 'Codex ACP session was reset after a failed turn; queued turns were dropped instead of replaying them on a fresh session';
 const require = createRequire(import.meta.url);
@@ -59,6 +58,7 @@ const DEFAULT_RUNTIME = {
     unlink: async (path) => {
         await fs.unlink(path);
     },
+    fetch: async (input, init) => fetch(input, init),
 };
 function hasVisibleText(value) {
     return typeof value === 'string' && value.trim().length > 0;
@@ -181,7 +181,7 @@ class CodexProgressCollector {
         this.onProgress({ text });
     }
 }
-function createDeferredTurn(channelId, prompt, promptContext, sessionPersistence, options) {
+function createDeferredTurn(channelId, preparedTurn, sessionPersistence, options) {
     let settled = false;
     let resolvePromise;
     let rejectPromise;
@@ -191,8 +191,7 @@ function createDeferredTurn(channelId, prompt, promptContext, sessionPersistence
     });
     return {
         channelId,
-        prompt,
-        promptContext,
+        preparedTurn,
         sessionPersistence,
         options,
         promise,
@@ -210,6 +209,28 @@ function createDeferredTurn(channelId, prompt, promptContext, sessionPersistence
         },
     };
 }
+function isAbsoluteHttpUrl(value) {
+    return value.startsWith('http://') || value.startsWith('https://');
+}
+function resolveHostedAttachmentUrl(rawUrl, borgeeBaseUrl) {
+    if (isAbsoluteHttpUrl(rawUrl)) {
+        return rawUrl;
+    }
+    const base = borgeeBaseUrl.replace(/\/$/, '');
+    const path = rawUrl.startsWith('/') ? rawUrl : `/${rawUrl}`;
+    return `${base}${path}`;
+}
+function isSameOrigin(left, right) {
+    try {
+        return new URL(left).origin === new URL(right).origin;
+    }
+    catch {
+        return false;
+    }
+}
+function asImagePart(part) {
+    return part.type === 'image' ? part : null;
+}
 function normalizeError(error) {
     return error instanceof Error ? error : new Error(String(error));
 }
@@ -296,6 +317,7 @@ export class CodexCliClient {
     sessionStore;
     resolveSessionStoreAgentId;
     logger;
+    imageInputConfig;
     runtime;
     channels = new Map();
     /**
@@ -333,12 +355,13 @@ export class CodexCliClient {
     sessionStoreWriteQueue = Promise.resolve();
     sessionCapabilities = DEFAULT_SESSION_CAPABILITIES;
     idleBackendShutdown;
-    constructor(command, args = [], runtimeOverrides = {}, sessionStore, resolveSessionStoreAgentId = () => undefined, logger = new HostLogger()) {
+    constructor(command, args = [], runtimeOverrides = {}, sessionStore, resolveSessionStoreAgentId = () => undefined, logger = new HostLogger(), imageInputConfig = {}) {
         this.command = command;
         this.args = args;
         this.sessionStore = sessionStore;
         this.resolveSessionStoreAgentId = resolveSessionStoreAgentId;
         this.logger = logger;
+        this.imageInputConfig = imageInputConfig;
         this.runtime = { ...DEFAULT_RUNTIME, ...runtimeOverrides };
         this.idleBackendShutdown = new IdleBackendShutdownScheduler({
             idleShutdownMs: this.runtime.idleBackendShutdownMs,
@@ -359,12 +382,19 @@ export class CodexCliClient {
         if (this.fatalError) {
             throw this.fatalError;
         }
-        const preparedTurn = typeof channelIdOrTurn === 'string'
+        const preparedTurnBase = typeof channelIdOrTurn === 'string'
             ? {
                 channelId: channelIdOrTurn,
+                incomingContent: '',
+                incomingParts: [],
                 prompt: typeof promptOrOptions === 'string' ? promptOrOptions : '',
             }
             : channelIdOrTurn;
+        const preparedTurn = {
+            ...preparedTurnBase,
+            incomingContent: preparedTurnBase.incomingContent ?? '',
+            incomingParts: preparedTurnBase.incomingParts ?? [],
+        };
         const options = typeof channelIdOrTurn === 'string'
             ? maybeOptions
             : promptOrOptions;
@@ -372,7 +402,7 @@ export class CodexCliClient {
         const state = this.getOrCreateChannelState(sessionRouting.key, preparedTurn.channelId, sessionRouting.persistence);
         this.clearIdleTimer(state);
         this.idleBackendShutdown.cancel();
-        const turn = createDeferredTurn(preparedTurn.channelId, preparedTurn.prompt, preparedTurn.promptContext, sessionRouting.persistence, options);
+        const turn = createDeferredTurn(preparedTurn.channelId, preparedTurn, sessionRouting.persistence, options);
         state.queue.push(turn);
         this.processChannelQueue(sessionRouting.key, state);
         return turn.promise;
@@ -536,8 +566,8 @@ export class CodexCliClient {
                     }
                     state.activeTurn = turn;
                     try {
-                        state.cwd = await this.resolveSessionCwd(turn.promptContext);
-                        const projectedPromptContext = await this.refreshProjectedPromptContextBestEffort(turn.channelId, turn.promptContext);
+                        state.cwd = await this.resolveSessionCwd(turn.preparedTurn.promptContext);
+                        const projectedPromptContext = await this.refreshProjectedPromptContextBestEffort(turn.channelId, turn.preparedTurn.promptContext);
                         state.additionalDirectories = this.resolveSessionAdditionalDirectories(projectedPromptContext);
                         state.visibilityKey = this.resolveSessionVisibilityKey(projectedPromptContext);
                         await this.ensureStarted();
@@ -545,7 +575,8 @@ export class CodexCliClient {
                         const session = await this.getOrCreateSession(channelId, state);
                         let reply;
                         try {
-                            reply = await this.runTurn(session, this.rewritePromptContextPaths(turn.prompt, turn.promptContext, projectedPromptContext?.promptContext), turn.options);
+                            const promptInput = await this.buildPromptInput(turn.preparedTurn, projectedPromptContext?.promptContext);
+                            reply = await this.runTurn(session, promptInput, turn.options);
                         }
                         catch (error) {
                             if (isSessionTainted(error)) {
@@ -740,7 +771,7 @@ export class CodexCliClient {
         return JSON.stringify({
             directoryPath: projectedPromptContext.directoryPath,
             channelContextPayloadPath: projectedPromptContext.promptContext.channelContextPayloadPath,
-            gatewayAuthPath: projectedPromptContext.promptContext.gatewayAuthPath ?? null,
+            gatewayCredentialPath: projectedPromptContext.promptContext.gatewayCredentialPath ?? null,
         });
     }
     resolveProjectedContextDirectory(payloadPath) {
@@ -755,8 +786,8 @@ export class CodexCliClient {
         return {
             ...promptContext,
             channelContextPayloadPath: join(projectedDirectoryPath, basename(payloadPath)),
-            gatewayAuthPath: promptContext.gatewayAuthPath
-                ? join(projectedDirectoryPath, basename(promptContext.gatewayAuthPath))
+            gatewayCredentialPath: promptContext.gatewayCredentialPath
+                ? join(projectedDirectoryPath, basename(promptContext.gatewayCredentialPath))
                 : undefined,
         };
     }
@@ -767,12 +798,11 @@ export class CodexCliClient {
             mode: 0o600,
         });
     }
-    async pruneProjectedGatewayAuthFiles(directoryPath, keepPath) {
+    async pruneProjectedGatewayCredentials(directoryPath, keepPath) {
         const keepFilename = keepPath ? basename(keepPath) : null;
         const entries = await this.runtime.readdir(directoryPath);
         await Promise.all(entries
-            .filter((entry) => entry === PROJECTED_GATEWAY_AUTH_FILENAME
-            || (entry.startsWith(PROJECTED_GATEWAY_AUTH_PREFIX) && entry.endsWith('.json')))
+            .filter((entry) => isGatewayCredentialSidecarBasename(entry))
             .filter((entry) => entry !== keepFilename)
             .map(async (entry) => {
             await this.runtime.unlink(join(directoryPath, entry)).catch((error) => {
@@ -795,10 +825,10 @@ export class CodexCliClient {
         }
         try {
             await this.runtime.mkdir(projectedDirectoryPath, { recursive: true, mode: 0o700 });
-            await this.pruneProjectedGatewayAuthFiles(projectedDirectoryPath, projectedPromptContext.gatewayAuthPath);
+            await this.pruneProjectedGatewayCredentials(projectedDirectoryPath, projectedPromptContext.gatewayCredentialPath);
             await this.copyProjectedFile(payloadPath, projectedPromptContext.channelContextPayloadPath);
-            if (resolvedPromptContext.gatewayAuthPath && projectedPromptContext.gatewayAuthPath) {
-                await this.copyProjectedFile(resolvedPromptContext.gatewayAuthPath, projectedPromptContext.gatewayAuthPath);
+            if (resolvedPromptContext.gatewayCredentialPath && projectedPromptContext.gatewayCredentialPath) {
+                await this.copyProjectedFile(resolvedPromptContext.gatewayCredentialPath, projectedPromptContext.gatewayCredentialPath);
             }
             const content = buildCodexProjectDocument(projectedPromptContext);
             assertCodexProjectDocumentSize(content);
@@ -827,7 +857,7 @@ export class CodexCliClient {
         let rewritten = prompt;
         const replacements = [
             [sourceContext.channelContextPayloadPath, targetContext?.channelContextPayloadPath],
-            [sourceContext.gatewayAuthPath, targetContext?.gatewayAuthPath],
+            [sourceContext.gatewayCredentialPath, targetContext?.gatewayCredentialPath],
         ];
         for (const [sourcePath, targetPath] of replacements) {
             if (!sourcePath || sourcePath === targetPath) {
@@ -837,6 +867,40 @@ export class CodexCliClient {
         }
         return rewritten;
     }
+    async buildPromptInput(turn, projectedPromptContext) {
+        const prompt = this.rewritePromptContextPaths(turn.prompt, turn.promptContext, projectedPromptContext);
+        const imageParts = turn.incomingParts.map(asImagePart).filter((part) => part !== null);
+        if (imageParts.length === 0) {
+            return prompt;
+        }
+        const imageBlocks = await Promise.all(imageParts.map(async (part) => this.fetchImageBlock(part.attachment.url, part.attachment.contentType)));
+        return [
+            { type: 'text', text: prompt },
+            ...imageBlocks,
+        ];
+    }
+    async fetchImageBlock(rawUrl, contentType) {
+        const baseUrl = this.imageInputConfig.borgeeBaseUrl?.trim();
+        const agentApiKey = this.imageInputConfig.agentApiKey?.trim();
+        if (!baseUrl || !agentApiKey) {
+            throw new Error('Codex image input requires Borgee base URL and agent API key');
+        }
+        const resolvedUrl = resolveHostedAttachmentUrl(rawUrl, baseUrl);
+        if (!isSameOrigin(resolvedUrl, baseUrl)) {
+            throw new Error(`Codex image input only supports Borgee-origin attachments: ${resolvedUrl}`);
+        }
+        const init = { headers: { Authorization: `Bearer ${agentApiKey}` } };
+        const response = await this.runtime.fetch(resolvedUrl, init);
+        if (!response.ok) {
+            throw new Error(`Codex image fetch failed with ${response.status} ${response.statusText}`.trim());
+        }
+        const blob = Buffer.from(await response.arrayBuffer()).toString('base64');
+        return {
+            type: 'image',
+            mimeType: contentType,
+            data: blob,
+        };
+    }
     async runTurn(session, prompt, options) {
         const promptPromise = this.raceWithFatal(session.prompt(prompt));
         const promptFailure = new Promise((_, reject) => {