@borgee/agents-host 0.2.35 → 0.2.44

package/dist/agents-host.d.ts

@@ -93,9 +93,11 @@ export declare class AgentsHost {
     private armProtocolFallback;
     private runProtocolFallback;
     private handleProtocolFallbackFailure;
+    private ensureProtocolAnchorIncomingParts;
     private finishProtocolState;
     private cancelProtocolState;
     private confirmProtocolMessage;
+    private findChannelHistoryMessageById;
     private resolveAttentionStatePath;
     private buildDefaultAttentionSnapshot;
     /**

package/dist/agents-host.js

@@ -14,6 +14,7 @@ import { createProvider } from './providers/create-provider.js';
 import { resolveAttentionStatePath, resolveSharedProtocolKickoffDecisionPath, resolveSharedProtocolStatusPath, } from './state-paths.js';
 import { appendVisibleMention as appendVisibleBodyMention, extractVisibleMentionIds as extractCanonicalMentionIds, } from './visible-mentions.js';
 import { waitForTaskForThread } from './task-thread-resolution.js';
+import { buildHostedIncomingContentText, buildHostedTurnContentParts, extractHostedMessageAttachments, normalizeHostedMessageAttachment, } from './hosted-turn-content.js';
 const PRIVATE_STATE_ROOT_MODE = 0o700;
 const STREAM_PROGRESS_EDIT_THROTTLE_MS = 150;
 const PROTOCOL_STATE_DIRNAME = 'protocol-state';
@@ -126,7 +127,9 @@ class DefaultHostRuntime {
             deps.provider ??
                 createProvider({
                     provider: config.agent.provider,
+                    borgeeBaseUrl: config.borgeeBaseUrl,
                     stateRootDir: config.stateRootDir,
+                    agentApiKey: config.agent.agentApiKey,
                     resolveStableAgentId: deps.resolveStableAgentId,
                     claudeCommand: config.claudeCommand,
                     claudeArgs: config.claudeArgs,
@@ -559,7 +562,7 @@ export class AgentsHost {
                 }
             }
         }
-        await this.runUngatedTurn(msg, normalized.authorId, normalized.content, taskThreadContext, attentionSnapshot);
+        await this.runUngatedTurn(msg, normalized.authorId, normalized.content, taskThreadContext, attentionSnapshot, normalized.incomingParts);
     }
     async handleCollaborationMessage(msg) {
         const normalized = await this.normalizeMessage(msg);
@@ -608,6 +611,7 @@ export class AgentsHost {
                     authorId: normalized.authorId,
                     authorKind: 'unknown',
                     content: normalized.content,
+                    incomingParts: normalized.incomingParts,
                     attentionSnapshot,
                     taskThreadContext,
                 });
@@ -626,6 +630,7 @@ export class AgentsHost {
                     authorId: normalized.authorId,
                     authorKind: 'human',
                     content: normalized.content,
+                    incomingParts: normalized.incomingParts,
                     attentionSnapshot,
                     taskThreadContext,
                     wakeBlockedState,
@@ -658,6 +663,7 @@ export class AgentsHost {
             authorId: normalized.authorId,
             authorKind,
             content: normalized.content,
+            incomingParts: normalized.incomingParts,
             attentionSnapshot,
             taskThreadContext,
         });
@@ -752,6 +758,7 @@ export class AgentsHost {
         const executed = await this.executeTurn(msg, normalized.authorId, normalized.content, {
             kickoff: protocolCandidate,
             silent: true,
+            incomingParts: normalized.incomingParts,
         });
         if (executed.stale) {
             return null;
@@ -912,6 +919,7 @@ export class AgentsHost {
                 authorId: normalized.authorId,
                 authorKind: 'human',
                 content: normalized.content,
+                incomingParts: normalized.incomingParts,
             });
             await this.ensureCollaborationProcessor(msg.channel_id, channelState);
             return;
@@ -924,6 +932,7 @@ export class AgentsHost {
             ownerAgentId: selfAgentId,
             anchorAuthorId: normalized.authorId,
             anchorContent: normalized.content,
+            anchorIncomingParts: normalized.incomingParts,
             anchorMessageId: msg.message_id ?? randomUUID(),
             participantIds: protocolRequest.participantIds,
             issuerId: protocolRequest.issuerId,
@@ -946,6 +955,7 @@ export class AgentsHost {
                 authorId: normalized.authorId,
                 authorKind: 'human',
                 content: normalized.content,
+                incomingParts: normalized.incomingParts,
             });
             await this.ensureCollaborationProcessor(msg.channel_id, channelState);
             return;
@@ -1014,6 +1024,7 @@ export class AgentsHost {
             authorId: normalized.authorId,
             authorKind: 'agent',
             content: normalized.content,
+            incomingParts: normalized.incomingParts,
         });
         await this.ensureCollaborationProcessor(msg.channel_id, channelState);
     }
@@ -1131,6 +1142,7 @@ export class AgentsHost {
         channelState.activeTurn = activeTurn;
         const executed = await this.executeTurn(message.raw, message.authorId, this.buildIncomingContent(message), {
             activeTurn,
+            incomingParts: message.incomingParts,
             incomingAuthorKind: message.authorKind,
             attentionSnapshot,
             taskThreadContext,
@@ -1234,6 +1246,7 @@ export class AgentsHost {
         channelState.activeTurn = activeTurn;
         const executed = await this.executeTurn(message.raw, message.authorId, this.buildIncomingContent(message), {
             activeTurn,
+            incomingParts: message.incomingParts,
             incomingAuthorKind: message.authorKind,
             attentionSnapshot,
             taskThreadContext,
@@ -1541,59 +1554,52 @@ export class AgentsHost {
     }
     async buildResumedProtocolMessage(channelId, protocolState) {
         if (protocolState.currentTurnIndex === 0) {
+            const anchorIncomingParts = await this.ensureProtocolAnchorIncomingParts(channelId, protocolState);
+            const anchorIncomingContent = buildHostedIncomingContentText(anchorIncomingParts);
             return {
                 kind: 'protocol-turn',
                 raw: {
                     channel_id: channelId,
                     message_id: protocolState.anchorMessageId,
                     user_id: protocolState.anchorAuthorId,
-                    content: protocolState.anchorContent,
-                    body: protocolState.anchorContent,
+                    content: anchorIncomingContent,
+                    body: anchorIncomingContent,
+                    attachments: extractHostedMessageAttachments(anchorIncomingParts),
                     type: 'message',
                 },
                 authorId: protocolState.anchorAuthorId,
                 authorKind: 'human',
-                content: protocolState.anchorContent,
+                content: anchorIncomingContent,
+                incomingParts: anchorIncomingParts,
             };
         }
         if (!protocolState.lastProtocolMessageId) {
             return null;
         }
-        let before;
-        for (;;) {
-            const history = await this.borgee.readChannelHistory({
-                channelId,
-                before,
-                limit: 200,
+        const priorMessage = await this.findChannelHistoryMessageById(channelId, protocolState.lastProtocolMessageId);
+        if (priorMessage) {
+            const incomingParts = buildHostedTurnContentParts({
+                text: priorMessage.body,
+                attachments: priorMessage.attachments,
             });
-            const priorMessage = history.find((entry) => entry.id === protocolState.lastProtocolMessageId);
-            if (priorMessage) {
-                return {
-                    kind: 'protocol-turn',
-                    raw: {
-                        channel_id: channelId,
-                        message_id: priorMessage.id,
-                        user_id: priorMessage.authorId,
-                        content: priorMessage.body,
-                        body: priorMessage.body,
-                        type: 'message',
-                        created_at: priorMessage.createdAt,
-                    },
-                    authorId: priorMessage.authorId,
-                    authorKind: 'agent',
-                    content: priorMessage.body,
-                };
-            }
-            if (history.length < 200) {
-                break;
-            }
-            const oldestCreatedAt = history.reduce((oldest, entry) => {
-                return oldest == null || entry.createdAt < oldest ? entry.createdAt : oldest;
-            }, null);
-            if (oldestCreatedAt == null || (before != null && oldestCreatedAt >= before)) {
-                break;
-            }
-            before = oldestCreatedAt;
+            const incomingContent = buildHostedIncomingContentText(incomingParts);
+            return {
+                kind: 'protocol-turn',
+                raw: {
+                    channel_id: channelId,
+                    message_id: priorMessage.id,
+                    user_id: priorMessage.authorId,
+                    content: incomingContent,
+                    body: incomingContent,
+                    attachments: priorMessage.attachments,
+                    type: 'message',
+                    created_at: priorMessage.createdAt,
+                },
+                authorId: priorMessage.authorId,
+                authorKind: 'agent',
+                content: incomingContent,
+                incomingParts,
+            };
         }
         return null;
     }
@@ -1604,6 +1610,7 @@ export class AgentsHost {
             ownerAgentId,
             anchorAuthorId: protocolState.anchorAuthorId,
             anchorContent: protocolState.anchorContent,
+            anchorIncomingParts: protocolState.anchorIncomingParts,
             anchorMessageId: protocolState.anchorMessageId,
             participantIds: protocolState.participantIds,
             issuerId: protocolState.issuerId,
@@ -1682,18 +1689,36 @@ export class AgentsHost {
             await this.persistProtocolState(channelId, protocolState);
             return;
         }
+        const anchorIncomingParts = await this.ensureProtocolAnchorIncomingParts(channelId, protocolState);
+        const anchorIncomingContent = buildHostedIncomingContentText(anchorIncomingParts);
         const fallbackMessage = {
             channel_id: channelId,
             message_id: protocolState.anchorMessageId,
             user_id: protocolState.anchorAuthorId,
-            content: protocolState.anchorContent,
-            body: protocolState.anchorContent,
+            content: anchorIncomingContent,
+            body: anchorIncomingContent,
+            attachments: extractHostedMessageAttachments(anchorIncomingParts),
             type: 'message',
         };
         this.cancelProtocolState(channelId, channelState);
         const taskThreadContext = await this.buildTurnTaskThreadContext(fallbackMessage, channelId);
         const attentionSnapshot = this.getAttentionSnapshotForTurn(channelId, taskThreadContext);
-        await this.runUngatedTurn(fallbackMessage, protocolState.anchorAuthorId, protocolState.anchorContent, taskThreadContext, attentionSnapshot);
+        await this.runUngatedTurn(fallbackMessage, protocolState.anchorAuthorId, anchorIncomingContent, taskThreadContext, attentionSnapshot, anchorIncomingParts);
+    }
+    async ensureProtocolAnchorIncomingParts(channelId, protocolState) {
+        if (protocolState.anchorIncomingParts) {
+            return protocolState.anchorIncomingParts;
+        }
+        const anchorMessage = await this.findChannelHistoryMessageById(channelId, protocolState.anchorMessageId);
+        if (!anchorMessage) {
+            return buildHostedTurnContentParts({ text: protocolState.anchorContent });
+        }
+        const anchorIncomingParts = buildHostedTurnContentParts({
+            text: protocolState.anchorContent,
+            attachments: anchorMessage.attachments,
+        });
+        protocolState.anchorIncomingParts = anchorIncomingParts;
+        return anchorIncomingParts;
     }
     finishProtocolState(channelId, channelState, protocolState, lastMessageId) {
         protocolState.active = false;
@@ -1733,6 +1758,36 @@ export class AgentsHost {
         }
         return matched;
     }
+    async findChannelHistoryMessageById(channelId, messageId) {
+        let before;
+        for (;;) {
+            const history = await this.borgee.readChannelHistory({
+                channelId,
+                before,
+                limit: 200,
+            });
+            const matched = history.find((entry) => entry.id === messageId);
+            if (matched) {
+                return {
+                    ...matched,
+                    ...(matched.attachments
+                        ? { attachments: matched.attachments.map(normalizeHostedMessageAttachment) }
+                        : {}),
+                };
+            }
+            if (history.length < 200) {
+                break;
+            }
+            const oldestCreatedAt = history.reduce((oldest, entry) => {
+                return oldest == null || entry.createdAt < oldest ? entry.createdAt : oldest;
+            }, null);
+            if (oldestCreatedAt == null || (before != null && oldestCreatedAt >= before)) {
+                break;
+            }
+            before = oldestCreatedAt;
+        }
+        return null;
+    }
     resolveAttentionStatePath(channelId) {
         return resolveAttentionStatePath(this.config.stateRootDir, channelId);
     }
@@ -2037,10 +2092,11 @@ export class AgentsHost {
             reason: 'wake-suppressed-attention-policy',
         });
     }
-    async runUngatedTurn(msg, authorId, content, taskThreadContext, attentionSnapshot) {
+    async runUngatedTurn(msg, authorId, content, taskThreadContext, attentionSnapshot, incomingParts) {
         const executed = await this.executeTurn(msg, authorId, content, {
             attentionSnapshot,
             taskThreadContext,
+            incomingParts,
         });
         if (executed.completed && executed.reply) {
             this.updateAwaitingUserState(msg.channel_id, executed.reply.awaitingUser);
@@ -2133,6 +2189,11 @@ export class AgentsHost {
             : undefined;
         const missedCollaborationDiagnostic = this.resolveMissedCollaborationDiagnosticForTurn(channelId);
         const collaborationCapabilities = this.resolveCollaborationCapabilityDeclarationForTurn();
+        const incomingParts = options?.incomingParts
+            ?? buildHostedTurnContentParts({
+                text: String(msg.content ?? msg.body ?? content),
+                attachments: msg.attachments,
+            });
         try {
             reply = await this.provider.generateReply({
                 agentName: this.config.agent.agentName,
@@ -2140,6 +2201,7 @@ export class AgentsHost {
                 channelId,
                 incomingAuthorId: authorId,
                 incomingContent: content,
+                incomingParts,
                 incomingEventKind: msg.type,
                 incomingMessageType: msg.message_type,
                 collaboration: turnExecutionId || options?.kickoff
@@ -2683,17 +2745,22 @@ export class AgentsHost {
             });
             return null;
         }
-        const content = String(msg.content ?? msg.body ?? '').trim();
-        if (!content) {
+        const incomingParts = buildHostedTurnContentParts({
+            text: String(msg.content ?? msg.body ?? ''),
+            attachments: msg.attachments,
+        });
+        if (incomingParts.length === 0) {
             this.logger.debug('ignored empty message', {
                 channelId: msg.channel_id,
                 messageId: msg.message_id,
             });
             return null;
         }
+        const content = buildHostedIncomingContentText(incomingParts);
         return {
             authorId,
             content,
+            incomingParts,
         };
     }
     // Only a task assigned to this agent drives a task-assignment turn: it keeps the message a

package/dist/chat/sdk-chat-control-plane.js

@@ -1,4 +1,5 @@
 import { createBorgeePlugin, } from '../plugin-sdk.js';
+import { normalizeHostedMessageAttachment } from '../hosted-turn-content.js';
 /**
  * Thin adapter over `@borgee/plugin-sdk` (the same BPP/`/ws/plugin` SDK used by
  * the OpenClaw plugin) that implements the minimal `ChatControlPlane` surface
@@ -97,6 +98,7 @@ export class SdkChatControlPlane {
             authorId: message.authorId,
             body: message.body,
             contentType: message.contentType,
+            attachments: message.attachments?.map(normalizeHostedMessageAttachment),
             type: message.type,
             replyToId: message.replyToId,
             createdAt: message.createdAt,
@@ -142,6 +144,7 @@ export function mapInboundToChannelMessage(event) {
         content: event.message?.body,
         body: event.message?.body,
         content_type: event.message?.contentType,
+        attachments: event.message?.attachments?.map(normalizeHostedMessageAttachment),
         created_at: event.createdAt,
     };
 }

package/dist/context/injection.d.ts

@@ -21,7 +21,7 @@ export interface PreparedChannelContext {
     directoryPath: string;
     payload: ChannelContextPayload;
     payloadPath?: string;
-    gatewayAuthPath?: string;
+    gatewayCredentialPath?: string;
     skillRuntime?: SkillRuntimeBootstrapMetadata;
     localhostGateway?: LocalhostGatewayBootstrapMetadata;
     taskWorkspace?: TaskWorkspaceContext;
@@ -83,6 +83,7 @@ interface ContextFileSystem {
         mode?: number;
     }): Promise<void>;
     unlink(path: string): Promise<void>;
+    rename(oldPath: string, newPath: string): Promise<void>;
     access(path: string): Promise<void>;
 }
 interface FileChannelContextStoreOptions {
@@ -98,8 +99,9 @@ export declare function resolveChannelContextDirectory(stateRootDir: string, cha
 export declare function resolveChannelContextPayloadPath(stateRootDir: string, channelId: string): string;
 export declare function resolveTaskWorkspaceRootDirectory(startupWorkspaceRootDir: string): string;
 export declare function resolveTaskWorkspaceDirectory(startupWorkspaceRootDir: string, channelId: string, taskId: string): string;
-export declare function resolveChannelContextGatewayAuthPath(stateRootDir: string, channelId: string, turnExecutionId?: string): string;
-export declare function resolveGatewayAuthPathFromPayloadPath(payloadPath: string): string;
+export declare function resolveChannelGatewayCredentialPath(stateRootDir: string, channelId: string): string;
+export declare function resolveGatewayCredentialPathFromPayloadPath(payloadPath: string): string;
+export declare function isGatewayCredentialSidecarBasename(basename: string): boolean;
 export declare function resolveBorgeeAgentSkillRuntimeAssets(moduleUrl: string, fileSystem?: Pick<ContextFileSystem, 'access'>): Promise<SkillRuntimeBootstrapMetadata>;
 export declare class FileChannelContextStore implements ChannelContextStore {
     private readonly stateRootDir;

package/dist/context/injection.js

@@ -1,9 +1,10 @@
 import { promises as fs } from 'node:fs';
+import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { dirname, join, resolve } from 'node:path';
 const CHANNEL_CONTEXT_ROOT_DIRNAME = 'channel-context';
 const CHANNEL_CONTEXT_PAYLOAD_FILENAME = 'context.json';
-const CHANNEL_CONTEXT_GATEWAY_AUTH_FILENAME = '.localhost-gateway-auth.json';
+const CHANNEL_GATEWAY_CREDENTIAL_FILENAME = '.borgee-agent-gateway.json';
 const TASK_WORKSPACE_ROOT_DIRNAME = '.borgee-task-workspaces';
 export class ChannelContextPreparationError extends Error {
     partialContext;
@@ -29,6 +30,9 @@ const DEFAULT_FILE_SYSTEM = {
     async unlink(path) {
         await fs.unlink(path);
     },
+    async rename(oldPath, newPath) {
+        await fs.rename(oldPath, newPath);
+    },
     async access(path) {
         await fs.access(path);
     },
@@ -45,7 +49,7 @@ function toSkillRuntimePayload(skillRuntime) {
         pythonCliPath: skillRuntime.pythonCliPath,
     };
 }
-function buildLocalhostGatewayAuthPayload(channelId, localhostGateway) {
+function buildBorgeeAgentGatewayCredential(channelId, localhostGateway) {
     if (!localhostGateway) {
         return undefined;
     }
@@ -53,6 +57,7 @@ function buildLocalhostGatewayAuthPayload(channelId, localhostGateway) {
         schemaVersion: 1,
         channelId,
         localhostGateway: {
+            baseUrl: localhostGateway.baseUrl,
             token: localhostGateway.token,
         },
     };
@@ -144,17 +149,28 @@ export function resolveTaskWorkspaceRootDirectory(startupWorkspaceRootDir) {
 export function resolveTaskWorkspaceDirectory(startupWorkspaceRootDir, channelId, taskId) {
     return join(resolveTaskWorkspaceRootDirectory(startupWorkspaceRootDir), encodeChannelPathSegment(channelId), encodeChannelPathSegment(taskId));
 }
-export function resolveChannelContextGatewayAuthPath(stateRootDir, channelId, turnExecutionId) {
-    const filename = turnExecutionId
-        ? `.localhost-gateway-auth.${Buffer.from(turnExecutionId, 'utf8').toString('hex')}.json`
-        : CHANNEL_CONTEXT_GATEWAY_AUTH_FILENAME;
-    return join(resolveChannelContextDirectory(stateRootDir, channelId), filename);
+export function resolveChannelGatewayCredentialPath(stateRootDir, channelId) {
+    return join(resolveChannelContextDirectory(stateRootDir, channelId), CHANNEL_GATEWAY_CREDENTIAL_FILENAME);
+}
+export function resolveGatewayCredentialPathFromPayloadPath(payloadPath) {
+    return join(dirname(payloadPath), CHANNEL_GATEWAY_CREDENTIAL_FILENAME);
 }
-export function resolveGatewayAuthPathFromPayloadPath(payloadPath) {
-    return join(dirname(payloadPath), CHANNEL_CONTEXT_GATEWAY_AUTH_FILENAME);
+/**
+ * Every basename a gateway credential can carry in a channel context directory, including the ones
+ * this host no longer writes. The directory holds at most one live credential — the token is
+ * reissued every turn — and this sweep is the only thing that ever unlinks the others, so a name
+ * dropped from this list leaves a 0600 file behind that still looks live.
+ */
+const GATEWAY_CREDENTIAL_SIDECAR_BASENAME_PREFIXES = [
+    '.borgee-agent-gateway.',
+    '.borgee-agent-bootstrap.',
+    '.localhost-gateway-auth.',
+];
+export function isGatewayCredentialSidecarBasename(basename) {
+    return basename.endsWith('.json')
+        && GATEWAY_CREDENTIAL_SIDECAR_BASENAME_PREFIXES.some((prefix) => basename.startsWith(prefix));
 }
-const LEGACY_TURN_SCOPED_GATEWAY_AUTH_BASENAME_PREFIX = '.localhost-gateway-auth.';
-async function pruneLegacyGatewayAuthSidecars(fileSystem, directoryPath) {
+async function pruneGatewayCredentialSidecars(fileSystem, directoryPath, keepBasename) {
     let entries;
     try {
         entries = await fileSystem.readdir(directoryPath);
@@ -167,8 +183,7 @@ async function pruneLegacyGatewayAuthSidecars(fileSystem, directoryPath) {
         throw error;
     }
     await Promise.all(entries
-        .filter((entry) => entry.startsWith(LEGACY_TURN_SCOPED_GATEWAY_AUTH_BASENAME_PREFIX)
-        && entry.endsWith('.json'))
+        .filter((entry) => isGatewayCredentialSidecarBasename(entry) && entry !== keepBasename)
         .map(async (entry) => {
         await fileSystem.unlink(join(directoryPath, entry)).catch((error) => {
             if (error.code !== 'ENOENT') {
@@ -196,8 +211,8 @@ export async function resolveBorgeeAgentSkillRuntimeAssets(moduleUrl, fileSystem
     const packageRootPath = await resolvePackageRootFromModuleUrl(moduleUrl, fileSystem);
     const skillDirectoryPath = join(packageRootPath, 'skills', BORGEE_AGENT_SKILL_DIRNAME);
     const skillMarkdownPath = join(skillDirectoryPath, 'SKILL.md');
-    const nodeCliPath = join(skillDirectoryPath, 'borgee-agent.mjs');
-    const pythonCliPath = join(skillDirectoryPath, 'borgee-agent.py');
+    const nodeCliPath = join(skillDirectoryPath, 'scripts', 'borgee-agent.mjs');
+    const pythonCliPath = join(skillDirectoryPath, 'scripts', 'borgee-agent.py');
     await Promise.all([
         fileSystem.access(skillDirectoryPath),
         fileSystem.access(skillMarkdownPath),
@@ -249,7 +264,7 @@ export class FileChannelContextStore {
         const auxiliaryCollaborationEnabled = collaborationCommandsEnabled && collaborationRoutesAllowedForTurnMode;
         const directoryPath = resolveChannelContextDirectory(this.stateRootDir, input.channelId);
         const payloadPath = resolveChannelContextPayloadPath(this.stateRootDir, input.channelId);
-        const gatewayAuthPath = resolveGatewayAuthPathFromPayloadPath(payloadPath);
+        const gatewayCredentialPath = resolveGatewayCredentialPathFromPayloadPath(payloadPath);
         const existingTaskAssignmentContext = await readExistingTaskAssignmentContext(payloadPath, this.fileSystem);
         const skillRuntime = this.skillRuntimeEnabled
             ? await this.resolveSkillRuntimeBestEffort()
@@ -292,15 +307,15 @@ export class FileChannelContextStore {
                 ...(taskWorkspace ? { taskWorkspace } : {}),
             }
             : undefined);
-        const gatewayAuthPayload = buildLocalhostGatewayAuthPayload(input.channelId, issuedLocalhostGateway);
+        const gatewayCredential = buildBorgeeAgentGatewayCredential(input.channelId, issuedLocalhostGateway);
         let taskWorkspaceMaterialized = false;
         let payloadWritten = false;
-        let gatewayAuthWritten = false;
+        let gatewayCredentialWritten = false;
         const preparedContext = {
             directoryPath,
             payload,
             payloadPath,
-            gatewayAuthPath: gatewayAuthPayload ? gatewayAuthPath : undefined,
+            gatewayCredentialPath: gatewayCredential ? gatewayCredentialPath : undefined,
             skillRuntime,
             localhostGateway,
             taskWorkspace,
@@ -311,19 +326,20 @@ export class FileChannelContextStore {
                 await this.fileSystem.mkdir(taskWorkspace.rootPath, { recursive: true, mode: 0o700 });
                 taskWorkspaceMaterialized = true;
             }
-            await pruneLegacyGatewayAuthSidecars(this.fileSystem, directoryPath);
+            await pruneGatewayCredentialSidecars(this.fileSystem, directoryPath, gatewayCredential ? CHANNEL_GATEWAY_CREDENTIAL_FILENAME : undefined);
             await this.fileSystem.writeFile(payloadPath, `${JSON.stringify(payload, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
             payloadWritten = true;
-            if (gatewayAuthPayload) {
-                await this.fileSystem.writeFile(gatewayAuthPath, `${JSON.stringify(gatewayAuthPayload, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
-                gatewayAuthWritten = true;
+            if (gatewayCredential) {
+                // Replaced atomically: a CLI invocation left over from an earlier turn must read either
+                // the old credential or the new one, never a missing or half-written file, because the
+                // documented correction for a rotated token is a 401 and not a usage error. The staging
+                // name is itself a credential sidecar, so a crashed run's leftover is swept above.
+                const stagingCredentialPath = join(directoryPath, `.borgee-agent-gateway.${randomUUID()}.json`);
+                await this.fileSystem.writeFile(stagingCredentialPath, `${JSON.stringify(gatewayCredential, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+                await this.fileSystem.rename(stagingCredentialPath, gatewayCredentialPath);
+                gatewayCredentialWritten = true;
             }
             else {
-                await this.fileSystem.unlink(gatewayAuthPath).catch((error) => {
-                    if (error.code !== 'ENOENT') {
-                        throw error;
-                    }
-                });
                 this.localhostGateway?.clearChannel(input.channelId);
             }
             if (issuedLocalhostGateway) {
@@ -336,7 +352,7 @@ export class FileChannelContextStore {
                 directoryPath,
                 payload,
                 payloadPath: payloadWritten ? payloadPath : undefined,
-                gatewayAuthPath: gatewayAuthWritten ? gatewayAuthPath : undefined,
+                gatewayCredentialPath: gatewayCredentialWritten ? gatewayCredentialPath : undefined,
                 skillRuntime: payloadWritten ? skillRuntime : undefined,
                 localhostGateway: payloadWritten ? localhostGateway : undefined,
                 taskWorkspace: taskWorkspaceMaterialized ? taskWorkspace : undefined,