@borgee/agents-host 0.2.94 → 0.2.101

package/dist/chat/sdk-chat-control-plane.js

@@ -1,4 +1,5 @@
 import { createBorgeePlugin, } from '../plugin-sdk.js';
+import { ExecutionTelemetryOutbox, ExecutionTelemetryOutboxCapacityError, } from '../execution-telemetry.js';
 import { normalizeHostedMessageAttachment } from '../hosted-turn-content.js';
 /**
  * Thin adapter over `@borgee/plugin-sdk` (the same BPP/`/ws/plugin` SDK used by
@@ -10,11 +11,32 @@ export class SdkChatControlPlane {
     pendingMessages = [];
     unsubscribe = null;
     stateUnsubscribe = null;
+    telemetryAckUnsubscribe = null;
+    executionTelemetryRetry;
     activityTransportReady;
+    executionTelemetryOutbox;
+    onExecutionTelemetryError;
     connected = false;
+    transportOnline = false;
+    executionTelemetryCapacityWaitMs;
     me = null;
     constructor(baseUrl, apiKey, createClient = createBorgeePlugin, options = {}) {
-        this.client = createClient({ baseUrl, apiKey, ...options });
+        this.client = createClient({
+            baseUrl,
+            apiKey,
+            ...(options.pluginId ? { pluginId: options.pluginId } : {}),
+        });
+        this.onExecutionTelemetryError =
+            options.onExecutionTelemetryError ??
+                (() => console.error('[agents-host] execution telemetry persistence failed'));
+        this.executionTelemetryCapacityWaitMs =
+            options.executionTelemetryCapacityWaitMs ?? 1_000;
+        this.executionTelemetryOutbox = new ExecutionTelemetryOutbox(options.executionTelemetryOutboxPath, {
+            onRetired: (count) => {
+                this.onExecutionTelemetryError(new Error(`Retired ${count} unacknowledged execution telemetry event(s)`));
+            },
+            policy: options.executionTelemetryOutboxPolicy,
+        });
     }
     onStopTurn(handler) {
         this.client.onStopTurn(handler);
@@ -26,6 +48,7 @@ export class SdkChatControlPlane {
         this.activityTransportReady = handler;
     }
     async connect(onMessage) {
+        await this.executionTelemetryOutbox.load();
         this.unsubscribe = this.client.on('message', (event) => {
             const message = mapInboundToChannelMessage(event);
             if (!this.connected) {
@@ -35,13 +58,26 @@ export class SdkChatControlPlane {
             onMessage(message);
         });
         this.stateUnsubscribe = this.client.on('connectionState', (state) => {
+            this.transportOnline = state.status === 'online';
             if (state.status === 'online') {
                 this.activityTransportReady?.();
+                void this.flushExecutionTelemetry(true);
             }
+            else {
+                this.cancelExecutionTelemetryRetry();
+            }
+        });
+        this.telemetryAckUnsubscribe = this.client.on('executionTelemetryAck', (ack) => {
+            void this.executionTelemetryOutbox
+                .acknowledge(ack.eventId)
+                .then(() => this.scheduleExecutionTelemetryRetry())
+                .catch(this.onExecutionTelemetryError);
         });
         try {
             await this.client.connect();
             this.connected = true;
+            this.transportOnline =
+                this.transportOnline || this.client.connectionState?.status === 'online';
             if (this.client.agentId) {
                 this.me = { id: this.client.agentId };
             }
@@ -49,26 +85,36 @@ export class SdkChatControlPlane {
                 onMessage(message);
             }
             this.pendingMessages = [];
+            await this.flushExecutionTelemetry(true);
         }
         catch (error) {
+            this.transportOnline = false;
+            this.cancelExecutionTelemetryRetry();
             this.unsubscribe?.();
             this.unsubscribe = null;
             this.stateUnsubscribe?.();
             this.stateUnsubscribe = null;
+            this.telemetryAckUnsubscribe?.();
+            this.telemetryAckUnsubscribe = null;
             this.pendingMessages = [];
             throw error;
         }
     }
     async close() {
         this.connected = false;
+        this.transportOnline = false;
+        this.cancelExecutionTelemetryRetry();
         this.pendingMessages = [];
         this.unsubscribe?.();
         this.unsubscribe = null;
         this.stateUnsubscribe?.();
         this.stateUnsubscribe = null;
+        this.telemetryAckUnsubscribe?.();
+        this.telemetryAckUnsubscribe = null;
         this.activityTransportReady = undefined;
         this.client.onStopTurn(undefined);
         this.client.onStopBackgroundRun?.(undefined);
+        await this.executionTelemetryOutbox.settle();
         await this.client.close();
     }
     async postMessage(input) {
@@ -82,18 +128,74 @@ export class SdkChatControlPlane {
     reportActivity(input) {
         this.client.reportActivity(input);
     }
+    reportTaskFinished(input) {
+        this.client.reportTaskFinished?.(input);
+    }
     async editMessage(messageId, content) {
         await this.client.editMessage({ messageId, body: content });
     }
     async deleteMessage(messageId) {
         await this.client.deleteMessage({ messageId });
     }
-    startTyping(channelId) {
-        return this.client.startTyping(channelId);
+    reportTyping(channelId) {
+        this.client.reportTyping(channelId);
     }
     reportTurnActivity(input) {
         return this.client.reportTurnActivity(input);
     }
+    async reportExecutionTelemetry(frame) {
+        if (!this.client.reportExecutionTelemetry) {
+            throw new Error('Plugin SDK execution telemetry is unavailable');
+        }
+        try {
+            await this.executionTelemetryOutbox.enqueue(frame);
+        }
+        catch (error) {
+            if (!(error instanceof ExecutionTelemetryOutboxCapacityError) ||
+                !this.transportOnline) {
+                throw error;
+            }
+            await this.flushExecutionTelemetry(true);
+            const capacityAvailable = await this.executionTelemetryOutbox.waitForCapacity(this.executionTelemetryCapacityWaitMs);
+            if (!capacityAvailable)
+                throw error;
+            await this.executionTelemetryOutbox.enqueue(frame);
+        }
+        await this.flushExecutionTelemetry();
+    }
+    async flushExecutionTelemetry(force = false) {
+        if (!this.connected || !this.transportOnline || !this.client.reportExecutionTelemetry)
+            return;
+        try {
+            await this.executionTelemetryOutbox.flush((frame) => {
+                this.client.reportExecutionTelemetry?.(frame);
+            }, force);
+        }
+        catch (error) {
+            this.onExecutionTelemetryError(error);
+        }
+        finally {
+            this.scheduleExecutionTelemetryRetry();
+        }
+    }
+    scheduleExecutionTelemetryRetry() {
+        this.cancelExecutionTelemetryRetry();
+        if (!this.connected || !this.transportOnline)
+            return;
+        const delay = this.executionTelemetryOutbox.nextRetryDelayMs();
+        if (delay === undefined)
+            return;
+        this.executionTelemetryRetry = setTimeout(() => {
+            this.executionTelemetryRetry = undefined;
+            void this.flushExecutionTelemetry();
+        }, Math.max(1, delay));
+    }
+    cancelExecutionTelemetryRetry() {
+        if (!this.executionTelemetryRetry)
+            return;
+        clearTimeout(this.executionTelemetryRetry);
+        this.executionTelemetryRetry = undefined;
+    }
     async getMe() {
         if (this.me) {
             return this.me;
@@ -114,6 +216,34 @@ export class SdkChatControlPlane {
             kind: user.kind,
         }));
     }
+    async listChannelFiles(input) {
+        const files = await this.client.listChannelFiles({ channelId: input.channelId });
+        return files.map((file) => ({
+            id: file.id,
+            ownerUserId: file.ownerUserId,
+            channelId: file.channelId,
+            path: file.path,
+            parentPath: file.parentPath,
+            name: file.name,
+            isDirectory: file.isDirectory,
+            mimeType: file.mimeType,
+            sizeBytes: file.sizeBytes,
+            source: file.source,
+            sourceMessageId: file.sourceMessageId,
+            createdAt: file.createdAt,
+            updatedAt: file.updatedAt,
+        }));
+    }
+    async readChannelFile(input) {
+        return await this.client.readChannelFile(input);
+    }
+    async publishChannelFile(input) {
+        const file = await this.client.publishChannelFile(input);
+        return {
+            ...file,
+            sourceMessageId: file.sourceMessageId,
+        };
+    }
     async readChannelHistory(input) {
         const messages = await this.client.readHistory({
             channelId: input.channelId,
@@ -175,5 +305,6 @@ export function mapInboundToChannelMessage(event) {
         content_type: event.message?.contentType,
         attachments: event.message?.attachments?.map(normalizeHostedMessageAttachment),
         created_at: event.createdAt,
+        ...(event.executionGrant ? { execution_grant: event.executionGrant } : {}),
     };
 }

package/dist/context/skill-manual.js

@@ -14,7 +14,7 @@ export function buildSkillManualReadLine(skillRuntime) {
  */
 export function buildSkillManualLines(skillRuntime) {
     return [
-        "A packaged local CLI reads this Borgee channel and acts on its tasks: channel history, visible participants, this channel's tasks and their properties, and short auxiliary mentions.",
+        "A packaged local CLI reads this Borgee channel and acts on its tasks: channel history, channel files, visible participants, this channel's tasks and their properties, and short auxiliary mentions.",
         buildSkillManualReadLine(skillRuntime),
         'Every command the manual documents is already authorized on a turn whose prompt names a gateway credential file. Run them directly and do not ask the user for permission first.',
     ];

package/dist/execution-telemetry.d.ts

@@ -0,0 +1,96 @@
+import type { ExecutionGrant, ExecutionTelemetryFrame } from './plugin-sdk.js';
+import type { ProviderKind, ProviderTokenUsage } from './types.js';
+export interface ExecutionTelemetrySink {
+    reportExecutionTelemetry(frame: ExecutionTelemetryFrame): Promise<void>;
+}
+export interface StoredExecutionUsage extends ProviderTokenUsage {
+    provider: ProviderKind;
+}
+export type ExecutionDeliveryClaim = 'new' | 'recovering' | 'completed';
+export declare class ExecutionDeliveryJournal {
+    private readonly path?;
+    private readonly maxCompletedEntries;
+    private readonly now;
+    private entries;
+    private loaded;
+    private writeQueue;
+    constructor(path?: string | undefined, maxCompletedEntries?: number, now?: () => number);
+    load(): Promise<void>;
+    claim(executionId: string): Promise<ExecutionDeliveryClaim>;
+    complete(executionId: string): Promise<void>;
+    recordUsage(executionId: string, usage: StoredExecutionUsage): Promise<void>;
+    readUsage(executionId: string): Promise<StoredExecutionUsage | undefined>;
+    private mutate;
+    private isStoredExecutionDelivery;
+    private isStoredExecutionUsage;
+}
+export declare class ExecutionTelemetryReporter {
+    private readonly grant;
+    private readonly sink;
+    private readonly now;
+    private readonly persistUsage?;
+    private started;
+    private finished;
+    private attemptCount;
+    private attemptsSucceeded;
+    private provider;
+    private pendingUsage;
+    private usageFrameDurable;
+    private usagePersistence;
+    private readonly continuations;
+    private finishing?;
+    get startFrameDurable(): boolean;
+    get terminalFrameDurable(): boolean;
+    get allRequiredFramesDurable(): boolean;
+    constructor(grant: ExecutionGrant, sink: ExecutionTelemetrySink, now?: () => number, persistUsage?: ((provider: ProviderKind, usage: ProviderTokenUsage) => Promise<void>) | undefined);
+    start(): Promise<void>;
+    usage(provider: ProviderKind, usage: ProviderTokenUsage): Promise<void>;
+    noteAttempt(succeeded: boolean): void;
+    noteFailure(): void;
+    hold(completion: Promise<boolean>): void;
+    finish(succeeded?: boolean): Promise<void>;
+    private finalize;
+}
+export interface ExecutionTelemetryOutboxPolicy {
+    maxEntries: number;
+    maxAttempts: number;
+    retentionMs: number;
+    retryIntervalMs: number;
+}
+export declare class ExecutionTelemetryOutboxCapacityError extends Error {
+    constructor();
+}
+type ExecutionTelemetryOutboxOptions = {
+    now?: () => number;
+    onRetired?: (count: number) => void;
+    policy?: Partial<ExecutionTelemetryOutboxPolicy>;
+};
+export declare class ExecutionTelemetryOutbox {
+    private readonly path?;
+    private frames;
+    private loaded;
+    private writeQueue;
+    private flushInFlight?;
+    private readonly now;
+    private readonly onRetired?;
+    private readonly policy;
+    private readonly capacityWaiters;
+    constructor(path?: string | undefined, options?: ExecutionTelemetryOutboxOptions);
+    load(): Promise<void>;
+    enqueue(frame: ExecutionTelemetryFrame): Promise<void>;
+    acknowledge(eventId: string): Promise<void>;
+    flush(send: (frame: ExecutionTelemetryFrame) => void, force?: boolean): Promise<void>;
+    private flushOnce;
+    settle(): Promise<void>;
+    pendingCount(): number;
+    nextRetryDelayMs(): number | undefined;
+    hasCapacity(): boolean;
+    waitForCapacity(timeoutMs: number): Promise<boolean>;
+    private retireExpired;
+    private mutate;
+    private persist;
+    private frameTimestamp;
+    private isStoredEntry;
+    private notifyCapacityAvailable;
+}
+export {};