@borgee/agents-host 0.2.73 → 0.2.84

package/dist/background-runs.js

@@ -0,0 +1,153 @@
+import { createHash } from 'node:crypto';
+const STOP_UNSUPPORTED_REASON = 'This provider does not support targeted background-run cancellation';
+const MAX_TRACKED_RUNS = 128;
+export class BackgroundRunTracker {
+    report;
+    options;
+    now;
+    mintRunId;
+    runs = new Map();
+    runsById = new Map();
+    constructor(report, options, now = Date.now, mintRunId = stableRunId) {
+        this.report = report;
+        this.options = options;
+        this.now = now;
+        this.mintRunId = mintRunId;
+    }
+    observe(channelId, update) {
+        if (!this.options.lifecycleSupported || update.type !== 'background_run')
+            return;
+        const key = `${channelId}\0${update.run.providerRunId}`;
+        const held = this.runs.get(key);
+        const state = runState(update.run.state);
+        const stopSupported = update.run.stopSupported &&
+            this.options.targetedCancellationSupported &&
+            this.options.cancel !== undefined;
+        const executionChanged = held !== undefined &&
+            update.run.startedAt !== undefined &&
+            update.run.startedAt !== held.startedAt;
+        const startsNewExecution = !held || executionChanged || (isTerminal(held.state) && !isTerminal(state));
+        if (held && isTerminal(held.state) && isTerminal(state) && !startsNewExecution)
+            return;
+        const startedAt = startsNewExecution
+            ? (update.run.startedAt ?? this.now())
+            : (update.run.startedAt ?? held.startedAt);
+        const run = startsNewExecution
+            ? {
+                channelId,
+                providerRunId: update.run.providerRunId,
+                runId: this.mintRunId(channelId, update.run.providerRunId, startedAt),
+                label: update.run.label,
+                state,
+                startedAt,
+                finishedAt: update.run.finishedAt,
+                reason: update.run.reason,
+                stopSupported,
+            }
+            : {
+                ...held,
+                label: update.run.label,
+                state,
+                startedAt,
+                finishedAt: update.run.finishedAt,
+                reason: update.run.reason,
+                stopSupported,
+            };
+        if (isTerminal(state) && run.finishedAt === undefined) {
+            run.finishedAt = this.now();
+        }
+        if (held && held.runId !== run.runId) {
+            this.runsById.delete(held.runId);
+        }
+        this.runs.delete(key);
+        this.runs.set(key, run);
+        this.runsById.set(run.runId, run);
+        while (this.runs.size > MAX_TRACKED_RUNS) {
+            const oldestKey = this.runs.keys().next().value;
+            if (typeof oldestKey !== 'string') {
+                break;
+            }
+            const oldest = this.runs.get(oldestKey);
+            this.runs.delete(oldestKey);
+            if (oldest) {
+                this.runsById.delete(oldest.runId);
+            }
+        }
+        this.publish(run);
+    }
+    async stop(channelId, runId) {
+        if (!this.options.lifecycleSupported ||
+            !this.options.targetedCancellationSupported ||
+            !this.options.cancel) {
+            return {
+                outcome: 'unsupported',
+                reason: STOP_UNSUPPORTED_REASON,
+            };
+        }
+        const run = this.runsById.get(runId);
+        if (!run || run.channelId !== channelId || isTerminal(run.state)) {
+            return { outcome: 'not_found' };
+        }
+        if (!run.stopSupported) {
+            return {
+                outcome: 'unsupported',
+                reason: STOP_UNSUPPORTED_REASON,
+            };
+        }
+        if (!(await this.options.cancel(channelId, run.providerRunId))) {
+            return { outcome: 'not_found' };
+        }
+        const current = this.runsById.get(runId);
+        if (current && current.channelId === channelId && !isTerminal(current.state)) {
+            current.state = 'stopping';
+            this.publish(current);
+        }
+        return { outcome: 'stopped' };
+    }
+    publish(run) {
+        this.report(run.channelId, {
+            shape: 'background_run',
+            runId: run.runId,
+            label: run.label,
+            state: run.state,
+            startedAt: run.startedAt,
+            ...(run.finishedAt !== undefined ? { finishedAt: run.finishedAt } : {}),
+            ...(run.reason ? { reason: run.reason } : {}),
+            stopSupported: run.stopSupported,
+            ...(!run.stopSupported ? { stopUnsupportedReason: STOP_UNSUPPORTED_REASON } : {}),
+        });
+    }
+}
+function runState(status) {
+    switch (status) {
+        case 'running':
+            return 'running';
+        case 'waiting':
+            return 'waiting';
+        case 'completed':
+            return 'completed';
+        case 'failed':
+            return 'failed';
+        case 'cancelled':
+            return 'cancelled';
+        case 'unknown':
+            return 'unknown';
+    }
+}
+function isTerminal(state) {
+    return (state === 'completed' ||
+        state === 'failed' ||
+        state === 'cancelled' ||
+        state === 'unknown');
+}
+function stableRunId(channelId, providerRunId, startedAt) {
+    const digest = createHash('sha256')
+        .update(channelId)
+        .update('\0')
+        .update(providerRunId)
+        .update('\0')
+        .update(String(startedAt))
+        .digest('hex')
+        .slice(0, 32);
+    return `run_${digest}`;
+}

