@borgee/agents-host 0.2.101 → 0.2.110

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,10 +1,20 @@
-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 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' | 'listChannelFiles' | 'readChannelFile' | 'publishChannelFile' | 'listChannels' | 'listTasks' | 'listUsers' | 'on' | 'onStopTurn' | 'onStopBackgroundRun' | 'reportActivity' | 'readHistory' | 'reportTurnActivity' | 'reportTyping' | 'sendMessage' | 'updateTask' | 'setTaskProperty' | 'deleteTaskProperty'> & Partial<Pick<BorgeePluginClient, 'connectionState' | 'reportExecutionTelemetry' | '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'> & {
+    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>;
@@ -30,12 +40,17 @@ export declare class SdkChatControlPlane implements ChatControlPlane {
     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>;

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

@@ -21,11 +21,29 @@ export class SdkChatControlPlane {
     executionTelemetryCapacityWaitMs;
     me = null;
     constructor(baseUrl, apiKey, createClient = createBorgeePlugin, options = {}) {
-        this.client = createClient({
-            baseUrl,
-            apiKey,
-            ...(options.pluginId ? { pluginId: options.pluginId } : {}),
-        });
+        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'));
@@ -38,6 +56,19 @@ export class SdkChatControlPlane {
             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);
     }
@@ -117,14 +148,16 @@ export class SdkChatControlPlane {
         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);
     }
@@ -294,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,
@@ -305,6 +341,5 @@ 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/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;
 }

package/dist/context/injection.js

