@borgee/agents-host 0.2.74 → 0.2.94

package/dist/background-runs.js

@@ -0,0 +1,184 @@
+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 refinesUnknown = held?.state === 'unknown' && state !== 'unknown';
+        const stopSupported = update.run.stopSupported &&
+            this.options.targetedCancellationSupported &&
+            this.options.cancel !== undefined;
+        const executionChanged = held !== undefined &&
+            ((update.run.executionId !== undefined &&
+                update.run.executionId !== held.executionId) ||
+                (update.run.startedAt !== undefined &&
+                    update.run.startedAt !== held.startedAt));
+        const startsNewExecution = !held ||
+            executionChanged ||
+            (held.state !== 'unknown' && isTerminal(held.state) && !isTerminal(state));
+        if (held &&
+            isTerminal(held.state) &&
+            isTerminal(state) &&
+            !startsNewExecution &&
+            held.state !== state &&
+            held.state !== 'unknown') {
+            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, update.run.executionId),
+                executionId: update.run.executionId,
+                label: update.run.label,
+                state,
+                parentActivityId: update.run.parentActivityId,
+                startedAt,
+                finishedAt: update.run.finishedAt,
+                reason: update.run.reason,
+                stopSupported,
+            }
+            : {
+                ...held,
+                label: update.run.label,
+                state,
+                parentActivityId: update.run.parentActivityId ?? held.parentActivityId,
+                startedAt,
+                finishedAt: refinesUnknown
+                    ? update.run.finishedAt
+                    : (update.run.finishedAt ?? held.finishedAt),
+                reason: refinesUnknown ? update.run.reason : (update.run.reason ?? held.reason),
+                stopSupported,
+            };
+        if (isTerminal(state) && run.finishedAt === undefined) {
+            run.finishedAt = this.now();
+        }
+        if (held &&
+            held.runId === run.runId &&
+            held.label === run.label &&
+            held.state === run.state &&
+            held.parentActivityId === run.parentActivityId &&
+            held.finishedAt === run.finishedAt &&
+            held.reason === run.reason &&
+            held.stopSupported === run.stopSupported) {
+            return;
+        }
+        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);
+        let historySize = [...this.runs.values()].filter((candidate) => isTerminal(candidate.state)).length;
+        while (historySize > MAX_TRACKED_RUNS) {
+            const oldest = [...this.runs].find(([, candidate]) => isTerminal(candidate.state));
+            if (!oldest) {
+                break;
+            }
+            this.runs.delete(oldest[0]);
+            this.runsById.delete(oldest[1].runId);
+            historySize -= 1;
+        }
+        this.publish(run);
+    }
+    replay() {
+        for (const run of this.runs.values()) {
+            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,
+            ...(run.parentActivityId ? { parentId: run.parentActivityId } : {}),
+            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, executionId) {
+    const digest = createHash('sha256')
+        .update(channelId)
+        .update('\0')
+        .update(providerRunId)
+        .update('\0')
+        .update(executionId ?? String(startedAt))
+        .digest('hex')
+        .slice(0, 32);
+    return `run_${digest}`;
+}

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

@@ -1,7 +1,9 @@
-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;
+    onActivityTransportReady?(handler: (() => void) | undefined): void;
     connect(onMessage: (message: ChannelMessageEvent) => void): Promise<void>;
     close(): Promise<void>;
     postMessage(input: PostMessageInput): Promise<PostedMessage>;
@@ -10,6 +12,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'>;
 /**
@@ -13,13 +13,18 @@ export declare class SdkChatControlPlane implements ChatControlPlane {
     private readonly client;
     private pendingMessages;
     private unsubscribe;
+    private stateUnsubscribe;
+    private activityTransportReady;
     private connected;
     private me;
     constructor(baseUrl: string, apiKey: string, createClient?: PluginClientFactory, options?: SdkChatControlPlaneOptions);
     onStopTurn(handler: StopTurnHandler | undefined): void;
+    onStopBackgroundRun(handler: StopBackgroundRunHandler | undefined): void;
+    onActivityTransportReady(handler: (() => void) | 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

@@ -9,6 +9,8 @@ export class SdkChatControlPlane {
     client;
     pendingMessages = [];
     unsubscribe = null;
+    stateUnsubscribe = null;
+    activityTransportReady;
     connected = false;
     me = null;
     constructor(baseUrl, apiKey, createClient = createBorgeePlugin, options = {}) {
@@ -17,6 +19,12 @@ export class SdkChatControlPlane {
     onStopTurn(handler) {
         this.client.onStopTurn(handler);
     }
+    onStopBackgroundRun(handler) {
+        this.client.onStopBackgroundRun?.(handler);
+    }
+    onActivityTransportReady(handler) {
+        this.activityTransportReady = handler;
+    }
     async connect(onMessage) {
         this.unsubscribe = this.client.on('message', (event) => {
             const message = mapInboundToChannelMessage(event);
@@ -26,6 +34,11 @@ export class SdkChatControlPlane {
             }
             onMessage(message);
         });
+        this.stateUnsubscribe = this.client.on('connectionState', (state) => {
+            if (state.status === 'online') {
+                this.activityTransportReady?.();
+            }
+        });
         try {
             await this.client.connect();
             this.connected = true;
@@ -40,6 +53,8 @@ export class SdkChatControlPlane {
         catch (error) {
             this.unsubscribe?.();
             this.unsubscribe = null;
+            this.stateUnsubscribe?.();
+            this.stateUnsubscribe = null;
             this.pendingMessages = [];
             throw error;
         }
@@ -49,7 +64,11 @@ export class SdkChatControlPlane {
         this.pendingMessages = [];
         this.unsubscribe?.();
         this.unsubscribe = null;
+        this.stateUnsubscribe?.();
+        this.stateUnsubscribe = null;
+        this.activityTransportReady = undefined;
         this.client.onStopTurn(undefined);
+        this.client.onStopBackgroundRun?.(undefined);
         await this.client.close();
     }
     async postMessage(input) {
@@ -60,6 +79,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;