@borgee/agents-host 0.2.44 → 0.2.62

package/dist/context/injection.js

@@ -1,11 +1,23 @@
-import { promises as fs } from 'node:fs';
-import { randomUUID } from 'node:crypto';
+import { constants as fsConstants, 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 TASK_ASSIGNMENT_STATE_ROOT_DIRNAME = 'task-assignment-state';
+const TASK_ASSIGNMENT_STATE_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_THREAD_SCRATCH_WORKSPACE_DIRNAME = 'scratch';
+const TASK_EXECUTION_LOCAL_DIRECTORY_PROPERTY_KEY = 'execution.local_directory';
+const DEFAULT_TASK_WORKSPACE_RESOLUTION_TIMEOUT_MS = 1_500;
 export class ChannelContextPreparationError extends Error {
     partialContext;
     constructor(message, partialContext, options) {
@@ -33,8 +45,11 @@ const DEFAULT_FILE_SYSTEM = {
     async rename(oldPath, newPath) {
         await fs.rename(oldPath, newPath);
     },
-    async access(path) {
-        await fs.access(path);
+    async access(path, mode) {
+        await fs.access(path, mode);
+    },
+    async stat(path) {
+        return await fs.stat(path);
     },
 };
 const BORGEE_AGENT_SKILL_DIRNAME = 'borgee-agent';
@@ -62,19 +77,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 +142,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;
@@ -123,9 +236,9 @@ function buildTaskAssignmentContextForTurn(options, existingContext) {
     }
     return existingContext;
 }
-async function readExistingTaskAssignmentContext(payloadPath, fileSystem) {
+async function readExistingTaskAssignmentContext(statePath, fileSystem) {
     try {
-        const raw = await fileSystem.readFile(payloadPath, { encoding: 'utf8' });
+        const raw = await fileSystem.readFile(statePath, { encoding: 'utf8' });
         const payload = JSON.parse(raw);
         return sanitizeTaskAssignmentContext(payload.taskAssignmentContext);
     }
@@ -133,6 +246,127 @@ async function readExistingTaskAssignmentContext(payloadPath, fileSystem) {
         return undefined;
     }
 }
+function buildChannelResolvedWorkspace(workspaceCollectionRootDir, channelId) {
+    return {
+        authority: 'channel',
+        owningChannelId: channelId,
+        rootPath: resolveChannelWorkspaceDirectory(workspaceCollectionRootDir, channelId),
+    };
+}
+function buildTaskThreadScratchResolvedWorkspace(workspaceCollectionRootDir, channelId, reason = 'missing-or-invalid-execution-target') {
+    return {
+        authority: 'task-thread-scratch',
+        rootPath: resolveTaskThreadScratchWorkspaceDirectory(workspaceCollectionRootDir, channelId),
+        reason,
+    };
+}
+async function isCrossAgentTaskCreatedByAnotherAgent(params) {
+    const selfAgentId = params.resolveStableAgentId?.()?.trim();
+    if (!selfAgentId) {
+        return true;
+    }
+    if (params.task.createdBy === selfAgentId) {
+        return false;
+    }
+    if (!params.taskReader) {
+        return true;
+    }
+    const users = await params.taskReader.listUsers();
+    const creator = users.find((user) => user.id === params.task.createdBy);
+    if (!creator) {
+        return true;
+    }
+    return creator.kind === 'agent';
+}
+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);
+        }
+    }
+}
+async function isExistingDirectory(fileSystem, path) {
+    if (!isAbsolute(path)) {
+        return false;
+    }
+    try {
+        await fileSystem.access(path, fsConstants.R_OK | fsConstants.W_OK | fsConstants.X_OK);
+        if (typeof fileSystem.stat !== 'function') {
+            return true;
+        }
+        return (await fileSystem.stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function resolveTaskThreadWorkspaceContext(params) {
+    const channelWorkspace = buildChannelResolvedWorkspace(params.workspaceCollectionRootDir, params.channelId);
+    const discussionOnlyWorkspace = buildTaskThreadScratchResolvedWorkspace(params.workspaceCollectionRootDir, params.channelId);
+    const taskAssignmentContext = params.taskAssignmentContext;
+    const currentTaskId = taskAssignmentContext?.currentTaskId?.trim();
+    if (taskAssignmentContext?.active !== true) {
+        return { taskAssignmentContext, resolvedWorkspace: channelWorkspace };
+    }
+    if (!currentTaskId || !params.taskReader) {
+        return { taskAssignmentContext, resolvedWorkspace: discussionOnlyWorkspace };
+    }
+    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: discussionOnlyWorkspace,
+            };
+        }
+        const executionLocalDirectory = task.properties[TASK_EXECUTION_LOCAL_DIRECTORY_PROPERTY_KEY];
+        if (typeof executionLocalDirectory !== 'string'
+            || executionLocalDirectory.length === 0
+            || !(await isExistingDirectory(params.fileSystem, executionLocalDirectory))) {
+            return {
+                taskAssignmentContext,
+                resolvedWorkspace: discussionOnlyWorkspace,
+            };
+        }
+        if (!params.allowCrossAgentIndependentWorkspaceHandoff
+            && await isCrossAgentTaskCreatedByAnotherAgent({
+                task,
+                taskReader: params.taskReader,
+                resolveStableAgentId: params.resolveStableAgentId,
+            })) {
+            return {
+                taskAssignmentContext,
+                resolvedWorkspace: buildTaskThreadScratchResolvedWorkspace(params.workspaceCollectionRootDir, params.channelId, 'cross-agent-independent-workspace-disabled'),
+            };
+        }
+        return {
+            taskAssignmentContext,
+            resolvedWorkspace: {
+                authority: 'task-execution-target',
+                taskId: task.id,
+                rootPath: executionLocalDirectory,
+            },
+        };
+    }
+    catch (error) {
+        return {
+            taskAssignmentContext,
+            resolvedWorkspace: discussionOnlyWorkspace,
+        };
+    }
+}
 export function encodeChannelPathSegment(channelId) {
     const encoded = Buffer.from(channelId, 'utf8').toString('hex');
     return encoded.length > 0 ? encoded : 'empty';
@@ -143,11 +377,38 @@ export function resolveChannelContextDirectory(stateRootDir, channelId) {
 export function resolveChannelContextPayloadPath(stateRootDir, channelId) {
     return join(resolveChannelContextDirectory(stateRootDir, channelId), CHANNEL_CONTEXT_PAYLOAD_FILENAME);
 }
+export function resolveTaskAssignmentStateDirectory(stateRootDir, channelId) {
+    return resolve(stateRootDir, TASK_ASSIGNMENT_STATE_ROOT_DIRNAME, encodeChannelPathSegment(channelId));
+}
+export function resolveTaskAssignmentStatePath(stateRootDir, channelId) {
+    return join(resolveTaskAssignmentStateDirectory(stateRootDir, channelId), TASK_ASSIGNMENT_STATE_FILENAME);
+}
 export function resolveTaskWorkspaceRootDirectory(startupWorkspaceRootDir) {
-    return join(resolve(startupWorkspaceRootDir), TASK_WORKSPACE_ROOT_DIRNAME);
+    return join(resolve(startupWorkspaceRootDir), TASK_ISOLATED_WORKSPACE_COLLECTION_DIRNAME);
 }
-export function resolveTaskWorkspaceDirectory(startupWorkspaceRootDir, channelId, taskId) {
-    return join(resolveTaskWorkspaceRootDirectory(startupWorkspaceRootDir), encodeChannelPathSegment(channelId), encodeChannelPathSegment(taskId));
+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 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 resolveTaskThreadScratchWorkspaceDirectory(workspaceCollectionRootDir, channelId) {
+    return join(resolveChannelWorkspaceRootDirectory(workspaceCollectionRootDir, channelId), TASK_THREAD_SCRATCH_WORKSPACE_DIRNAME, CHANNEL_WORKSPACE_DIRNAME);
 }
 export function resolveChannelGatewayCredentialPath(stateRootDir, channelId) {
     return join(resolveChannelContextDirectory(stateRootDir, channelId), CHANNEL_GATEWAY_CREDENTIAL_FILENAME);
@@ -155,6 +416,9 @@ export function resolveChannelGatewayCredentialPath(stateRootDir, channelId) {
 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 +509,23 @@ export class FileChannelContextStore {
     skillRuntimeEnabled;
     skillAssetResolver;
     localhostGateway;
-    startupWorkspaceRootDir;
+    workspaceCollectionRootDir;
+    taskReader;
+    taskResolutionTimeoutMs;
+    allowCrossAgentIndependentWorkspaceHandoff;
+    resolveStableAgentId;
     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;
+        this.allowCrossAgentIndependentWorkspaceHandoff
+            = options.allowCrossAgentIndependentWorkspaceHandoff ?? true;
+        this.resolveStableAgentId = options.resolveStableAgentId;
     }
     async prepare(inputOrChannelId, options) {
         const input = typeof inputOrChannelId === 'string'
@@ -264,8 +537,10 @@ export class FileChannelContextStore {
         const auxiliaryCollaborationEnabled = collaborationCommandsEnabled && collaborationRoutesAllowedForTurnMode;
         const directoryPath = resolveChannelContextDirectory(this.stateRootDir, input.channelId);
         const payloadPath = resolveChannelContextPayloadPath(this.stateRootDir, input.channelId);
+        const taskAssignmentStatePath = resolveTaskAssignmentStatePath(this.stateRootDir, input.channelId);
+        const claudeProjectedBriefPath = resolveClaudeProjectedBriefPathFromPayloadPath(payloadPath);
         const gatewayCredentialPath = resolveGatewayCredentialPathFromPayloadPath(payloadPath);
-        const existingTaskAssignmentContext = await readExistingTaskAssignmentContext(payloadPath, this.fileSystem);
+        const existingTaskAssignmentContext = await readExistingTaskAssignmentContext(taskAssignmentStatePath, this.fileSystem);
         const skillRuntime = this.skillRuntimeEnabled
             ? await this.resolveSkillRuntimeBestEffort()
             : undefined;
@@ -291,24 +566,41 @@ export class FileChannelContextStore {
                     : {}),
             }
             : undefined;
-        const taskAssignmentContext = buildTaskAssignmentContextForTurn({
-            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 taskAssignmentContext = input.taskAssignmentContextOverride
+            ?? buildTaskAssignmentContextForTurn({
+                incomingMessageType: input.incomingMessageType,
+                incomingContent: input.incomingContent,
+            }, existingTaskAssignmentContext);
+        const workspaceResolution = await resolveTaskThreadWorkspaceContext({
+            channelId: input.channelId,
+            workspaceCollectionRootDir: this.workspaceCollectionRootDir,
+            taskAssignmentContext,
+            taskReader: this.taskReader,
+            taskResolutionTimeoutMs: this.taskResolutionTimeoutMs,
+            allowCrossAgentIndependentWorkspaceHandoff: this.allowCrossAgentIndependentWorkspaceHandoff,
+            resolveStableAgentId: this.resolveStableAgentId,
+            fileSystem: this.fileSystem,
+        });
+        const resolvedWorkspace = workspaceResolution.resolvedWorkspace;
+        const runtimeTaskAssignmentContext = workspaceResolution.taskAssignmentContext ?? taskAssignmentContext;
+        const persistedTaskAssignmentContext = input.taskAssignmentContextOverridePersistence === 'ephemeral'
+            ? existingTaskAssignmentContext
+            : runtimeTaskAssignmentContext;
+        const runtimeSurface = buildRuntimeSurfaceForTurn({
+            localhostGateway,
+            collaboration: input.collaboration,
+            taskAssignmentContext: runtimeTaskAssignmentContext,
+        });
+        const payload = buildChannelContextPayload(input.channelId, runtimeSurface, input.collaborationOutcome, input.attentionSnapshot, input.compactionSnapshot, input.taskThreadCollaborationContract, input.collaborationCapabilities, input.missedCollaborationDiagnostic, skillRuntime, localhostGateway, persistedTaskAssignmentContext || resolvedWorkspace
             ? {
-                ...(taskAssignmentContext ? { taskAssignmentContext } : {}),
-                ...(taskWorkspace ? { taskWorkspace } : {}),
+                ...(persistedTaskAssignmentContext
+                    ? { taskAssignmentContext: persistedTaskAssignmentContext }
+                    : {}),
+                resolvedWorkspace,
             }
             : undefined);
         const gatewayCredential = buildBorgeeAgentGatewayCredential(input.channelId, issuedLocalhostGateway);
-        let taskWorkspaceMaterialized = false;
+        let claudeProjectedBriefWritten = false;
         let payloadWritten = false;
         let gatewayCredentialWritten = false;
         const preparedContext = {
@@ -318,17 +610,39 @@ 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(resolveTaskAssignmentStateDirectory(this.stateRootDir, input.channelId), { recursive: true, mode: 0o700 });
+            if (resolvedWorkspace.authority !== 'task-execution-target') {
+                await this.fileSystem.mkdir(resolvedWorkspace.rootPath, { recursive: true, mode: 0o700 });
             }
             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 (persistedTaskAssignmentContext) {
+                const stagingTaskAssignmentStatePath = join(resolveTaskAssignmentStateDirectory(this.stateRootDir, input.channelId), `.task-assignment-state.${randomUUID()}.json`);
+                await this.fileSystem.writeFile(stagingTaskAssignmentStatePath, `${JSON.stringify({ taskAssignmentContext: persistedTaskAssignmentContext }, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+                await this.fileSystem.rename(stagingTaskAssignmentStatePath, taskAssignmentStatePath);
+            }
+            else {
+                await unlinkIfPresent(this.fileSystem, taskAssignmentStatePath);
+            }
             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
@@ -342,20 +656,40 @@ 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,
+                payload: {
+                    ...payload,
+                    ...(resolvedWorkspace.authority === 'task-execution-target' && runtimeTaskAssignmentContext?.active === true
+                        ? {
+                            resolvedWorkspace: buildTaskThreadScratchResolvedWorkspace(this.workspaceCollectionRootDir, input.channelId),
+                        }
+                        : {}),
+                },
+                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: resolvedWorkspace.authority === 'task-execution-target' && runtimeTaskAssignmentContext?.active === true
+                    ? buildTaskThreadScratchResolvedWorkspace(this.workspaceCollectionRootDir, input.channelId)
+                    : resolvedWorkspace,
             };
             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}`;
+    }
+}