@borgee/agents-host 0.2.94 → 0.2.101

package/dist/agents-host.d.ts

@@ -1,5 +1,6 @@
 import type { ChatControlPlane } from './chat/chat-control-plane.js';
 import { type AgentsHostRuntimeOptions } from './debug.js';
+import { ExecutionDeliveryJournal } from './execution-telemetry.js';
 import { type ProviderAdapter } from './providers/provider-adapter.js';
 import type { AgentsHostConfig } from './types.js';
 /**
@@ -13,6 +14,7 @@ export declare class AgentsHost {
     private readonly borgee;
     private readonly backgroundRuns;
     private readonly logger;
+    private readonly executionDeliveryJournal;
     private readonly contextInjectionEnabled;
     private readonly collaborationEnabled;
     private readonly collaborationOutcomeModelEnabled;
@@ -20,6 +22,8 @@ export declare class AgentsHost {
     private readonly taskThreadCollaborationContractEnabled;
     private readonly collaborationCapabilitiesDiagnosticsEnabled;
     private readonly activeTurns;
+    private readonly executionTelemetryByExecutionId;
+    private readonly executionDispatches;
     private readonly awaitingUserByChannel;
     private readonly collaborationOutcomeByChannel;
     /**
@@ -49,6 +53,7 @@ export declare class AgentsHost {
     private controlPlaneClosed;
     constructor(config: AgentsHostConfig, deps?: {
         borgee?: ChatControlPlane;
+        executionDeliveryJournal?: ExecutionDeliveryJournal;
         provider?: ProviderAdapter;
         runtimeOptions?: AgentsHostRuntimeOptions;
     });
@@ -56,6 +61,9 @@ export declare class AgentsHost {
     stop(): Promise<void>;
     private trackActiveTurn;
     private dispatchMessage;
+    private runClaimedExecution;
+    private runMessageWithExecutionTelemetry;
+    private createExecutionTelemetryReporter;
     private dispatchAutonomousReply;
     private handleLegacyMessage;
     private handleCollaborationMessage;

package/dist/agents-host.js

@@ -5,6 +5,8 @@ import { SdkChatControlPlane } from './chat/sdk-chat-control-plane.js';
 import { HostLogger, summarizeError } from './debug.js';
 import { toReportedActivity } from './progress-to-activity.js';
 import { BackgroundRunTracker } from './background-runs.js';
+import { ExecutionDeliveryJournal, ExecutionTelemetryReporter, } from './execution-telemetry.js';
+import { startTypingLease } from './typing-lease.js';
 import { ATTENTION_FOLLOW_SEMANTICS_COMPATIBILITY_GATE, COLLABORATION_CAPABILITIES_DIAGNOSTICS_COMPATIBILITY_GATE, COLLABORATION_OUTCOME_MODEL_COMPATIBILITY_GATE, COLLABORATION_SKILL_FIRST_COMPATIBILITY_GATE, CONTEXT_INJECTION_COMPATIBILITY_GATE, LOCALHOST_GATEWAY_COMPATIBILITY_GATE, POLICY_AUDIT_ENFORCEMENT_COMPATIBILITY_GATE, resolveInternalPolicyMode, resolveInternalCompatibilityGates, SKILL_RUNTIME_COMPATIBILITY_GATE, TASK_THREAD_COLLABORATION_CONTRACT_COMPATIBILITY_GATE, TOKEN_BINDING_COMPATIBILITY_GATE, } from './compatibility-gates.js';
 import { buildNormalizedAttentionSnapshot, parsePersistedAttentionSnapshot, } from './context/attention.js';
 import { mergeCompactionSnapshot, parsePersistedCompactionSnapshot, } from './context/compaction.js';
@@ -14,7 +16,7 @@ import { extractTaskIdFromTaskAssignmentContent, resolveTaskAssignmentStatePath,
 import { AuthorizationAuditSink, } from './policy/authorization-audit.js';
 import { createProvider } from './providers/create-provider.js';
 import { ProviderTurnCancelledError } from './providers/provider-adapter.js';
-import { resolveAttentionStatePath, resolveCompactionStatePath, resolveSharedProtocolKickoffDecisionPath, resolveSharedProtocolStatusPath, } from './state-paths.js';
+import { resolveAttentionStatePath, resolveCompactionStatePath, resolveExecutionDeliveryJournalPath, resolveExecutionTelemetryOutboxPath, resolveSharedProtocolKickoffDecisionPath, resolveSharedProtocolStatusPath, } from './state-paths.js';
 import { appendVisibleMention as appendVisibleBodyMention, extractVisibleMentionIds as extractCanonicalMentionIds, } from './visible-mentions.js';
 import { buildHostedIncomingContentText, buildHostedTurnContentParts, extractHostedMessageAttachments, normalizeHostedMessageAttachment, } from './hosted-turn-content.js';
 import { waitForTaskForThread } from './task-thread-resolution.js';
@@ -110,6 +112,12 @@ class DefaultHostRuntime {
             deps.borgee ??
                 new SdkChatControlPlane(config.borgeeBaseUrl, config.agent.agentApiKey, undefined, {
                     pluginId: `agents-host:${config.agent.provider}`,
+                    executionTelemetryOutboxPath: resolveExecutionTelemetryOutboxPath(config.stateRootDir),
+                    onExecutionTelemetryError: (error) => {
+                        deps.logger.error('execution telemetry transport failed', {
+                            error: summarizeError(error),
+                        });
+                    },
                 });
         this.gateway = createLocalhostGatewayController({
             gateEnabled: localhostGatewayGateEnabled,
@@ -291,6 +299,7 @@ export class AgentsHost {
     borgee;
     backgroundRuns;
     logger;
+    executionDeliveryJournal;
     contextInjectionEnabled;
     collaborationEnabled;
     collaborationOutcomeModelEnabled;
@@ -298,6 +307,8 @@ export class AgentsHost {
     taskThreadCollaborationContractEnabled;
     collaborationCapabilitiesDiagnosticsEnabled;
     activeTurns = new Set();
+    executionTelemetryByExecutionId = new Map();
+    executionDispatches = new Map();
     awaitingUserByChannel = new Map();
     collaborationOutcomeByChannel = new Map();
     /**
@@ -328,6 +339,9 @@ export class AgentsHost {
     constructor(config, deps) {
         this.config = config;
         this.logger = new HostLogger(deps?.runtimeOptions);
+        this.executionDeliveryJournal =
+            deps?.executionDeliveryJournal ??
+                new ExecutionDeliveryJournal(resolveExecutionDeliveryJournalPath(config.stateRootDir));
         const compatibilityGates = resolveInternalCompatibilityGates();
         const contextInjectionGateEnabled = compatibilityGates.has(CONTEXT_INJECTION_COMPATIBILITY_GATE);
         this.contextInjectionEnabled = contextInjectionGateEnabled;
@@ -368,6 +382,14 @@ export class AgentsHost {
             cancel: this.provider.cancelBackgroundRun
                 ? (channelId, providerRunId) => (this.provider.cancelBackgroundRun(channelId, providerRunId))
                 : undefined,
+            onFinished: (channelId, run) => {
+                this.borgee.reportTaskFinished?.({
+                    channelId,
+                    taskId: run.runId,
+                    outcome: run.state,
+                    ...(run.state === 'failed' ? { reason: 'unknown' } : {}),
+                });
+            },
         });
     }
     async start() {
@@ -384,6 +406,7 @@ export class AgentsHost {
         const bufferedMessages = [];
         let bufferingMessages = true;
         try {
+            await this.executionDeliveryJournal.load();
             this.provider.onAutonomousReply?.((reply) => this.dispatchAutonomousReply(reply));
             await this.runtime.start((message) => {
                 if (!this.started) {
@@ -463,16 +486,145 @@ export class AgentsHost {
     }
     trackActiveTurn(task) {
         this.activeTurns.add(task);
-        void task.finally(() => {
+        void task
+            .catch((error) => {
+            this.logger.error('dispatched turn failed', {
+                error: summarizeError(error),
+            });
+        })
+            .finally(() => {
             this.activeTurns.delete(task);
         });
     }
     dispatchMessage(message) {
-        const task = this.collaborationEnabled
+        const executionId = message.execution_grant?.executionId;
+        const existing = executionId
+            ? this.executionDispatches.get(executionId)
+            : undefined;
+        if (existing) {
+            this.trackActiveTurn(existing);
+            return;
+        }
+        const run = () => this.collaborationEnabled
             ? this.handleCollaborationMessage(message)
             : this.enqueueChannelTurn(message.channel_id, () => this.handleLegacyMessage(message));
+        const work = executionId
+            ? this.runClaimedExecution(message, run)
+            : this.runMessageWithExecutionTelemetry(message, run).then((result) => {
+                if (result.error)
+                    throw result.error;
+            });
+        const task = executionId
+            ? work.finally(() => {
+                this.executionDispatches.delete(executionId);
+            })
+            : work;
+        if (executionId)
+            this.executionDispatches.set(executionId, task);
         this.trackActiveTurn(task);
     }
+    async runClaimedExecution(message, run) {
+        const grant = message.execution_grant;
+        const claim = await this.executionDeliveryJournal.claim(grant.executionId);
+        if (claim === 'completed')
+            return;
+        if (claim === 'recovering') {
+            if (this.borgee.reportExecutionTelemetry) {
+                let reporter = this.executionTelemetryByExecutionId.get(grant.executionId);
+                const restoredReporter = !reporter;
+                reporter ??= this.createExecutionTelemetryReporter(grant);
+                this.executionTelemetryByExecutionId.set(grant.executionId, reporter);
+                await reporter.start();
+                if (restoredReporter) {
+                    const persistedUsage = await this.executionDeliveryJournal.readUsage(grant.executionId);
+                    if (persistedUsage) {
+                        const { provider, ...usage } = persistedUsage;
+                        await reporter.usage(provider, usage);
+                    }
+                }
+                reporter.noteFailure();
+                let finishError;
+                try {
+                    await reporter.finish(false);
+                }
+                catch (error) {
+                    finishError = error;
+                }
+                if (reporter.allRequiredFramesDurable) {
+                    await this.executionDeliveryJournal.complete(grant.executionId);
+                    this.executionTelemetryByExecutionId.delete(grant.executionId);
+                }
+                if (finishError)
+                    throw finishError;
+                return;
+            }
+            throw new Error('Execution telemetry is unavailable for interrupted delivery recovery');
+        }
+        const result = await this.runMessageWithExecutionTelemetry(message, run);
+        if (result.allRequiredFramesDurable) {
+            await this.executionDeliveryJournal.complete(grant.executionId);
+        }
+        if (result.error)
+            throw result.error;
+    }
+    async runMessageWithExecutionTelemetry(message, run) {
+        const grant = message.execution_grant;
+        const reporter = grant && this.borgee.reportExecutionTelemetry
+            ? this.executionTelemetryByExecutionId.get(grant.executionId) ??
+                this.createExecutionTelemetryReporter(grant)
+            : undefined;
+        if (grant && !reporter) {
+            return {
+                allRequiredFramesDurable: false,
+                error: new Error('Execution telemetry is unavailable for admitted delivery'),
+            };
+        }
+        if (grant && reporter) {
+            this.executionTelemetryByExecutionId.set(grant.executionId, reporter);
+        }
+        let runError;
+        try {
+            await run();
+        }
+        catch (error) {
+            reporter?.noteFailure();
+            runError = error;
+        }
+        let finishError;
+        if (reporter) {
+            try {
+                await reporter.finish();
+            }
+            catch (error) {
+                finishError = error;
+                this.logger.error('execution telemetry finish failed', {
+                    error: summarizeError(error),
+                });
+            }
+            finally {
+                if (reporter.allRequiredFramesDurable &&
+                    grant &&
+                    this.executionTelemetryByExecutionId.get(grant.executionId) === reporter) {
+                    this.executionTelemetryByExecutionId.delete(grant.executionId);
+                }
+            }
+        }
+        const error = runError && finishError
+            ? new AggregateError([runError, finishError], 'Execution and telemetry finalization both failed')
+            : runError ?? finishError;
+        return {
+            allRequiredFramesDurable: reporter?.allRequiredFramesDurable ?? grant === undefined,
+            ...(error ? { error } : {}),
+        };
+    }
+    createExecutionTelemetryReporter(grant) {
+        return new ExecutionTelemetryReporter(grant, {
+            reportExecutionTelemetry: (frame) => this.borgee.reportExecutionTelemetry(frame),
+        }, Date.now, (provider, usage) => this.executionDeliveryJournal.recordUsage(grant.executionId, {
+            provider,
+            ...usage,
+        }));
+    }
     dispatchAutonomousReply(reply) {
         if (!this.started
             || this.controlPlaneClosed
@@ -2314,17 +2466,6 @@ export class AgentsHost {
                 ? 'silent-kickoff'
                 : undefined;
         const turnExecutionId = activeTurn?.turnExecutionId ?? null;
-        const stopTyping = silentTurn ? () => { } : this.borgee.startTyping(channelId);
-        const collaborationGrounding = await this.buildCollaborationGrounding(authorId, options?.incomingAuthorKind, activeTurn, options?.kickoff);
-        const publishesCollaborationDraft = !silentTurn &&
-            !deferDelivery &&
-            this.collaborationEnabled &&
-            turnExecutionId != null &&
-            activeTurn?.protocol === undefined;
-        const supportsProviderProgress = this.provider.capabilities?.progressUpdates?.support === 'supported';
-        const supportsBackgroundRunLifecycle = this.provider.capabilities?.backgroundRuns?.lifecycle === 'supported';
-        const reportsProviderActivity = !silentTurn && supportsProviderProgress;
-        const observeProviderProgress = supportsProviderProgress || supportsBackgroundRunLifecycle;
         const turnContext = {
             eventType: msg.type,
             channelId,
@@ -2337,26 +2478,58 @@ export class AgentsHost {
         };
         const turnStartedAt = Date.now();
         this.logger.debug('starting turn', turnContext);
+        const executionTelemetry = msg.execution_grant
+            ? this.executionTelemetryByExecutionId.get(msg.execution_grant.executionId)
+            : undefined;
+        let executionSucceeded = false;
+        let executionTelemetryStartFailed = false;
         let reply;
         let publicReplyText;
         let visibleReplyBody;
-        const taskThreadCollaborationContract = this.resolveTaskThreadCollaborationContractForTurn(msg, taskThreadContext);
-        const collaborationOutcome = this.collaborationOutcomeModelEnabled
-            ? this.collaborationOutcomeByChannel.get(channelId)
-            : undefined;
-        const missedCollaborationDiagnostic = this.resolveMissedCollaborationDiagnosticForTurn(channelId);
-        const collaborationCapabilities = this.resolveCollaborationCapabilityDeclarationForTurn(taskThreadContext);
-        const incomingParts = options?.incomingParts
-            ?? buildHostedTurnContentParts({
-                text: String(msg.content ?? msg.body ?? content),
-                attachments: msg.attachments,
-            });
-        const activityReporter = silentTurn
-            ? undefined
-            : this.beginTurnActivity(channelId, activeTurn?.generation);
-        await this.ensureCompactionSnapshotLoaded(channelId);
-        const compactionSnapshot = this.compactionSnapshotByChannel.get(channelId);
+        let activityReporter;
+        let typingLease;
         try {
+            if (!silentTurn) {
+                typingLease = startTypingLease(() => this.borgee.reportTyping(channelId));
+            }
+            const collaborationGrounding = await this.buildCollaborationGrounding(authorId, options?.incomingAuthorKind, activeTurn, options?.kickoff);
+            const publishesCollaborationDraft = !silentTurn &&
+                !deferDelivery &&
+                this.collaborationEnabled &&
+                turnExecutionId != null &&
+                activeTurn?.protocol === undefined;
+            const supportsProviderProgress = this.provider.capabilities?.progressUpdates?.support === 'supported';
+            const supportsBackgroundRunLifecycle = this.provider.capabilities?.backgroundRuns?.lifecycle === 'supported';
+            const reportsProviderActivity = !silentTurn && supportsProviderProgress;
+            const observeProviderProgress = supportsProviderProgress || supportsBackgroundRunLifecycle;
+            const taskThreadCollaborationContract = this.resolveTaskThreadCollaborationContractForTurn(msg, taskThreadContext);
+            const collaborationOutcome = this.collaborationOutcomeModelEnabled
+                ? this.collaborationOutcomeByChannel.get(channelId)
+                : undefined;
+            const missedCollaborationDiagnostic = this.resolveMissedCollaborationDiagnosticForTurn(channelId);
+            const collaborationCapabilities = this.resolveCollaborationCapabilityDeclarationForTurn(taskThreadContext);
+            const incomingParts = options?.incomingParts
+                ?? buildHostedTurnContentParts({
+                    text: String(msg.content ?? msg.body ?? content),
+                    attachments: msg.attachments,
+                });
+            activityReporter = silentTurn
+                ? undefined
+                : this.beginTurnActivity(channelId, activeTurn?.generation);
+            await this.ensureCompactionSnapshotLoaded(channelId);
+            const compactionSnapshot = this.compactionSnapshotByChannel.get(channelId);
+            if (executionTelemetry) {
+                try {
+                    await executionTelemetry.start();
+                }
+                catch (error) {
+                    executionTelemetryStartFailed = true;
+                    this.logger.error('execution telemetry start failed', {
+                        error: summarizeError(error),
+                    });
+                    throw error;
+                }
+            }
             reply = await this.provider.generateReply({
                 agentName: this.config.agent.agentName,
                 provider: this.config.agent.provider,
@@ -2397,42 +2570,61 @@ export class AgentsHost {
                             : { taskAssignmentContextOverridePersistence: 'ephemeral' }),
                     }
                     : {}),
-            }, observeProviderProgress
+            }, observeProviderProgress || executionTelemetry
                 ? {
-                    onProgress: (update) => {
-                        if (supportsBackgroundRunLifecycle) {
-                            this.backgroundRuns.observe(channelId, update);
-                            if (update.type === 'activity' && update.activity.background === true) {
-                                this.borgee.reportActivity?.({
-                                    channelId,
-                                    activity: { shape: 'activity', ...update.activity },
-                                });
-                                return;
-                            }
-                        }
-                        if (!this.canAcceptTurnOutput(channelId, activeTurn?.generation)) {
-                            return;
+                    ...(executionTelemetry
+                        ? {
+                            onUsage: (usage) => {
+                                void executionTelemetry.usage(this.config.agent.provider, usage);
+                            },
+                            onExecutionContinuation: (completion) => {
+                                executionTelemetry.hold(completion);
+                            },
                         }
-                        if (supportsProviderProgress && update.type === 'compaction') {
-                            this.noteCompactionProgress(channelId, update.compaction, {
-                                turnExecutionId: activeTurn?.turnExecutionId ?? undefined,
-                            });
-                            return;
-                        }
-                        const reportedActivity = toReportedActivity(update);
-                        if (reportsProviderActivity && reportedActivity) {
-                            activityReporter?.progress(reportedActivity);
-                        }
-                        if (!supportsProviderProgress
-                            || update.type !== 'text'
-                            || update.stream !== 'answer') {
-                            return;
-                        }
-                        if (!publishesCollaborationDraft) {
-                            return;
+                        : {}),
+                    ...(observeProviderProgress
+                        ? {
+                            onProgress: (update) => {
+                                if (supportsBackgroundRunLifecycle) {
+                                    this.backgroundRuns.observe(channelId, update);
+                                    if (update.type === 'activity' && update.activity.background === true) {
+                                        this.borgee.reportActivity?.({
+                                            channelId,
+                                            activity: { shape: 'activity', ...update.activity },
+                                        });
+                                        return;
+                                    }
+                                }
+                                if (!this.canAcceptTurnOutput(channelId, activeTurn?.generation)) {
+                                    return;
+                                }
+                                if (update.type === 'text'
+                                    && update.stream === 'answer'
+                                    && hasVisibleText(update.text)) {
+                                    typingLease?.renew();
+                                }
+                                if (supportsProviderProgress && update.type === 'compaction') {
+                                    this.noteCompactionProgress(channelId, update.compaction, {
+                                        turnExecutionId: activeTurn?.turnExecutionId ?? undefined,
+                                    });
+                                    return;
+                                }
+                                const reportedActivity = toReportedActivity(update);
+                                if (reportsProviderActivity && reportedActivity) {
+                                    activityReporter?.progress(reportedActivity);
+                                }
+                                if (!supportsProviderProgress ||
+                                    update.type !== 'text' ||
+                                    update.stream !== 'answer') {
+                                    return;
+                                }
+                                if (!publishesCollaborationDraft) {
+                                    return;
+                                }
+                                this.publishCollaborationDraft(channelId, activeTurn, update.text);
+                            },
                         }
-                        this.publishCollaborationDraft(channelId, activeTurn, update.text);
-                    },
+                        : {}),
                 }
                 : undefined);
             publicReplyText = resolvePublicReplyText(reply);
@@ -2460,6 +2652,7 @@ export class AgentsHost {
                 return { reply, stale: true, completed: false };
             }
             if (silentTurn) {
+                executionSucceeded = true;
                 this.logger.debug('completed turn', {
                     ...turnContext,
                     durationMs: Date.now() - turnStartedAt,
@@ -2480,6 +2673,7 @@ export class AgentsHost {
                 };
             }
             if (deferDelivery) {
+                executionSucceeded = true;
                 this.logger.debug('completed turn', {
                     ...turnContext,
                     durationMs: Date.now() - turnStartedAt,
@@ -2516,6 +2710,7 @@ export class AgentsHost {
                 if (publishesCollaborationDraft) {
                     this.finalizeCollaborationDraft(channelId, activeTurn, posted.messageId, visibleReplyBody);
                 }
+                executionSucceeded = true;
                 return {
                     reply,
                     deliveredMessageId: posted.messageId,
@@ -2539,6 +2734,7 @@ export class AgentsHost {
                     turnExecutionId: activeTurn.turnExecutionId,
                 });
             }
+            executionSucceeded = true;
             return {
                 reply,
                 deliveredMessageId: null,
@@ -2557,6 +2753,9 @@ export class AgentsHost {
                     turnExecutionId: activeTurn.turnExecutionId,
                 });
             }
+            if (executionTelemetryStartFailed) {
+                throw error;
+            }
             if (error instanceof ProviderTurnCancelledError) {
                 const cancelledReplyText = error.publicReplyText?.trim();
                 if (!silentTurn &&
@@ -2634,7 +2833,10 @@ export class AgentsHost {
             };
         }
         finally {
-            stopTyping();
+            if (executionTelemetry) {
+                executionTelemetry.noteAttempt(executionSucceeded);
+            }
+            typingLease?.stop();
             activityReporter?.end();
         }
     }

package/dist/background-runs.d.ts

@@ -4,6 +4,10 @@ interface BackgroundRunTrackerOptions {
     lifecycleSupported: boolean;
     targetedCancellationSupported: boolean;
     cancel?: (channelId: string, providerRunId: string) => Promise<boolean>;
+    onFinished?: (channelId: string, run: {
+        runId: string;
+        state: 'completed' | 'failed' | 'cancelled';
+    }) => void;
 }
 export declare class BackgroundRunTracker {
     private readonly report;

package/dist/background-runs.js

@@ -99,6 +99,10 @@ export class BackgroundRunTracker {
             historySize -= 1;
         }
         this.publish(run);
+        if (isConcreteTerminal(state) &&
+            (startsNewExecution || !held || !isConcreteTerminal(held.state))) {
+            this.options.onFinished?.(channelId, { runId: run.runId, state });
+        }
     }
     replay() {
         for (const run of this.runs.values()) {
@@ -166,10 +170,10 @@ function runState(status) {
     }
 }
 function isTerminal(state) {
-    return (state === 'completed' ||
-        state === 'failed' ||
-        state === 'cancelled' ||
-        state === 'unknown');
+    return (isConcreteTerminal(state) || state === 'unknown');
+}
+function isConcreteTerminal(state) {
+    return state === 'completed' || state === 'failed' || state === 'cancelled';
 }
 function stableRunId(channelId, providerRunId, startedAt, executionId) {
     const digest = createHash('sha256')

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

@@ -1,5 +1,5 @@
-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';
+import type { AgentActivity, ExecutionTelemetryFrame, ReportTaskFinishedInput, ReportTurnActivityInput, StopBackgroundRunHandler, StopTurnHandler, TurnActivityReporter } from '../plugin-sdk.js';
+import type { ChannelSummary, ChannelFileEntry, ChannelFileContent, PublishChannelFileInput, 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;
@@ -9,15 +9,26 @@ export interface ChatControlPlane {
     postMessage(input: PostMessageInput): Promise<PostedMessage>;
     editMessage(messageId: string, content: string): Promise<void>;
     deleteMessage(messageId: string): Promise<void>;
-    startTyping(channelId: string): () => void;
+    reportTyping(channelId: string): void;
     /** Opens one turn's report on the activity rail. Fire-and-forget: nothing recovers what it sends. */
     reportTurnActivity(input: ReportTurnActivityInput): TurnActivityReporter;
