@borgee/agents-host 0.2.33 → 0.2.44

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

@@ -6,8 +6,19 @@ 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;
+const IDLE_BACKEND_STOPPED_MESSAGE = 'Codex ACP backend stopped after idle timeout';
+/**
+ * A fatal teardown has callers waiting on it, so it force-kills quickly. An
+ * idle recycle has nobody waiting, and the CLIs unlink their on-disk session
+ * locks during SIGTERM cleanup — a lock left behind by SIGKILL makes the next
+ * restore believe the session is still in use (github/copilot-cli#3255). So the
+ * idle path trades latency nobody observes for a clean exit.
+ */
+const DEFAULT_IDLE_SHUTDOWN_GRACE_PERIOD_MS = 5_000;
 const DEFAULT_SHUTDOWN_GRACE_PERIOD_MS = 250;
 const DEFAULT_SHUTDOWN_FORCE_KILL_WAIT_MS = 250;
 const DEFAULT_SESSION_CAPABILITIES = {
@@ -17,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);
@@ -30,6 +39,8 @@ const DEFAULT_RUNTIME = {
     protocolVersion: PROTOCOL_VERSION,
     cwd: process.cwd(),
     idleSessionTtlMs: DEFAULT_IDLE_SESSION_TTL_MS,
+    idleBackendShutdownMs: IDLE_BACKEND_SHUTDOWN_DISABLED_MS,
+    idleShutdownGracePeriodMs: DEFAULT_IDLE_SHUTDOWN_GRACE_PERIOD_MS,
     shutdownGracePeriodMs: DEFAULT_SHUTDOWN_GRACE_PERIOD_MS,
     shutdownForceKillWaitMs: DEFAULT_SHUTDOWN_FORCE_KILL_WAIT_MS,
     readFile: async (path, options) => {
@@ -47,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;
@@ -169,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;
@@ -179,8 +191,7 @@ function createDeferredTurn(channelId, prompt, promptContext, sessionPersistence
     });
     return {
         channelId,
-        prompt,
-        promptContext,
+        preparedTurn,
         sessionPersistence,
         options,
         promise,
@@ -198,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));
 }
