@borgee/agents-host 0.2.35 → 0.2.56

package/dist/context/injection.js

@@ -1,10 +1,21 @@
 import { promises as fs } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { findTaskForThread } from '../task-thread-resolution.js';
+import { buildClaudeFileBrief } from './claude-file-brief.js';
 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 TASK_WORKSPACE_ROOT_DIRNAME = '.borgee-task-workspaces';
+const CHANNEL_GATEWAY_CREDENTIAL_FILENAME = '.borgee-agent-gateway.json';
+const CLAUDE_PROJECTED_BRIEF_FILENAME = 'CLAUDE.md';
+const DEFAULT_HOME_BORGEE_DIRNAME = '.borgee';
+const CHANNEL_WORKSPACE_COLLECTION_DIRNAME = 'channels';
+const CHANNEL_WORKSPACE_DIRNAME = 'workspace';
+const TASK_ISOLATED_WORKSPACE_COLLECTION_DIRNAME = 'tasks';
+const TASK_WORKSPACE_MODE_PROPERTY_KEY = 'workspace.mode';
+const TASK_WORKSPACE_MODE_ISOLATED = 'isolated';
+const DEFAULT_TASK_WORKSPACE_RESOLUTION_TIMEOUT_MS = 1_500;
 export class ChannelContextPreparationError extends Error {
     partialContext;
     constructor(message, partialContext, options) {
@@ -29,6 +40,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 +59,7 @@ function toSkillRuntimePayload(skillRuntime) {
         pythonCliPath: skillRuntime.pythonCliPath,
     };
 }
-function buildLocalhostGatewayAuthPayload(channelId, localhostGateway) {
+function buildBorgeeAgentGatewayCredential(channelId, localhostGateway) {
     if (!localhostGateway) {
         return undefined;
     }
@@ -53,23 +67,55 @@ function buildLocalhostGatewayAuthPayload(channelId, localhostGateway) {
         schemaVersion: 1,
         channelId,
         localhostGateway: {
+            baseUrl: localhostGateway.baseUrl,
             token: localhostGateway.token,
         },
     };
 }
-function buildChannelContextPayload(channelId, collaborationOutcome, attentionSnapshot, taskThreadCollaborationContract, collaborationCapabilities, missedCollaborationDiagnostic, skillRuntime, localhostGateway, options) {
+function buildChannelContextPayload(channelId, runtimeSurface, collaborationOutcome, attentionSnapshot, compactionSnapshot, taskThreadCollaborationContract, collaborationCapabilities, missedCollaborationDiagnostic, skillRuntime, localhostGateway, options) {
     return {
         schemaVersion: 1,
         channelId,
+        runtimeSurface,
         ...(collaborationOutcome ? { collaborationOutcome } : {}),
         ...(attentionSnapshot ? { attentionSnapshot } : {}),
+        ...(compactionSnapshot ? { compactionSnapshot } : {}),
         ...(taskThreadCollaborationContract ? { taskThreadCollaborationContract } : {}),
         ...(collaborationCapabilities ? { collaborationCapabilities } : {}),
         ...(missedCollaborationDiagnostic ? { missedCollaborationDiagnostic } : {}),
         ...(skillRuntime ? { skillRuntime: toSkillRuntimePayload(skillRuntime) } : {}),
         ...(localhostGateway ? { localhostGateway } : {}),
         ...(options?.taskAssignmentContext ? { taskAssignmentContext: options.taskAssignmentContext } : {}),
-        ...(options?.taskWorkspace ? { taskWorkspace: options.taskWorkspace } : {}),
+        ...(options?.resolvedWorkspace ? { resolvedWorkspace: options.resolvedWorkspace } : {}),
+    };
+}
+function hashUtf8Content(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+async function unlinkIfPresent(fileSystem, path) {
+    await fileSystem.unlink(path).catch((error) => {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+    });
+}
+function buildPromptContextForClaudeProjectedBrief(preparedContext) {
+    return {
+        channelContextPayloadPath: preparedContext.payloadPath,
+        claudeProjectedBriefPath: preparedContext.claudeProjectedBriefPath,
+        claudeProjectedBriefHash: preparedContext.claudeProjectedBriefHash,
+        gatewayCredentialPath: preparedContext.gatewayCredentialPath,
+        skillRuntime: preparedContext.skillRuntime,
+        localhostGateway: preparedContext.localhostGateway,
+        taskAssignmentContext: preparedContext.payload.taskAssignmentContext,
+        resolvedWorkspace: preparedContext.resolvedWorkspace,
+        runtimeSurface: preparedContext.payload.runtimeSurface,
+        collaborationOutcome: preparedContext.payload.collaborationOutcome,
+        attentionSnapshot: preparedContext.payload.attentionSnapshot,
+        compactionSnapshot: preparedContext.payload.compactionSnapshot,
+        collaborationCapabilities: preparedContext.payload.collaborationCapabilities,
+        missedCollaborationDiagnostic: preparedContext.payload.missedCollaborationDiagnostic,
+        taskThreadCollaborationContract: preparedContext.payload.taskThreadCollaborationContract,
     };
 }
 function isRecord(value) {
@@ -91,6 +137,73 @@ function isUsableTaskId(value) {
         && !/[\u0000-\u001f\u007f\s]/u.test(value)
         && canRoundTripThroughUriComponentEncoding(value);
 }
+function normalizeTaskAssignmentCurrentTaskId(taskAssignmentContext) {
+    const currentTaskId = typeof taskAssignmentContext?.currentTaskId === 'string'
+        ? taskAssignmentContext.currentTaskId.trim()
+        : '';
+    return currentTaskId && isUsableTaskId(currentTaskId)
+        ? currentTaskId
+        : undefined;
+}
+export function buildRuntimeSurfaceForTurn(options) {
+    const turnMode = options?.collaboration?.turnMode ?? 'ordinary';
+    const gatewayAvailable = options?.localhostGateway !== undefined;
+    const currentTaskId = normalizeTaskAssignmentCurrentTaskId(options?.taskAssignmentContext);
+    const taskAssignmentThreadActive = options?.taskAssignmentContext?.active === true;
+    const collaborationGatewayEnabled = gatewayAvailable && options.localhostGateway?.collaboration?.enabled === true;
+    const auxiliarySendAvailable = turnMode === 'ordinary'
+        && collaborationGatewayEnabled
+        && options?.collaboration?.sendRoutesAllowed === true;
+    return {
+        schemaVersion: 1,
+        turnMode,
+        gateway: {
+            available: gatewayAvailable,
+            readOnlyRoutesAuthorized: gatewayAvailable,
+            inspectBeforeAnswer: gatewayAvailable,
+        },
+        task: {
+            currentThread: taskAssignmentThreadActive ? 'task-assignment-thread' : 'parent-channel',
+            parentChannelTaskCollection: taskAssignmentThreadActive ? 'parent-channel-only' : 'available',
+            currentTaskShorthand: currentTaskId
+                ? 'persisted-current-task'
+                : taskAssignmentThreadActive
+                    ? 'fallback-current-task'
+                    : 'requires-task-id',
+            currentTaskIdPersisted: currentTaskId !== undefined,
+            currentTaskFallback: !currentTaskId && taskAssignmentThreadActive
+                ? 'visible-parent-channel-thread-scan'
+                : 'disallowed',
+        },
+        collaboration: gatewayAvailable
+            ? turnMode === 'ordinary'
+                ? {
+                    participantLookup: collaborationGatewayEnabled ? 'available' : 'unavailable',
+                    draftRead: auxiliarySendAvailable ? 'available' : 'unavailable',
+                    auxiliarySend: auxiliarySendAvailable ? 'available' : 'unavailable',
+                }
+                : {
+                    participantLookup: 'unavailable',
+                    draftRead: 'unavailable',
+                    auxiliarySend: 'unavailable',
+                }
+            : {
+                participantLookup: 'unavailable',
+                draftRead: 'unavailable',
+                auxiliarySend: 'unavailable',
+            },
+        response: {
+            mainVisibleReply: turnMode === 'ordinary'
+                ? 'model-visible-reply'
+                : turnMode === 'protocol-managed'
+                    ? 'host-visible-protocol-reply'
+                    : 'no-visible-reply',
+            auxiliaryMessageUsage: auxiliarySendAvailable
+                ? 'targeted-escalation-only'
+                : 'unavailable',
+        },
+    };
+}
 function sanitizeTaskAssignmentContext(value) {
     if (!isRecord(value) || value.active !== true) {
         return undefined;
@@ -128,6 +241,128 @@ async function readExistingTaskAssignmentContext(payloadPath, fileSystem) {
         return undefined;
     }
 }
+function sanitizeResolvedWorkspaceContext(value) {
+    if (!isRecord(value) || typeof value.rootPath !== 'string' || !isAbsolute(value.rootPath)) {
+        return undefined;
+    }
+    if (value.authority === 'channel'
+        && typeof value.owningChannelId === 'string'
+        && value.owningChannelId.length > 0) {
+        return {
+            authority: 'channel',
+            owningChannelId: value.owningChannelId,
+            rootPath: value.rootPath,
+        };
+    }
+    if (value.authority === 'task'
+        && typeof value.taskId === 'string'
+        && isUsableTaskId(value.taskId.trim())) {
+        return {
+            authority: 'task',
+            taskId: value.taskId.trim(),
+            rootPath: value.rootPath,
+        };
+    }
+    return undefined;
+}
+async function readExistingResolvedWorkspaceContext(payloadPath, fileSystem) {
+    try {
+        const raw = await fileSystem.readFile(payloadPath, { encoding: 'utf8' });
+        const payload = JSON.parse(raw);
+        return sanitizeResolvedWorkspaceContext(payload.resolvedWorkspace);
+    }
+    catch {
+        return undefined;
+    }
+}
+function buildChannelResolvedWorkspace(workspaceCollectionRootDir, channelId) {
+    return {
+        authority: 'channel',
+        owningChannelId: channelId,
+        rootPath: resolveChannelWorkspaceDirectory(workspaceCollectionRootDir, channelId),
+    };
+}
+function buildStickyChannelResolvedWorkspace(workspaceCollectionRootDir, resolvedWorkspace) {
+    if (resolvedWorkspace?.authority !== 'channel') {
+        return undefined;
+    }
+    const expectedRootPath = resolveChannelWorkspaceDirectory(workspaceCollectionRootDir, resolvedWorkspace.owningChannelId);
+    if (resolvedWorkspace.rootPath !== expectedRootPath) {
+        return undefined;
+    }
+    return {
+        authority: 'channel',
+        owningChannelId: resolvedWorkspace.owningChannelId,
+        rootPath: expectedRootPath,
+    };
+}
+async function resolveTaskThreadWorkspaceContext(params) {
+    const channelWorkspace = buildChannelResolvedWorkspace(params.workspaceCollectionRootDir, params.channelId);
+    const taskAssignmentContext = params.taskAssignmentContext;
+    const currentTaskId = taskAssignmentContext?.currentTaskId?.trim();
+    if (taskAssignmentContext?.active !== true
+        || !currentTaskId
+        || !params.taskReader) {
+        return { taskAssignmentContext, resolvedWorkspace: channelWorkspace };
+    }
+    const stickyTaskWorkspace = params.existingResolvedWorkspace?.authority === 'task'
+        && params.existingResolvedWorkspace.taskId === currentTaskId
+        ? {
+            authority: 'task',
+            taskId: currentTaskId,
+            rootPath: resolveTaskWorkspaceDirectory(params.workspaceCollectionRootDir, params.channelId, currentTaskId),
+        }
+        : undefined;
+    const stickyChannelWorkspace = buildStickyChannelResolvedWorkspace(params.workspaceCollectionRootDir, params.existingResolvedWorkspace);
+    try {
+        const task = await withDeadline(findTaskForThread(params.taskReader, params.channelId, currentTaskId), params.taskResolutionTimeoutMs, `workspace resolution timed out for task ${currentTaskId}`);
+        if (!task) {
+            return {
+                taskAssignmentContext,
+                resolvedWorkspace: channelWorkspace,
+            };
+        }
+        async function withDeadline(promise, timeoutMs, timeoutMessage) {
+            if (timeoutMs <= 0) {
+                return await promise;
+            }
+            let timer;
+            try {
+                return await Promise.race([
+                    promise,
+                    new Promise((_, reject) => {
+                        timer = setTimeout(() => reject(new Error(timeoutMessage)), timeoutMs);
+                    }),
+                ]);
+            }
+            finally {
+                if (timer) {
+                    clearTimeout(timer);
+                }
+            }
+        }
+        if (task.properties[TASK_WORKSPACE_MODE_PROPERTY_KEY] !== TASK_WORKSPACE_MODE_ISOLATED) {
+            return {
+                taskAssignmentContext,
+                resolvedWorkspace: buildChannelResolvedWorkspace(params.workspaceCollectionRootDir, task.channelId),
+            };
+        }
+        return {
+            taskAssignmentContext,
+            resolvedWorkspace: {
+                authority: 'task',
+                taskId: task.id,
+                rootPath: resolveTaskWorkspaceDirectory(params.workspaceCollectionRootDir, params.channelId, task.id),
+            },
+        };
+    }
+    catch (error) {
+        return {
+            taskAssignmentContext,
+            resolvedWorkspace: stickyTaskWorkspace ?? stickyChannelWorkspace ?? channelWorkspace,
+        };
+    }
+}
 export function encodeChannelPathSegment(channelId) {
     const encoded = Buffer.from(channelId, 'utf8').toString('hex');
     return encoded.length > 0 ? encoded : 'empty';
@@ -139,22 +374,54 @@ export function resolveChannelContextPayloadPath(stateRootDir, channelId) {
     return join(resolveChannelContextDirectory(stateRootDir, channelId), CHANNEL_CONTEXT_PAYLOAD_FILENAME);
 }
 export function resolveTaskWorkspaceRootDirectory(startupWorkspaceRootDir) {
-    return join(resolve(startupWorkspaceRootDir), TASK_WORKSPACE_ROOT_DIRNAME);
+    return join(resolve(startupWorkspaceRootDir), TASK_ISOLATED_WORKSPACE_COLLECTION_DIRNAME);
+}
+export function resolveManagedWorkspaceCollectionRoot(workspaceCollectionRootDir, env = process.env, resolvedHomeDir = homedir()) {
+    const explicitRoot = workspaceCollectionRootDir?.trim();
+    if (explicitRoot) {
+        return resolve(explicitRoot);
+    }
+    const home = env.HOME?.trim() || resolvedHomeDir.trim();
+    if (!home) {
+        throw new Error('Unable to resolve a user home directory for agents-host workspaces');
+    }
+    return join(resolve(home), DEFAULT_HOME_BORGEE_DIRNAME, CHANNEL_WORKSPACE_COLLECTION_DIRNAME);
+}
+export function resolveChannelWorkspaceRootDirectory(workspaceCollectionRootDir, channelId) {
+    return join(resolve(workspaceCollectionRootDir), encodeChannelPathSegment(channelId));
 }
-export function resolveTaskWorkspaceDirectory(startupWorkspaceRootDir, channelId, taskId) {
-    return join(resolveTaskWorkspaceRootDirectory(startupWorkspaceRootDir), encodeChannelPathSegment(channelId), encodeChannelPathSegment(taskId));
+export function resolveChannelWorkspaceDirectory(workspaceCollectionRootDir, channelId) {
+    return join(resolveChannelWorkspaceRootDirectory(workspaceCollectionRootDir, channelId), CHANNEL_WORKSPACE_DIRNAME);
 }
-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 resolveTaskIsolatedWorkspaceDirectory(workspaceCollectionRootDir, channelId, taskId) {
+    return join(resolveTaskWorkspaceRootDirectory(resolveChannelWorkspaceRootDirectory(workspaceCollectionRootDir, channelId)), encodeChannelPathSegment(taskId), CHANNEL_WORKSPACE_DIRNAME);
 }
-export function resolveGatewayAuthPathFromPayloadPath(payloadPath) {
-    return join(dirname(payloadPath), CHANNEL_CONTEXT_GATEWAY_AUTH_FILENAME);
+export const resolveTaskWorkspaceDirectory = resolveTaskIsolatedWorkspaceDirectory;
+export function resolveChannelGatewayCredentialPath(stateRootDir, channelId) {
+    return join(resolveChannelContextDirectory(stateRootDir, channelId), CHANNEL_GATEWAY_CREDENTIAL_FILENAME);
 }
-const LEGACY_TURN_SCOPED_GATEWAY_AUTH_BASENAME_PREFIX = '.localhost-gateway-auth.';
-async function pruneLegacyGatewayAuthSidecars(fileSystem, directoryPath) {
+export function resolveGatewayCredentialPathFromPayloadPath(payloadPath) {
+    return join(dirname(payloadPath), CHANNEL_GATEWAY_CREDENTIAL_FILENAME);
+}
+export function resolveClaudeProjectedBriefPathFromPayloadPath(payloadPath) {
+    return join(dirname(payloadPath), CLAUDE_PROJECTED_BRIEF_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));
+}
+async function pruneGatewayCredentialSidecars(fileSystem, directoryPath, keepBasename) {
     let entries;
     try {
         entries = await fileSystem.readdir(directoryPath);
@@ -167,8 +434,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 +462,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),
@@ -230,14 +496,18 @@ export class FileChannelContextStore {
     skillRuntimeEnabled;
     skillAssetResolver;
     localhostGateway;
-    startupWorkspaceRootDir;
+    workspaceCollectionRootDir;
+    taskReader;
+    taskResolutionTimeoutMs;
     constructor(stateRootDir, options = {}) {
         this.stateRootDir = stateRootDir;
         this.fileSystem = options.fileSystem ?? DEFAULT_FILE_SYSTEM;
         this.skillRuntimeEnabled = options.skillRuntimeEnabled ?? false;
         this.skillAssetResolver = options.skillAssetResolver ?? new PackageSkillAssetResolver(import.meta.url, this.fileSystem);
         this.localhostGateway = options.localhostGateway;
-        this.startupWorkspaceRootDir = resolve(options.taskWorkspaceRootDir ?? process.cwd());
+        this.workspaceCollectionRootDir = resolveManagedWorkspaceCollectionRoot(options.workspaceCollectionRootDir, options.env, options.resolvedHomeDir);
+        this.taskReader = options.taskReader;
+        this.taskResolutionTimeoutMs = options.taskResolutionTimeoutMs ?? DEFAULT_TASK_WORKSPACE_RESOLUTION_TIMEOUT_MS;
     }
     async prepare(inputOrChannelId, options) {
         const input = typeof inputOrChannelId === 'string'
@@ -249,8 +519,10 @@ 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 claudeProjectedBriefPath = resolveClaudeProjectedBriefPathFromPayloadPath(payloadPath);
+        const gatewayCredentialPath = resolveGatewayCredentialPathFromPayloadPath(payloadPath);
         const existingTaskAssignmentContext = await readExistingTaskAssignmentContext(payloadPath, this.fileSystem);
+        const existingResolvedWorkspace = await readExistingResolvedWorkspaceContext(payloadPath, this.fileSystem);
         const skillRuntime = this.skillRuntimeEnabled
             ? await this.resolveSkillRuntimeBestEffort()
             : undefined;
@@ -280,66 +552,101 @@ export class FileChannelContextStore {
             incomingMessageType: input.incomingMessageType,
             incomingContent: input.incomingContent,
         }, existingTaskAssignmentContext);
-        const taskWorkspace = taskAssignmentContext?.currentTaskId
-            ? {
-                currentTaskId: taskAssignmentContext.currentTaskId,
-                rootPath: resolveTaskWorkspaceDirectory(this.startupWorkspaceRootDir, input.channelId, taskAssignmentContext.currentTaskId),
-            }
-            : undefined;
-        const payload = buildChannelContextPayload(input.channelId, input.collaborationOutcome, input.attentionSnapshot, input.taskThreadCollaborationContract, input.collaborationCapabilities, input.missedCollaborationDiagnostic, skillRuntime, localhostGateway, taskAssignmentContext || taskWorkspace
+        const workspaceResolution = await resolveTaskThreadWorkspaceContext({
+            channelId: input.channelId,
+            workspaceCollectionRootDir: this.workspaceCollectionRootDir,
+            taskAssignmentContext,
+            existingResolvedWorkspace,
+            taskReader: this.taskReader,
+            taskResolutionTimeoutMs: this.taskResolutionTimeoutMs,
+        });
+        const resolvedWorkspace = workspaceResolution.resolvedWorkspace;
+        const runtimeSurface = buildRuntimeSurfaceForTurn({
+            localhostGateway,
+            collaboration: input.collaboration,
+            taskAssignmentContext: workspaceResolution.taskAssignmentContext ?? taskAssignmentContext,
+        });
+        const payload = buildChannelContextPayload(input.channelId, runtimeSurface, input.collaborationOutcome, input.attentionSnapshot, input.compactionSnapshot, input.taskThreadCollaborationContract, input.collaborationCapabilities, input.missedCollaborationDiagnostic, skillRuntime, localhostGateway, workspaceResolution.taskAssignmentContext || resolvedWorkspace
             ? {
-                ...(taskAssignmentContext ? { taskAssignmentContext } : {}),
-                ...(taskWorkspace ? { taskWorkspace } : {}),
+                ...(workspaceResolution.taskAssignmentContext
+                    ? { taskAssignmentContext: workspaceResolution.taskAssignmentContext }
+                    : {}),
+                resolvedWorkspace,
             }
             : undefined);
-        const gatewayAuthPayload = buildLocalhostGatewayAuthPayload(input.channelId, issuedLocalhostGateway);
-        let taskWorkspaceMaterialized = false;
+        const gatewayCredential = buildBorgeeAgentGatewayCredential(input.channelId, issuedLocalhostGateway);
+        let resolvedWorkspaceMaterialized = false;
+        let claudeProjectedBriefWritten = 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,
+            resolvedWorkspace,
         };
+        const shouldProjectClaudeBrief = input.provider === 'claude' && input.projectionStrategy === 'file-brief';
+        const claudeProjectedBriefContent = shouldProjectClaudeBrief
+            ? buildClaudeFileBrief(buildPromptContextForClaudeProjectedBrief({
+                ...preparedContext,
+                claudeProjectedBriefPath,
+            }))
+            : undefined;
+        if (claudeProjectedBriefContent) {
+            preparedContext.claudeProjectedBriefPath = claudeProjectedBriefPath;
+            preparedContext.claudeProjectedBriefHash = hashUtf8Content(claudeProjectedBriefContent);
+        }
         try {
             await this.fileSystem.mkdir(directoryPath, { recursive: true, mode: 0o700 });
-            if (taskWorkspace) {
-                await this.fileSystem.mkdir(taskWorkspace.rootPath, { recursive: true, mode: 0o700 });
-                taskWorkspaceMaterialized = true;
+            await this.fileSystem.mkdir(resolvedWorkspace.rootPath, { recursive: true, mode: 0o700 });
+            resolvedWorkspaceMaterialized = true;
+            await pruneGatewayCredentialSidecars(this.fileSystem, directoryPath, gatewayCredential ? CHANNEL_GATEWAY_CREDENTIAL_FILENAME : undefined);
+            if (!claudeProjectedBriefContent) {
+                await unlinkIfPresent(this.fileSystem, claudeProjectedBriefPath);
             }
-            await pruneLegacyGatewayAuthSidecars(this.fileSystem, directoryPath);
             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 (claudeProjectedBriefContent) {
+                const stagingProjectedBriefPath = join(directoryPath, `.claude-file-brief.${randomUUID()}.md`);
+                await this.fileSystem.writeFile(stagingProjectedBriefPath, claudeProjectedBriefContent, { encoding: 'utf8', mode: 0o600 });
+                await this.fileSystem.rename(stagingProjectedBriefPath, claudeProjectedBriefPath);
+                claudeProjectedBriefWritten = true;
+            }
             if (issuedLocalhostGateway) {
                 this.localhostGateway?.publishPayload(input.channelId, payloadPath, payload);
             }
             return preparedContext;
         }
         catch (error) {
+            if (claudeProjectedBriefContent && !claudeProjectedBriefWritten) {
+                await unlinkIfPresent(this.fileSystem, claudeProjectedBriefPath);
+            }
             const partialContext = {
                 directoryPath,
                 payload,
+                claudeProjectedBriefPath: claudeProjectedBriefWritten ? claudeProjectedBriefPath : undefined,
+                claudeProjectedBriefHash: claudeProjectedBriefWritten ? preparedContext.claudeProjectedBriefHash : undefined,
                 payloadPath: payloadWritten ? payloadPath : undefined,
-                gatewayAuthPath: gatewayAuthWritten ? gatewayAuthPath : undefined,
+                gatewayCredentialPath: gatewayCredentialWritten ? gatewayCredentialPath : undefined,
                 skillRuntime: payloadWritten ? skillRuntime : undefined,
                 localhostGateway: payloadWritten ? localhostGateway : undefined,
-                taskWorkspace: taskWorkspaceMaterialized ? taskWorkspace : undefined,
+                resolvedWorkspace: resolvedWorkspaceMaterialized ? resolvedWorkspace : undefined,
             };
             throw new ChannelContextPreparationError('failed to persist channel context payload', partialContext, { cause: error });
         }

package/dist/context/main-session-delegation.d.ts

@@ -1 +1 @@
-export declare const MAIN_SESSION_DELEGATION_LINES: readonly string[];
+export declare const MAIN_SESSION_DELEGATION_LINES: readonly ["This session is your coordination surface: read the channel, answer the human, break work down, and keep task state current here.", "Delegate the actual work to subagents — research, code edits, long builds and test runs, and broad repository sweeps belong in a delegated worker instead of running inline here.", "Delegation changes who executes, not who owns: the work still belongs to this thread, and you still report the result here yourself.", "Stay responsive while delegated work runs, so a new incoming message never waits behind a long local operation."];

package/dist/context/projection-strategy.d.ts

@@ -0,0 +1,24 @@
+import type { DebugLogger } from '../debug.js';
+import type { ChatControlPlane } from '../chat/chat-control-plane.js';
+import type { ProjectionStrategy } from '../types.js';
+interface ProjectionStrategyResolverOptions {
+    baseUrl?: string;
+    agentApiKey?: string;
+    resolveStableAgentId?: () => string | undefined;
+    fetch?: typeof fetch;
+    fallback?: () => ProjectionStrategy;
+    logger?: Pick<DebugLogger, 'error'>;
+    taskReader?: Pick<ChatControlPlane, 'getTask' | 'listChannels' | 'listTasks'>;
+}
+export declare class ServerProjectionStrategyResolver {
+    private readonly options;
+    private readonly strategyCache;
+    private readonly channelAliases;
+    private readonly fetchImpl;
+    private readonly fallback;
+    constructor(options: ProjectionStrategyResolverOptions);
+    resolve(channelId: string): Promise<ProjectionStrategy>;
+    private resolveCachedStrategy;
+    private resolveEffectiveCacheKey;
+}
+export {};