@borgee/agents-host 0.2.33 → 0.2.35

package/dist/policy/gateway-authorization.d.ts

@@ -8,6 +8,21 @@ export interface GatewayTaskRoute {
     taskId: string;
     resource: 'task' | 'task-history';
 }
+/** One task property, addressed by key. PUT writes it, DELETE removes it. */
+export interface GatewayTaskPropertyRoute {
+    taskId: string;
+    key: string;
+    resource: 'task-property';
+}
+/** The same, on the thread's own task, so an agent need not resolve a task id. */
+export interface GatewayCurrentTaskPropertyRoute {
+    channelId: string;
+    key: string;
+    resource: 'current-task-property';
+}
+export type GatewayRoute = GatewayChannelRoute | GatewayTaskRoute | GatewayTaskPropertyRoute | GatewayCurrentTaskPropertyRoute | {
+    resource: 'health';
+};
 export interface GatewayAuthorizationBinding {
     channelId: string;
     agentId?: string;
@@ -23,9 +38,7 @@ export interface GatewayAuthorizationDecision {
     };
     allowHeader?: string;
     binding?: GatewayAuthorizationBinding;
-    route?: GatewayChannelRoute | GatewayTaskRoute | {
-        resource: 'health';
-    };
+    route?: GatewayRoute;
     path: string;
     token?: string;
 }
@@ -39,4 +52,6 @@ export declare function hasVisibleHeader(value: string | string[] | undefined):
 export declare function parseBearerToken(value: string | string[] | undefined): string | null;
 export declare function matchChannelRoute(pathname: string, allowCollaborationRoutes?: boolean): GatewayChannelRoute | null;
 export declare function matchTaskRoute(pathname: string): GatewayTaskRoute | null;
+export declare function matchTaskPropertyRoute(pathname: string): GatewayTaskPropertyRoute | null;
+export declare function matchCurrentTaskPropertyRoute(pathname: string): GatewayCurrentTaskPropertyRoute | null;
 export declare function evaluateGatewayAuthorization(input: GatewayAuthorizationInput): GatewayAuthorizationDecision;

package/dist/policy/gateway-authorization.js

@@ -61,6 +61,30 @@ export function matchTaskRoute(pathname) {
         resource: match[2] ? 'task-history' : 'task',
     };
 }
