@borgee/agents-host 0.2.44 → 0.2.62

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

@@ -1,3 +1,4 @@
+import type { ReportTurnActivityInput, TurnActivityReporter } from '../plugin-sdk.js';
 import type { ChannelSummary, ChannelHistoryEntry, ChannelMessageEvent, CreateTaskInput, DirectoryUser, MeResponseUser, PostMessageInput, PostedMessage, ReadChannelHistoryInput, Task, UpdateTaskInput } from '../types.js';
 export interface ChatControlPlane {
     connect(onMessage: (message: ChannelMessageEvent) => void): Promise<void>;
@@ -6,6 +7,8 @@ export interface ChatControlPlane {
     editMessage(messageId: string, content: string): Promise<void>;
     deleteMessage(messageId: string): Promise<void>;
     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;
     getMe(): Promise<MeResponseUser>;
     listUsers(): Promise<DirectoryUser[]>;
     listChannels(): Promise<ChannelSummary[]>;

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

@@ -1,9 +1,9 @@
-import { type BorgeePluginClient, type BorgeePluginOptions, type InboundMessageEvent } from '../plugin-sdk.js';
+import { type BorgeePluginClient, type BorgeePluginOptions, type InboundMessageEvent, type ReportTurnActivityInput, 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' | 'readHistory' | 'sendMessage' | 'startTyping' | 'updateTask' | 'setTaskProperty' | 'deleteTaskProperty'>;
+type PluginClientLike = Pick<BorgeePluginClient, 'agentId' | 'close' | 'connect' | 'createTask' | 'deleteMessage' | 'editMessage' | 'getMe' | 'getTask' | 'listChannels' | 'listTasks' | 'listUsers' | 'on' | 'readHistory' | 'reportTurnActivity' | 'sendMessage' | 'startTyping' | 'updateTask' | 'setTaskProperty' | 'deleteTaskProperty'>;
 type PluginClientFactory = (options: BorgeePluginOptions) => PluginClientLike;
-type SdkChatControlPlaneOptions = Pick<BorgeePluginOptions, 'cursorStore' | 'pluginId'>;
+type SdkChatControlPlaneOptions = Pick<BorgeePluginOptions, 'pluginId'>;
 /**
  * Thin adapter over `@borgee/plugin-sdk` (the same BPP/`/ws/plugin` SDK used by
  * the OpenClaw plugin) that implements the minimal `ChatControlPlane` surface
@@ -22,6 +22,7 @@ export declare class SdkChatControlPlane implements ChatControlPlane {
     editMessage(messageId: string, content: string): Promise<void>;
     deleteMessage(messageId: string): Promise<void>;
     startTyping(channelId: string): () => void;
+    reportTurnActivity(input: ReportTurnActivityInput): TurnActivityReporter;
     getMe(): Promise<MeResponseUser>;
     listUsers(): Promise<DirectoryUser[]>;
     readChannelHistory(input: ReadChannelHistoryInput): Promise<ChannelHistoryEntry[]>;

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

@@ -65,6 +65,9 @@ export class SdkChatControlPlane {
     startTyping(channelId) {
         return this.client.startTyping(channelId);
     }
+    reportTurnActivity(input) {
+        return this.client.reportTurnActivity(input);
+    }
     async getMe() {
         if (this.me) {
             return this.me;

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { realpathSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
+import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { assertNoUpdateArgs, CliUsageError, parseApplyManagedArgs, parseDaemonArgs, parseDescribeArgs, parseDescribeManagedArgs, parseCleanupManagedArgs, parseGenerateConfigArgs, parseLogArgs, parseManagedStartArgs, parsePrintLayoutArgs, parseStartArgs, parseValidateArgs, USAGE, } from './cli-args.js';
 import { resolveAgentsHostDebugMode } from './debug.js';
@@ -15,7 +15,6 @@ function formatErrorMessage(error) {
     }
     return String(error);
 }
-const TASK_WORKSPACE_ROOT_DIR_ENV = 'AGENTS_HOST_INTERNAL_TASK_WORKSPACE_ROOT_DIR';
 export async function dispatchCli(argv, deps = {}) {
     const [command, ...rest] = argv;
     const env = deps.env ?? process.env;
@@ -31,7 +30,6 @@ export async function dispatchCli(argv, deps = {}) {
     const applyManagedSpecImpl = deps.applyManagedSpec ?? applyManagedSpec;
     const startManagedDaemonImpl = deps.startManagedDaemon ??
         (async (rootPath, debug) => {
-            env[TASK_WORKSPACE_ROOT_DIR_ENV] = rootPath;
             const daemon = new ManagedAgentsHostDaemon(rootPath, debug, {
                 logPath: env.AGENTS_HOST_MANAGED_DAEMON_LOG_PATH,
             });
@@ -63,7 +61,6 @@ export async function dispatchCli(argv, deps = {}) {
             await runMainImpl({ debug });
             return;
         }
-        env[TASK_WORKSPACE_ROOT_DIR_ENV] = dirname(resolve(parsed.configPath));
         await runMainImpl({ configPath: parsed.configPath, debug });
         return;
     }
@@ -167,7 +164,6 @@ export async function dispatchCli(argv, deps = {}) {
     }
     if (command === 'daemon') {
         const parsed = parseDaemonArgs(rest);
-        env[TASK_WORKSPACE_ROOT_DIR_ENV] = parsed.rootPath;
         await startManagedDaemonImpl(parsed.rootPath, parsed.debug);
         return;
     }

package/dist/compatibility-gates.d.ts

@@ -1,3 +1,4 @@
+import type { ProjectionStrategy } from './types.js';
 export declare const CLAUDE_PROVIDER_V2_COMPATIBILITY_GATE = "claude-provider-v2";
 export declare const COPILOT_PROVIDER_V2_COMPATIBILITY_GATE = "copilot-provider-v2";
 export declare const CODEX_PROVIDER_COMPATIBILITY_GATE = "codex-provider";
@@ -18,6 +19,7 @@ export declare const COMPATIBILITY_GATES_ENV = "AGENTS_HOST_INTERNAL_COMPATIBILI
 export declare const INTERNAL_DISABLED_COMPATIBILITY_GATES_ENV = "AGENTS_HOST_INTERNAL_DISABLED_COMPATIBILITY_GATES";
 export declare const INTERNAL_POLICY_MODE_ENV = "AGENTS_HOST_INTERNAL_POLICY_MODE";
 export declare const INTERNAL_PROVIDER_IMPLEMENTATIONS_ENV = "AGENTS_HOST_INTERNAL_PROVIDER_IMPLEMENTATIONS";
+export declare const INTERNAL_CLAUDE_PROMPT_STRATEGY_ENV = "AGENTS_HOST_INTERNAL_CLAUDE_PROMPT_STRATEGY";
 export declare const MANAGED_RUNTIME_SETTINGS_SCHEMA_VERSION = 1;
 export type InternalPolicyMode = 'audit-only' | 'enforce';
 export type InternalProviderImplementationPath = 'v1' | 'v2';
@@ -28,8 +30,10 @@ export interface ManagedRuntimeSettingsSnapshot {
     compatibilityGates: string[];
     providerImplementationOverrides: string[];
     internalPolicyMode: InternalPolicyMode;
+    projectionStrategy: ProjectionStrategy;
 }
 export declare const DEFAULT_INTERNAL_COMPATIBILITY_GATES: readonly string[];
+export declare function resolveInternalProjectionStrategy(env?: NodeJS.ProcessEnv): ProjectionStrategy;
 export declare function parseCompatibilityGates(rawValue: string | undefined): ReadonlySet<string>;
 export declare function resolveInternalCompatibilityGates(env?: NodeJS.ProcessEnv): ReadonlySet<string>;
 export declare function resolveDisabledDefaultCompatibilityGates(compatibilityGates: Iterable<string>): string[];

package/dist/compatibility-gates.js

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { DEFAULT_PROJECTION_STRATEGY, normalizeProjectionStrategy, } from './projection-strategy-values.js';
 export const CLAUDE_PROVIDER_V2_COMPATIBILITY_GATE = 'claude-provider-v2';
 export const COPILOT_PROVIDER_V2_COMPATIBILITY_GATE = 'copilot-provider-v2';
 export const CODEX_PROVIDER_COMPATIBILITY_GATE = 'codex-provider';
@@ -19,11 +20,14 @@ export const COMPATIBILITY_GATES_ENV = 'AGENTS_HOST_INTERNAL_COMPATIBILITY_GATES
 export const INTERNAL_DISABLED_COMPATIBILITY_GATES_ENV = 'AGENTS_HOST_INTERNAL_DISABLED_COMPATIBILITY_GATES';
 export const INTERNAL_POLICY_MODE_ENV = 'AGENTS_HOST_INTERNAL_POLICY_MODE';
 export const INTERNAL_PROVIDER_IMPLEMENTATIONS_ENV = 'AGENTS_HOST_INTERNAL_PROVIDER_IMPLEMENTATIONS';
+export const INTERNAL_CLAUDE_PROMPT_STRATEGY_ENV = 'AGENTS_HOST_INTERNAL_CLAUDE_PROMPT_STRATEGY';
 export const MANAGED_RUNTIME_SETTINGS_SCHEMA_VERSION = 1;
 const VALID_PROVIDER_IMPLEMENTATION_ENTRIES = '"claude:v1", "claude:v2", "copilot:v1", or "copilot:v2"';
 export const DEFAULT_INTERNAL_COMPATIBILITY_GATES = Object.freeze([
+    ATTENTION_FOLLOW_SEMANTICS_COMPATIBILITY_GATE,
     COLLABORATION_CAPABILITIES_DIAGNOSTICS_COMPATIBILITY_GATE,
     COLLABORATION_OUTCOME_MODEL_COMPATIBILITY_GATE,
+    COLLABORATION_SKILL_FIRST_COMPATIBILITY_GATE,
     CONNECTIONS_STATE_LAYER_COMPATIBILITY_GATE,
     CONTEXT_INJECTION_COMPATIBILITY_GATE,
     CODEX_PROVIDER_COMPATIBILITY_GATE,
@@ -44,6 +48,17 @@ function sortUniqueStrings(values) {
     return [...new Set([...values].map((value) => value.trim()).filter((value) => value.length > 0))]
         .sort((left, right) => left.localeCompare(right));
 }
+export function resolveInternalProjectionStrategy(env = process.env) {
+    const rawValue = env[INTERNAL_CLAUDE_PROMPT_STRATEGY_ENV]?.trim();
+    if (!rawValue || rawValue.length === 0) {
+        return DEFAULT_PROJECTION_STRATEGY;
+    }
+    const strategy = normalizeProjectionStrategy(rawValue);
+    if (strategy) {
+        return strategy;
+    }
+    throw new Error(`Invalid ${INTERNAL_CLAUDE_PROMPT_STRATEGY_ENV}: expected "session-brief", "turn-full", "message-only", or "turn-thin"`);
+}
 function isInternalProviderImplementationPath(value) {
     return value === 'v1' || value === 'v2';
 }
@@ -160,10 +175,14 @@ export function resolveManagedRuntimeSettingsSnapshot(env = process.env) {
         compatibilityGates,
         providerImplementationOverrides: resolveManagedRuntimeProviderImplementationOverrides(env, compatibilityGates),
         internalPolicyMode: resolveInternalPolicyMode(compatibilityGates.includes(POLICY_AUDIT_ENFORCEMENT_COMPATIBILITY_GATE), env),
+        projectionStrategy: resolveInternalProjectionStrategy(env),
     };
 }
 export function serializeManagedRuntimeSettingsSnapshot(snapshot) {
-    return JSON.stringify(snapshot);
+    return JSON.stringify({
+        ...snapshot,
+        claudePromptStrategy: snapshot.projectionStrategy,
+    });
 }
 export function createManagedRuntimeSettingsFingerprint(snapshot) {
     return createHash('sha256')

package/dist/config.d.ts

@@ -3,6 +3,7 @@ export declare const MAX_TIMER_DELAY_MINUTES: number;
 export declare const DEFAULT_COPILOT_SESSION_TTL_MINUTES: number;
 export declare const PROVIDER_IDLE_SHUTDOWN_DISABLED_MINUTES = 0;
 export declare const DEFAULT_PROVIDER_IDLE_SHUTDOWN_MINUTES = 10;
+export declare const DEFAULT_ALLOW_CROSS_AGENT_INDEPENDENT_WORKSPACE_HANDOFF = true;
 export declare const DEFAULT_CLAUDE_COMMAND = "claude-agent-acp";
 export declare const LEGACY_CLAUDE_COMMAND = "claude";
 export declare const LEGACY_CLAUDE_ONE_SHOT_ARGS: readonly ["--print", "--permission-mode", "bypassPermissions"];
@@ -13,6 +14,7 @@ export declare function parseArgs(value: string): string[];
 export declare function optionalStringArray(value: unknown, fieldName: string, sourceLabel: string): string[] | undefined;
 export declare function parseCopilotSessionTtlMinutesValue(value: unknown, sourceLabel: string): number;
 export declare function parseProviderIdleShutdownMinutesValue(value: unknown, sourceLabel: string): number;
+export declare function parseBooleanValue(value: unknown, envName: string, sourceLabel: string): boolean;
 export declare function resolveProvider(rawValue: string, sourceLabel: string): ProviderKind;
 export declare function assertProviderCompatibility(provider: ProviderKind, sourceLabel: string, env?: NodeJS.ProcessEnv): void;
 export declare function isLegacyClaudeCompatibilityAlias(command: string, args: string[]): boolean;

package/dist/config.js

@@ -6,6 +6,7 @@ export const MAX_TIMER_DELAY_MINUTES = MAX_TIMER_DELAY_MS / 60_000;
 export const DEFAULT_COPILOT_SESSION_TTL_MINUTES = 2 * 24 * 60;
 export const PROVIDER_IDLE_SHUTDOWN_DISABLED_MINUTES = 0;
 export const DEFAULT_PROVIDER_IDLE_SHUTDOWN_MINUTES = 10;
+export const DEFAULT_ALLOW_CROSS_AGENT_INDEPENDENT_WORKSPACE_HANDOFF = true;
 export const DEFAULT_CLAUDE_COMMAND = 'claude-agent-acp';
 export const LEGACY_CLAUDE_COMMAND = 'claude';
 export const LEGACY_CLAUDE_ONE_SHOT_ARGS = ['--print', '--permission-mode', 'bypassPermissions'];
@@ -18,6 +19,7 @@ export const DEFAULT_PROVIDER_COMMAND_CONFIG = {
     copilotArgs: ['-s', '--no-color', '--allow-all-tools', '--output-format', 'text'],
     copilotSessionTtlMinutes: DEFAULT_COPILOT_SESSION_TTL_MINUTES,
     providerIdleShutdownMinutes: DEFAULT_PROVIDER_IDLE_SHUTDOWN_MINUTES,
+    allowCrossAgentIndependentWorkspaceHandoff: DEFAULT_ALLOW_CROSS_AGENT_INDEPENDENT_WORKSPACE_HANDOFF,
 };
 function requireEnv(name, env) {
     return requireNonEmptyString(env[name], `Missing required environment variable: ${name}`);
@@ -75,6 +77,19 @@ export function parseProviderIdleShutdownMinutesValue(value, sourceLabel) {
     }
     return parsed;
 }
+export function parseBooleanValue(value, envName, sourceLabel) {
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    const normalized = String(value).trim().toLowerCase();
+    if (normalized === 'true') {
+        return true;
+    }
+    if (normalized === 'false') {
+        return false;
+    }
+    throw new Error(`Invalid ${envName} in ${sourceLabel}: expected true or false`);
+}
 export function resolveProvider(rawValue, sourceLabel) {
     const raw = rawValue.trim().toLowerCase();
     if (raw === 'claude' || raw === 'codex' || raw === 'copilot') {
@@ -134,6 +149,8 @@ export function resolveProviderCommandConfig(overrides = {}) {
         copilotSessionTtlMinutes: overrides.copilotSessionTtlMinutes ?? DEFAULT_PROVIDER_COMMAND_CONFIG.copilotSessionTtlMinutes,
         providerIdleShutdownMinutes: overrides.providerIdleShutdownMinutes
             ?? DEFAULT_PROVIDER_COMMAND_CONFIG.providerIdleShutdownMinutes,
+        allowCrossAgentIndependentWorkspaceHandoff: overrides.allowCrossAgentIndependentWorkspaceHandoff
+            ?? DEFAULT_PROVIDER_COMMAND_CONFIG.allowCrossAgentIndependentWorkspaceHandoff,
     };
 }
 export function loadConfigFromEnv(env = process.env) {
@@ -153,6 +170,10 @@ export function loadConfigFromEnv(env = process.env) {
         providerIdleShutdownMinutes: env.PROVIDER_IDLE_SHUTDOWN_MINUTES && env.PROVIDER_IDLE_SHUTDOWN_MINUTES.trim().length > 0
             ? parseProviderIdleShutdownMinutesValue(env.PROVIDER_IDLE_SHUTDOWN_MINUTES, 'environment variable PROVIDER_IDLE_SHUTDOWN_MINUTES')
             : DEFAULT_PROVIDER_COMMAND_CONFIG.providerIdleShutdownMinutes,
+        allowCrossAgentIndependentWorkspaceHandoff: env.ALLOW_CROSS_AGENT_INDEPENDENT_WORKSPACE_HANDOFF
+            && env.ALLOW_CROSS_AGENT_INDEPENDENT_WORKSPACE_HANDOFF.trim().length > 0
+            ? parseBooleanValue(env.ALLOW_CROSS_AGENT_INDEPENDENT_WORKSPACE_HANDOFF, 'ALLOW_CROSS_AGENT_INDEPENDENT_WORKSPACE_HANDOFF', 'environment variable ALLOW_CROSS_AGENT_INDEPENDENT_WORKSPACE_HANDOFF')
+            : DEFAULT_PROVIDER_COMMAND_CONFIG.allowCrossAgentIndependentWorkspaceHandoff,
     });
     assertProviderCommandCompatibility(provider, providerConfig, 'environment variables');
     return {

package/dist/context/claude-file-brief.d.ts

@@ -0,0 +1,2 @@
+import type { PreparedPromptContext } from '../types.js';
+export declare function buildClaudeFileBrief(context: PreparedPromptContext | undefined): string;

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

@@ -0,0 +1,83 @@
+import { buildCollaborationCapabilityDeclarationSummaryLines, } from './collaboration-capabilities-diagnostics.js';
+import { MAIN_SESSION_DELEGATION_LINES } from './main-session-delegation.js';
+import { buildResolvedWorkspaceGuidanceLines } from './resolved-workspace.js';
+import { buildSkillManualLines, buildSkillManualReadLine } from './skill-manual.js';
+function buildStableSkillLines(context) {
+    if (!context?.skillRuntime) {
+        return [];
+    }
+    return context.gatewayCredentialPath
+        ? buildSkillManualLines(context.skillRuntime)
+        : [buildSkillManualReadLine(context.skillRuntime)];
+}
+function buildStableGatewayLines(context) {
+    if (!context?.localhostGateway || !context.gatewayCredentialPath) {
+        return [];
+    }
+    const lines = [`Gateway credential file: ${context.gatewayCredentialPath}`];
+    if (context.runtimeSurface?.task.currentThread === 'parent-channel') {
+        lines.push('This channel is a parent channel, not a task thread.', 'For parent-channel task operations, use the packaged borgee-agent task rail through this gateway credential file.', 'Do not invent a bare task or bare borgee command.');
+        if (context.runtimeSurface.task.currentTaskShorthand === 'requires-task-id') {
+            lines.push('In this parent channel, task get, task update, task history, and task property commands require an explicit task id.');
+        }
+    }
+    else if (context.runtimeSurface?.task.currentThread === 'task-assignment-thread') {
+        lines.push('This channel is an active task thread.', 'Task list and task create stay on the parent channel.', 'Keep the main work in this thread.', 'Return your normal final response in this thread, and do not move the main work back to the parent channel.');
+        if (context.taskAssignmentContext?.currentTaskId) {
+            lines.push(`Current assigned task id: ${context.taskAssignmentContext.currentTaskId}.`);
+        }
+        else if (context.taskAssignmentContext?.active === true) {
+            lines.push('No current task id is persisted in the injected thread context for this task thread.');
+        }
+    }
+    return lines;
+}
+function buildStableTaskThreadLines(context) {
+    if (context?.taskAssignmentContext?.active !== true) {
+        return [];
+    }
+    const lines = [
+        'This session is an active task assignment thread.',
+        'Keep the main work in this thread.',
+        'Return your normal final response in this thread, and do not move the main work back to the parent channel.',
+    ];
+    if (context.taskAssignmentContext.currentTaskId) {
+        lines.push(`Current assigned task id: ${context.taskAssignmentContext.currentTaskId}.`);
+    }
+    else {
+        lines.push('No current task id is persisted in the injected thread context for this task thread.');
+    }
+    return lines;
+}
+export function buildClaudeFileBrief(context) {
+    const sessionDelegationLines = context?.skillRuntime ? [] : MAIN_SESSION_DELEGATION_LINES;
+    const lines = [
+        '# Borgee Claude runtime brief',
+        '',
+        'This directory belongs to one Borgee Claude channel session hosted by agents-host.',
+        'Keep visible replies concise, honest, and grounded in the current channel. Do not claim actions you did not actually perform.',
+        '',
+        ...sessionDelegationLines,
+        ...(() => {
+            const workspaceLines = buildResolvedWorkspaceGuidanceLines(context);
+            return workspaceLines.length > 0 ? ['', ...workspaceLines] : [];
+        })(),
+        ...(() => {
+            const capabilityLines = buildCollaborationCapabilityDeclarationSummaryLines(context?.collaborationCapabilities);
+            return capabilityLines.length > 0 ? ['', ...capabilityLines] : [];
+        })(),
+        ...(() => {
+            const taskThreadLines = buildStableTaskThreadLines(context);
+            return taskThreadLines.length > 0 ? ['', ...taskThreadLines] : [];
+        })(),
+        ...(() => {
+            const skillLines = buildStableSkillLines(context);
+            return skillLines.length > 0 ? ['', ...skillLines] : [];
+        })(),
+        ...(() => {
+            const gatewayLines = buildStableGatewayLines(context);
+            return gatewayLines.length > 0 ? ['', ...gatewayLines] : [];
+        })(),
+    ];
+    return `${lines.join('\n').trimEnd()}\n`;
+}

package/dist/context/compaction.d.ts

@@ -0,0 +1,20 @@
+import type { CompactionSnapshot, ProviderCompactionStage, ProviderKind } from '../types.js';
+export declare function buildCompactionSnapshot(params: {
+    provider: ProviderKind;
+    stage: ProviderCompactionStage;
+    observedAt?: number;
+    turnExecutionId?: string;
+    usedTokens?: number;
+    contextWindowTokens?: number;
+    failureReason?: string;
+}): CompactionSnapshot;
+export declare function mergeCompactionSnapshot(current: CompactionSnapshot | undefined, update: {
+    provider: ProviderKind;
+    stage: ProviderCompactionStage;
+    observedAt?: number;
+    turnExecutionId?: string;
+    usedTokens?: number;
+    contextWindowTokens?: number;
+    failureReason?: string;
+}): CompactionSnapshot;
+export declare function parsePersistedCompactionSnapshot(raw: unknown): CompactionSnapshot | undefined;

package/dist/context/compaction.js

@@ -0,0 +1,59 @@
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isProviderKind(value) {
+    return value === 'claude' || value === 'copilot' || value === 'codex';
+}
+function isCompactionStage(value) {
+    return value === 'started' || value === 'completed' || value === 'failed';
+}
+function isTerminalCompactionStage(value) {
+    return value === 'completed' || value === 'failed';
+}
+function normalizeFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function normalizeNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value : undefined;
+}
+export function buildCompactionSnapshot(params) {
+    return {
+        source: 'host-observed',
+        provider: params.provider,
+        stage: params.stage,
+        observedAt: params.observedAt ?? Date.now(),
+        ...(params.turnExecutionId ? { turnExecutionId: params.turnExecutionId } : {}),
+        ...(params.usedTokens !== undefined ? { usedTokens: params.usedTokens } : {}),
+        ...(params.contextWindowTokens !== undefined
+            ? { contextWindowTokens: params.contextWindowTokens }
+            : {}),
+        ...(params.failureReason ? { failureReason: params.failureReason } : {}),
+    };
+}
+export function mergeCompactionSnapshot(current, update) {
+    const retainUsageFromCurrent = current?.stage === 'completed' && update.stage === 'completed';
+    return buildCompactionSnapshot({
+        provider: update.provider,
+        stage: update.stage,
+        observedAt: update.observedAt,
+        turnExecutionId: update.turnExecutionId,
+        usedTokens: update.usedTokens ?? (retainUsageFromCurrent ? current?.usedTokens : undefined),
+        contextWindowTokens: update.contextWindowTokens
+            ?? (retainUsageFromCurrent ? current?.contextWindowTokens : undefined),
+        failureReason: update.failureReason,
+    });
+}
+export function parsePersistedCompactionSnapshot(raw) {
+    if (!isRecord(raw) || !isProviderKind(raw.provider) || !isTerminalCompactionStage(raw.stage)) {
+        return undefined;
+    }
+    return buildCompactionSnapshot({
+        provider: raw.provider,
+        stage: raw.stage,
+        observedAt: normalizeFiniteNumber(raw.observedAt) ?? Date.now(),
+        turnExecutionId: normalizeNonEmptyString(raw.turnExecutionId),
+        usedTokens: normalizeFiniteNumber(raw.usedTokens),
+        contextWindowTokens: normalizeFiniteNumber(raw.contextWindowTokens),
+        failureReason: normalizeNonEmptyString(raw.failureReason),
+    });
+}

package/dist/context/injection.d.ts

@@ -1,4 +1,5 @@
-import type { AttentionSnapshot, CollaborationCapabilityDeclaration, CollaborationOutcomeSnapshot, LocalhostGatewayBootstrapMetadata, MissedCollaborationDiagnostic, ProviderCollaborationContext, SkillRuntimeBootstrapMetadata, TaskThreadCollaborationContract, TaskAssignmentThreadContext, TaskWorkspaceContext } from '../types.js';
+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';
 export interface SkillRuntimeBootstrapPayload {
     skillDirectoryPath: string;
     nodeCliPath: string;
@@ -7,24 +8,28 @@ export interface SkillRuntimeBootstrapPayload {
 export interface ChannelContextPayload {
     schemaVersion: 1;
     channelId: string;
+    runtimeSurface?: RuntimeSurface;
     collaborationOutcome?: CollaborationOutcomeSnapshot;
     attentionSnapshot?: AttentionSnapshot;
+    compactionSnapshot?: CompactionSnapshot;
     taskThreadCollaborationContract?: TaskThreadCollaborationContract;
     collaborationCapabilities?: CollaborationCapabilityDeclaration;
     missedCollaborationDiagnostic?: MissedCollaborationDiagnostic;
     skillRuntime?: SkillRuntimeBootstrapPayload;
     localhostGateway?: LocalhostGatewayBootstrapMetadata;
     taskAssignmentContext?: TaskAssignmentThreadContext;
-    taskWorkspace?: TaskWorkspaceContext;
+    resolvedWorkspace?: ResolvedWorkspaceContext;
 }
 export interface PreparedChannelContext {
     directoryPath: string;
     payload: ChannelContextPayload;
     payloadPath?: string;
+    claudeProjectedBriefPath?: string;
+    claudeProjectedBriefHash?: string;
     gatewayCredentialPath?: string;
     skillRuntime?: SkillRuntimeBootstrapMetadata;
     localhostGateway?: LocalhostGatewayBootstrapMetadata;
-    taskWorkspace?: TaskWorkspaceContext;
+    resolvedWorkspace?: ResolvedWorkspaceContext;
 }
 export declare class ChannelContextPreparationError extends Error {
     readonly partialContext: PreparedChannelContext;
@@ -33,24 +38,34 @@ export declare class ChannelContextPreparationError extends Error {
 export interface ChannelContextStore {
     prepare(input: {
         channelId: string;
+        provider?: ProviderKind;
+        projectionStrategy?: ProjectionStrategy;
         collaboration?: ProviderCollaborationContext;
         collaborationOutcome?: CollaborationOutcomeSnapshot;
         attentionSnapshot?: AttentionSnapshot;
+        compactionSnapshot?: CompactionSnapshot;
         taskThreadCollaborationContract?: TaskThreadCollaborationContract;
         collaborationCapabilities?: CollaborationCapabilityDeclaration;
         missedCollaborationDiagnostic?: MissedCollaborationDiagnostic;
         incomingMessageType?: string;
         incomingContent?: string;
+        taskAssignmentContextOverride?: TaskAssignmentThreadContext;
+        taskAssignmentContextOverridePersistence?: 'persist' | 'ephemeral';
     }): Promise<PreparedChannelContext>;
     prepare(channelId: string, options?: {
+        provider?: ProviderKind;
+        projectionStrategy?: ProjectionStrategy;
         collaboration?: ProviderCollaborationContext;
         collaborationOutcome?: CollaborationOutcomeSnapshot;
         attentionSnapshot?: AttentionSnapshot;
+        compactionSnapshot?: CompactionSnapshot;
         taskThreadCollaborationContract?: TaskThreadCollaborationContract;
         collaborationCapabilities?: CollaborationCapabilityDeclaration;
         missedCollaborationDiagnostic?: MissedCollaborationDiagnostic;
         incomingMessageType?: string;
         incomingContent?: string;
+        taskAssignmentContextOverride?: TaskAssignmentThreadContext;
+        taskAssignmentContextOverridePersistence?: 'persist' | 'ephemeral';
     }): Promise<PreparedChannelContext>;
 }
 export interface SkillAssetResolver {
@@ -84,23 +99,45 @@ interface ContextFileSystem {
     }): Promise<void>;
     unlink(path: string): Promise<void>;
     rename(oldPath: string, newPath: string): Promise<void>;
-    access(path: string): Promise<void>;
+    access(path: string, mode?: number): Promise<void>;
+    stat?(path: string): Promise<{
+        isDirectory(): boolean;
+    }>;
 }
 interface FileChannelContextStoreOptions {
     fileSystem?: ContextFileSystem;
     skillRuntimeEnabled?: boolean;
     skillAssetResolver?: SkillAssetResolver;
     localhostGateway?: LocalhostGatewayContextPublisher;
-    taskWorkspaceRootDir?: string;
+    workspaceCollectionRootDir?: string;
+    taskReader?: Pick<ChatControlPlane, 'getTask' | 'listChannels' | 'listTasks' | 'listUsers'>;
+    taskResolutionTimeoutMs?: number;
+    allowCrossAgentIndependentWorkspaceHandoff?: boolean;
+    resolveStableAgentId?: () => string | undefined;
+    env?: NodeJS.ProcessEnv;
+    resolvedHomeDir?: string;
 }
+export declare function buildRuntimeSurfaceForTurn(options?: {
+    localhostGateway?: LocalhostGatewayBootstrapMetadata;
+    collaboration?: Pick<ProviderCollaborationContext, 'sendRoutesAllowed' | 'turnMode'>;
+    taskAssignmentContext?: TaskAssignmentThreadContext;
+}): RuntimeSurface;
 export declare function extractTaskIdFromTaskAssignmentContent(incomingContent: string | undefined): string | undefined;
 export declare function encodeChannelPathSegment(channelId: string): string;
 export declare function resolveChannelContextDirectory(stateRootDir: string, channelId: string): string;
 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 resolveTaskWorkspaceDirectory(startupWorkspaceRootDir: string, channelId: string, taskId: 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 resolveChannelGatewayCredentialPath(stateRootDir: string, channelId: string): string;
 export declare function resolveGatewayCredentialPathFromPayloadPath(payloadPath: string): string;
+export declare function resolveClaudeProjectedBriefPathFromPayloadPath(payloadPath: string): string;
 export declare function isGatewayCredentialSidecarBasename(basename: string): boolean;
 export declare function resolveBorgeeAgentSkillRuntimeAssets(moduleUrl: string, fileSystem?: Pick<ContextFileSystem, 'access'>): Promise<SkillRuntimeBootstrapMetadata>;
 export declare class FileChannelContextStore implements ChannelContextStore {
@@ -109,27 +146,41 @@ export declare class FileChannelContextStore implements ChannelContextStore {
     private readonly skillRuntimeEnabled;
     private readonly skillAssetResolver;
     private readonly localhostGateway?;
-    private readonly startupWorkspaceRootDir;
+    private readonly workspaceCollectionRootDir;
+    private readonly taskReader?;
+    private readonly taskResolutionTimeoutMs;
+    private readonly allowCrossAgentIndependentWorkspaceHandoff;
+    private readonly resolveStableAgentId?;
     constructor(stateRootDir: string, options?: FileChannelContextStoreOptions);
     prepare(inputOrChannelId: {
         channelId: string;
+        provider?: ProviderKind;
+        projectionStrategy?: ProjectionStrategy;
         collaboration?: ProviderCollaborationContext;
         collaborationOutcome?: CollaborationOutcomeSnapshot;
         attentionSnapshot?: AttentionSnapshot;
+        compactionSnapshot?: CompactionSnapshot;
         taskThreadCollaborationContract?: TaskThreadCollaborationContract;
         collaborationCapabilities?: CollaborationCapabilityDeclaration;
         missedCollaborationDiagnostic?: MissedCollaborationDiagnostic;
         incomingMessageType?: string;
         incomingContent?: string;
+        taskAssignmentContextOverride?: TaskAssignmentThreadContext;
+        taskAssignmentContextOverridePersistence?: 'persist' | 'ephemeral';
     } | string, options?: {
+        provider?: ProviderKind;
+        projectionStrategy?: ProjectionStrategy;
         collaboration?: ProviderCollaborationContext;
         collaborationOutcome?: CollaborationOutcomeSnapshot;
         attentionSnapshot?: AttentionSnapshot;
+        compactionSnapshot?: CompactionSnapshot;
         taskThreadCollaborationContract?: TaskThreadCollaborationContract;
         collaborationCapabilities?: CollaborationCapabilityDeclaration;
         missedCollaborationDiagnostic?: MissedCollaborationDiagnostic;
         incomingMessageType?: string;
         incomingContent?: string;
+        taskAssignmentContextOverride?: TaskAssignmentThreadContext;
+        taskAssignmentContextOverridePersistence?: 'persist' | 'ephemeral';
     }): Promise<PreparedChannelContext>;
     private resolveSkillRuntimeBestEffort;
 }