package/dist/chat/chat-control-plane.d.ts

@@ -1,7 +1,8 @@
-import type { ReportTurnActivityInput, StopTurnHandler, TurnActivityReporter } from '../plugin-sdk.js';
+import type { AgentActivity, ReportTurnActivityInput, StopBackgroundRunHandler, StopTurnHandler, TurnActivityReporter } from '../plugin-sdk.js';
 import type { ChannelSummary, ChannelHistoryEntry, ChannelMessageEvent, CreateTaskInput, DirectoryUser, MeResponseUser, PostMessageInput, PostedMessage, ReadChannelHistoryInput, Task, UpdateTaskInput } from '../types.js';
 export interface ChatControlPlane {
     onStopTurn?(handler: StopTurnHandler | undefined): void;
+    onStopBackgroundRun?(handler: StopBackgroundRunHandler | undefined): void;
     connect(onMessage: (message: ChannelMessageEvent) => void): Promise<void>;
     close(): Promise<void>;
     postMessage(input: PostMessageInput): Promise<PostedMessage>;
@@ -10,6 +11,10 @@ export interface ChatControlPlane {
     startTyping(channelId: string): () => void;
     /** Opens one turn's report on the activity rail. Fire-and-forget: nothing recovers what it sends. */
     reportTurnActivity(input: ReportTurnActivityInput): TurnActivityReporter;
+    reportActivity?(input: {
+        channelId: string;
+        activity: AgentActivity;
+    }): void;
     getMe(): Promise<MeResponseUser>;
     listUsers(): Promise<DirectoryUser[]>;
     listChannels(): Promise<ChannelSummary[]>;

package/dist/chat/sdk-chat-control-plane.d.ts

@@ -1,7 +1,7 @@
-import { type BorgeePluginClient, type BorgeePluginOptions, type InboundMessageEvent, type ReportTurnActivityInput, type StopTurnHandler, type TurnActivityReporter } from '../plugin-sdk.js';
+import { type BorgeePluginClient, type BorgeePluginOptions, type InboundMessageEvent, type ReportTurnActivityInput, type StopTurnHandler, type StopBackgroundRunHandler, type TurnActivityReporter } from '../plugin-sdk.js';
 import type { ChannelSummary, ChannelHistoryEntry, ChannelMessageEvent, CreateTaskInput, DirectoryUser, MeResponseUser, PostMessageInput, PostedMessage, ReadChannelHistoryInput, Task, UpdateTaskInput } from '../types.js';
 import type { ChatControlPlane } from './chat-control-plane.js';
-type PluginClientLike = Pick<BorgeePluginClient, 'agentId' | 'close' | 'connect' | 'createTask' | 'deleteMessage' | 'editMessage' | 'getMe' | 'getTask' | 'listChannels' | 'listTasks' | 'listUsers' | 'on' | 'onStopTurn' | 'readHistory' | 'reportTurnActivity' | 'sendMessage' | 'startTyping' | 'updateTask' | 'setTaskProperty' | 'deleteTaskProperty'>;
+type PluginClientLike = Pick<BorgeePluginClient, 'agentId' | 'close' | 'connect' | 'createTask' | 'deleteMessage' | 'editMessage' | 'getMe' | 'getTask' | 'listChannels' | 'listTasks' | 'listUsers' | 'on' | 'onStopTurn' | 'onStopBackgroundRun' | 'reportActivity' | 'readHistory' | 'reportTurnActivity' | 'sendMessage' | 'startTyping' | 'updateTask' | 'setTaskProperty' | 'deleteTaskProperty'>;
 type PluginClientFactory = (options: BorgeePluginOptions) => PluginClientLike;
 type SdkChatControlPlaneOptions = Pick<BorgeePluginOptions, 'pluginId'>;
 /**
@@ -17,9 +17,11 @@ export declare class SdkChatControlPlane implements ChatControlPlane {
     private me;
     constructor(baseUrl: string, apiKey: string, createClient?: PluginClientFactory, options?: SdkChatControlPlaneOptions);
     onStopTurn(handler: StopTurnHandler | undefined): void;
+    onStopBackgroundRun(handler: StopBackgroundRunHandler | undefined): void;
     connect(onMessage: (message: ChannelMessageEvent) => void): Promise<void>;
     close(): Promise<void>;
     postMessage(input: PostMessageInput): Promise<PostedMessage>;
+    reportActivity(input: Parameters<BorgeePluginClient['reportActivity']>[0]): void;
     editMessage(messageId: string, content: string): Promise<void>;
     deleteMessage(messageId: string): Promise<void>;
     startTyping(channelId: string): () => void;

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

@@ -17,6 +17,9 @@ export class SdkChatControlPlane {
     onStopTurn(handler) {
         this.client.onStopTurn(handler);
     }
+    onStopBackgroundRun(handler) {
+        this.client.onStopBackgroundRun?.(handler);
+    }
     async connect(onMessage) {
         this.unsubscribe = this.client.on('message', (event) => {
             const message = mapInboundToChannelMessage(event);
@@ -50,6 +53,7 @@ export class SdkChatControlPlane {
         this.unsubscribe?.();
         this.unsubscribe = null;
         this.client.onStopTurn(undefined);
+        this.client.onStopBackgroundRun?.(undefined);
         await this.client.close();
     }
     async postMessage(input) {
@@ -60,6 +64,9 @@ export class SdkChatControlPlane {
         });
         return { messageId: sent.messageId };
     }
+    reportActivity(input) {
+        this.client.reportActivity(input);
+    }
     async editMessage(messageId, content) {
         await this.client.editMessage({ messageId, body: content });
     }

package/dist/context/claude-file-brief.js

@@ -1,6 +1,6 @@
 import { buildCollaborationCapabilityDeclarationSummaryLines, } from './collaboration-capabilities-diagnostics.js';
 import { MAIN_SESSION_DELEGATION_LINES } from './main-session-delegation.js';
-import { buildResolvedWorkspaceGuidanceLines } from './resolved-workspace.js';
+import { buildResolvedWorkingFolderGuidanceLines } from './resolved-working-folder.js';
 import { buildSkillManualLines, buildSkillManualReadLine } from './skill-manual.js';
 import { PARENT_CHANNEL_TASK_BOUNDARY_LINES } from './task-channel-boundary.js';
 function buildStableSkillLines(context) {
@@ -60,8 +60,8 @@ export function buildClaudeFileBrief(context) {
         '',
         ...sessionDelegationLines,
         ...(() => {
-            const workspaceLines = buildResolvedWorkspaceGuidanceLines(context);
-            return workspaceLines.length > 0 ? ['', ...workspaceLines] : [];
+            const workingFolderLines = buildResolvedWorkingFolderGuidanceLines(context);
+            return workingFolderLines.length > 0 ? ['', ...workingFolderLines] : [];
         })(),
         ...(() => {
             const capabilityLines = buildCollaborationCapabilityDeclarationSummaryLines(context?.collaborationCapabilities);

package/dist/context/injection.d.ts

@@ -1,5 +1,5 @@
 import type { ChatControlPlane } from '../chat/chat-control-plane.js';
-import type { AttentionSnapshot, ProjectionStrategy, CollaborationCapabilityDeclaration, CollaborationOutcomeSnapshot, CompactionSnapshot, LocalhostGatewayBootstrapMetadata, MissedCollaborationDiagnostic, ProviderKind, ProviderCollaborationContext, ResolvedWorkspaceContext, RuntimeSurface, SkillRuntimeBootstrapMetadata, TaskThreadCollaborationContract, TaskAssignmentThreadContext } from '../types.js';
+import type { AttentionSnapshot, ProjectionStrategy, CollaborationCapabilityDeclaration, CollaborationOutcomeSnapshot, CompactionSnapshot, LocalhostGatewayBootstrapMetadata, MissedCollaborationDiagnostic, ProviderKind, ProviderCollaborationContext, ResolvedWorkingFolderContext, RuntimeSurface, SkillRuntimeBootstrapMetadata, TaskThreadCollaborationContract, TaskAssignmentThreadContext } from '../types.js';
 export interface SkillRuntimeBootstrapPayload {
     skillDirectoryPath: string;
     nodeCliPath: string;
@@ -18,7 +18,13 @@ export interface ChannelContextPayload {
     skillRuntime?: SkillRuntimeBootstrapPayload;
     localhostGateway?: LocalhostGatewayBootstrapMetadata;
     taskAssignmentContext?: TaskAssignmentThreadContext;
-    resolvedWorkspace?: ResolvedWorkspaceContext;
+    /**
+     * Serialized into `context.json` and echoed by the gateway bootstrap response, so the key name is
+     * observable outside this process: `cleanup --purge` reads payloads written by whichever version
+     * happened to run last, and a payload whose key it does not recognize is skipped, silently leaving
+     * the directory it names on disk.
+     */
+    resolvedWorkspace?: ResolvedWorkingFolderContext;
 }
 export interface PreparedChannelContext {
     directoryPath: string;
@@ -29,7 +35,7 @@ export interface PreparedChannelContext {
     gatewayCredentialPath?: string;
     skillRuntime?: SkillRuntimeBootstrapMetadata;
     localhostGateway?: LocalhostGatewayBootstrapMetadata;
-    resolvedWorkspace?: ResolvedWorkspaceContext;
+    resolvedWorkingFolder?: ResolvedWorkingFolderContext;
 }
 export declare class ChannelContextPreparationError extends Error {
     readonly partialContext: PreparedChannelContext;
@@ -109,7 +115,7 @@ interface FileChannelContextStoreOptions {
     skillRuntimeEnabled?: boolean;
     skillAssetResolver?: SkillAssetResolver;
     localhostGateway?: LocalhostGatewayContextPublisher;
-    workspaceCollectionRootDir?: string;
+    workingFolderCollectionRootDir?: string;
     taskReader?: Pick<ChatControlPlane, 'getTask' | 'listChannels' | 'listTasks' | 'listUsers'>;
     taskResolutionTimeoutMs?: number;
     allowCrossAgentIndependentWorkspaceHandoff?: boolean;
@@ -128,13 +134,13 @@ export declare function resolveChannelContextDirectory(stateRootDir: string, cha
 export declare function resolveChannelContextPayloadPath(stateRootDir: string, channelId: string): string;
 export declare function resolveTaskAssignmentStateDirectory(stateRootDir: string, channelId: string): string;
 export declare function resolveTaskAssignmentStatePath(stateRootDir: string, channelId: string): string;
-export declare function resolveTaskWorkspaceRootDirectory(startupWorkspaceRootDir: string): string;
-export declare function resolveManagedWorkspaceCollectionRoot(workspaceCollectionRootDir: string | undefined, env?: NodeJS.ProcessEnv, resolvedHomeDir?: string): string;
-export declare function resolveChannelWorkspaceRootDirectory(workspaceCollectionRootDir: string, channelId: string): string;
-export declare function resolveChannelWorkspaceDirectory(workspaceCollectionRootDir: string, channelId: string): string;
-export declare function resolveTaskIsolatedWorkspaceDirectory(workspaceCollectionRootDir: string, channelId: string, taskId: string): string;
-export declare const resolveTaskWorkspaceDirectory: typeof resolveTaskIsolatedWorkspaceDirectory;
-export declare function resolveTaskThreadScratchWorkspaceDirectory(workspaceCollectionRootDir: string, channelId: string): string;
+export declare function resolveTaskWorkingFolderRootDirectory(channelRootDir: string): string;
+export declare function resolveManagedWorkingFolderCollectionRoot(workingFolderCollectionRootDir: string | undefined, env?: NodeJS.ProcessEnv, resolvedHomeDir?: string): string;
+export declare function resolveChannelWorkingFolderRootDirectory(workingFolderCollectionRootDir: string, channelId: string): string;
+export declare function resolveChannelWorkingFolderDirectory(workingFolderCollectionRootDir: string, channelId: string): string;
+export declare function resolveTaskIsolatedWorkingFolderDirectory(workingFolderCollectionRootDir: string, channelId: string, taskId: string): string;
+export declare const resolveTaskWorkingFolderDirectory: typeof resolveTaskIsolatedWorkingFolderDirectory;
+export declare function resolveTaskThreadScratchWorkingFolderDirectory(workingFolderCollectionRootDir: string, channelId: string): string;
 export declare function resolveChannelGatewayCredentialPath(stateRootDir: string, channelId: string): string;
 export declare function resolveGatewayCredentialPathFromPayloadPath(payloadPath: string): string;
 export declare function resolveClaudeProjectedBriefPathFromPayloadPath(payloadPath: string): string;
@@ -146,7 +152,7 @@ export declare class FileChannelContextStore implements ChannelContextStore {
     private readonly skillRuntimeEnabled;
     private readonly skillAssetResolver;
     private readonly localhostGateway?;
-    private readonly workspaceCollectionRootDir;
+    private readonly workingFolderCollectionRootDir;
     private readonly taskReader?;
     private readonly taskResolutionTimeoutMs;
     private readonly allowCrossAgentIndependentWorkspaceHandoff;

package/dist/context/injection.js

@@ -12,12 +12,12 @@ const TASK_ASSIGNMENT_STATE_FILENAME = 'context.json';
 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_THREAD_SCRATCH_WORKSPACE_DIRNAME = 'scratch';
+const CHANNEL_WORKING_FOLDER_COLLECTION_DIRNAME = 'channels';
+const CHANNEL_WORKING_FOLDER_DIRNAME = 'workspace';
+const TASK_ISOLATED_WORKING_FOLDER_COLLECTION_DIRNAME = 'tasks';
+const TASK_THREAD_SCRATCH_WORKING_FOLDER_DIRNAME = 'scratch';
 const TASK_EXECUTION_LOCAL_DIRECTORY_PROPERTY_KEY = 'execution.local_directory';
-const DEFAULT_TASK_WORKSPACE_RESOLUTION_TIMEOUT_MS = 1_500;
+const DEFAULT_TASK_WORKING_FOLDER_RESOLUTION_TIMEOUT_MS = 1_500;
 export class ChannelContextPreparationError extends Error {
     partialContext;
     constructor(message, partialContext, options) {
@@ -113,7 +113,7 @@ function buildPromptContextForClaudeProjectedBrief(preparedContext) {
         skillRuntime: preparedContext.skillRuntime,
         localhostGateway: preparedContext.localhostGateway,
         taskAssignmentContext: preparedContext.payload.taskAssignmentContext,
-        resolvedWorkspace: preparedContext.resolvedWorkspace,
+        resolvedWorkingFolder: preparedContext.resolvedWorkingFolder,
         runtimeSurface: preparedContext.payload.runtimeSurface,
         collaborationOutcome: preparedContext.payload.collaborationOutcome,
         attentionSnapshot: preparedContext.payload.attentionSnapshot,
@@ -246,17 +246,17 @@ async function readExistingTaskAssignmentContext(statePath, fileSystem) {
         return undefined;
     }
 }
-function buildChannelResolvedWorkspace(workspaceCollectionRootDir, channelId) {
+function buildChannelResolvedWorkingFolder(workingFolderCollectionRootDir, channelId) {
     return {
         authority: 'channel',
         owningChannelId: channelId,
-        rootPath: resolveChannelWorkspaceDirectory(workspaceCollectionRootDir, channelId),
+        rootPath: resolveChannelWorkingFolderDirectory(workingFolderCollectionRootDir, channelId),
     };
 }
-function buildTaskThreadScratchResolvedWorkspace(workspaceCollectionRootDir, channelId, reason = 'missing-or-invalid-execution-target') {
+function buildTaskThreadScratchResolvedWorkingFolder(workingFolderCollectionRootDir, channelId, reason = 'missing-or-invalid-execution-target') {
     return {
         authority: 'task-thread-scratch',
-        rootPath: resolveTaskThreadScratchWorkspaceDirectory(workspaceCollectionRootDir, channelId),
+        rootPath: resolveTaskThreadScratchWorkingFolderDirectory(workingFolderCollectionRootDir, channelId),
         reason,
     };
 }
@@ -312,23 +312,23 @@ async function isExistingDirectory(fileSystem, path) {
         return false;
     }
 }
-async function resolveTaskThreadWorkspaceContext(params) {
-    const channelWorkspace = buildChannelResolvedWorkspace(params.workspaceCollectionRootDir, params.channelId);
-    const discussionOnlyWorkspace = buildTaskThreadScratchResolvedWorkspace(params.workspaceCollectionRootDir, params.channelId);
+async function resolveTaskThreadWorkingFolderContext(params) {
+    const channelWorkingFolder = buildChannelResolvedWorkingFolder(params.workingFolderCollectionRootDir, params.channelId);
+    const discussionOnlyWorkingFolder = buildTaskThreadScratchResolvedWorkingFolder(params.workingFolderCollectionRootDir, params.channelId);
     const taskAssignmentContext = params.taskAssignmentContext;
     const currentTaskId = taskAssignmentContext?.currentTaskId?.trim();
     if (taskAssignmentContext?.active !== true) {
-        return { taskAssignmentContext, resolvedWorkspace: channelWorkspace };
+        return { taskAssignmentContext, resolvedWorkingFolder: channelWorkingFolder };
     }
     if (!currentTaskId || !params.taskReader) {
-        return { taskAssignmentContext, resolvedWorkspace: discussionOnlyWorkspace };
+        return { taskAssignmentContext, resolvedWorkingFolder: discussionOnlyWorkingFolder };
     }
     try {
-        const task = await withDeadline(findTaskForThread(params.taskReader, params.channelId, currentTaskId), params.taskResolutionTimeoutMs, `workspace resolution timed out for task ${currentTaskId}`);
+        const task = await withDeadline(findTaskForThread(params.taskReader, params.channelId, currentTaskId), params.taskResolutionTimeoutMs, `working folder resolution timed out for task ${currentTaskId}`);
         if (!task) {
             return {
                 taskAssignmentContext,
-                resolvedWorkspace: discussionOnlyWorkspace,
+                resolvedWorkingFolder: discussionOnlyWorkingFolder,
             };
         }
         const executionLocalDirectory = task.properties[TASK_EXECUTION_LOCAL_DIRECTORY_PROPERTY_KEY];
@@ -337,7 +337,7 @@ async function resolveTaskThreadWorkspaceContext(params) {
             || !(await isExistingDirectory(params.fileSystem, executionLocalDirectory))) {
             return {
                 taskAssignmentContext,
-                resolvedWorkspace: discussionOnlyWorkspace,
+                resolvedWorkingFolder: discussionOnlyWorkingFolder,
             };
         }
         if (!params.allowCrossAgentIndependentWorkspaceHandoff
@@ -348,12 +348,12 @@ async function resolveTaskThreadWorkspaceContext(params) {
             })) {
             return {
                 taskAssignmentContext,
-                resolvedWorkspace: buildTaskThreadScratchResolvedWorkspace(params.workspaceCollectionRootDir, params.channelId, 'cross-agent-independent-workspace-disabled'),
+                resolvedWorkingFolder: buildTaskThreadScratchResolvedWorkingFolder(params.workingFolderCollectionRootDir, params.channelId, 'cross-agent-independent-workspace-disabled'),
             };
         }
         return {
             taskAssignmentContext,
-            resolvedWorkspace: {
+            resolvedWorkingFolder: {
                 authority: 'task-execution-target',
                 taskId: task.id,
                 rootPath: executionLocalDirectory,
@@ -363,7 +363,7 @@ async function resolveTaskThreadWorkspaceContext(params) {
     catch (error) {
         return {
             taskAssignmentContext,
-            resolvedWorkspace: discussionOnlyWorkspace,
+            resolvedWorkingFolder: discussionOnlyWorkingFolder,
         };
     }
 }
@@ -383,32 +383,32 @@ export function resolveTaskAssignmentStateDirectory(stateRootDir, channelId) {
 export function resolveTaskAssignmentStatePath(stateRootDir, channelId) {
     return join(resolveTaskAssignmentStateDirectory(stateRootDir, channelId), TASK_ASSIGNMENT_STATE_FILENAME);
 }
-export function resolveTaskWorkspaceRootDirectory(startupWorkspaceRootDir) {
-    return join(resolve(startupWorkspaceRootDir), TASK_ISOLATED_WORKSPACE_COLLECTION_DIRNAME);
+export function resolveTaskWorkingFolderRootDirectory(channelRootDir) {
+    return join(resolve(channelRootDir), TASK_ISOLATED_WORKING_FOLDER_COLLECTION_DIRNAME);
 }
-export function resolveManagedWorkspaceCollectionRoot(workspaceCollectionRootDir, env = process.env, resolvedHomeDir = homedir()) {
-    const explicitRoot = workspaceCollectionRootDir?.trim();
+export function resolveManagedWorkingFolderCollectionRoot(workingFolderCollectionRootDir, env = process.env, resolvedHomeDir = homedir()) {
+    const explicitRoot = workingFolderCollectionRootDir?.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');
+        throw new Error('Unable to resolve a user home directory for agents-host working folders');
     }
-    return join(resolve(home), DEFAULT_HOME_BORGEE_DIRNAME, CHANNEL_WORKSPACE_COLLECTION_DIRNAME);
+    return join(resolve(home), DEFAULT_HOME_BORGEE_DIRNAME, CHANNEL_WORKING_FOLDER_COLLECTION_DIRNAME);
 }
-export function resolveChannelWorkspaceRootDirectory(workspaceCollectionRootDir, channelId) {
-    return join(resolve(workspaceCollectionRootDir), encodeChannelPathSegment(channelId));
+export function resolveChannelWorkingFolderRootDirectory(workingFolderCollectionRootDir, channelId) {
+    return join(resolve(workingFolderCollectionRootDir), encodeChannelPathSegment(channelId));
 }
-export function resolveChannelWorkspaceDirectory(workspaceCollectionRootDir, channelId) {
-    return join(resolveChannelWorkspaceRootDirectory(workspaceCollectionRootDir, channelId), CHANNEL_WORKSPACE_DIRNAME);
+export function resolveChannelWorkingFolderDirectory(workingFolderCollectionRootDir, channelId) {
+    return join(resolveChannelWorkingFolderRootDirectory(workingFolderCollectionRootDir, channelId), CHANNEL_WORKING_FOLDER_DIRNAME);
 }
-export function resolveTaskIsolatedWorkspaceDirectory(workspaceCollectionRootDir, channelId, taskId) {
-    return join(resolveTaskWorkspaceRootDirectory(resolveChannelWorkspaceRootDirectory(workspaceCollectionRootDir, channelId)), encodeChannelPathSegment(taskId), CHANNEL_WORKSPACE_DIRNAME);
+export function resolveTaskIsolatedWorkingFolderDirectory(workingFolderCollectionRootDir, channelId, taskId) {
+    return join(resolveTaskWorkingFolderRootDirectory(resolveChannelWorkingFolderRootDirectory(workingFolderCollectionRootDir, channelId)), encodeChannelPathSegment(taskId), CHANNEL_WORKING_FOLDER_DIRNAME);
 }
-export const resolveTaskWorkspaceDirectory = resolveTaskIsolatedWorkspaceDirectory;
-export function resolveTaskThreadScratchWorkspaceDirectory(workspaceCollectionRootDir, channelId) {
-    return join(resolveChannelWorkspaceRootDirectory(workspaceCollectionRootDir, channelId), TASK_THREAD_SCRATCH_WORKSPACE_DIRNAME, CHANNEL_WORKSPACE_DIRNAME);
+export const resolveTaskWorkingFolderDirectory = resolveTaskIsolatedWorkingFolderDirectory;
+export function resolveTaskThreadScratchWorkingFolderDirectory(workingFolderCollectionRootDir, channelId) {
+    return join(resolveChannelWorkingFolderRootDirectory(workingFolderCollectionRootDir, channelId), TASK_THREAD_SCRATCH_WORKING_FOLDER_DIRNAME, CHANNEL_WORKING_FOLDER_DIRNAME);
 }
 export function resolveChannelGatewayCredentialPath(stateRootDir, channelId) {
     return join(resolveChannelContextDirectory(stateRootDir, channelId), CHANNEL_GATEWAY_CREDENTIAL_FILENAME);
@@ -509,7 +509,7 @@ export class FileChannelContextStore {
     skillRuntimeEnabled;
     skillAssetResolver;
     localhostGateway;
-    workspaceCollectionRootDir;
+    workingFolderCollectionRootDir;
     taskReader;
     taskResolutionTimeoutMs;
     allowCrossAgentIndependentWorkspaceHandoff;
@@ -520,9 +520,9 @@ export class FileChannelContextStore {
         this.skillRuntimeEnabled = options.skillRuntimeEnabled ?? false;
         this.skillAssetResolver = options.skillAssetResolver ?? new PackageSkillAssetResolver(import.meta.url, this.fileSystem);
         this.localhostGateway = options.localhostGateway;
-        this.workspaceCollectionRootDir = resolveManagedWorkspaceCollectionRoot(options.workspaceCollectionRootDir, options.env, options.resolvedHomeDir);
+        this.workingFolderCollectionRootDir = resolveManagedWorkingFolderCollectionRoot(options.workingFolderCollectionRootDir, options.env, options.resolvedHomeDir);
         this.taskReader = options.taskReader;
-        this.taskResolutionTimeoutMs = options.taskResolutionTimeoutMs ?? DEFAULT_TASK_WORKSPACE_RESOLUTION_TIMEOUT_MS;
+        this.taskResolutionTimeoutMs = options.taskResolutionTimeoutMs ?? DEFAULT_TASK_WORKING_FOLDER_RESOLUTION_TIMEOUT_MS;
         this.allowCrossAgentIndependentWorkspaceHandoff
             = options.allowCrossAgentIndependentWorkspaceHandoff ?? true;
         this.resolveStableAgentId = options.resolveStableAgentId;
@@ -571,9 +571,9 @@ export class FileChannelContextStore {
                 incomingMessageType: input.incomingMessageType,
                 incomingContent: input.incomingContent,
             }, existingTaskAssignmentContext);
-        const workspaceResolution = await resolveTaskThreadWorkspaceContext({
+        const workingFolderResolution = await resolveTaskThreadWorkingFolderContext({
             channelId: input.channelId,
-            workspaceCollectionRootDir: this.workspaceCollectionRootDir,
+            workingFolderCollectionRootDir: this.workingFolderCollectionRootDir,
             taskAssignmentContext,
             taskReader: this.taskReader,
             taskResolutionTimeoutMs: this.taskResolutionTimeoutMs,
@@ -581,8 +581,8 @@ export class FileChannelContextStore {
             resolveStableAgentId: this.resolveStableAgentId,
             fileSystem: this.fileSystem,
         });
-        const resolvedWorkspace = workspaceResolution.resolvedWorkspace;
-        const runtimeTaskAssignmentContext = workspaceResolution.taskAssignmentContext ?? taskAssignmentContext;
+        const resolvedWorkingFolder = workingFolderResolution.resolvedWorkingFolder;
+        const runtimeTaskAssignmentContext = workingFolderResolution.taskAssignmentContext ?? taskAssignmentContext;
         const persistedTaskAssignmentContext = input.taskAssignmentContextOverridePersistence === 'ephemeral'
             ? existingTaskAssignmentContext
             : runtimeTaskAssignmentContext;
@@ -591,12 +591,12 @@ export class FileChannelContextStore {
             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
+        const payload = buildChannelContextPayload(input.channelId, runtimeSurface, input.collaborationOutcome, input.attentionSnapshot, input.compactionSnapshot, input.taskThreadCollaborationContract, input.collaborationCapabilities, input.missedCollaborationDiagnostic, skillRuntime, localhostGateway, persistedTaskAssignmentContext || resolvedWorkingFolder
             ? {
                 ...(persistedTaskAssignmentContext
                     ? { taskAssignmentContext: persistedTaskAssignmentContext }
                     : {}),
-                resolvedWorkspace,
+                resolvedWorkspace: resolvedWorkingFolder,
             }
             : undefined);
         const gatewayCredential = buildBorgeeAgentGatewayCredential(input.channelId, issuedLocalhostGateway);
@@ -610,7 +610,7 @@ export class FileChannelContextStore {
             gatewayCredentialPath: gatewayCredential ? gatewayCredentialPath : undefined,
             skillRuntime,
             localhostGateway,
-            resolvedWorkspace,
+            resolvedWorkingFolder,
         };
         const shouldProjectClaudeBrief = input.provider === 'claude' && input.projectionStrategy === 'file-brief';
         const claudeProjectedBriefContent = shouldProjectClaudeBrief
@@ -626,8 +626,8 @@ export class FileChannelContextStore {
         try {
             await this.fileSystem.mkdir(directoryPath, { recursive: true, mode: 0o700 });
             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 });
+            if (resolvedWorkingFolder.authority !== 'task-execution-target') {
+                await this.fileSystem.mkdir(resolvedWorkingFolder.rootPath, { recursive: true, mode: 0o700 });
             }
             await pruneGatewayCredentialSidecars(this.fileSystem, directoryPath, gatewayCredential ? CHANNEL_GATEWAY_CREDENTIAL_FILENAME : undefined);
             if (!claudeProjectedBriefContent) {
@@ -675,9 +675,9 @@ export class FileChannelContextStore {
                 directoryPath,
                 payload: {
                     ...payload,
-                    ...(resolvedWorkspace.authority === 'task-execution-target' && runtimeTaskAssignmentContext?.active === true
+                    ...(resolvedWorkingFolder.authority === 'task-execution-target' && runtimeTaskAssignmentContext?.active === true
                         ? {
-                            resolvedWorkspace: buildTaskThreadScratchResolvedWorkspace(this.workspaceCollectionRootDir, input.channelId),
+                            resolvedWorkspace: buildTaskThreadScratchResolvedWorkingFolder(this.workingFolderCollectionRootDir, input.channelId),
                         }
                         : {}),
                 },
@@ -687,9 +687,9 @@ export class FileChannelContextStore {
                 gatewayCredentialPath: gatewayCredentialWritten ? gatewayCredentialPath : undefined,
                 skillRuntime: payloadWritten ? skillRuntime : undefined,
                 localhostGateway: payloadWritten ? localhostGateway : undefined,
-                resolvedWorkspace: resolvedWorkspace.authority === 'task-execution-target' && runtimeTaskAssignmentContext?.active === true
-                    ? buildTaskThreadScratchResolvedWorkspace(this.workspaceCollectionRootDir, input.channelId)
-                    : resolvedWorkspace,
+                resolvedWorkingFolder: resolvedWorkingFolder.authority === 'task-execution-target' && runtimeTaskAssignmentContext?.active === true
+                    ? buildTaskThreadScratchResolvedWorkingFolder(this.workingFolderCollectionRootDir, input.channelId)
+                    : resolvedWorkingFolder,
             };
             throw new ChannelContextPreparationError('failed to persist channel context payload', partialContext, { cause: error });
         }