@borgee/agents-host 0.2.44 → 0.2.56

package/dist/context/injection.js

@@ -1,11 +1,21 @@
 import { promises as fs } from 'node:fs';
-import { randomUUID } from 'node:crypto';
+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_GATEWAY_CREDENTIAL_FILENAME = '.borgee-agent-gateway.json';
-const TASK_WORKSPACE_ROOT_DIRNAME = '.borgee-task-workspaces';
+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) {
@@ -62,19 +72,50 @@ function buildBorgeeAgentGatewayCredential(channelId, localhostGateway) {
         },
     };
 }
-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) {
@@ -96,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;
@@ -133,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';
@@ -144,17 +374,38 @@ 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 resolveTaskIsolatedWorkspaceDirectory(workspaceCollectionRootDir, channelId, taskId) {
+    return join(resolveTaskWorkspaceRootDirectory(resolveChannelWorkspaceRootDirectory(workspaceCollectionRootDir, channelId)), encodeChannelPathSegment(taskId), CHANNEL_WORKSPACE_DIRNAME);
+}
+export const resolveTaskWorkspaceDirectory = resolveTaskIsolatedWorkspaceDirectory;
 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 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
@@ -245,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'
@@ -264,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 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;
@@ -295,20 +552,31 @@ 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 gatewayCredential = buildBorgeeAgentGatewayCredential(input.channelId, issuedLocalhostGateway);
-        let taskWorkspaceMaterialized = false;
+        let resolvedWorkspaceMaterialized = false;
+        let claudeProjectedBriefWritten = false;
         let payloadWritten = false;
         let gatewayCredentialWritten = false;
         const preparedContext = {
@@ -318,15 +586,27 @@ export class FileChannelContextStore {
             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 this.fileSystem.writeFile(payloadPath, `${JSON.stringify(payload, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
             payloadWritten = true;
             if (gatewayCredential) {
@@ -342,20 +622,31 @@ export class FileChannelContextStore {
             else {
                 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,
                 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 {};

package/dist/context/projection-strategy.js

@@ -0,0 +1,90 @@
+import { DEFAULT_PROJECTION_STRATEGY, normalizeProjectionStrategy, } from '../projection-strategy-values.js';
+import { findTaskForThread } from '../task-thread-resolution.js';
+export class ServerProjectionStrategyResolver {
+    options;
+    strategyCache = new Map();
+    channelAliases = new Map();
+    fetchImpl;
+    fallback;
+    constructor(options) {
+        this.options = options;
+        this.fetchImpl = options.fetch ?? fetch;
+        this.fallback = options.fallback ?? (() => DEFAULT_PROJECTION_STRATEGY);
+    }
+    async resolve(channelId) {
+        const baseUrl = this.options.baseUrl?.trim();
+        const agentApiKey = this.options.agentApiKey?.trim();
+        const agentId = this.options.resolveStableAgentId?.()?.trim();
+        if (!baseUrl || !agentApiKey || !agentId) {
+            return this.fallback();
+        }
+        const cacheKey = `${agentId}::${channelId}`;
+        const url = new URL(`/api/v1/agents/${encodeURIComponent(agentId)}/channels/${encodeURIComponent(channelId)}/projection-strategy`, baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`);
+        try {
+            const response = await this.fetchImpl(url.toString(), {
+                headers: {
+                    Authorization: `Bearer ${agentApiKey}`,
+                },
+            });
+            if (response.status === 404) {
+                const effectiveCacheKey = await this.resolveEffectiveCacheKey(agentId, channelId, cacheKey);
+                this.channelAliases.set(cacheKey, effectiveCacheKey);
+                this.strategyCache.set(effectiveCacheKey, DEFAULT_PROJECTION_STRATEGY);
+                return DEFAULT_PROJECTION_STRATEGY;
+            }
+            if (!response.ok) {
+                throw new Error(`server returned ${response.status} ${response.statusText}`.trim());
+            }
+            const body = await response.json();
+            const strategy = normalizeProjectionStrategy(typeof body.projection_strategy === 'string' ? body.projection_strategy : undefined);
+            if (!strategy) {
+                throw new Error('server returned an invalid projection strategy');
+            }
+            const effectiveChannelId = typeof body.channel_id === 'string' && body.channel_id.length > 0
+                ? body.channel_id
+                : channelId;
+            const effectiveCacheKey = `${agentId}::${effectiveChannelId}`;
+            this.channelAliases.set(cacheKey, effectiveCacheKey);
+            this.strategyCache.set(effectiveCacheKey, strategy);
+            return strategy;
+        }
+        catch (error) {
+            const cached = await this.resolveCachedStrategy(agentId, channelId, cacheKey);
+            if (cached) {
+                return cached;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            this.options.logger?.error('failed to resolve server-backed projection strategy; using fallback', {
+                agentId,
+                channelId,
+                error: message,
+            });
+            return DEFAULT_PROJECTION_STRATEGY;
+        }
+    }
+    async resolveCachedStrategy(agentId, channelId, cacheKey) {
+        const direct = this.strategyCache.get(this.channelAliases.get(cacheKey) ?? cacheKey);
+        if (direct) {
+            return direct;
+        }
+        if (!this.options.taskReader) {
+            return undefined;
+        }
+        const effectiveCacheKey = await this.resolveEffectiveCacheKey(agentId, channelId, cacheKey);
+        if (effectiveCacheKey === cacheKey) {
+            return undefined;
+        }
+        this.channelAliases.set(cacheKey, effectiveCacheKey);
+        return this.strategyCache.get(effectiveCacheKey);
+    }
+    async resolveEffectiveCacheKey(agentId, channelId, cacheKey) {
+        if (!this.options.taskReader) {
+            return cacheKey;
+        }
+        const task = await findTaskForThread(this.options.taskReader, channelId);
+        if (!task?.channelId) {
+            return cacheKey;
+        }
+        return `${agentId}::${task.channelId}`;
+    }
+}

package/dist/context/prompt.d.ts

@@ -1,4 +1,4 @@
-import type { PreparedPromptContext, ProviderKind } from '../types.js';
+import type { ProjectionStrategy, PreparedPromptContext, ProviderKind } from '../types.js';
 /**
  * Builds the per-turn prompt. Conversation memory is intentionally NOT
  * assembled here: each provider's CLI client resumes a native per-channel
@@ -16,3 +16,18 @@ export declare function buildPrompt(params: {
     incomingMessageType?: string;
     promptContext?: PreparedPromptContext;
 }): string;
+export declare function buildClaudeSessionPromptAppend(params: {
+    agentName: string;
+    promptContext?: PreparedPromptContext;
+    promptStrategy?: ProjectionStrategy;
+}): string | undefined;
+export declare function buildClaudeTurnPrompt(params: {
+    agentName?: string;
+    channelId: string;
+    incomingAuthorId: string;
+    incomingContent: string;
+    incomingEventKind?: string;
+    incomingMessageType?: string;
+    promptContext?: PreparedPromptContext;
+    promptStrategy?: ProjectionStrategy;
+}): string;