+    reportExecutionTelemetry?(frame: ExecutionTelemetryFrame): Promise<void>;
+    reportTaskFinished?(input: ReportTaskFinishedInput): void;
     reportActivity?(input: {
         channelId: string;
         activity: AgentActivity;
     }): void;
     getMe(): Promise<MeResponseUser>;
     listUsers(): Promise<DirectoryUser[]>;
+    listChannelFiles(input: {
+        channelId: string;
+    }): Promise<ChannelFileEntry[]>;
+    readChannelFile(input: {
+        channelId: string;
+        path: string;
+        textOnly: boolean;
+    }): Promise<ChannelFileContent>;
+    publishChannelFile(input: PublishChannelFileInput): Promise<ChannelFileEntry>;
     listChannels(): Promise<ChannelSummary[]>;
     readChannelHistory(input: ReadChannelHistoryInput): Promise<ChannelHistoryEntry[]>;
     createTask(input: CreateTaskInput): Promise<Task>;

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

@@ -1,9 +1,15 @@
-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 BorgeePluginClient, type BorgeePluginOptions, type ExecutionTelemetryFrame, type InboundMessageEvent, type ReportTaskFinishedInput, type ReportTurnActivityInput, type StopTurnHandler, type StopBackgroundRunHandler, type TurnActivityReporter } from '../plugin-sdk.js';
+import { type ExecutionTelemetryOutboxPolicy } from '../execution-telemetry.js';
+import type { ChannelSummary, ChannelFileEntry, ChannelFileContent, PublishChannelFileInput, 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' | 'onStopBackgroundRun' | 'reportActivity' | 'readHistory' | 'reportTurnActivity' | 'sendMessage' | 'startTyping' | 'updateTask' | 'setTaskProperty' | 'deleteTaskProperty'>;
+type PluginClientLike = Pick<BorgeePluginClient, 'agentId' | 'close' | 'connect' | 'createTask' | 'deleteMessage' | 'editMessage' | 'getMe' | 'getTask' | 'listChannelFiles' | 'readChannelFile' | 'publishChannelFile' | 'listChannels' | 'listTasks' | 'listUsers' | 'on' | 'onStopTurn' | 'onStopBackgroundRun' | 'reportActivity' | 'readHistory' | 'reportTurnActivity' | 'reportTyping' | 'sendMessage' | 'updateTask' | 'setTaskProperty' | 'deleteTaskProperty'> & Partial<Pick<BorgeePluginClient, 'connectionState' | 'reportExecutionTelemetry' | 'reportTaskFinished'>>;
 type PluginClientFactory = (options: BorgeePluginOptions) => PluginClientLike;
-type SdkChatControlPlaneOptions = Pick<BorgeePluginOptions, 'pluginId'>;
+type SdkChatControlPlaneOptions = Pick<BorgeePluginOptions, 'pluginId'> & {
+    executionTelemetryCapacityWaitMs?: number;
+    executionTelemetryOutboxPath?: string;
+    executionTelemetryOutboxPolicy?: Partial<ExecutionTelemetryOutboxPolicy>;
+    onExecutionTelemetryError?: (error: unknown) => void;
+};
 /**
  * Thin adapter over `@borgee/plugin-sdk` (the same BPP/`/ws/plugin` SDK used by
  * the OpenClaw plugin) that implements the minimal `ChatControlPlane` surface
@@ -14,8 +20,14 @@ export declare class SdkChatControlPlane implements ChatControlPlane {
     private pendingMessages;
     private unsubscribe;
     private stateUnsubscribe;
+    private telemetryAckUnsubscribe;
+    private executionTelemetryRetry?;
     private activityTransportReady;
+    private readonly executionTelemetryOutbox;
+    private readonly onExecutionTelemetryError;
     private connected;
+    private transportOnline;
+    private readonly executionTelemetryCapacityWaitMs;
     private me;
     constructor(baseUrl: string, apiKey: string, createClient?: PluginClientFactory, options?: SdkChatControlPlaneOptions);
     onStopTurn(handler: StopTurnHandler | undefined): void;
@@ -25,12 +37,26 @@ export declare class SdkChatControlPlane implements ChatControlPlane {
     close(): Promise<void>;
     postMessage(input: PostMessageInput): Promise<PostedMessage>;
     reportActivity(input: Parameters<BorgeePluginClient['reportActivity']>[0]): void;
+    reportTaskFinished(input: ReportTaskFinishedInput): void;
     editMessage(messageId: string, content: string): Promise<void>;
     deleteMessage(messageId: string): Promise<void>;
-    startTyping(channelId: string): () => void;
+    reportTyping(channelId: string): void;
     reportTurnActivity(input: ReportTurnActivityInput): TurnActivityReporter;
+    reportExecutionTelemetry(frame: ExecutionTelemetryFrame): Promise<void>;
+    private flushExecutionTelemetry;
+    private scheduleExecutionTelemetryRetry;
+    private cancelExecutionTelemetryRetry;
     getMe(): Promise<MeResponseUser>;
     listUsers(): Promise<DirectoryUser[]>;
+    listChannelFiles(input: {
+        channelId: string;
+    }): Promise<ChannelFileEntry[]>;
+    readChannelFile(input: {
+        channelId: string;
+        path: string;
+        textOnly: boolean;
+    }): Promise<ChannelFileContent>;
+    publishChannelFile(input: PublishChannelFileInput): Promise<ChannelFileEntry>;
     readChannelHistory(input: ReadChannelHistoryInput): Promise<ChannelHistoryEntry[]>;
     listChannels(): Promise<ChannelSummary[]>;
     createTask(input: CreateTaskInput): Promise<Task>;