@@ -216,9 +216,14 @@ function sanitizeTaskAssignmentContext(value) {
     const currentTaskId = typeof value.currentTaskId === 'string'
         ? value.currentTaskId.trim()
         : '';
-    return currentTaskId && isUsableTaskId(currentTaskId)
-        ? { active: true, currentTaskId }
-        : { active: true };
+    const taskChannelId = typeof value.taskChannelId === 'string'
+        ? value.taskChannelId.trim()
+        : '';
+    return {
+        active: true,
+        ...(currentTaskId && isUsableTaskId(currentTaskId) ? { currentTaskId } : {}),
+        ...(taskChannelId.length > 0 ? { taskChannelId } : {}),
+    };
 }
 export function extractTaskIdFromTaskAssignmentContent(incomingContent) {
     if (typeof incomingContent !== 'string') {
@@ -232,7 +237,11 @@ export function extractTaskIdFromTaskAssignmentContent(incomingContent) {
 function buildTaskAssignmentContextForTurn(options, existingContext) {
     if (options?.incomingMessageType === 'task_assignment') {
         const currentTaskId = extractTaskIdFromTaskAssignmentContent(options.incomingContent);
-        return currentTaskId ? { active: true, currentTaskId } : { active: true };
+        return {
+            active: true,
+            ...(existingContext?.taskChannelId ? { taskChannelId: existingContext.taskChannelId } : {}),
+            ...(currentTaskId ? { currentTaskId } : {}),
+        };
     }
     return existingContext;
 }
@@ -352,7 +361,10 @@ async function resolveTaskThreadWorkingFolderContext(params) {
             };
         }
         return {
-            taskAssignmentContext,
+            taskAssignmentContext: {
+                ...taskAssignmentContext,
+                taskChannelId: task.channelId,
+            },
             resolvedWorkingFolder: {
                 authority: 'task-execution-target',
                 taskId: task.id,
@@ -535,9 +547,11 @@ export class FileChannelContextStore {
         const collaborationCommandsEnabled = input.collaboration?.enabled === true && input.collaboration.sendRoutesAllowed === true;
         const collaborationRoutesAllowedForTurnMode = turnMode === 'ordinary';
         const auxiliaryCollaborationEnabled = collaborationCommandsEnabled && collaborationRoutesAllowedForTurnMode;
-        const directoryPath = resolveChannelContextDirectory(this.stateRootDir, input.channelId);
-        const payloadPath = resolveChannelContextPayloadPath(this.stateRootDir, input.channelId);
-        const taskAssignmentStatePath = resolveTaskAssignmentStatePath(this.stateRootDir, input.channelId);
+        const contextRoot = input.independentSessionWorkspace
+            ? join(this.stateRootDir, 'session-context', encodeURIComponent(input.independentSessionWorkspace.bindingId)) : this.stateRootDir;
+        const directoryPath = resolveChannelContextDirectory(contextRoot, input.channelId);
+        const payloadPath = resolveChannelContextPayloadPath(contextRoot, input.channelId);
+        const taskAssignmentStatePath = resolveTaskAssignmentStatePath(contextRoot, input.channelId);
         const claudeProjectedBriefPath = resolveClaudeProjectedBriefPathFromPayloadPath(payloadPath);
         const gatewayCredentialPath = resolveGatewayCredentialPathFromPayloadPath(payloadPath);
         const existingTaskAssignmentContext = await readExistingTaskAssignmentContext(taskAssignmentStatePath, this.fileSystem);
@@ -571,16 +585,18 @@ export class FileChannelContextStore {
                 incomingMessageType: input.incomingMessageType,
                 incomingContent: input.incomingContent,
             }, existingTaskAssignmentContext);
-        const workingFolderResolution = await resolveTaskThreadWorkingFolderContext({
-            channelId: input.channelId,
-            workingFolderCollectionRootDir: this.workingFolderCollectionRootDir,
-            taskAssignmentContext,
-            taskReader: this.taskReader,
-            taskResolutionTimeoutMs: this.taskResolutionTimeoutMs,
-            allowCrossAgentIndependentWorkspaceHandoff: this.allowCrossAgentIndependentWorkspaceHandoff,
-            resolveStableAgentId: this.resolveStableAgentId,
-            fileSystem: this.fileSystem,
-        });
+        const workingFolderResolution = input.independentSessionWorkspace
+            ? { resolvedWorkingFolder: { authority: 'channel', owningChannelId: input.channelId, rootPath: input.independentSessionWorkspace.cwd }, taskAssignmentContext }
+            : await resolveTaskThreadWorkingFolderContext({
+                channelId: input.channelId,
+                workingFolderCollectionRootDir: this.workingFolderCollectionRootDir,
+                taskAssignmentContext,
+                taskReader: this.taskReader,
+                taskResolutionTimeoutMs: this.taskResolutionTimeoutMs,
+                allowCrossAgentIndependentWorkspaceHandoff: this.allowCrossAgentIndependentWorkspaceHandoff,
+                resolveStableAgentId: this.resolveStableAgentId,
+                fileSystem: this.fileSystem,
+            });
         const resolvedWorkingFolder = workingFolderResolution.resolvedWorkingFolder;
         const runtimeTaskAssignmentContext = workingFolderResolution.taskAssignmentContext ?? taskAssignmentContext;
         const persistedTaskAssignmentContext = input.taskAssignmentContextOverridePersistence === 'ephemeral'
@@ -625,8 +641,8 @@ export class FileChannelContextStore {
         }
         try {
             await this.fileSystem.mkdir(directoryPath, { recursive: true, mode: 0o700 });
-            await this.fileSystem.mkdir(resolveTaskAssignmentStateDirectory(this.stateRootDir, input.channelId), { recursive: true, mode: 0o700 });
-            if (resolvedWorkingFolder.authority !== 'task-execution-target') {
+            await this.fileSystem.mkdir(resolveTaskAssignmentStateDirectory(contextRoot, input.channelId), { recursive: true, mode: 0o700 });
+            if (!input.independentSessionWorkspace && resolvedWorkingFolder.authority !== 'task-execution-target') {
                 await this.fileSystem.mkdir(resolvedWorkingFolder.rootPath, { recursive: true, mode: 0o700 });
             }
             await pruneGatewayCredentialSidecars(this.fileSystem, directoryPath, gatewayCredential ? CHANNEL_GATEWAY_CREDENTIAL_FILENAME : undefined);
@@ -636,7 +652,7 @@ export class FileChannelContextStore {
             await this.fileSystem.writeFile(payloadPath, `${JSON.stringify(payload, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
             payloadWritten = true;
             if (persistedTaskAssignmentContext) {
-                const stagingTaskAssignmentStatePath = join(resolveTaskAssignmentStateDirectory(this.stateRootDir, input.channelId), `.task-assignment-state.${randomUUID()}.json`);
+                const stagingTaskAssignmentStatePath = join(resolveTaskAssignmentStateDirectory(contextRoot, input.channelId), `.task-assignment-state.${randomUUID()}.json`);
                 await this.fileSystem.writeFile(stagingTaskAssignmentStatePath, `${JSON.stringify({ taskAssignmentContext: persistedTaskAssignmentContext }, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
                 await this.fileSystem.rename(stagingTaskAssignmentStatePath, taskAssignmentStatePath);
             }

package/dist/context/prompt.d.ts

@@ -31,3 +31,15 @@ export declare function buildClaudeTurnPrompt(params: {
     promptContext?: PreparedPromptContext;
     promptStrategy?: ProjectionStrategy;
 }): string;
+/** Native context keys are stable; Codex owns deduplication and conversation history. */
+export declare function buildCodexTurnContext(params: {
+    agentName: string;
+    channelId: string;
+    incomingAuthorId: string;
+    incomingEventKind?: string;
+    incomingMessageType?: string;
+    promptContext?: PreparedPromptContext;
+}): Record<string, {
+    kind: 'application' | 'untrusted';
+    value: string;
+}>;

package/dist/context/prompt.js

@@ -681,3 +681,28 @@ export function buildClaudeTurnPrompt(params) {
         }),
     ].join('\n');
 }
+/** Native context keys are stable; Codex owns deduplication and conversation history. */
+export function buildCodexTurnContext(params) {
+    const context = params.promptContext;
+    const provider = 'codex';
+    // Dynamic context can contain peer/user-authored names and summaries. Keep its original user trust level.
+    const blocks = {
+        borgee_identity: { kind: 'application', value: [
+                ...buildPromptHeaderLines({ agentName: params.agentName, provider }),
+                ...buildSessionDelegationPromptLines(provider, context),
+                buildProviderIdentityReminderLine(provider),
+                ...(context?.skillRuntime ? buildSkillManualLines(context.skillRuntime) : []),
+            ].join('\n') },
+        borgee_control: { kind: 'untrusted', value: buildTurnControlPromptLines(context).join('\n') },
+        borgee_metadata: { kind: 'untrusted', value: [
+                `Channel: ${params.channelId}`, `Incoming author: ${params.incomingAuthorId}`,
+                ...buildInboundMetadataLines({ ...params, provider }),
+            ].join('\n') },
+        borgee_outcome: { kind: 'untrusted', value: buildCollaborationOutcomeSummaryLines(context?.collaborationOutcome).join('\n') },
+        borgee_attention: { kind: 'untrusted', value: buildAttentionSummaryLines(context?.attentionSnapshot).join('\n') },
+        borgee_capabilities: { kind: 'untrusted', value: buildCollaborationCapabilityDeclarationSummaryLines(context?.collaborationCapabilities).join('\n') },
+        borgee_diagnostic: { kind: 'untrusted', value: buildMissedCollaborationDiagnosticSummaryLines(context?.missedCollaborationDiagnostic).join('\n') },
+        borgee_gateway: { kind: 'untrusted', value: buildLocalhostGatewayPromptLines(context).join('\n') },
+    };
+    return blocks;
+}

package/dist/context/turn-preparation.d.ts

@@ -1,5 +1,5 @@
 import { type DebugLogger } from '../debug.js';
-import type { ProjectionStrategy, PreparedProviderTurnInput, ProviderInput } from '../types.js';
+import type { ProjectionStrategy, PreparedPromptContext, PreparedProviderTurnInput, ProviderInput } from '../types.js';
 import { type ChannelContextStore } from './injection.js';
 type ResolveProjectionStrategy = (input: ProviderInput) => Promise<ProjectionStrategy>;
 export declare class ProviderTurnPreparer {
@@ -10,6 +10,7 @@ export declare class ProviderTurnPreparer {
         projectionStrategy?: ProjectionStrategy;
         resolveProjectionStrategy?: ResolveProjectionStrategy;
     });
+    prepareSession(channelId: string, provider: ProviderInput['provider']): Promise<PreparedPromptContext | undefined>;
     prepare(input: ProviderInput): Promise<PreparedProviderTurnInput>;
 }
 export {};

package/dist/context/turn-preparation.js

@@ -89,6 +89,17 @@ export class ProviderTurnPreparer {
         this.resolveProjectionStrategy = options.resolveProjectionStrategy
             ?? (async () => options.projectionStrategy ?? DEFAULT_PROJECTION_STRATEGY);
     }
+    async prepareSession(channelId, provider) {
+        const context = await this.channelContextStore?.prepare({ channelId, provider });
+        if (!context)
+            return undefined;
+        return {
+            channelContextPayloadPath: context.payloadPath,
+            claudeProjectedBriefPath: context.claudeProjectedBriefPath,
+            gatewayCredentialPath: context.gatewayCredentialPath,
+            resolvedWorkingFolder: context.resolvedWorkingFolder,
+        };
+    }
     async prepare(input) {
         const incomingParts = input.incomingParts ?? buildHostedTurnContentParts({
             text: input.incomingContent,
@@ -100,10 +111,12 @@ export class ProviderTurnPreparer {
             ? await this.resolveProjectionStrategy(input)
             : undefined;
         let channelContext;
+        let contextPreparationFailed = false;
         if (this.channelContextStore) {
             try {
                 const prepareInput = {
                     channelId: input.channelId,
+                    ...(input.independentSessionWorkspace ? { independentSessionWorkspace: input.independentSessionWorkspace } : {}),
                     provider: input.provider,
                     projectionStrategy,
                     collaboration: input.collaboration
@@ -139,6 +152,7 @@ export class ProviderTurnPreparer {
                 channelContext = await this.channelContextStore.prepare(prepareInput);
             }
             catch (error) {
+                contextPreparationFailed = true;
                 if (error instanceof ChannelContextPreparationError) {
                     channelContext = error.partialContext;
                 }
@@ -154,6 +168,7 @@ export class ProviderTurnPreparer {
             channelId: input.channelId,
             incomingContent,
             incomingParts,
+            ...(contextPreparationFailed ? { contextPreparationFailed: true } : {}),
             incomingEventKind: input.incomingEventKind,
             incomingMessageType: input.incomingMessageType,
             prompt: input.provider === 'claude'