@@ -284,8 +317,17 @@ export class CodexCliClient {
     sessionStore;
     resolveSessionStoreAgentId;
     logger;
+    imageInputConfig;
     runtime;
     channels = new Map();
+    /**
+     * The provider session currently bound to channelId, or undefined before a
+     * turn has opened one. Surfaced so agents-host can record which session
+     * worked a task without the agent being asked to report its own id.
+     */
+    sessionIdForChannel(channelId) {
+        return this.channels.get(channelId)?.session?.sessionId;
+    }
     persistedSessions = new Map();
     closingSessions = new WeakSet();
     pendingSessionStarts = new Set();
@@ -298,7 +340,13 @@ export class CodexCliClient {
     startPromise;
     shutdownPromise;
     childExitPromise;
-    resolveChildExit;
+    /**
+     * Bumped on every spawn so the `exit` / `connection.closed` handlers of a
+     * backend we deliberately recycled stay silent instead of latching a fatal
+     * error onto the client that already owns its successor.
+     */
+    backendGeneration = 0;
+    idleShutdownPromise;
     fatalError = null;
     disposing = false;
     backendClosed = false;
@@ -306,13 +354,25 @@ export class CodexCliClient {
     sessionStoreLoadPromise = null;
     sessionStoreWriteQueue = Promise.resolve();
     sessionCapabilities = DEFAULT_SESSION_CAPABILITIES;
-    constructor(command, args = [], runtimeOverrides = {}, sessionStore, resolveSessionStoreAgentId = () => undefined, logger = new HostLogger()) {
+    idleBackendShutdown;
+    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,
+            isIdle: () => this.isBackendIdle(),
+            shutdown: () => this.shutdownIdleBackend(),
+            onShutdownFailed: (error) => {
+                this.logger.error('failed to stop the idle Codex ACP backend', {
+                    error: summarizeError(error),
+                });
+            },
+        });
         this.fatalPromise = new Promise((_, reject) => {
             this.rejectFatalPromise = reject;
         });
@@ -322,19 +382,27 @@ 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;
         const sessionRouting = resolveSessionRouting(preparedTurn);
         const state = this.getOrCreateChannelState(sessionRouting.key, preparedTurn.channelId, sessionRouting.persistence);
         this.clearIdleTimer(state);
-        const turn = createDeferredTurn(preparedTurn.channelId, preparedTurn.prompt, preparedTurn.promptContext, sessionRouting.persistence, options);
+        this.idleBackendShutdown.cancel();
+        const turn = createDeferredTurn(preparedTurn.channelId, preparedTurn, sessionRouting.persistence, options);
         state.queue.push(turn);
         this.processChannelQueue(sessionRouting.key, state);
         return turn.promise;
@@ -342,12 +410,17 @@ export class CodexCliClient {
     async dispose() {
         const error = new Error('Codex ACP backend stopped');
         this.disposing = true;
+        this.idleBackendShutdown.cancel();
         this.logger?.debug('stopping Codex ACP backend');
         const closed = this.connection?.closed ?? Promise.resolve();
         this.failAll(error);
         let thrown;
         try {
-            await Promise.all([closed, this.shutdownPromise ?? Promise.resolve()]);
+            await Promise.all([
+                closed,
+                this.idleShutdownPromise ?? Promise.resolve(),
+                this.shutdownPromise ?? Promise.resolve(),
+            ]);
         }
         catch (disposeError) {
             thrown = disposeError;
@@ -368,6 +441,12 @@ export class CodexCliClient {
         if (this.fatalError) {
             throw this.fatalError;
         }
+        if (this.idleShutdownPromise) {
+            await this.idleShutdownPromise;
+            if (this.fatalError) {
+                throw this.fatalError;
+            }
+        }
         if (!this.startPromise) {
             this.startPromise = this.startBackend();
         }
@@ -380,6 +459,8 @@ export class CodexCliClient {
         }
     }
     async startBackend() {
+        const generation = ++this.backendGeneration;
+        const ownsCurrentBackend = () => (this.backendGeneration === generation && !this.disposing);
         const launch = resolveAdapterLaunch(this.command, this.args);
         this.logger?.debug('starting Codex ACP process', {
             command: launch.command,
@@ -396,13 +477,20 @@ export class CodexCliClient {
         });
         child.stderr.resume();
         this.logger?.debug('spawned Codex ACP process', { pid: child.pid });
+        let resolveChildExit;
+        this.childExitPromise = new Promise((resolve) => {
+            resolveChildExit = resolve;
+        });
         child.once('error', (error) => {
             this.logger?.debugError('Codex ACP process error', error);
+            if (!ownsCurrentBackend()) {
+                return;
+            }
             this.failAll(new Error(`Codex ACP process error: ${normalizeError(error).message}`));
         });
         child.once('exit', (code, signal) => {
-            this.resolveChildExit?.();
-            if (this.disposing) {
+            resolveChildExit();
+            if (!ownsCurrentBackend()) {
                 this.logger?.debug('Codex ACP process exited during shutdown', { code, signal });
                 return;
             }
@@ -410,9 +498,6 @@ export class CodexCliClient {
             const suffix = signal ? `signal ${signal}` : `code ${String(code ?? 'unknown')}`;
             this.failAll(new Error(`Codex ACP process exited unexpectedly (${suffix})`));
         });
-        this.childExitPromise = new Promise((resolveChildExit) => {
-            this.resolveChildExit = resolveChildExit;
-        });
         const output = Writable.toWeb(child.stdin);
         const input = Readable.toWeb(child.stdout);
         const stream = this.runtime.ndJsonStream(output, input);
@@ -422,7 +507,7 @@ export class CodexCliClient {
         const connection = app.connect(stream);
         this.connection = connection;
         void connection.closed.then(() => {
-            if (!this.disposing) {
+            if (ownsCurrentBackend()) {
                 this.logger?.debugError('Codex ACP connection closed unexpectedly');
                 this.failAll(new Error('Codex ACP connection closed unexpectedly'));
             }
@@ -481,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();
@@ -490,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)) {
@@ -512,6 +598,7 @@ export class CodexCliClient {
             finally {
                 state.processing = false;
                 this.reconcileIdleChannelState(channelId, state);
+                this.idleBackendShutdown.reconcile();
             }
         })();
     }
@@ -684,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) {
@@ -699,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,
         };
     }
@@ -711,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) => {
@@ -739,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);
@@ -771,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) {
@@ -781,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) => {
@@ -856,6 +976,7 @@ export class CodexCliClient {
         }
         this.fatalError = error;
         this.rejectFatalPromise(error);
+        this.idleBackendShutdown.cancel();
         for (const [channelId, state] of this.channels.entries()) {
             this.clearIdleTimer(state);
             state.activeTurn?.reject(error);
@@ -1073,6 +1194,66 @@ export class CodexCliClient {
             return;
         }
         this.backendClosed = true;
+        await this.closeBackendProcess(error, this.runtime.shutdownGracePeriodMs);
+    }
+    /**
+     * Backend teardown without the fatal latch: the client stays usable and
+     * `ensureStarted()` spawns a replacement process on the next turn. Only safe
+     * while `isBackendIdle()` holds, because every channel's live ACP session is
+     * dropped here and no turn is ever replayed onto its successor.
+     */
+    async shutdownIdleBackend() {
+        // Detach the running backend before any signal reaches it, so its own exit
+        // and connection-closed handlers read this teardown as deliberate instead
+        // of latching a fatal error on a client that stays usable.
+        this.backendGeneration += 1;
+        const error = new Error(IDLE_BACKEND_STOPPED_MESSAGE);
+        const sessions = [];
+        for (const [channelId, state] of [...this.channels.entries()]) {
+            this.clearIdleTimer(state);
+            if (state.session) {
+                sessions.push(state.session);
+            }
+            state.session = undefined;
+            state.sessionCwd = undefined;
+            state.sessionAdditionalDirectories = undefined;
+            state.sessionVisibilityKey = undefined;
+            this.channels.delete(channelId);
+        }
+        this.logger?.debug('stopping idle Codex ACP backend', {
+            channels: sessions.length,
+            idleShutdownMs: this.runtime.idleBackendShutdownMs,
+        });
+        for (const session of sessions) {
+            this.closeSession(session);
+        }
+        const idleShutdownPromise = this.closeBackendProcess(error, this.runtime.idleShutdownGracePeriodMs).finally(() => {
+            this.startPromise = undefined;
+            this.childExitPromise = undefined;
+            this.sessionCapabilities = DEFAULT_SESSION_CAPABILITIES;
+            this.idleShutdownPromise = undefined;
+        });
+        this.idleShutdownPromise = idleShutdownPromise;
+        await idleShutdownPromise;
+    }
+    isBackendIdle() {
+        if (this.disposing || this.fatalError || this.backendClosed || this.idleShutdownPromise) {
+            return false;
+        }
+        if (!this.child) {
+            return false;
+        }
+        if (this.pendingSessionStarts.size > 0) {
+            return false;
+        }
+        for (const state of this.channels.values()) {
+            if (state.activeTurn || state.queue.length > 0 || state.sessionPromise || state.processing) {
+                return false;
+            }
+        }
+        return true;
+    }
+    async closeBackendProcess(error, gracePeriodMs) {
         const connection = this.connection;
         const child = this.child;
         await this.waitForPendingSessionStarts();
@@ -1084,9 +1265,9 @@ export class CodexCliClient {
             return;
         }
         const childExitPromise = this.childExitPromise ?? Promise.resolve();
-        this.logger?.debug('sending SIGTERM to Codex ACP process');
+        this.logger?.debug('sending SIGTERM to Codex ACP process', { gracePeriodMs });
         child.kill('SIGTERM');
-        const exitedAfterTerm = await this.waitForChildExit(childExitPromise, this.runtime.shutdownGracePeriodMs);
+        const exitedAfterTerm = await this.waitForChildExit(childExitPromise, gracePeriodMs);
         if (exitedAfterTerm) {
             this.logger?.debug('Codex ACP process exited after SIGTERM');
             this.child = undefined;

package/dist/providers/codex/project-doc.js

@@ -1,35 +1,27 @@
-import { basename } from 'node:path';
 import { buildAttentionSummaryLines } from '../../context/attention.js';
 import { buildCollaborationCapabilityDeclarationSummaryLines, buildMissedCollaborationDiagnosticSummaryLines, } from '../../context/collaboration-capabilities-diagnostics.js';
 import { buildCollaborationOutcomeSummaryLines } from '../../context/collaboration-outcome.js';
+import { MAIN_SESSION_DELEGATION_LINES } from '../../context/main-session-delegation.js';
+import { buildSkillManualLines } from '../../context/skill-manual.js';
 import { buildTaskThreadCollaborationSummaryLines } from '../../context/task-thread-collaboration.js';
 const PROJECT_DOC_MAX_BYTES = 32 * 1024;
+// Every command the CLI carries needs the gateway credential file, so the capability is only
+// worth naming in a workspace that also names one; otherwise the model is handed an invocation
+// template it cannot fill.
 function buildSkillRuntimeLines(context) {
-    if (!context?.skillRuntime || !context.channelContextPayloadPath) {
+    if (!context?.skillRuntime || !context.gatewayCredentialPath) {
         return [];
     }
-    return [
-        'Read-only local skill runtime bootstrap is available in this workspace.',
-        `Context payload: ${context.channelContextPayloadPath}`,
-        `Skill guide: ${context.skillRuntime.skillMarkdownPath}`,
-        `Node CLI: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --print-bootstrap`,
-        `Python CLI: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --print-bootstrap`,
-        'These CLIs are local-only, may only access the loopback gateway surfaced by the host, and must not mutate files or the local environment.',
-    ];
+    return buildSkillManualLines(context.skillRuntime);
 }
-function buildGatewayLines(context) {
-    if (!context?.localhostGateway || !context.channelContextPayloadPath) {
+// The credential file is the whole handoff: it carries the gateway's base URL along with the
+// channel id and the token, and the CLI reads all three out of it. Naming the base URL separately
+// would only invite a hand-rolled request that carries the token off the CLI's one path.
+function buildGatewayCredentialLines(context) {
+    if (!context?.localhostGateway || !context.gatewayCredentialPath) {
         return [];
     }
-    const lines = [
-        'A loopback-only localhost gateway may be available for this channel.',
-        `Gateway base URL: ${context.localhostGateway.baseUrl}`,
-        'Use the packaged local CLI with the context payload above for gateway access.',
-    ];
-    if (context.gatewayAuthPath) {
-        lines.push(`Per-turn gateway auth sidecar: ${context.gatewayAuthPath}`, 'If a later turn prompt advertises a different auth sidecar path, prefer the prompt-visible path for that turn.');
-    }
-    return lines;
+    return [`Gateway credential file: ${context.gatewayCredentialPath}`];
 }
 export function buildCodexProjectDocument(context) {
     const lines = [
@@ -37,13 +29,8 @@ export function buildCodexProjectDocument(context) {
         '',
         'This workspace belongs to one Borgee channel session hosted by agents-host.',
         'Keep visible replies concise, do not claim actions you did not perform, and prefer the per-turn prompt when it provides newer turn-local details.',
-        ...(context?.channelContextPayloadPath
-            ? [
-                '',
-                `Context payload file: ${context.channelContextPayloadPath}`,
-                `Workspace anchor: ${basename(context.channelContextPayloadPath)}`,
-            ]
-            : []),
+        '',
+        ...MAIN_SESSION_DELEGATION_LINES,
         ...(context?.taskWorkspace
             ? [
                 '',
@@ -76,7 +63,7 @@ export function buildCodexProjectDocument(context) {
             return skillRuntimeLines.length > 0 ? ['', ...skillRuntimeLines] : [];
         })(),
         ...(() => {
-            const gatewayLines = buildGatewayLines(context);
+            const gatewayLines = buildGatewayCredentialLines(context);
             return gatewayLines.length > 0 ? ['', ...gatewayLines] : [];
         })(),
     ];

package/dist/providers/copilot/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 { CopilotCliClient } from './cli-client.js';
+export declare const COPILOT_HOSTED_PROVIDER_CAPABILITIES: import("../provider-adapter.js").ProviderCapabilities;
 export declare class CopilotProviderAdapter implements ProviderAdapter {
     private readonly cli;
     private readonly turnPreparer;
+    readonly capabilities: import("../provider-adapter.js").ProviderCapabilities;
     constructor(cli: CopilotCliClient, turnPreparer: ProviderTurnPreparer);
     generateReply(input: ProviderInput, options?: ProviderGenerateOptions): Promise<ProviderReply>;
     dispose(): Promise<void>;

package/dist/providers/copilot/adapter.js

@@ -1,7 +1,17 @@
+import { createHostedProviderCapabilities } from '../provider-adapter.js';
 import { createAwaitingUserProgressHandler, parseProviderReply } from '../awaiting-user.js';
+export const COPILOT_HOSTED_PROVIDER_CAPABILITIES = createHostedProviderCapabilities({
+    imageInputTransport: {
+        source: 'transport-derived',
+        support: 'supported',
+        reason: 'real-media-delivered',
+        delivery: ['blob'],
+    },
+});
 export class CopilotProviderAdapter {
     cli;
     turnPreparer;
+    capabilities = COPILOT_HOSTED_PROVIDER_CAPABILITIES;
     constructor(cli, turnPreparer) {
         this.cli = cli;
         this.turnPreparer = turnPreparer;
@@ -11,7 +21,9 @@ export class CopilotProviderAdapter {
         const text = await this.cli.generateReply(preparedTurn, {
             onProgress: createAwaitingUserProgressHandler(options?.onProgress),
         });
-        return parseProviderReply(text);
+        // Read the session AFTER the turn: a first turn on a channel opens the
+        // session as it runs, so before this point there is nothing to report.
+        return { ...parseProviderReply(text), sessionId: this.cli.sessionIdForChannel(input.channelId) };
     }
     async dispose() {
         await this.cli.dispose();