@borgee/agents-host 0.2.44 → 0.2.56

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,6 +20,7 @@ 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([
@@ -44,6 +46,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 +173,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/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,9 +38,12 @@ 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;
@@ -43,9 +51,12 @@ export interface ChannelContextStore {
         incomingContent?: string;
     }): Promise<PreparedChannelContext>;
     prepare(channelId: string, options?: {
+        provider?: ProviderKind;
+        projectionStrategy?: ProjectionStrategy;
         collaboration?: ProviderCollaborationContext;
         collaborationOutcome?: CollaborationOutcomeSnapshot;
         attentionSnapshot?: AttentionSnapshot;
+        compactionSnapshot?: CompactionSnapshot;
         taskThreadCollaborationContract?: TaskThreadCollaborationContract;
         collaborationCapabilities?: CollaborationCapabilityDeclaration;
         missedCollaborationDiagnostic?: MissedCollaborationDiagnostic;
@@ -91,16 +102,30 @@ interface FileChannelContextStoreOptions {
     skillRuntimeEnabled?: boolean;
     skillAssetResolver?: SkillAssetResolver;
     localhostGateway?: LocalhostGatewayContextPublisher;
-    taskWorkspaceRootDir?: string;
+    workspaceCollectionRootDir?: string;
+    taskReader?: Pick<ChatControlPlane, 'getTask' | 'listChannels' | 'listTasks'>;
+    taskResolutionTimeoutMs?: number;
+    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 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 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,22 +134,30 @@ 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;
     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;
     } | string, options?: {
+        provider?: ProviderKind;
+        projectionStrategy?: ProjectionStrategy;
         collaboration?: ProviderCollaborationContext;
         collaborationOutcome?: CollaborationOutcomeSnapshot;
         attentionSnapshot?: AttentionSnapshot;
+        compactionSnapshot?: CompactionSnapshot;
         taskThreadCollaborationContract?: TaskThreadCollaborationContract;
         collaborationCapabilities?: CollaborationCapabilityDeclaration;
         missedCollaborationDiagnostic?: MissedCollaborationDiagnostic;