@borgee/agents-host 0.2.97 → 0.2.110

package/dist/catalog-worker.js

@@ -0,0 +1,21 @@
+import { createRequire as __nodeCreateRequire } from 'node:module';
+const require = __nodeCreateRequire(import.meta.url);
+
+// ../agent-provider-claude/src/catalog-worker.ts
+import { getSessionInfo, getSessionMessages, listSessions, listSubagents, getSubagentMessages } from "@borgee/claude-native-sdk";
+var [operation, sessionId, childId] = process.argv.slice(2);
+try {
+  const result = operation === "list" ? await listSessions() : operation === "info" && sessionId ? await getSessionInfo(sessionId) : operation === "messages" && sessionId ? await getSessionMessages(sessionId) : operation === "child-messages" && sessionId && childId ? await getSubagentMessages(sessionId, childId) : operation === "children" && sessionId ? await readChildren(sessionId) : (() => {
+    throw new Error("Unknown catalog operation.");
+  })();
+  process.stdout.write(JSON.stringify(result ?? null));
+} catch {
+  process.stderr.write("Claude native catalog could not be read.\n");
+  process.exitCode = 1;
+}
+async function readChildren(parentId) {
+  const children = [];
+  for (const id of await listSubagents(parentId)) children.push({ id, messages: await getSubagentMessages(parentId, id) });
+  return children;
+}
+//# sourceMappingURL=catalog-worker.js.map

package/dist/catalog-worker.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../agent-provider-claude/src/catalog-worker.ts"],
+  "sourcesContent": ["import { getSessionInfo, getSessionMessages, listSessions, listSubagents, getSubagentMessages } from '@anthropic-ai/claude-agent-sdk';\n\nconst [operation, sessionId, childId] = process.argv.slice(2);\ntry {\n  const result = operation === 'list' ? await listSessions() : operation === 'info' && sessionId ? await getSessionInfo(sessionId)\n    : operation === 'messages' && sessionId ? await getSessionMessages(sessionId)\n    : operation === 'child-messages' && sessionId && childId ? await getSubagentMessages(sessionId, childId)\n    : operation === 'children' && sessionId ? await readChildren(sessionId)\n    : (() => { throw new Error('Unknown catalog operation.'); })();\n  process.stdout.write(JSON.stringify(result ?? null));\n} catch {\n  process.stderr.write('Claude native catalog could not be read.\\n');\n  process.exitCode = 1;\n}\n\nasync function readChildren(parentId: string) {\n  const children = [];\n  for (const id of await listSubagents(parentId)) children.push({ id, messages: await getSubagentMessages(parentId, id) });\n  return children;\n}\n"],
+  "mappings": ";;;;AAAA,SAAS,gBAAgB,oBAAoB,cAAc,eAAe,2BAA2B;AAErG,IAAM,CAAC,WAAW,WAAW,OAAO,IAAI,QAAQ,KAAK,MAAM,CAAC;AAC5D,IAAI;AACF,QAAM,SAAS,cAAc,SAAS,MAAM,aAAa,IAAI,cAAc,UAAU,YAAY,MAAM,eAAe,SAAS,IAC3H,cAAc,cAAc,YAAY,MAAM,mBAAmB,SAAS,IAC1E,cAAc,oBAAoB,aAAa,UAAU,MAAM,oBAAoB,WAAW,OAAO,IACrG,cAAc,cAAc,YAAY,MAAM,aAAa,SAAS,KACnE,MAAM;AAAE,UAAM,IAAI,MAAM,4BAA4B;AAAA,EAAG,GAAG;AAC/D,UAAQ,OAAO,MAAM,KAAK,UAAU,UAAU,IAAI,CAAC;AACrD,QAAQ;AACN,UAAQ,OAAO,MAAM,4CAA4C;AACjE,UAAQ,WAAW;AACrB;AAEA,eAAe,aAAa,UAAkB;AAC5C,QAAM,WAAW,CAAC;AAClB,aAAW,MAAM,MAAM,cAAc,QAAQ,EAAG,UAAS,KAAK,EAAE,IAAI,UAAU,MAAM,oBAAoB,UAAU,EAAE,EAAE,CAAC;AACvH,SAAO;AACT;",
+  "names": []
+}

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