+export function matchTaskPropertyRoute(pathname) {
+    const match = /^\/v1\/tasks\/([^/]+)\/properties\/([^/]+)$/.exec(pathname);
+    if (!match) {
+        return null;
+    }
+    const taskId = decodePathSegment(match[1]);
+    const key = decodePathSegment(match[2]);
+    if (taskId == null || key == null) {
+        return null;
+    }
+    return { taskId, key, resource: 'task-property' };
+}
+export function matchCurrentTaskPropertyRoute(pathname) {
+    const match = /^\/v1\/channels\/([^/]+)\/current-task\/properties\/([^/]+)$/.exec(pathname);
+    if (!match) {
+        return null;
+    }
+    const channelId = decodePathSegment(match[1]);
+    const key = decodePathSegment(match[2]);
+    if (channelId == null || key == null) {
+        return null;
+    }
+    return { channelId, key, resource: 'current-task-property' };
+}
 function allowedMethodsForRoute(route, collaborationRoutesEnabled) {
     switch (route.resource) {
         case 'health':
@@ -78,6 +102,11 @@ function allowedMethodsForRoute(route, collaborationRoutesEnabled) {
         case 'current-task':
         case 'task':
             return ['GET', 'PATCH'];
+        // No GET: a property is read back with the task it belongs to, so a
+        // per-key read would be a second way to learn the same thing.
+        case 'current-task-property':
+        case 'task-property':
+            return ['PUT', 'DELETE'];
     }
 }
 export function evaluateGatewayAuthorization(input) {
@@ -96,7 +125,10 @@ export function evaluateGatewayAuthorization(input) {
     const collaborationRoutesEnabled = input.allowCollaborationRoutes ?? false;
     const route = url.pathname === '/health'
         ? { resource: 'health' }
-        : matchChannelRoute(url.pathname, collaborationRoutesEnabled) ?? matchTaskRoute(url.pathname);
+        : matchChannelRoute(url.pathname, collaborationRoutesEnabled)
+            ?? matchCurrentTaskPropertyRoute(url.pathname)
+            ?? matchTaskPropertyRoute(url.pathname)
+            ?? matchTaskRoute(url.pathname);
     if (hiddenCollaborationRoute) {
         return {
             reason: 'not-found',

package/dist/providers/claude/adapter.js

@@ -11,7 +11,9 @@ export class ClaudeProviderAdapter {
         const text = await this.cli.generateReply(preparedTurn, {
             onProgress: createAwaitingUserProgressHandler(options?.onProgress),
         });
-        return parseProviderReply(text);
+        // Read the session AFTER the turn: a first turn on a channel opens the
+        // session as it runs, so before this point there is nothing to report.
+        return { ...parseProviderReply(text), sessionId: this.cli.sessionIdForChannel(input.channelId) };
     }
     async dispose() {
         await this.cli.dispose();

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

@@ -10,6 +10,8 @@ interface ClaudeAcpRuntime {
     methods: typeof methods;
     protocolVersion: typeof PROTOCOL_VERSION;
     cwd: string;
+    idleBackendShutdownMs: number;
+    idleShutdownGracePeriodMs: number;
     shutdownGracePeriodMs: number;
     shutdownForceKillWaitMs: number;
 }
@@ -29,6 +31,12 @@ export declare class ClaudeCliClient {
     private readonly logger;
     private readonly runtime;
     private readonly channels;
+    /**
+     * 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;
     private readonly persistedSessions;
     private readonly closingSessions;
     private readonly pendingSessionStarts;
@@ -41,7 +49,13 @@ export declare class ClaudeCliClient {
     private startPromise?;
     private shutdownPromise?;
     private childExitPromise?;
-    private resolveChildExit?;
+    /**
+     * Bumped on every spawn so the `exit` / `connection.closed` handlers of a
+     * backend we deliberately recycled stay silent instead of latching a fatal
+     * error onto the client that already owns its successor.
+     */
+    private backendGeneration;
+    private idleShutdownPromise?;
     private fatalError;
     private disposing;
     private backendClosed;
@@ -49,6 +63,7 @@ export declare class ClaudeCliClient {
     private sessionStoreLoadPromise;
     private sessionStoreWriteQueue;
     private sessionCapabilities;
+    private readonly idleBackendShutdown;
     private childStderr;
     constructor(command: string, args?: string[], runtimeOverrides?: Partial<ClaudeAcpRuntime>, sessionStore?: ClaudeChannelSessionStore | undefined, resolveSessionStoreAgentId?: () => string | undefined, logger?: DebugLogger);
     generateReply(turn: PreparedProviderTurnInput, options?: ProviderGenerateOptions): Promise<string>;
@@ -83,6 +98,15 @@ export declare class ClaudeCliClient {
     private enqueueSessionStoreWrite;
     private trackSessionStoreOperation;
     private shutdownBackend;
+    /**
+     * Backend teardown without the fatal latch: the client stays usable and
+     * `ensureStarted()` spawns a replacement process on the next turn. Only safe
+     * while `isBackendIdle()` holds, because every channel's live ACP session is
+     * dropped here and no turn is ever replayed onto its successor.
+     */
+    private shutdownIdleBackend;
+    private isBackendIdle;
+    private closeBackendProcess;
     private waitForPendingSessionStarts;
     private waitForPendingSessionCloses;
     private waitForChildExit;

package/dist/providers/claude/cli-client.js

@@ -6,7 +6,17 @@ import { assertClaudeCommandCompatibility, DEFAULT_CLAUDE_COMMAND, isLegacyClaud
 import { PROTOCOL_VERSION, client, methods, ndJsonStream, } from '@agentclientprotocol/sdk';
 import { HostLogger, summarizeChildStderr, summarizeError } from '../../debug.js';
 import { resolveCopilotPermissionResponse } from '../../policy/copilot-permission.js';
+import { IDLE_BACKEND_SHUTDOWN_DISABLED_MS, IdleBackendShutdownScheduler, } from '../idle-backend-shutdown.js';
 const SESSION_TAINTED_ERRORS = new WeakSet();
+const IDLE_BACKEND_STOPPED_MESSAGE = 'Claude ACP backend stopped after idle timeout';
+/**
+ * A fatal teardown has callers waiting on it, so it force-kills quickly. An
+ * idle recycle has nobody waiting, and the CLIs unlink their on-disk session
+ * locks during SIGTERM cleanup — a lock left behind by SIGKILL makes the next
+ * restore believe the session is still in use (github/copilot-cli#3255). So the
+ * idle path trades latency nobody observes for a clean exit.
+ */
+const DEFAULT_IDLE_SHUTDOWN_GRACE_PERIOD_MS = 5_000;
 const DEFAULT_SHUTDOWN_GRACE_PERIOD_MS = 250;
 const DEFAULT_SHUTDOWN_FORCE_KILL_WAIT_MS = 250;
 const DEFAULT_SESSION_CAPABILITIES = {
@@ -21,6 +31,8 @@ const DEFAULT_RUNTIME = {
     methods,
     protocolVersion: PROTOCOL_VERSION,
     cwd: process.cwd(),
+    idleBackendShutdownMs: IDLE_BACKEND_SHUTDOWN_DISABLED_MS,
+    idleShutdownGracePeriodMs: DEFAULT_IDLE_SHUTDOWN_GRACE_PERIOD_MS,
     shutdownGracePeriodMs: DEFAULT_SHUTDOWN_GRACE_PERIOD_MS,
     shutdownForceKillWaitMs: DEFAULT_SHUTDOWN_FORCE_KILL_WAIT_MS,
 };
@@ -359,6 +371,14 @@ export class ClaudeCliClient {
     logger;
     runtime;
     channels = new Map();
+    /**
+     * 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) {
+        return this.channels.get(channelId)?.session?.sessionId;
+    }
     persistedSessions = new Map();
     closingSessions = new WeakSet();
     pendingSessionStarts = new Set();
@@ -371,7 +391,13 @@ export class ClaudeCliClient {
     startPromise;
     shutdownPromise;
     childExitPromise;
-    resolveChildExit;
+    /**
+     * Bumped on every spawn so the `exit` / `connection.closed` handlers of a
+     * backend we deliberately recycled stay silent instead of latching a fatal
+     * error onto the client that already owns its successor.
+     */
+    backendGeneration = 0;
+    idleShutdownPromise;
     fatalError = null;
     disposing = false;
     backendClosed = false;
@@ -379,6 +405,7 @@ export class ClaudeCliClient {
     sessionStoreLoadPromise = null;
     sessionStoreWriteQueue = Promise.resolve();
     sessionCapabilities = DEFAULT_SESSION_CAPABILITIES;
+    idleBackendShutdown;
     childStderr = '';
     constructor(command, args = [], runtimeOverrides = {}, sessionStore, resolveSessionStoreAgentId = () => undefined, logger = new HostLogger()) {
         this.command = command;
@@ -388,6 +415,16 @@ export class ClaudeCliClient {
         this.logger = logger;
         this.runtime = { ...DEFAULT_RUNTIME, ...runtimeOverrides };
         assertClaudeCommandCompatibility(command, args, 'Claude provider runtime');
+        this.idleBackendShutdown = new IdleBackendShutdownScheduler({
+            idleShutdownMs: this.runtime.idleBackendShutdownMs,
+            isIdle: () => this.isBackendIdle(),
+            shutdown: () => this.shutdownIdleBackend(),
+            onShutdownFailed: (error) => {
+                this.logger.error('failed to stop the idle Claude ACP backend', {
+                    error: summarizeError(error),
+                });
+            },
+        });
         this.fatalPromise = new Promise((_, reject) => {
             this.rejectFatalPromise = reject;
         });
@@ -408,6 +445,7 @@ export class ClaudeCliClient {
             : promptOrOptions;
         const sessionRouting = resolveSessionRouting(preparedTurn);
         const state = this.getOrCreateChannelState(sessionRouting.key, preparedTurn.channelId, sessionRouting.persistence);
+        this.idleBackendShutdown.cancel();
         const turn = createDeferredTurn(preparedTurn.channelId, preparedTurn.prompt, sessionRouting.persistence, preparedTurn.promptContext, options);
         state.queue.push(turn);
         this.processChannelQueue(sessionRouting.key, state);
@@ -416,12 +454,17 @@ export class ClaudeCliClient {
     async dispose() {
         const error = new Error('Claude ACP backend stopped');
         this.disposing = true;
+        this.idleBackendShutdown.cancel();
         this.logger?.debug('stopping Claude ACP backend');
         const closed = this.connection?.closed ?? Promise.resolve();
         this.failAll(error);
         let thrown;
         try {
-            await Promise.all([closed, this.shutdownPromise ?? Promise.resolve()]);
+            await Promise.all([
+                closed,
+                this.idleShutdownPromise ?? Promise.resolve(),
+                this.shutdownPromise ?? Promise.resolve(),
+            ]);
         }
         catch (disposeError) {
             thrown = disposeError;
@@ -442,6 +485,12 @@ export class ClaudeCliClient {
         if (this.fatalError) {
             throw this.fatalError;
         }
+        if (this.idleShutdownPromise) {
+            await this.idleShutdownPromise;
+            if (this.fatalError) {
+                throw this.fatalError;
+            }
+        }
         if (!this.startPromise) {
             this.startPromise = this.startBackend();
         }
@@ -454,6 +503,8 @@ export class ClaudeCliClient {
         }
     }
     async startBackend() {
+        const generation = ++this.backendGeneration;
+        const ownsCurrentBackend = () => (this.backendGeneration === generation && !this.disposing);
         const launch = resolveClaudeLaunch(this.command, this.args, this.runtime.cwd);
         this.childStderr = '';
         this.logger?.debug('starting Claude ACP process', {
@@ -473,13 +524,20 @@ export class ClaudeCliClient {
         });
         child.stderr.resume();
         this.logger?.debug('spawned Claude ACP process', { pid: child.pid });
+        let resolveChildExit;
+        this.childExitPromise = new Promise((resolve) => {
+            resolveChildExit = resolve;
+        });
         child.once('error', (error) => {
             this.logger?.debugError('Claude ACP process error', error);
+            if (!ownsCurrentBackend()) {
+                return;
+            }
             this.failAll(new Error(`Claude ACP process error: ${normalizeError(error).message}`));
         });
         child.once('exit', (code, signal) => {
-            this.resolveChildExit?.();
-            if (this.disposing) {
+            resolveChildExit();
+            if (!ownsCurrentBackend()) {
                 this.logger?.debug('Claude ACP process exited during shutdown', { code, signal });
                 return;
             }
@@ -493,9 +551,6 @@ export class ClaudeCliClient {
             });
             this.failAll(failure);
         });
-        this.childExitPromise = new Promise((resolveChildExit) => {
-            this.resolveChildExit = resolveChildExit;
-        });
         const output = Writable.toWeb(child.stdin);
         const input = Readable.toWeb(child.stdout);
         const stream = this.runtime.ndJsonStream(output, input);
@@ -505,7 +560,7 @@ export class ClaudeCliClient {
         const connection = app.connect(stream);
         this.connection = connection;
         void connection.closed.then(() => {
-            if (!this.disposing) {
+            if (ownsCurrentBackend()) {
                 this.logger?.debugError('Claude ACP connection closed unexpectedly');
                 this.failAll(new Error('Claude ACP connection closed unexpectedly'));
             }
@@ -604,6 +659,9 @@ export class ClaudeCliClient {
                 if (state.queue.length > 0 && !this.fatalError) {
                     this.processChannelQueue(channelId, state);
                 }
+                else {
+                    this.idleBackendShutdown.reconcile();
+                }
             }
         })();
     }
@@ -807,6 +865,7 @@ export class ClaudeCliClient {
         }
         this.fatalError = error;
         this.rejectFatalPromise(error);
+        this.idleBackendShutdown.cancel();
         for (const [channelId, state] of this.channels.entries()) {
             state.activeTurn?.reject(error);
             for (const turn of state.queue) {
@@ -1020,6 +1079,64 @@ export class ClaudeCliClient {
             return;
         }
         this.backendClosed = true;
+        await this.closeBackendProcess(error, this.runtime.shutdownGracePeriodMs);
+    }
+    /**
+     * Backend teardown without the fatal latch: the client stays usable and
+     * `ensureStarted()` spawns a replacement process on the next turn. Only safe
+     * while `isBackendIdle()` holds, because every channel's live ACP session is
+     * dropped here and no turn is ever replayed onto its successor.
+     */
+    async shutdownIdleBackend() {
+        // Detach the running backend before any signal reaches it, so its own exit
+        // and connection-closed handlers read this teardown as deliberate instead
+        // of latching a fatal error on a client that stays usable.
+        this.backendGeneration += 1;
+        const error = new Error(IDLE_BACKEND_STOPPED_MESSAGE);
+        const sessions = [];
+        for (const [channelId, state] of [...this.channels.entries()]) {
+            if (state.session) {
+                sessions.push(state.session);
+            }
+            state.session = undefined;
+            state.sessionCwd = undefined;
+            state.sessionVisibilityKey = undefined;
+            this.channels.delete(channelId);
+        }
+        this.logger?.debug('stopping idle Claude ACP backend', {
+            channels: sessions.length,
+            idleShutdownMs: this.runtime.idleBackendShutdownMs,
+        });
+        for (const session of sessions) {
+            this.closeSession(session);
+        }
+        const idleShutdownPromise = this.closeBackendProcess(error, this.runtime.idleShutdownGracePeriodMs).finally(() => {
+            this.startPromise = undefined;
+            this.childExitPromise = undefined;
+            this.sessionCapabilities = DEFAULT_SESSION_CAPABILITIES;
+            this.idleShutdownPromise = undefined;
+        });
+        this.idleShutdownPromise = idleShutdownPromise;
+        await idleShutdownPromise;
+    }
+    isBackendIdle() {
+        if (this.disposing || this.fatalError || this.backendClosed || this.idleShutdownPromise) {
+            return false;
+        }
+        if (!this.child) {
+            return false;
+        }
+        if (this.pendingSessionStarts.size > 0) {
+            return false;
+        }
+        for (const state of this.channels.values()) {
+            if (state.activeTurn || state.queue.length > 0 || state.sessionPromise || state.processing) {
+                return false;
+            }
+        }
+        return true;
+    }
+    async closeBackendProcess(error, gracePeriodMs) {
         const connection = this.connection;
         const child = this.child;
         await this.waitForPendingSessionStarts();
@@ -1031,9 +1148,9 @@ export class ClaudeCliClient {
             return;
         }
         const childExitPromise = this.childExitPromise ?? Promise.resolve();
-        this.logger?.debug('sending SIGTERM to Claude ACP process');
+        this.logger?.debug('sending SIGTERM to Claude ACP process', { gracePeriodMs });
         child.kill('SIGTERM');
-        const exitedAfterTerm = await this.waitForChildExit(childExitPromise, this.runtime.shutdownGracePeriodMs);
+        const exitedAfterTerm = await this.waitForChildExit(childExitPromise, gracePeriodMs);
         if (exitedAfterTerm) {
             this.logger?.debug('Claude ACP process exited after SIGTERM');
             this.child = undefined;

package/dist/providers/codex/adapter.js

@@ -11,7 +11,9 @@ export class CodexProviderAdapter {
         const text = await this.cli.generateReply(preparedTurn, {
             onProgress: createAwaitingUserProgressHandler(options?.onProgress),
         });
-        return parseProviderReply(text);
+        // Read the session AFTER the turn: a first turn on a channel opens the
+        // session as it runs, so before this point there is nothing to report.
+        return { ...parseProviderReply(text), sessionId: this.cli.sessionIdForChannel(input.channelId) };
     }
     async dispose() {
         await this.cli.dispose();

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

@@ -11,6 +11,8 @@ interface CodexAcpRuntime {
     protocolVersion: typeof PROTOCOL_VERSION;
     cwd: string;
     idleSessionTtlMs: number;
+    idleBackendShutdownMs: number;
+    idleShutdownGracePeriodMs: number;
     shutdownGracePeriodMs: number;
     shutdownForceKillWaitMs: number;
     readFile(path: string, options?: {
@@ -35,6 +37,12 @@ export declare class CodexCliClient {
     private readonly logger;
     private readonly runtime;
     private readonly channels;
+    /**
+     * 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;
     private readonly persistedSessions;
     private readonly closingSessions;
     private readonly pendingSessionStarts;
@@ -47,7 +55,13 @@ export declare class CodexCliClient {
     private startPromise?;
     private shutdownPromise?;
     private childExitPromise?;
-    private resolveChildExit?;
+    /**
+     * Bumped on every spawn so the `exit` / `connection.closed` handlers of a
+     * backend we deliberately recycled stay silent instead of latching a fatal
+     * error onto the client that already owns its successor.
+     */
+    private backendGeneration;
+    private idleShutdownPromise?;
     private fatalError;
     private disposing;
     private backendClosed;
@@ -55,6 +69,7 @@ export declare class CodexCliClient {
     private sessionStoreLoadPromise;
     private sessionStoreWriteQueue;
     private sessionCapabilities;
+    private readonly idleBackendShutdown;
     constructor(command: string, args?: string[], runtimeOverrides?: Partial<CodexAcpRuntime>, sessionStore?: CodexChannelSessionStore | undefined, resolveSessionStoreAgentId?: () => string | undefined, logger?: DebugLogger);
     generateReply(turn: PreparedProviderTurnInput, options?: ProviderGenerateOptions): Promise<string>;
     generateReply(channelId: string, prompt: string, options?: ProviderGenerateOptions): Promise<string>;
@@ -96,6 +111,15 @@ export declare class CodexCliClient {
     private trackSessionStoreOperation;
     private evictIdleChannel;
     private shutdownBackend;
+    /**
+     * Backend teardown without the fatal latch: the client stays usable and
+     * `ensureStarted()` spawns a replacement process on the next turn. Only safe
+     * while `isBackendIdle()` holds, because every channel's live ACP session is
+     * dropped here and no turn is ever replayed onto its successor.
+     */
+    private shutdownIdleBackend;
+    private isBackendIdle;
+    private closeBackendProcess;
     private waitForPendingSessionStarts;
     private waitForPendingSessionCloses;
     private waitForChildExit;