@borgee/agents-host 0.2.97 → 0.2.101

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

@@ -2,7 +2,7 @@ import type { IncomingMessage } from 'node:http';
 export type GatewayDecisionReason = 'browser-origin-not-allowed' | 'method-not-allowed' | 'missing-or-invalid-token' | 'invalid-token' | 'channel-mismatch' | 'not-found' | 'bootstrap-unavailable' | 'authorized';
 export interface GatewayChannelRoute {
     channelId: string;
-    resource: 'bootstrap' | 'me' | 'history' | 'draft' | 'users' | 'messages' | 'tasks' | 'current-task';
+    resource: 'bootstrap' | 'me' | 'history' | 'files' | 'file-content' | 'file-download' | 'file-sync' | 'file-publish' | 'draft' | 'users' | 'messages' | 'tasks' | 'current-task';
 }
 export interface GatewayTaskRoute {
     taskId: string;

package/dist/policy/gateway-authorization.js

@@ -31,9 +31,23 @@ function decodePathSegment(segment) {
     }
 }
 export function matchChannelRoute(pathname, allowCollaborationRoutes = false) {
+    const fileOperation = /^\/v1\/channels\/([^/]+)\/files\/(content|download|sync|publish)$/.exec(pathname);
+    if (fileOperation) {
+        const channelId = decodePathSegment(fileOperation[1]);
+        if (channelId == null) {
+            return null;
+        }
+        const resources = {
+            content: 'file-content',
+            download: 'file-download',
+            sync: 'file-sync',
+            publish: 'file-publish',
+        };
+        return { channelId, resource: resources[fileOperation[2]] };
+    }
     const resources = allowCollaborationRoutes
-        ? '(bootstrap|me|history|draft|users|messages|tasks|current-task)'
-        : '(bootstrap|me|history|users|tasks|current-task)';
+        ? '(bootstrap|me|history|files|draft|users|messages|tasks|current-task)'
+        : '(bootstrap|me|history|files|users|tasks|current-task)';
     const match = new RegExp(`^/v1/channels/([^/]+)/${resources}$`).exec(pathname);
     if (!match) {
         return null;
@@ -91,10 +105,16 @@ function allowedMethodsForRoute(route, collaborationRoutesEnabled) {
         case 'bootstrap':
         case 'me':
         case 'history':
+        case 'files':
+        case 'file-content':
         case 'draft':
         case 'users':
         case 'task-history':
             return ['GET'];
+        case 'file-download':
+        case 'file-sync':
+        case 'file-publish':
+            return ['POST'];
         case 'messages':
             return collaborationRoutesEnabled ? ['POST'] : [];
         case 'tasks':

package/dist/providers/claude/adapter.js

@@ -55,6 +55,7 @@ export class ClaudeProviderAdapter {
         const preparedTurn = await this.turnPreparer.prepare(input);
         const text = await this.cli.generateReply(preparedTurn, {
             onProgress: createAwaitingUserProgressHandler(options?.onProgress),
+            ...(options?.onUsage ? { onUsage: options.onUsage } : {}),
         });
         // 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.

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

@@ -9,6 +9,7 @@ import { assertClaudeCommandCompatibility, DEFAULT_CLAUDE_COMMAND, isLegacyClaud
 import { PROTOCOL_VERSION, client, methods, ndJsonStream, } from '@agentclientprotocol/sdk';
 import { HostLogger, summarizeChildStderr, summarizeError } from '../../debug.js';
 import { AcpProgressCollector } from '../acp-progress-collector.js';
+import { normalizeAcpPromptUsage } from '../prompt-usage.js';
 import { ProviderTurnCancelledError } from '../provider-adapter.js';
 import { readClaudeActivityMetadata } from './activity-metadata.js';
 import { ClaudeBackgroundRunObserver } from './background-run-observer.js';
@@ -1506,6 +1507,9 @@ export class ClaudeCliClient {
                     catch (error) {
                         throw markSessionTainted(error);
                     }
+                    const usage = normalizeAcpPromptUsage(response.usage);
+                    if (usage)
+                        options?.onUsage?.(usage);
                     const output = collector.getFinalText();
                     if (response.stopReason === 'cancelled') {
                         throw new ProviderTurnCancelledError('Claude ACP turn cancelled', {

package/dist/providers/codex/adapter.js

@@ -27,6 +27,7 @@ export class CodexProviderAdapter {
         const preparedTurn = await this.turnPreparer.prepare(input);
         const text = await this.cli.generateReply(preparedTurn, {
             onProgress: createAwaitingUserProgressHandler(options?.onProgress),
+            ...(options?.onUsage ? { onUsage: options.onUsage } : {}),
         });
         // 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.

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

@@ -6,6 +6,7 @@ import spawn from 'cross-spawn';
 import { PROTOCOL_VERSION, client, methods, ndJsonStream, } from '@agentclientprotocol/sdk';
 import { HostLogger, summarizeChildStderr, summarizeError } from '../../debug.js';
 import { AcpProgressCollector } from '../acp-progress-collector.js';
+import { normalizeAcpPromptUsage } from '../prompt-usage.js';
 import { ProviderTurnCancelledError } from '../provider-adapter.js';
 import { assertCodexProjectDocumentSize, buildCodexProjectDocument } from './project-doc.js';
 import { isGatewayCredentialSidecarBasename } from '../../context/injection.js';
@@ -850,6 +851,10 @@ export class CodexCliClient {
                 catch (error) {
                     throw markSessionTainted(error);
                 }
+                const usage = normalizeAcpPromptUsage(response.usage);
+                if (usage) {
+                    options?.onUsage?.(usage);
+                }
                 const output = collector.getFinalText();
                 if (response.stopReason === 'cancelled') {
                     throw new ProviderTurnCancelledError('Codex ACP turn cancelled', {

package/dist/providers/copilot/adapter.js

@@ -27,6 +27,10 @@ export class CopilotProviderAdapter {
         const preparedTurn = await this.turnPreparer.prepare(input);
         const text = await this.cli.generateReply(preparedTurn, {
             onProgress: createAwaitingUserProgressHandler(options?.onProgress),
+            ...(options?.onUsage ? { onUsage: options.onUsage } : {}),
+            ...(options?.onExecutionContinuation
+                ? { onExecutionContinuation: options.onExecutionContinuation }
+                : {}),
         });
         // 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.

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

@@ -4,6 +4,7 @@ import { PROTOCOL_VERSION, client, methods, ndJsonStream, } from '@agentclientpr
 import { toCopilotBackgroundActivity } from './activity-metadata.js';
 import { HostLogger, summarizeChildStderr, summarizeError } from '../../debug.js';
 import { AcpProgressCollector, } from '../acp-progress-collector.js';
+import { normalizeAcpPromptUsage } from '../prompt-usage.js';
 import { ProviderTurnCancelledError } from '../provider-adapter.js';
 import { resolveCopilotPermissionResponse, resolveCopilotSdkPermissionResponse, } from '../../policy/copilot-permission.js';
 import { isDiscussionOnlyResolvedWorkingFolder } from '../../context/resolved-working-folder.js';
@@ -1001,7 +1002,12 @@ export class CopilotCliClient {
         this.closeSession(session);
     }
     async runTurn(session, prompt, options, onBackgroundAgentStarted) {
-        const promptPromise = this.raceWithFatal(session.prompt(prompt));
+        const promptPromise = this.raceWithFatal(isCopilotSdkSession(session)
+            ? session.prompt(prompt, {
+                onUsage: options?.onUsage,
+                onExecutionContinuation: options?.onExecutionContinuation,
+            })
+            : session.prompt(prompt));
         const promptFailure = new Promise((_, reject) => {
             void promptPromise.catch((error) => reject(markSessionTainted(error)));
         });
@@ -1042,6 +1048,10 @@ export class CopilotCliClient {
                 catch (error) {
                     throw markSessionTainted(error);
                 }
+                const usage = normalizeAcpPromptUsage(response.usage);
+                if (usage) {
+                    options?.onUsage?.(usage);
+                }
                 if (response.stopReason === 'cancelled') {
                     throw new ProviderTurnCancelledError('Copilot turn cancelled');
                 }

package/dist/providers/copilot/sdk-session.d.ts

@@ -1,6 +1,6 @@
 import type { ActiveSession, ContentBlock } from '@agentclientprotocol/sdk';
 import { type MessageOptions, type PermissionHandler, type ResumeSessionConfig, type SessionConfig, type SessionEventHandler } from '@github/copilot-sdk';
-import type { ProviderBackgroundRunProgress } from '../../types.js';
+import type { ProviderBackgroundRunProgress, ProviderGenerateOptions } from '../../types.js';
 type CopilotSessionUpdate = Awaited<ReturnType<ActiveSession['nextUpdate']>>;
 type CopilotPromptResponse = Awaited<ReturnType<ActiveSession['prompt']>>;
 interface CopilotSdkTaskInfo {
@@ -77,6 +77,7 @@ export declare class CopilotSdkSessionAdapter {
     private readonly onAutonomousReply;
     private readonly onAutonomousTurnPresenceChanged;
     private readonly onBackgroundTaskExecutionsChanged;
+    private readonly backgroundUsageOwnerTimeoutMs;
     readonly transport = "sdk";
     private readonly pendingUpdates;
     private readonly updateWaiters;
@@ -98,11 +99,12 @@ export declare class CopilotSdkSessionAdapter {
     private readonly backgroundTaskExecutions;
     private backgroundTaskExecutionsDirty;
     private readonly backgroundWaits;
+    private readonly backgroundUsageOwners;
     private lastSyntheticExecutionStartedAt;
     private closePromise?;
-    constructor(session: CopilotSdkSessionLike, onBackgroundRun: (run: ProviderBackgroundRunProgress) => void, onBackgroundAgentPresenceChanged: (active: boolean) => void, onBackgroundRunError: (error: Error) => void, onAutonomousReply: (reply: CopilotAutonomousReply) => void, onAutonomousTurnPresenceChanged: (active: boolean) => void, initialBackgroundTaskExecutions?: Readonly<Record<string, CopilotBackgroundExecutionState>>, onBackgroundTaskExecutionsChanged?: (executions: Readonly<Record<string, CopilotBackgroundExecutionState>>) => Promise<void>);
+    constructor(session: CopilotSdkSessionLike, onBackgroundRun: (run: ProviderBackgroundRunProgress) => void, onBackgroundAgentPresenceChanged: (active: boolean) => void, onBackgroundRunError: (error: Error) => void, onAutonomousReply: (reply: CopilotAutonomousReply) => void, onAutonomousTurnPresenceChanged: (active: boolean) => void, initialBackgroundTaskExecutions?: Readonly<Record<string, CopilotBackgroundExecutionState>>, onBackgroundTaskExecutionsChanged?: (executions: Readonly<Record<string, CopilotBackgroundExecutionState>>) => Promise<void>, backgroundUsageOwnerTimeoutMs?: number);
     get sessionId(): string;
-    prompt(input: string | ContentBlock[]): Promise<CopilotPromptResponse>;
+    prompt(input: string | ContentBlock[], telemetry?: Pick<ProviderGenerateOptions, 'onExecutionContinuation' | 'onUsage'>): Promise<CopilotPromptResponse>;
     nextUpdate(): Promise<CopilotSessionUpdate>;
     interruptMainTurn(): Promise<boolean>;
     cancelAllBackgroundWork(): Promise<boolean>;
@@ -139,6 +141,13 @@ export declare class CopilotSdkSessionAdapter {
     private resolveBackgroundWait;
     private backgroundWaitFor;
     private handleOwnedTurnEvent;
+    private recordTurnUsage;
+    private deliverAccumulatedTurnUsage;
+    private recordBackgroundUsage;
+    private settleBackgroundUsageOwner;
+    private settleBackgroundUsageGroup;
+    private updateBackgroundUsageRegistryState;
+    private refreshMissingBackgroundTerminalGrace;
     private interruptAttachedTurn;
     private finishActiveTurn;
     private resolveEventTurnId;

package/dist/providers/copilot/sdk-session.js

@@ -1,6 +1,7 @@
 import { accessSync, constants as fsConstants, existsSync, statSync } from 'node:fs';
 import { delimiter, extname, isAbsolute, resolve } from 'node:path';
 import { CopilotClient, RuntimeConnection, } from '@github/copilot-sdk';
+import { normalizeProviderCallUsage } from '../prompt-usage.js';
 function isExecutableFile(path) {
     if (!existsSync(path) || !statSync(path).isFile()) {
         return false;
@@ -79,6 +80,15 @@ export function createCopilotSdkSessionConfig(cwd, onPermissionRequest) {
         onPermissionRequest,
     };
 }
+const DEFAULT_BACKGROUND_USAGE_OWNER_TIMEOUT_MS = 30 * 60 * 1_000;
+function addUsage(current, next) {
+    return {
+        inputTokens: (current?.inputTokens ?? 0) + next.inputTokens,
+        outputTokens: (current?.outputTokens ?? 0) + next.outputTokens,
+        cacheReadTokens: (current?.cacheReadTokens ?? 0) + next.cacheReadTokens,
+        cacheWriteTokens: (current?.cacheWriteTokens ?? 0) + next.cacheWriteTokens,
+    };
+}
 const BACKGROUND_COMPLETION_SIGNAL_TTL_MS = 30_000;
 const MAX_BACKGROUND_COMPLETION_SIGNALS = 32;
 function normalizeError(error) {
@@ -193,6 +203,7 @@ export class CopilotSdkSessionAdapter {
     onAutonomousReply;
     onAutonomousTurnPresenceChanged;
     onBackgroundTaskExecutionsChanged;
+    backgroundUsageOwnerTimeoutMs;
     transport = 'sdk';
     pendingUpdates = [];
     updateWaiters = [];
@@ -214,9 +225,10 @@ export class CopilotSdkSessionAdapter {
     backgroundTaskExecutions;
     backgroundTaskExecutionsDirty = false;
     backgroundWaits = new Map();
+    backgroundUsageOwners = new Map();
     lastSyntheticExecutionStartedAt = 0;
     closePromise;
-    constructor(session, onBackgroundRun, onBackgroundAgentPresenceChanged, onBackgroundRunError, onAutonomousReply, onAutonomousTurnPresenceChanged, initialBackgroundTaskExecutions = {}, onBackgroundTaskExecutionsChanged = async () => { }) {
+    constructor(session, onBackgroundRun, onBackgroundAgentPresenceChanged, onBackgroundRunError, onAutonomousReply, onAutonomousTurnPresenceChanged, initialBackgroundTaskExecutions = {}, onBackgroundTaskExecutionsChanged = async () => { }, backgroundUsageOwnerTimeoutMs = DEFAULT_BACKGROUND_USAGE_OWNER_TIMEOUT_MS) {
         this.session = session;
         this.onBackgroundRun = onBackgroundRun;
         this.onBackgroundAgentPresenceChanged = onBackgroundAgentPresenceChanged;
@@ -224,6 +236,7 @@ export class CopilotSdkSessionAdapter {
         this.onAutonomousReply = onAutonomousReply;
         this.onAutonomousTurnPresenceChanged = onAutonomousTurnPresenceChanged;
         this.onBackgroundTaskExecutionsChanged = onBackgroundTaskExecutionsChanged;
+        this.backgroundUsageOwnerTimeoutMs = backgroundUsageOwnerTimeoutMs;
         this.backgroundTaskExecutions = new Map(Object.entries(initialBackgroundTaskExecutions).map(([taskId, execution]) => [
             taskId,
             { ...execution },
@@ -233,7 +246,7 @@ export class CopilotSdkSessionAdapter {
     get sessionId() {
         return this.session.sessionId;
     }
-    async prompt(input) {
+    async prompt(input, telemetry = {}) {
         if (this.closePromise) {
             throw new Error('Copilot SDK session is closed');
         }
@@ -249,7 +262,13 @@ export class CopilotSdkSessionAdapter {
         const turn = {
             messageIdsWithDeltas: new Set(),
             ownedTurnIds: new Set(),
+            usageKeys: new Set(),
+            backgroundAgentIds: new Set(),
+            backgroundSucceeded: true,
+            onUsage: telemetry.onUsage,
+            onExecutionContinuation: telemetry.onExecutionContinuation,
             userMessageObserved: false,
+            usageDelivered: false,
             aborted: false,
             cancelRequested: false,
             resolve: resolveTurn,
@@ -263,6 +282,7 @@ export class CopilotSdkSessionAdapter {
             if (this.activeTurn === turn) {
                 this.activeTurn = undefined;
             }
+            this.deliverAccumulatedTurnUsage(turn);
             turn.reject(normalizeError(error));
         }
         return completion;
@@ -338,9 +358,16 @@ export class CopilotSdkSessionAdapter {
             this.autonomousTurnIdByRuntimeTurnId.clear();
             this.autonomousTurnIdByInteractionId.clear();
             this.refreshAutonomousTurnPresence();
+            for (const owner of new Set(this.backgroundUsageOwners.values())) {
+                this.settleBackgroundUsageGroup(owner, false);
+            }
+            this.backgroundUsageOwners.clear();
             this.closePromise = (async () => {
                 this.unsubscribe();
-                this.activeTurn?.reject(reason ?? new Error('Copilot SDK session closed'));
+                if (this.activeTurn) {
+                    this.deliverAccumulatedTurnUsage(this.activeTurn);
+                    this.activeTurn.reject(reason ?? new Error('Copilot SDK session closed'));
+                }
                 this.activeTurn = undefined;
                 for (const waiter of this.updateWaiters.splice(0)) {
                     waiter.reject(reason ?? new Error('Copilot SDK session closed'));
@@ -398,10 +425,11 @@ export class CopilotSdkSessionAdapter {
                 }
                 const fingerprint = JSON.stringify(run);
                 const previous = this.reportedBackgroundTasks.get(run.providerRunId);
+                this.reportedBackgroundTasks.set(run.providerRunId, run);
+                this.updateBackgroundUsageRegistryState(run.providerRunId, run.state === 'running' || run.state === 'waiting');
                 if (previous && JSON.stringify(previous) === fingerprint) {
                     continue;
                 }
-                this.reportedBackgroundTasks.set(run.providerRunId, run);
                 this.onBackgroundRun(run);
             }
             for (const [providerRunId, previous] of this.reportedBackgroundTasks) {
@@ -411,6 +439,10 @@ export class CopilotSdkSessionAdapter {
                         this.backgroundTaskExecutionsDirty = true;
                     }
                     this.backgroundWaits.delete(providerRunId);
+                    if (this.activeTurn?.backgroundAgentIds.delete(providerRunId)) {
+                        this.activeTurn.backgroundSucceeded = false;
+                    }
+                    this.refreshMissingBackgroundTerminalGrace(providerRunId);
                     if (previous.state === 'running' || previous.state === 'waiting') {
                         this.onBackgroundRun({
                             ...previous,
@@ -666,7 +698,46 @@ export class CopilotSdkSessionAdapter {
             this.noteBackgroundCompletion(event);
             return;
         }
+        if (event.type === 'session.error') {
+            if (event.agentId) {
+                if (this.activeTurn?.backgroundAgentIds.delete(event.agentId)) {
+                    this.activeTurn.backgroundSucceeded = false;
+                }
+                this.settleBackgroundUsageOwner(event.agentId, false);
+            }
+            else {
+                for (const owner of new Set(this.backgroundUsageOwners.values())) {
+                    this.settleBackgroundUsageGroup(owner, false);
+                }
+            }
+        }
         if (event.agentId) {
+            if (event.type === 'subagent.started' && this.activeTurn) {
+                this.activeTurn.backgroundAgentIds.add(event.agentId);
+            }
+            else if (event.type === 'assistant.usage') {
+                if (this.activeTurn &&
+                    this.activeTurn.backgroundAgentIds.has(event.agentId)) {
+                    this.recordTurnUsage(this.activeTurn, event);
+                }
+                else {
+                    this.recordBackgroundUsage(event.agentId, event);
+                }
+            }
+            else if (event.type === 'subagent.completed' ||
+                event.type === 'subagent.failed') {
+                const succeeded = event.type === 'subagent.completed' && event.data.cancelled !== true;
+                if (this.activeTurn?.backgroundAgentIds.delete(event.agentId) && !succeeded) {
+                    this.activeTurn.backgroundSucceeded = false;
+                }
+                this.settleBackgroundUsageOwner(event.agentId, succeeded);
+            }
+            else if (event.type === 'abort') {
+                if (this.activeTurn?.backgroundAgentIds.delete(event.agentId)) {
+                    this.activeTurn.backgroundSucceeded = false;
+                }
+                this.settleBackgroundUsageOwner(event.agentId, false);
+            }
             this.handleBackgroundAgentEvent(event, event.agentId);
             return;
         }
@@ -906,12 +977,18 @@ export class CopilotSdkSessionAdapter {
                     rawOutput: event.data.result ?? event.data.error,
                 }));
                 return;
+            case 'assistant.usage': {
+                this.recordTurnUsage(this.activeTurn, event);
+                return;
+            }
             case 'abort':
+                this.deliverAccumulatedTurnUsage(this.activeTurn);
                 this.activeTurn.aborted = true;
                 return;
             case 'session.error': {
                 const turn = this.activeTurn;
                 this.activeTurn = undefined;
+                this.deliverAccumulatedTurnUsage(turn);
                 turn.reject(new Error(event.data.message));
                 return;
             }
@@ -923,6 +1000,93 @@ export class CopilotSdkSessionAdapter {
                 return;
         }
     }
+    recordTurnUsage(turn, event) {
+        const usageKey = event.data.apiCallId ?? event.id;
+        if (turn.usageKeys.has(usageKey))
+            return;
+        const usage = normalizeProviderCallUsage(event.data);
+        if (!usage)
+            return;
+        turn.usageKeys.add(usageKey);
+        turn.usage = addUsage(turn.usage, usage);
+    }
+    deliverAccumulatedTurnUsage(turn) {
+        if (!turn.usage || turn.usageDelivered)
+            return;
+        turn.usageDelivered = true;
+        turn.onUsage?.({ ...turn.usage });
+    }
+    recordBackgroundUsage(agentId, event) {
+        const owner = this.backgroundUsageOwners.get(agentId);
+        if (!owner)
+            return;
+        const usageKey = event.data.apiCallId ?? event.id;
+        if (owner.usageKeys.has(usageKey))
+            return;
+        const usage = normalizeProviderCallUsage(event.data);
+        if (!usage)
+            return;
+        owner.usageKeys.add(usageKey);
+        owner.onUsage?.(usage);
+        this.refreshMissingBackgroundTerminalGrace(agentId);
+    }
+    settleBackgroundUsageOwner(agentId, succeeded) {
+        const owner = this.backgroundUsageOwners.get(agentId);
+        if (!owner)
+            return;
+        const timer = owner.missingTerminalTimers.get(agentId);
+        if (timer)
+            clearTimeout(timer);
+        owner.missingTerminalTimers.delete(agentId);
+        owner.succeeded &&= succeeded;
+        owner.agentIds.delete(agentId);
+        this.backgroundUsageOwners.delete(agentId);
+        if (owner.agentIds.size === 0) {
+            this.settleBackgroundUsageGroup(owner, owner.succeeded);
+        }
+    }
+    settleBackgroundUsageGroup(owner, succeeded) {
+        for (const timer of owner.missingTerminalTimers.values()) {
+            clearTimeout(timer);
+        }
+        owner.missingTerminalTimers.clear();
+        for (const agentId of owner.agentIds) {
+            if (this.backgroundUsageOwners.get(agentId) === owner) {
+                this.backgroundUsageOwners.delete(agentId);
+            }
+        }
+        owner.agentIds.clear();
+        owner.resolve(succeeded && owner.succeeded);
+    }
+    updateBackgroundUsageRegistryState(agentId, active) {
+        const owner = this.backgroundUsageOwners.get(agentId);
+        if (!owner)
+            return;
+        const existing = owner.missingTerminalTimers.get(agentId);
+        if (active) {
+            if (existing)
+                clearTimeout(existing);
+            owner.missingTerminalTimers.delete(agentId);
+            return;
+        }
+        this.refreshMissingBackgroundTerminalGrace(agentId);
+    }
+    refreshMissingBackgroundTerminalGrace(agentId) {
+        const owner = this.backgroundUsageOwners.get(agentId);
+        if (!owner)
+            return;
+        const registryRun = this.reportedBackgroundTasks.get(agentId);
+        if (registryRun?.state === 'running' || registryRun?.state === 'waiting') {
+            this.updateBackgroundUsageRegistryState(agentId, true);
+            return;
+        }
+        const existing = owner.missingTerminalTimers.get(agentId);
+        if (existing)
+            clearTimeout(existing);
+        owner.missingTerminalTimers.set(agentId, setTimeout(() => {
+            this.settleBackgroundUsageOwner(agentId, false);
+        }, this.backgroundUsageOwnerTimeoutMs));
+    }
     async interruptAttachedTurn(turn) {
         try {
             const result = await this.session.rpc.interruptMainTurn({ flushQueued: false });
@@ -935,6 +1099,7 @@ export class CopilotSdkSessionAdapter {
                 return;
             }
             this.activeTurn = undefined;
+            this.deliverAccumulatedTurnUsage(turn);
             turn.reject(normalizeError(error));
         }
     }
@@ -946,7 +1111,58 @@ export class CopilotSdkSessionAdapter {
         this.activeTurn = undefined;
         const stopReason = aborted || turn.aborted ? 'cancelled' : 'end_turn';
         this.emitUpdate(stopUpdate(stopReason));
-        turn.resolve({ stopReason });
+        if (!turn.backgroundSucceeded) {
+            turn.onExecutionContinuation?.(Promise.resolve(false));
+        }
+        if (turn.backgroundAgentIds.size > 0 &&
+            turn.onExecutionContinuation) {
+            let resolveContinuation;
+            const completion = new Promise((resolve) => {
+                resolveContinuation = resolve;
+            });
+            const owner = {
+                agentIds: new Set(turn.backgroundAgentIds),
+                usageKeys: new Set(turn.usageKeys),
+                onUsage: turn.onUsage,
+                succeeded: true,
+                missingTerminalTimers: new Map(),
+                resolve: resolveContinuation,
+            };
+            for (const agentId of owner.agentIds) {
+                const previous = this.backgroundUsageOwners.get(agentId);
+                if (previous) {
+                    const previousTimer = previous.missingTerminalTimers.get(agentId);
+                    if (previousTimer)
+                        clearTimeout(previousTimer);
+                    previous.missingTerminalTimers.delete(agentId);
+                    previous.agentIds.delete(agentId);
+                    previous.succeeded = false;
+                    if (previous.agentIds.size === 0) {
+                        this.settleBackgroundUsageGroup(previous, false);
+                    }
+                }
+                this.backgroundUsageOwners.set(agentId, owner);
+                this.refreshMissingBackgroundTerminalGrace(agentId);
+            }
+            turn.onExecutionContinuation(completion);
+        }
+        turn.resolve({
+            stopReason,
+            ...(turn.usage && !turn.usageDelivered
+                ? {
+                    usage: {
+                        inputTokens: turn.usage.inputTokens,
+                        outputTokens: turn.usage.outputTokens,
+                        totalTokens: turn.usage.inputTokens +
+                            turn.usage.outputTokens +
+                            turn.usage.cacheReadTokens +
+                            turn.usage.cacheWriteTokens,
+                        cachedReadTokens: turn.usage.cacheReadTokens,
+                        cachedWriteTokens: turn.usage.cacheWriteTokens,
+                    },
+                }
+                : {}),
+        });
     }
     resolveEventTurnId(event) {
         switch (event.type) {
@@ -956,6 +1172,7 @@ export class CopilotSdkSessionAdapter {
             case 'tool.execution_start':
             case 'tool.execution_complete':
                 return event.data.turnId ?? this.currentRootTurnId;
+            case 'assistant.usage':
             case 'assistant.idle':
                 return this.currentRootTurnId ?? this.lastRootTurnId;
             default:

package/dist/providers/create-provider.js

@@ -59,6 +59,10 @@ class CliBackedProviderV2 {
     async generateReply(input, options) {
         const text = await this.cli.generateReply(input.turn, {
             onProgress: createAwaitingUserProgressHandler(options?.onProgress),
+            ...(options?.onUsage ? { onUsage: options.onUsage } : {}),
+            ...(options?.onExecutionContinuation
+                ? { onExecutionContinuation: options.onExecutionContinuation }
+                : {}),
         });
         // 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.

package/dist/providers/prompt-usage.d.ts

@@ -0,0 +1,8 @@
+import type { ProviderTokenUsage } from '../types.js';
+/**
+ * ACP prompt usage defines input and cached tokens as separate counters.
+ * Provider totals, context occupancy, and thought tokens have no equivalent in
+ * the execution ledger and are deliberately not projected.
+ */
+export declare function normalizeAcpPromptUsage(value: unknown): ProviderTokenUsage | undefined;
+export declare function normalizeProviderCallUsage(value: unknown): ProviderTokenUsage | undefined;

package/dist/providers/prompt-usage.js

@@ -0,0 +1,52 @@
+function tokenCount(value, optional = false) {
+    if (value == null && optional)
+        return 0;
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0)
+        return undefined;
+    return value;
+}
+/**
+ * ACP prompt usage defines input and cached tokens as separate counters.
+ * Provider totals, context occupancy, and thought tokens have no equivalent in
+ * the execution ledger and are deliberately not projected.
+ */
+export function normalizeAcpPromptUsage(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const usage = value;
+    const inputTokens = tokenCount(usage.inputTokens);
+    const outputTokens = tokenCount(usage.outputTokens);
+    const cacheReadTokens = tokenCount(usage.cachedReadTokens, true);
+    const cacheWriteTokens = tokenCount(usage.cachedWriteTokens, true);
+    if (inputTokens === undefined ||
+        outputTokens === undefined ||
+        cacheReadTokens === undefined ||
+        cacheWriteTokens === undefined) {
+        return undefined;
+    }
+    return { inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens };
+}
+export function normalizeProviderCallUsage(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const usage = value;
+    const reported = [
+        usage.inputTokens,
+        usage.outputTokens,
+        usage.cacheReadTokens,
+        usage.cacheWriteTokens,
+    ];
+    if (reported.every((tokens) => tokens == null))
+        return undefined;
+    const inputTokens = tokenCount(usage.inputTokens, true);
+    const outputTokens = tokenCount(usage.outputTokens, true);
+    const cacheReadTokens = tokenCount(usage.cacheReadTokens, true);
+    const cacheWriteTokens = tokenCount(usage.cacheWriteTokens, true);
+    if (inputTokens === undefined ||
+        outputTokens === undefined ||
+        cacheReadTokens === undefined ||
+        cacheWriteTokens === undefined) {
+        return undefined;
+    }
+    return { inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens };
+}

package/dist/state-paths.d.ts

@@ -23,6 +23,8 @@ export declare function resolveLocalConfigAgentStateRoot(rootPath: string, agent
 export declare function resolveSharedProtocolKickoffDecisionPath(stateRootDir: string, channelId: string, anchorMessageId: string): string;
 export declare function resolveSharedProtocolStatusPath(stateRootDir: string, channelId: string, anchorMessageId: string): string;
 export declare function resolveConnectionsStatePath(stateRootDir: string): string;
+export declare function resolveExecutionTelemetryOutboxPath(stateRootDir: string): string;
+export declare function resolveExecutionDeliveryJournalPath(stateRootDir: string): string;
 export declare function resolveAttentionStatePath(stateRootDir: string, channelId: string): string;
 export declare function resolveCompactionStatePath(stateRootDir: string, channelId: string): string;
 export declare function resolveAuthorizationAuditPath(stateRootDir: string): string;

package/dist/state-paths.js

@@ -138,6 +138,12 @@ export function resolveSharedProtocolStatusPath(stateRootDir, channelId, anchorM
 export function resolveConnectionsStatePath(stateRootDir) {
     return join(stateRootDir, 'connections-state.sqlite');
 }
+export function resolveExecutionTelemetryOutboxPath(stateRootDir) {
+    return join(stateRootDir, 'execution-telemetry-outbox.json');
+}
+export function resolveExecutionDeliveryJournalPath(stateRootDir) {
+    return join(stateRootDir, 'execution-delivery-journal.json');
+}
 export function resolveAttentionStatePath(stateRootDir, channelId) {
     return join(stateRootDir, 'attention-state', `${encodeSegment(channelId)}.json`);
 }