@@ -1,24 +1,39 @@
-import type { AgentActivity, ReportTaskFinishedInput, 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, ServerRequestHandler, 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 {
+    reportExecutionTelemetryFrame?(frame: ExecutionTelemetryFrame): void;
+    onExecutionTelemetryAck?(handler: (ack: import('../plugin-sdk.js').ExecutionTelemetryAck) => void): () => void;
+    onExecutionTransportReady?(handler: () => void): () => void;
+    onServerRequest?(handler: ServerRequestHandler | undefined): void;
     onStopTurn?(handler: StopTurnHandler | undefined): void;
     onStopBackgroundRun?(handler: StopBackgroundRunHandler | undefined): void;
     onActivityTransportReady?(handler: (() => void) | undefined): void;
     connect(onMessage: (message: ChannelMessageEvent) => void): Promise<void>;
     close(): Promise<void>;
-    postMessage(input: PostMessageInput): Promise<PostedMessage>;
+    postMessage(input: PostMessageInput, source?: Pick<import('../plugin-sdk.js').ServerRequestContext, 'isConnectionCurrent'>): 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;
+    readonly sessionBindingsSupported?: boolean;
     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/normalized-input.d.ts

@@ -0,0 +1,9 @@
+import type { ChannelMessageEvent } from '../types.js';
+import type { ChatControlPlane } from './chat-control-plane.js';
+/** Plugin bodies may include server-only instructions; only the durable row is public input. */
+export declare function readNormalizedInputText(controlPlane: Pick<ChatControlPlane, 'readChannelHistory'>, message: ChannelMessageEvent, timeoutMs?: number): Promise<string | null>;
+export declare function readDurableInputText(controlPlane: Pick<ChatControlPlane, 'readChannelHistory'>, inputRef: {
+    channelId: string;
+    inputMessageId?: string;
+    createdAt?: number;
+}, timeoutMs?: number): Promise<string | null>;

package/dist/chat/normalized-input.js

@@ -0,0 +1,24 @@
+/** Plugin bodies may include server-only instructions; only the durable row is public input. */
+export async function readNormalizedInputText(controlPlane, message, timeoutMs = 2000) {
+    return readDurableInputText(controlPlane, { channelId: message.channel_id, inputMessageId: message.message_id, createdAt: message.created_at }, timeoutMs);
+}
+export async function readDurableInputText(controlPlane, inputRef, timeoutMs = 2000) {
+    if (!inputRef.inputMessageId)
+        return null;
+    let timer;
+    try {
+        const history = await Promise.race([
+            controlPlane.readChannelHistory({ channelId: inputRef.channelId, before: inputRef.createdAt == null ? undefined : inputRef.createdAt + 1, limit: 200 }),
+            new Promise(resolve => { timer = setTimeout(() => resolve(null), timeoutMs); }),
+        ]);
+        const input = history?.find(entry => entry.id === inputRef.inputMessageId && entry.channelId === inputRef.channelId);
+        return typeof input?.body === 'string' ? input.body : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

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

@@ -1,9 +1,25 @@
-import { type BorgeePluginClient, type BorgeePluginOptions, type InboundMessageEvent, type ReportTaskFinishedInput, 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 ServerRequestHandler, 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'> & Partial<Pick<BorgeePluginClient, 'reportTaskFinished'>>;
+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' | 'onServerRequest' | 'sessionBindingsSupported'>>;
 type PluginClientFactory = (options: BorgeePluginOptions) => PluginClientLike;
-type SdkChatControlPlaneOptions = Pick<BorgeePluginOptions, 'pluginId'>;
+type SdkChatControlPlaneOptions = Pick<BorgeePluginOptions, 'pluginId'> & {
+    providerOutputMode?: () => 'normalized' | 'legacy';
+    normalizedActivitySync?: () => boolean;
+    sessionControl?: () => boolean;
+    sessionBindings?: () => boolean;
+    sessionDirectory?: () => boolean;
+    sessionManagement?: () => boolean;
+    sessionRelations?: () => boolean;
+    sessionObservation?: () => boolean;
+    connectionLiveness?: () => BorgeePluginOptions['connectionLiveness'];
+    sessionInputOperations?: () => readonly ('start_turn' | 'steer' | 'next_turn')[];
+    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,24 +30,48 @@ 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);
+    reportExecutionTelemetryFrame(frame: ExecutionTelemetryFrame): void;
+    onExecutionTelemetryAck(handler: (ack: import('../plugin-sdk.js').ExecutionTelemetryAck) => void): () => void;
+    onExecutionTransportReady(handler: () => void): () => void;
+    onServerRequest(handler: ServerRequestHandler | undefined): void;
     onStopTurn(handler: StopTurnHandler | undefined): void;
     onStopBackgroundRun(handler: StopBackgroundRunHandler | undefined): void;
     onActivityTransportReady(handler: (() => void) | undefined): void;
     connect(onMessage: (message: ChannelMessageEvent) => void): Promise<void>;
     close(): Promise<void>;
-    postMessage(input: PostMessageInput): Promise<PostedMessage>;
+    postMessage(input: PostMessageInput, source?: Pick<import('../plugin-sdk.js').ServerRequestContext, 'isConnectionCurrent'>): Promise<PostedMessage>;
+    get sessionBindingsSupported(): boolean;
     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>;

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,63 @@ 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 });
+        const clientOptions = { baseUrl, apiKey, pluginId: options.pluginId };
+        // The adapter is selected after its control plane; read its policy at connect.
+        if (options.providerOutputMode)
+            Object.defineProperty(clientOptions, 'providerOutputMode', { enumerable: true, get: options.providerOutputMode });
+        if (options.normalizedActivitySync)
+            Object.defineProperty(clientOptions, 'normalizedActivitySync', { enumerable: true, get: options.normalizedActivitySync });
+        if (options.sessionControl)
+            Object.defineProperty(clientOptions, 'sessionControl', { enumerable: true, get: options.sessionControl });
+        if (options.sessionBindings)
+            Object.defineProperty(clientOptions, 'sessionBindings', { enumerable: true, get: options.sessionBindings });
+        if (options.sessionManagement)
+            Object.defineProperty(clientOptions, 'sessionManagement', { enumerable: true, get: options.sessionManagement });
+        if (options.sessionDirectory)
+            Object.defineProperty(clientOptions, 'sessionDirectory', { enumerable: true, get: options.sessionDirectory });
+        if (options.sessionRelations)
+            Object.defineProperty(clientOptions, 'sessionRelations', { enumerable: true, get: options.sessionRelations });
+        if (options.sessionObservation)
+            Object.defineProperty(clientOptions, 'sessionObservation', { enumerable: true, get: options.sessionObservation });
+        if (options.connectionLiveness)
+            Object.defineProperty(clientOptions, 'connectionLiveness', { enumerable: true, get: options.connectionLiveness });
+        if (options.sessionInputOperations)
+            clientOptions.sessionInputOperations = options.sessionInputOperations;
+        this.client = createClient(clientOptions);
+        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,
+        });
+    }
+    reportExecutionTelemetryFrame(frame) {
+        this.client.reportExecutionTelemetry?.(frame);
+    }
+    onExecutionTelemetryAck(handler) {
+        return this.client.on('executionTelemetryAck', handler);
+    }
+    onExecutionTransportReady(handler) {
+        return this.client.on('connectionState', state => { if (state.status === 'online')
+            handler(); });
+    }
+    onServerRequest(handler) {
+        this.client.onServerRequest?.(handler);
     }
     onStopTurn(handler) {
         this.client.onStopTurn(handler);
@@ -26,6 +79,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 +89,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,36 +116,48 @@ 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) {
-        const sent = await this.client.sendMessage({
+    async postMessage(input, source) {
+        const message = {
             channelId: input.channelId,
             body: input.body,
             replyToId: input.replyToId,
-        });
+        };
+        const sent = source ? await this.client.sendMessage(message, source) : await this.client.sendMessage(message);
         return { messageId: sent.messageId };
     }
+    get sessionBindingsSupported() { return this.client.sessionBindingsSupported ?? false; }
     reportActivity(input) {
         this.client.reportActivity(input);
     }
@@ -91,12 +170,65 @@ export class SdkChatControlPlane {
     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;
@@ -117,6 +249,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,
@@ -167,6 +327,9 @@ export class SdkChatControlPlane {
 export function mapInboundToChannelMessage(event) {
     return {
         type: event.kind,
+        ...(event.executionGrant ? { execution_grant: { ...event.executionGrant } } : {}),
+        ...(event.sessionTarget ? { sessionTarget: { ...event.sessionTarget } } : {}),
+        ...(event.sourceCurrent ? { sourceCurrent: event.sourceCurrent } : {}),
         ...(event.message?.type != null ? { message_type: event.message.type } : {}),
         channel_id: event.channelId,
         channel_type: event.channelType,

package/dist/cli-args.d.ts

@@ -85,4 +85,4 @@ export declare function parseCleanupManagedArgs(argv: string[]): ParsedCleanupMa
 export declare function parseApplyManagedArgs(argv: string[]): ParsedApplyManagedArgs;
 /** `update` always installs the latest published release; it takes no options. */
 export declare function assertNoUpdateArgs(argv: string[]): void;
-export declare const USAGE = "Usage:\n  agents-host start <serverUrl> <apiKey> [options]\n  agents-host start-managed <serverUrl>\n  agents-host start-managed <serverUrl> <apiKey> [agent-options]\n  agents-host describe-managed <serverUrl>\n  agents-host cleanup-managed <serverUrl> [--purge]\n  agents-host apply-managed <serverUrl> --stdin\n  agents-host apply-managed <serverUrl> --spec-json <json>\n  agents-host log <serverUrl> [--lines <n>] [--follow]\n  agents-host log <serverUrl> --path\n  agents-host start --config <path-to-host-config> [--debug]\n  agents-host validate --config <path-to-host-config>\n  agents-host describe --config <path-to-host-config>\n  agents-host print-layout --root <dir>\n  agents-host generate-config --root <dir> --stdin\n  agents-host generate-config --root <dir> --spec-json <json>\n  agents-host update\n\nForeground start options:\n  --debug                         Enable host/provider debug logs (or set AGENTS_HOST_DEBUG=1)\n\nSingle-agent agent options:\n  --name <name>                   Display name (default: Assistant)\n  --provider <claude|codex|copilot>\n                                   Runtime provider (default: claude)\n  --claude-command <cmd>          Local Claude ACP adapter command (default: claude-agent-acp)\n  --claude-args <args>            Local Claude ACP adapter args (empty on the shipped bundled path)\n  --codex-command <cmd>           Local Codex ACP adapter command (default: codex-acp)\n  --codex-args <args>             Local Codex ACP adapter args\n  --copilot-command <cmd>         Local Copilot CLI command (default: copilot)\n  --copilot-args <args>           Ignored by the Copilot ACP prototype\n  --copilot-session-ttl-minutes <minutes>\n                                   Idle session TTL for Copilot ACP sessions (default: 2880)\n  --provider-idle-shutdown-minutes <minutes>\n                                   Shut the shared ACP adapter process down after this much idle\n                                   time and re-spawn it on the next turn; 0 keeps it resident\n                                   (default: 10)\n\nCommand summary:\n  start <serverUrl> <apiKey>      Start one foreground hosted agent (legacy-compatible behavior)\n  start --config <path>           Start agents + supervisor + watchers from a host config file\n  start-managed <serverUrl>       Restart or resume an existing per-serverUrl managed daemon\n  start-managed <serverUrl> <apiKey>\n                                   Upsert one agent into the per-serverUrl local daemon and exit after reconcile\n  describe-managed <serverUrl>    Print managed-runtime spec JSON for machine callers\n  cleanup-managed <serverUrl>     Stop one managed-runtime daemon locally; --purge also removes its runtime root\n  apply-managed <serverUrl>       Apply one managed-runtime full-set spec for machine callers\n  log <serverUrl>                 Print the managed daemon log tail for one server runtime\n  validate --config <path>        Validate local-config files without starting agents or watchers\n  describe --config <path>        Print the current managed full-set spec as JSON\n  print-layout --root <dir>       Print the canonical default local-config layout as JSON\n  generate-config --root <dir> --stdin  Materialize canonical local-config files from stdin\n  generate-config --root <dir> --spec-json <json>\n                                   Compatibility input; JSON is exposed in process arguments\n  update                          Update the globally installed @borgee/agents-host to the latest release\n\nStartup update check:\n  Startup commands print an advisory notice on stderr when a newer release is published.\n  Set AGENTS_HOST_DISABLE_UPDATE_CHECK=1 to turn that check off.\n\nExamples:\n  agents-host start https://borgee.example.com bgr_xxxxxxxx --provider copilot --debug\n  agents-host start-managed https://borgee.example.com\n  agents-host start-managed https://borgee.example.com bgr_xxxxxxxx --provider copilot\n  agents-host describe-managed https://borgee.example.com\n  agents-host cleanup-managed https://borgee.example.com --purge\n  printf '%s' '{\"host\":{\"borgeeBaseUrl\":\"https://borgee.example.com\"},\"agents\":[{\"key\":\"cp1\",\"name\":\"Copilot\",\"apiKey\":\"bgr_xxx\",\"provider\":\"copilot\"}]}' | agents-host apply-managed https://borgee.example.com --stdin\n  agents-host log https://borgee.example.com --lines 200 --follow\n  agents-host log https://borgee.example.com --path\n  agents-host start --config ./agents-host.yaml --debug\n  agents-host validate --config ./agents-host.yaml\n  agents-host describe --config ./agents-host.yaml\n  agents-host print-layout --root ./runtime-root\n  printf '%s' '{\"host\":{\"borgeeBaseUrl\":\"https://borgee.example.com\"},\"agents\":[{\"key\":\"cp1\",\"name\":\"Copilot\",\"apiKey\":\"bgr_xxx\",\"provider\":\"copilot\"}]}' | agents-host generate-config --root ./runtime-root --stdin\n  agents-host update\n";
+export declare const USAGE = "Usage:\n  agents-host start <serverUrl> <apiKey> [options]\n  agents-host start-managed <serverUrl>\n  agents-host start-managed <serverUrl> <apiKey> [agent-options]\n  agents-host describe-managed <serverUrl>\n  agents-host cleanup-managed <serverUrl> [--purge]\n  agents-host apply-managed <serverUrl> --stdin\n  agents-host apply-managed <serverUrl> --spec-json <json>\n  agents-host log <serverUrl> [--lines <n>] [--follow]\n  agents-host log <serverUrl> --path\n  agents-host start --config <path-to-host-config> [--debug]\n  agents-host validate --config <path-to-host-config>\n  agents-host describe --config <path-to-host-config>\n  agents-host print-layout --root <dir>\n  agents-host generate-config --root <dir> --stdin\n  agents-host generate-config --root <dir> --spec-json <json>\n  agents-host update\n\nForeground start options:\n  --debug                         Enable host/provider debug logs (or set AGENTS_HOST_DEBUG=1)\n\nSingle-agent agent options:\n  --name <name>                   Display name (default: Assistant)\n  --provider <claude|codex|copilot>\n                                   Runtime provider (default: claude)\n  --provider-output-mode <legacy|normalized>\n                                   Output adapter (default: legacy; overrides PROVIDER_OUTPUT_MODE)\n  --native-provider-command <path>\n                                   Native executable for normalized output (overrides NATIVE_PROVIDER_COMMAND)\n  --codex-connection-mode <shared|stdio>\n                                   Normalized Codex transport (default: stdio; overrides CODEX_CONNECTION_MODE)\n  --claude-command <cmd>          Local Claude ACP adapter command (default: claude-agent-acp)\n  --claude-args <args>            Local Claude ACP adapter args (empty on the shipped bundled path)\n  --codex-command <cmd>           Local Codex ACP adapter command (default: codex-acp)\n  --codex-args <args>             Local Codex ACP adapter args\n  --copilot-command <cmd>         Legacy Copilot CLI command (default: copilot)\n  --copilot-args <args>           Parsed but ignored by the legacy Copilot SDK adapter\n  --copilot-session-ttl-minutes <minutes>\n                                   Idle session TTL for legacy Copilot SDK sessions (default: 2880)\n  --provider-idle-shutdown-minutes <minutes>\n                                   Shut the legacy provider process down after this much idle\n                                   time and re-spawn it on the next turn; 0 keeps it resident\n                                   (default: 10)\n\nCommand summary:\n  start <serverUrl> <apiKey>      Start one foreground hosted agent (legacy-compatible behavior)\n  start --config <path>           Start agents + supervisor + watchers from a host config file\n  start-managed <serverUrl>       Restart or resume an existing per-serverUrl managed daemon\n  start-managed <serverUrl> <apiKey>\n                                   Upsert one agent into the per-serverUrl local daemon and exit after reconcile\n  describe-managed <serverUrl>    Print managed-runtime spec JSON for machine callers\n  cleanup-managed <serverUrl>     Stop one managed-runtime daemon locally; --purge also removes its runtime root\n  apply-managed <serverUrl>       Apply one managed-runtime full-set spec for machine callers\n  log <serverUrl>                 Print the managed daemon log tail for one server runtime\n  validate --config <path>        Validate local-config files without starting agents or watchers\n  describe --config <path>        Print the current managed full-set spec as JSON\n  print-layout --root <dir>       Print the canonical default local-config layout as JSON\n  generate-config --root <dir> --stdin  Materialize canonical local-config files from stdin\n  generate-config --root <dir> --spec-json <json>\n                                   Compatibility input; JSON is exposed in process arguments\n  update                          Update the globally installed @borgee/agents-host to the latest release\n\nStartup update check:\n  Startup commands print an advisory notice on stderr when a newer release is published.\n  Set AGENTS_HOST_DISABLE_UPDATE_CHECK=1 to turn that check off.\n\nExamples:\n  agents-host start https://borgee.example.com bgr_xxxxxxxx --provider copilot --debug\n  agents-host start-managed https://borgee.example.com\n  agents-host start-managed https://borgee.example.com bgr_xxxxxxxx --provider copilot\n  agents-host describe-managed https://borgee.example.com\n  agents-host cleanup-managed https://borgee.example.com --purge\n  printf '%s' '{\"host\":{\"borgeeBaseUrl\":\"https://borgee.example.com\"},\"agents\":[{\"key\":\"cp1\",\"name\":\"Copilot\",\"apiKey\":\"bgr_xxx\",\"provider\":\"copilot\"}]}' | agents-host apply-managed https://borgee.example.com --stdin\n  agents-host log https://borgee.example.com --lines 200 --follow\n  agents-host log https://borgee.example.com --path\n  agents-host start --config ./agents-host.yaml --debug\n  agents-host validate --config ./agents-host.yaml\n  agents-host describe --config ./agents-host.yaml\n  agents-host print-layout --root ./runtime-root\n  printf '%s' '{\"host\":{\"borgeeBaseUrl\":\"https://borgee.example.com\"},\"agents\":[{\"key\":\"cp1\",\"name\":\"Copilot\",\"apiKey\":\"bgr_xxx\",\"provider\":\"copilot\"}]}' | agents-host generate-config --root ./runtime-root --stdin\n  agents-host update\n";

package/dist/cli-args.js

@@ -8,6 +8,9 @@
 export const CLI_FLAG_TO_ENV = {
     name: 'BORGEE_AGENT_NAME',
     provider: 'RUNTIME_PROVIDER',
+    'provider-output-mode': 'PROVIDER_OUTPUT_MODE',
+    'native-provider-command': 'NATIVE_PROVIDER_COMMAND',
+    'codex-connection-mode': 'CODEX_CONNECTION_MODE',
     'claude-command': 'CLAUDE_COMMAND',
     'claude-args': 'CLAUDE_ARGS',
     'codex-command': 'CODEX_COMMAND',
@@ -505,16 +508,22 @@ Single-agent agent options:
   --name <name>                   Display name (default: Assistant)
   --provider <claude|codex|copilot>
                                    Runtime provider (default: claude)
+  --provider-output-mode <legacy|normalized>
+                                   Output adapter (default: legacy; overrides PROVIDER_OUTPUT_MODE)
+  --native-provider-command <path>
+                                   Native executable for normalized output (overrides NATIVE_PROVIDER_COMMAND)
+  --codex-connection-mode <shared|stdio>
+                                   Normalized Codex transport (default: stdio; overrides CODEX_CONNECTION_MODE)
   --claude-command <cmd>          Local Claude ACP adapter command (default: claude-agent-acp)
   --claude-args <args>            Local Claude ACP adapter args (empty on the shipped bundled path)
   --codex-command <cmd>           Local Codex ACP adapter command (default: codex-acp)
   --codex-args <args>             Local Codex ACP adapter args
-  --copilot-command <cmd>         Local Copilot CLI command (default: copilot)
-  --copilot-args <args>           Ignored by the Copilot ACP prototype
+  --copilot-command <cmd>         Legacy Copilot CLI command (default: copilot)
+  --copilot-args <args>           Parsed but ignored by the legacy Copilot SDK adapter
   --copilot-session-ttl-minutes <minutes>
-                                   Idle session TTL for Copilot ACP sessions (default: 2880)
+                                   Idle session TTL for legacy Copilot SDK sessions (default: 2880)
   --provider-idle-shutdown-minutes <minutes>
-                                   Shut the shared ACP adapter process down after this much idle
+                                   Shut the legacy provider process down after this much idle
                                    time and re-spawn it on the next turn; 0 keeps it resident
                                    (default: 10)
 

package/dist/config.d.ts

@@ -21,6 +21,8 @@ export declare function isLegacyClaudeCompatibilityAlias(command: string, args:
 export declare function isLegacyClaudeBinaryCommand(command: string): boolean;
 export declare function hasLegacyClaudeOneShotArgs(args: string[]): boolean;
 export declare function assertClaudeCommandCompatibility(command: string, args: string[], sourceLabel: string): void;
-export declare function assertProviderCommandCompatibility(provider: ProviderKind, config: Pick<ProviderCommandConfig, 'claudeCommand' | 'claudeArgs'>, sourceLabel: string): void;
+export declare function assertProviderCommandCompatibility(provider: ProviderKind, config: Pick<ProviderCommandConfig, 'claudeCommand' | 'claudeArgs'> & Partial<Pick<ProviderCommandConfig, 'providerOutputMode' | 'codexConnectionMode' | 'codexSharedSocketPath'>>, sourceLabel: string): void;
+export declare function parseCodexConnectionMode(value: unknown): 'shared' | 'stdio';
+export declare function parseProviderOutputMode(value: unknown): 'legacy' | 'normalized';
 export declare function resolveProviderCommandConfig(overrides?: Partial<ProviderCommandConfig>): ProviderCommandConfig;
 export declare function loadConfigFromEnv(env?: NodeJS.ProcessEnv): AgentsHostConfig;

package/dist/config.js

@@ -137,9 +137,28 @@ export function assertProviderCommandCompatibility(provider, config, sourceLabel
     if (provider === 'claude') {
         assertClaudeCommandCompatibility(config.claudeCommand, config.claudeArgs, sourceLabel);
     }
+    if (provider === 'codex' && config.providerOutputMode === 'normalized' && (config.codexConnectionMode ?? 'stdio') === 'stdio' && config.codexSharedSocketPath !== undefined) {
+        throw new Error(`${sourceLabel}: a Codex shared socket cannot be configured in stdio mode. Set codexConnectionMode: shared (CODEX_CONNECTION_MODE=shared) explicitly to use a shared daemon.`);
+    }
+}
+export function parseCodexConnectionMode(value) {
+    if (value !== 'shared' && value !== 'stdio')
+        throw new Error('codexConnectionMode must be shared or stdio.');
+    return value;
+}
+export function parseProviderOutputMode(value) {
+    if (value !== 'legacy' && value !== 'normalized')
+        throw new Error('providerOutputMode must be legacy or normalized.');
+    return value;
 }
 export function resolveProviderCommandConfig(overrides = {}) {
     return {
+        ...(overrides.providerOutputMode !== undefined ? { providerOutputMode: parseProviderOutputMode(overrides.providerOutputMode) } : {}),
+        ...(overrides.sessionWorkspaceRoot !== undefined ? { sessionWorkspaceRoot: overrides.sessionWorkspaceRoot } : {}),
+        ...(overrides.nativeProviderCommand !== undefined ? { nativeProviderCommand: overrides.nativeProviderCommand } : {}),
+        ...(overrides.codexConnectionMode !== undefined ? { codexConnectionMode: parseCodexConnectionMode(overrides.codexConnectionMode) } : {}),
+        ...(overrides.codexSharedSocketPath !== undefined ? { codexSharedSocketPath: overrides.codexSharedSocketPath } : {}),
+        ...(overrides.codexTrustShared !== undefined ? { codexTrustShared: parseBooleanValue(overrides.codexTrustShared, 'codexTrustShared', 'provider configuration') } : {}),
         claudeCommand: overrides.claudeCommand ?? DEFAULT_PROVIDER_COMMAND_CONFIG.claudeCommand,
         claudeArgs: [...(overrides.claudeArgs ?? DEFAULT_PROVIDER_COMMAND_CONFIG.claudeArgs)],
         codexCommand: overrides.codexCommand ?? DEFAULT_PROVIDER_COMMAND_CONFIG.codexCommand,
@@ -158,8 +177,14 @@ export function loadConfigFromEnv(env = process.env) {
     assertProviderCompatibility(provider, 'Unsupported RUNTIME_PROVIDER', env);
     const agentApiKey = requireEnv('BORGEE_AGENT_API_KEY', env);
     const providerConfig = resolveProviderCommandConfig({
+        ...(env.PROVIDER_OUTPUT_MODE ? { providerOutputMode: parseProviderOutputMode(env.PROVIDER_OUTPUT_MODE) } : {}),
+        ...(env.SESSION_WORKSPACE_ROOT ? { sessionWorkspaceRoot: requireNonEmptyString(env.SESSION_WORKSPACE_ROOT, 'SESSION_WORKSPACE_ROOT') } : {}),
+        ...(env.NATIVE_PROVIDER_COMMAND ? { nativeProviderCommand: env.NATIVE_PROVIDER_COMMAND } : {}),
         claudeCommand: envOr('CLAUDE_COMMAND', DEFAULT_PROVIDER_COMMAND_CONFIG.claudeCommand, env),
         claudeArgs: parseArgs(envOr('CLAUDE_ARGS', DEFAULT_PROVIDER_COMMAND_CONFIG.claudeArgs.join(' '), env)),
+        ...(env.CODEX_CONNECTION_MODE !== undefined ? { codexConnectionMode: parseCodexConnectionMode(env.CODEX_CONNECTION_MODE) } : {}),
+        ...(env.CODEX_SHARED_SOCKET_PATH ? { codexSharedSocketPath: requireNonEmptyString(env.CODEX_SHARED_SOCKET_PATH, 'CODEX_SHARED_SOCKET_PATH') } : {}),
+        ...(env.CODEX_TRUST_SHARED !== undefined ? { codexTrustShared: parseBooleanValue(env.CODEX_TRUST_SHARED, 'CODEX_TRUST_SHARED', 'environment') } : {}),
         codexCommand: envOr('CODEX_COMMAND', DEFAULT_PROVIDER_COMMAND_CONFIG.codexCommand, env),
         codexArgs: parseArgs(envOr('CODEX_ARGS', DEFAULT_PROVIDER_COMMAND_CONFIG.codexArgs.join(' '), env)),
         copilotCommand: envOr('COPILOT_COMMAND', DEFAULT_PROVIDER_COMMAND_CONFIG.copilotCommand, env),

package/dist/context/injection.d.ts

@@ -57,6 +57,10 @@ export interface ChannelContextStore {
         incomingContent?: string;
         taskAssignmentContextOverride?: TaskAssignmentThreadContext;
         taskAssignmentContextOverridePersistence?: 'persist' | 'ephemeral';
+        independentSessionWorkspace?: {
+            bindingId: string;
+            cwd: string;
+        };
     }): Promise<PreparedChannelContext>;
     prepare(channelId: string, options?: {
         provider?: ProviderKind;
@@ -72,6 +76,10 @@ export interface ChannelContextStore {
         incomingContent?: string;
         taskAssignmentContextOverride?: TaskAssignmentThreadContext;
         taskAssignmentContextOverridePersistence?: 'persist' | 'ephemeral';
+        independentSessionWorkspace?: {
+            bindingId: string;
+            cwd: string;
+        };
     }): Promise<PreparedChannelContext>;
 }
 export interface SkillAssetResolver {
@@ -173,6 +181,10 @@ export declare class FileChannelContextStore implements ChannelContextStore {
         incomingContent?: string;
         taskAssignmentContextOverride?: TaskAssignmentThreadContext;
         taskAssignmentContextOverridePersistence?: 'persist' | 'ephemeral';
+        independentSessionWorkspace?: {
+            bindingId: string;
+            cwd: string;
+        };
     } | string, options?: {
         provider?: ProviderKind;
         projectionStrategy?: ProjectionStrategy;
@@ -187,6 +199,10 @@ export declare class FileChannelContextStore implements ChannelContextStore {
         incomingContent?: string;
         taskAssignmentContextOverride?: TaskAssignmentThreadContext;
         taskAssignmentContextOverridePersistence?: 'persist' | 'ephemeral';
+        independentSessionWorkspace?: {
+            bindingId: string;
+            cwd: string;
+        };
     }): Promise<PreparedChannelContext>;
     private resolveSkillRuntimeBestEffort;
 }