@borgee/agents-host 0.2.84 → 0.2.97

package/dist/progress-to-activity.d.ts

@@ -1,8 +1,8 @@
 import type { AgentActivity } from './plugin-sdk.js';
 import type { ProviderProgressUpdate } from './types.js';
-/** Everything a provider reports. The turn boundary is the reporter's own and never arrives here. */
-export type ReportedActivity = Exclude<AgentActivity, {
-    shape: 'turn' | 'background_run';
+/** Absolute provider state accepted by the foreground activity coalescer. */
+export type ReportedActivity = Extract<AgentActivity, {
+    shape: 'activity' | 'plan' | 'output';
 }>;
 /**
  * Restates one progress update in the rail's own vocabulary.

package/dist/providers/claude/adapter.d.ts

@@ -1,5 +1,5 @@
 import { type ProviderAdapter } from '../provider-adapter.js';
-import type { ProviderGenerateOptions, ProviderInput, ProviderReply } from '../../types.js';
+import type { ProviderAutonomousReply, ProviderGenerateOptions, ProviderInput, ProviderReply } from '../../types.js';
 import { ProviderTurnPreparer } from '../../context/turn-preparation.js';
 import { ClaudeCliClient } from './cli-client.js';
 export declare const CLAUDE_HOSTED_PROVIDER_CAPABILITIES: import("../provider-adapter.js").ProviderCapabilities;
@@ -7,8 +7,10 @@ export declare class ClaudeProviderAdapter implements ProviderAdapter {
     private readonly cli;
     private readonly turnPreparer;
     readonly capabilities: import("../provider-adapter.js").ProviderCapabilities;
+    readonly cancelBackgroundRun?: (channelId: string, providerRunId: string) => Promise<boolean>;
     constructor(cli: ClaudeCliClient, turnPreparer: Pick<ProviderTurnPreparer, 'prepare'>);
     generateReply(input: ProviderInput, options?: ProviderGenerateOptions): Promise<ProviderReply>;
+    onAutonomousReply(handler: ((reply: ProviderAutonomousReply) => void) | undefined): void;
     cancelTurn(channelId: string): Promise<boolean>;
     dispose(): Promise<void>;
 }

package/dist/providers/claude/adapter.js

@@ -11,17 +11,45 @@ export const CLAUDE_HOSTED_PROVIDER_CAPABILITIES = createHostedProviderCapabilit
         support: 'supported',
     },
     backgroundRuns: {
-        lifecycle: 'not-supported',
-        targetedCancellation: 'not-supported',
+        lifecycle: 'supported',
+        targetedCancellation: 'supported',
+    },
+    foregroundHandoff: {
+        support: 'not-supported',
     },
 });
 export class ClaudeProviderAdapter {
     cli;
     turnPreparer;
-    capabilities = CLAUDE_HOSTED_PROVIDER_CAPABILITIES;
+    capabilities;
+    cancelBackgroundRun;
     constructor(cli, turnPreparer) {
         this.cli = cli;
         this.turnPreparer = turnPreparer;
+        const targetedCancellationSupported = cli.targetedBackgroundRunCancellationConfigured;
+        this.capabilities = targetedCancellationSupported
+            ? CLAUDE_HOSTED_PROVIDER_CAPABILITIES
+            : createHostedProviderCapabilities({
+                imageInputTransport: {
+                    source: 'transport-derived',
+                    support: 'supported',
+                    reason: 'real-media-delivered',
+                    delivery: ['blob'],
+                },
+                progressUpdates: {
+                    support: 'supported',
+                },
+                backgroundRuns: {
+                    lifecycle: 'supported',
+                    targetedCancellation: 'not-supported',
+                },
+                foregroundHandoff: {
+                    support: 'not-supported',
+                },
+            });
+        if (targetedCancellationSupported) {
+            this.cancelBackgroundRun = (channelId, providerRunId) => (this.cli.cancelBackgroundRun(channelId, providerRunId));
+        }
     }
     async generateReply(input, options) {
         const preparedTurn = await this.turnPreparer.prepare(input);
@@ -32,6 +60,16 @@ export class ClaudeProviderAdapter {
         // session as it runs, so before this point there is nothing to report.
         return { ...parseProviderReply(text), sessionId: this.cli.sessionIdForChannel(input.channelId) };
     }
+    onAutonomousReply(handler) {
+        this.cli.onAutonomousReply(handler
+            ? (reply) => {
+                const parsed = parseProviderReply(reply.text);
+                if (parsed.text.trim()) {
+                    handler({ ...reply, text: parsed.text });
+                }
+            }
+            : undefined);
+    }
     async cancelTurn(channelId) {
         return this.cli.cancelTurn(channelId);
     }

package/dist/providers/claude/background-run-observer.d.ts

@@ -0,0 +1,32 @@
+import type { ProviderGenerateOptions } from '../../types.js';
+export declare class ClaudeBackgroundRunObserver {
+    private onProgress?;
+    private readonly limits;
+    private readonly tasks;
+    private readonly emitted;
+    private backgroundTasksActive;
+    constructor(onProgress?: ProviderGenerateOptions['onProgress'], limits?: {
+        terminalRetentionMs?: number;
+        maxTrackedTasks?: number;
+        onBackgroundTasksActiveChanged?: (active: boolean) => void;
+        targetedCancellationSupported?: boolean;
+    });
+    setOnProgress(onProgress?: ProviderGenerateOptions['onProgress']): void;
+    dispose(): void;
+    fail(reason?: string): void;
+    consume(value: unknown): boolean;
+    private getOrCreate;
+    private mapTaskStatus;
+    private isConcreteTerminal;
+    private scheduleMissing;
+    private cancelMissing;
+    private scheduleRetention;
+    private cancelRetention;
+    private touch;
+    private enforceLimit;
+    private isTerminal;
+    private deleteTask;
+    private publish;
+    private reconcileBackgroundTasksActive;
+    private setBackgroundTasksActive;
+}

package/dist/providers/claude/background-run-observer.js

@@ -0,0 +1,381 @@
+const MISSING_TASK_GRACE_MS = 250;
+const TERMINAL_TASK_RETENTION_MS = 30_000;
+const MAX_TRACKED_TASKS = 256;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function readOptionalString(record, key) {
+    const value = record[key];
+    return typeof value === 'string' ? value : undefined;
+}
+function parseClaudeTaskLifecycleUpdate(value) {
+    if (!isRecord(value) ||
+        value.sessionUpdate !== 'session_info_update' ||
+        !isRecord(value._meta) ||
+        !isRecord(value._meta.claudeCode) ||
+        !isRecord(value._meta.claudeCode.taskLifecycle)) {
+        return null;
+    }
+    return parseClaudeTaskLifecycleRecord(value._meta.claudeCode.taskLifecycle);
+}
+export class ClaudeBackgroundRunObserver {
+    onProgress;
+    limits;
+    tasks = new Map();
+    emitted = new Map();
+    backgroundTasksActive = false;
+    constructor(onProgress, limits = {}) {
+        this.onProgress = onProgress;
+        this.limits = limits;
+    }
+    setOnProgress(onProgress) {
+        if (onProgress) {
+            this.onProgress = onProgress;
+        }
+    }
+    dispose() {
+        for (const taskId of [...this.tasks.keys()]) {
+            this.deleteTask(taskId);
+        }
+        this.emitted.clear();
+        this.onProgress = undefined;
+        this.setBackgroundTasksActive(false);
+    }
+    fail(reason = 'Claude background run state is unknown because the provider session ended unexpectedly') {
+        for (const [taskId, record] of this.tasks) {
+            if (!record.background || this.isTerminal(record.state)) {
+                continue;
+            }
+            this.cancelMissing(record);
+            record.state = 'unknown';
+            record.reason = reason;
+            this.publish(taskId, record);
+        }
+        this.dispose();
+    }
+    consume(value) {
+        const update = parseClaudeTaskLifecycleUpdate(value);
+        if (!update) {
+            return false;
+        }
+        if (update.event === 'background_tasks_changed') {
+            const liveTaskIds = new Set(update.tasks.map((task) => task.taskId));
+            for (const [taskId, record] of this.tasks) {
+                if (record.background && !this.isConcreteTerminal(record.state)) {
+                    if (liveTaskIds.has(taskId)) {
+                        this.cancelMissing(record);
+                    }
+                    else {
+                        this.scheduleMissing(taskId, record);
+                    }
+                }
+            }
+            for (const task of update.tasks) {
+                const record = this.getOrCreate(task.taskId, task.description);
+                record.label = task.description;
+                record.background = true;
+                this.cancelMissing(record);
+                if (record.state === 'unknown') {
+                    record.state = 'running';
+                    record.reason = undefined;
+                    this.cancelRetention(record);
+                }
+                this.touch(task.taskId, record);
+                this.publish(task.taskId, record);
+            }
+            this.enforceLimit();
+            this.reconcileBackgroundTasksActive();
+            return true;
+        }
+        const record = this.getOrCreate(update.taskId, update.event === 'started' ? update.description : 'Claude background task');
+        switch (update.event) {
+            case 'started':
+                record.label = update.description;
+                if (update.toolUseId) {
+                    record.parentActivityId = update.toolUseId;
+                }
+                this.cancelRetention(record);
+                this.touch(update.taskId, record);
+                if (record.background) {
+                    this.publish(update.taskId, record);
+                }
+                this.enforceLimit();
+                this.reconcileBackgroundTasksActive();
+                return true;
+            case 'updated':
+                if (update.patch.description) {
+                    record.label = update.patch.description;
+                }
+                if (update.patch.is_backgrounded === true) {
+                    record.background = true;
+                }
+                if (update.patch.status) {
+                    const wasUnknown = record.state === 'unknown';
+                    record.state = this.mapTaskStatus(update.patch.status);
+                    this.cancelMissing(record);
+                    if (wasUnknown && !this.isConcreteTerminal(record.state)) {
+                        record.reason = undefined;
+                    }
+                    if (this.isConcreteTerminal(record.state)) {
+                        this.scheduleRetention(update.taskId, record);
+                    }
+                    else {
+                        this.cancelRetention(record);
+                    }
+                }
+                if (update.patch.error) {
+                    record.reason = update.patch.error;
+                }
+                if (record.background) {
+                    this.publish(update.taskId, record);
+                }
+                this.touch(update.taskId, record);
+                this.enforceLimit();
+                this.reconcileBackgroundTasksActive();
+                return true;
+            case 'notification':
+                if (update.toolUseId) {
+                    record.parentActivityId = update.toolUseId;
+                }
+                record.state =
+                    update.status === 'completed'
+                        ? 'completed'
+                        : update.status === 'failed'
+                            ? 'failed'
+                            : 'cancelled';
+                this.cancelMissing(record);
+                if (update.status !== 'completed' && update.summary.trim().length > 0) {
+                    record.reason = update.summary;
+                }
+                this.scheduleRetention(update.taskId, record);
+                if (record.background) {
+                    this.publish(update.taskId, record);
+                }
+                this.touch(update.taskId, record);
+                this.enforceLimit();
+                this.reconcileBackgroundTasksActive();
+                return true;
+        }
+    }
+    getOrCreate(taskId, label) {
+        const existing = this.tasks.get(taskId);
+        if (existing) {
+            this.touch(taskId, existing);
+            return existing;
+        }
+        const record = {
+            label,
+            background: false,
+            missingFromSnapshot: false,
+            state: 'running',
+        };
+        this.tasks.set(taskId, record);
+        return record;
+    }
+    mapTaskStatus(status) {
+        switch (status) {
+            case 'pending':
+            case 'running':
+                return 'running';
+            case 'paused':
+                return 'waiting';
+            case 'completed':
+                return 'completed';
+            case 'failed':
+                return 'failed';
+            case 'killed':
+                return 'cancelled';
+        }
+    }
+    isConcreteTerminal(state) {
+        return state === 'completed' || state === 'failed' || state === 'cancelled';
+    }
+    scheduleMissing(taskId, record) {
+        if (record.missingFromSnapshot) {
+            return;
+        }
+        record.missingFromSnapshot = true;
+        record.missingTimer = setTimeout(() => {
+            record.missingTimer = undefined;
+            if (!record.missingFromSnapshot || this.isConcreteTerminal(record.state)) {
+                return;
+            }
+            record.state = 'unknown';
+            record.reason =
+                'Provider background task disappeared before a terminal lifecycle event was observed';
+            this.publish(taskId, record);
+            this.reconcileBackgroundTasksActive();
+            this.scheduleRetention(taskId, record);
+        }, MISSING_TASK_GRACE_MS);
+    }
+    cancelMissing(record) {
+        record.missingFromSnapshot = false;
+        if (record.missingTimer) {
+            clearTimeout(record.missingTimer);
+            record.missingTimer = undefined;
+        }
+    }
+    scheduleRetention(taskId, record) {
+        this.cancelRetention(record);
+        record.retentionTimer = setTimeout(() => {
+            if (this.tasks.get(taskId) === record) {
+                this.deleteTask(taskId);
+            }
+        }, this.limits.terminalRetentionMs ?? TERMINAL_TASK_RETENTION_MS);
+    }
+    cancelRetention(record) {
+        if (record.retentionTimer) {
+            clearTimeout(record.retentionTimer);
+            record.retentionTimer = undefined;
+        }
+    }
+    touch(taskId, record) {
+        this.tasks.delete(taskId);
+        this.tasks.set(taskId, record);
+    }
+    enforceLimit() {
+        const limit = this.limits.maxTrackedTasks ?? MAX_TRACKED_TASKS;
+        const countsAsHistory = (record) => !record.background || this.isTerminal(record.state);
+        let historySize = [...this.tasks.values()].filter(countsAsHistory).length;
+        while (historySize > limit) {
+            const candidate = [...this.tasks].find(([, record]) => countsAsHistory(record) && !record.retentionTimer);
+            if (!candidate) {
+                // Live identities and terminal enrichment windows are required state.
+                // Their timers converge the temporary history excess after the window.
+                return;
+            }
+            this.deleteTask(candidate[0]);
+            historySize -= 1;
+        }
+    }
+    isTerminal(state) {
+        return this.isConcreteTerminal(state) || state === 'unknown';
+    }
+    deleteTask(taskId) {
+        const record = this.tasks.get(taskId);
+        if (!record) {
+            return;
+        }
+        this.cancelMissing(record);
+        this.cancelRetention(record);
+        this.tasks.delete(taskId);
+        this.emitted.delete(taskId);
+        this.reconcileBackgroundTasksActive();
+    }
+    publish(taskId, record) {
+        if (!this.onProgress) {
+            return;
+        }
+        const run = {
+            providerRunId: taskId,
+            executionId: taskId,
+            label: record.label,
+            state: record.state,
+            ...(record.parentActivityId ? { parentActivityId: record.parentActivityId } : {}),
+            ...(record.reason ? { reason: record.reason } : {}),
+            stopSupported: this.limits.targetedCancellationSupported === true,
+        };
+        const fingerprint = JSON.stringify(run);
+        if (this.emitted.get(taskId) === fingerprint) {
+            return;
+        }
+        this.emitted.set(taskId, fingerprint);
+        this.onProgress({ type: 'background_run', run });
+    }
+    reconcileBackgroundTasksActive() {
+        this.setBackgroundTasksActive([...this.tasks.values()].some((record) => record.background && !this.isTerminal(record.state)));
+    }
+    setBackgroundTasksActive(active) {
+        if (this.backgroundTasksActive === active) {
+            return;
+        }
+        this.backgroundTasksActive = active;
+        this.limits.onBackgroundTasksActiveChanged?.(active);
+    }
+}
+function parseClaudeTaskLifecycleRecord(lifecycle) {
+    const event = lifecycle.event;
+    if (event === 'background_tasks_changed') {
+        if (!Array.isArray(lifecycle.tasks)) {
+            return null;
+        }
+        const tasks = lifecycle.tasks.flatMap((task) => {
+            if (!isRecord(task)) {
+                return [];
+            }
+            const taskId = readOptionalString(task, 'taskId');
+            const taskType = readOptionalString(task, 'taskType');
+            const description = readOptionalString(task, 'description');
+            return taskId && taskType && description ? [{ taskId, taskType, description }] : [];
+        });
+        return tasks.length === lifecycle.tasks.length ? { event, tasks } : null;
+    }
+    const taskId = readOptionalString(lifecycle, 'taskId');
+    if (!taskId) {
+        return null;
+    }
+    if (event === 'started') {
+        const description = readOptionalString(lifecycle, 'description');
+        if (!description) {
+            return null;
+        }
+        const toolUseId = readOptionalString(lifecycle, 'toolUseId');
+        const subagentType = readOptionalString(lifecycle, 'subagentType');
+        const taskType = readOptionalString(lifecycle, 'taskType');
+        return {
+            event,
+            taskId,
+            description,
+            ...(toolUseId ? { toolUseId } : {}),
+            ...(subagentType ? { subagentType } : {}),
+            ...(taskType ? { taskType } : {}),
+        };
+    }
+    if (event === 'updated') {
+        if (!isRecord(lifecycle.patch)) {
+            return null;
+        }
+        const status = readOptionalString(lifecycle.patch, 'status');
+        const validStatuses = new Set([
+            'pending',
+            'running',
+            'completed',
+            'failed',
+            'killed',
+            'paused',
+        ]);
+        if (status !== undefined && !validStatuses.has(status)) {
+            return null;
+        }
+        const description = readOptionalString(lifecycle.patch, 'description');
+        const error = readOptionalString(lifecycle.patch, 'error');
+        return {
+            event,
+            taskId,
+            patch: {
+                ...(status ? { status: status } : {}),
+                ...(description ? { description } : {}),
+                ...(error ? { error } : {}),
+                ...(typeof lifecycle.patch.is_backgrounded === 'boolean'
+                    ? { is_backgrounded: lifecycle.patch.is_backgrounded }
+                    : {}),
+            },
+        };
+    }
+    if (event === 'notification') {
+        const status = readOptionalString(lifecycle, 'status');
+        const summary = readOptionalString(lifecycle, 'summary');
+        if (!summary || (status !== 'completed' && status !== 'failed' && status !== 'stopped')) {
+            return null;
+        }
+        const toolUseId = readOptionalString(lifecycle, 'toolUseId');
+        return {
+            event,
+            taskId,
+            status,
+            summary,
+            ...(toolUseId ? { toolUseId } : {}),
+        };
+    }
+    return null;
+}

package/dist/providers/claude/cli-client.d.ts

@@ -1,7 +1,7 @@
 import spawn from 'cross-spawn';
 import { PROTOCOL_VERSION, client, methods, ndJsonStream } from '@agentclientprotocol/sdk';
 import { type DebugLogger } from '../../debug.js';
-import type { PreparedProviderTurnInput, ProviderGenerateOptions } from '../../types.js';
+import type { PreparedProviderTurnInput, ProviderAutonomousReply, ProviderGenerateOptions } from '../../types.js';
 import type { ClaudeChannelSessionStore } from './session-store.js';
 interface ClaudeAcpRuntime {
     spawn: typeof spawn;
@@ -37,15 +37,22 @@ export declare class ClaudeCliClient {
     private readonly imageInputConfig;
     private readonly runtime;
     private readonly channels;
+    private readonly channelWorkerRoutes;
+    readonly targetedBackgroundRunCancellationConfigured: boolean;
     /**
      * The provider session currently bound to channelId, or undefined before a
      * turn has opened one. Surfaced so agents-host can record which session
      * worked a task without the agent being asked to report its own id.
      */
     sessionIdForChannel(channelId: string): string | undefined;
+    handoffForegroundTurn(channelId: string): Promise<{
+        outcome: 'admitted' | 'not_found';
+    }>;
     cancelTurn(channelId: string): Promise<boolean>;
+    cancelBackgroundRun(channelId: string, providerRunId: string): Promise<boolean>;
     private readonly persistedSessions;
     private readonly closingSessions;
+    private readonly sessionUpdatePumps;
     private readonly pendingSessionStarts;
     private readonly pendingSessionCloses;
     private readonly pendingSessionStoreOperations;
@@ -70,15 +77,19 @@ export declare class ClaudeCliClient {
     private sessionStoreLoadPromise;
     private sessionStoreWriteQueue;
     private sessionCapabilities;
+    private targetedBackgroundRunCancellationAvailable;
+    private autonomousReplyHandler?;
     private readonly idleBackendShutdown;
     private childStderr;
     constructor(command: string, args?: string[], runtimeOverrides?: Partial<ClaudeAcpRuntime>, sessionStore?: ClaudeChannelSessionStore | undefined, resolveSessionStoreAgentId?: () => string | undefined, logger?: DebugLogger, imageInputConfig?: ClaudeHostedImageInputConfig);
+    onAutonomousReply(handler: ((reply: ProviderAutonomousReply) => void) | undefined): void;
     generateReply(turn: PreparedProviderTurnInput, options?: ProviderGenerateOptions): Promise<string>;
     generateReply(channelId: string, prompt: string, options?: ProviderGenerateOptions): Promise<string>;
     dispose(): Promise<void>;
     private ensureStarted;
     private startBackend;
     private getOrCreateChannelState;
+    private resolveChannelState;
     private processChannelQueue;
     private getOrCreateSession;
     private startFreshSession;
@@ -92,6 +103,9 @@ export declare class ClaudeCliClient {
     private failAll;
     private handlePermissionRequest;
     private invalidateSession;
+    private promoteWorkerRoute;
+    private releaseWorkerRoute;
+    private reconcileIdleChannelState;
     private closeSession;
     private rejectQueuedTurnsAfterSessionTaint;
     private findChannelStateBySessionId;