@borgee/agents-host 0.2.1 → 0.2.26

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

@@ -1,12 +1,63 @@
 import { randomUUID } from 'node:crypto';
 import { mkdir, open, readFile, rename, unlink } from 'node:fs/promises';
 import { dirname } from 'node:path';
-async function syncDirectory(path) {
-    const directoryHandle = await open(path, 'r');
+const nodeFileSystem = {
+    async mkdir(path, options) {
+        await mkdir(path, options);
+    },
+    async openDirectory(path) {
+        return open(path, 'r');
+    },
+    async openFile(path, flags, mode) {
+        return open(path, flags, mode);
+    },
+    async readFile(path, encoding) {
+        return readFile(path, encoding);
+    },
+    async rename(from, to) {
+        await rename(from, to);
+    },
+    async unlink(path) {
+        await unlink(path);
+    },
+};
+function shouldIgnoreDirectorySyncError(platform, error) {
+    const code = error.code;
+    return platform === 'win32' && (code === 'EPERM' || code === 'EINVAL');
+}
+async function syncDirectory(path, fileSystem, platform) {
+    let directoryHandle;
     try {
-        await directoryHandle.sync();
+        try {
+            directoryHandle = await fileSystem.openDirectory(path);
+        }
+        catch (error) {
+            if (!shouldIgnoreDirectorySyncError(platform, error)) {
+                throw error;
+            }
+            return;
+        }
+        try {
+            await directoryHandle.sync();
+        }
+        catch (error) {
+            if (!shouldIgnoreDirectorySyncError(platform, error)) {
+                throw error;
+            }
+        }
+    }
+    catch (error) {
+        if (directoryHandle) {
+            try {
+                await directoryHandle.close();
+            }
+            catch {
+                // Preserve the original directory durability failure.
+            }
+        }
+        throw error;
     }
-    finally {
+    if (directoryHandle) {
         await directoryHandle.close();
     }
 }
@@ -30,7 +81,7 @@ export class FileCopilotChannelSessionStore {
         this.options = options;
     }
     async loadFromPath(filePath) {
-        const raw = await readFile(filePath, 'utf8');
+        const raw = await (this.options.fileSystem ?? nodeFileSystem).readFile(filePath, 'utf8');
         return normalizePersistedSessions(JSON.parse(raw), filePath);
     }
     async load(agentId) {
@@ -48,11 +99,13 @@ export class FileCopilotChannelSessionStore {
     async save(agentId, sessions) {
         const filePath = this.options.resolvePath(agentId);
         const parentPath = dirname(filePath);
-        await mkdir(parentPath, { recursive: true, mode: 0o700 });
+        const fileSystem = this.options.fileSystem ?? nodeFileSystem;
+        const platform = this.options.platform ?? process.platform;
+        await fileSystem.mkdir(parentPath, { recursive: true, mode: 0o700 });
         const entries = Object.entries(sessions).sort(([left], [right]) => left.localeCompare(right));
         if (entries.length === 0) {
             try {
-                await unlink(filePath);
+                await fileSystem.unlink(filePath);
             }
             catch (error) {
                 if (error.code !== 'ENOENT') {
@@ -60,21 +113,21 @@ export class FileCopilotChannelSessionStore {
                 }
                 return;
             }
-            await syncDirectory(parentPath);
+            await syncDirectory(parentPath, fileSystem, platform);
             return;
         }
         const temporaryPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
         let temporaryHandle;
         try {
-            temporaryHandle = await open(temporaryPath, 'wx', 0o600);
+            temporaryHandle = await fileSystem.openFile(temporaryPath, 'wx', 0o600);
             await temporaryHandle.writeFile(JSON.stringify(Object.fromEntries(entries)), {
                 encoding: 'utf8',
             });
             await temporaryHandle.sync();
             await temporaryHandle.close();
             temporaryHandle = undefined;
-            await rename(temporaryPath, filePath);
-            await syncDirectory(parentPath);
+            await fileSystem.rename(temporaryPath, filePath);
+            await syncDirectory(parentPath, fileSystem, platform);
         }
         catch (error) {
             if (temporaryHandle) {
@@ -86,7 +139,7 @@ export class FileCopilotChannelSessionStore {
                 }
             }
             try {
-                await unlink(temporaryPath);
+                await fileSystem.unlink(temporaryPath);
             }
             catch {
                 // Cleanup is best effort.

package/dist/providers/create-provider.d.ts

@@ -1,3 +1,12 @@
-import type { ProviderAdapter } from './provider-adapter.js';
+import type { DebugLogger } from '../debug.js';
 import type { ProviderRuntimeConfig } from '../types.js';
-export declare function createProvider(config: ProviderRuntimeConfig): ProviderAdapter;
+import type { ProviderAdapter } from './provider-adapter.js';
+import type { LocalhostGatewayContextPublisher } from '../context/injection.js';
+import type { AuthorizationAuditSinkLike } from '../policy/authorization-audit.js';
+interface CreateProviderOptions {
+    compatibilityGates?: ReadonlySet<string>;
+    localhostGateway?: LocalhostGatewayContextPublisher;
+    authorizationAuditSink?: AuthorizationAuditSinkLike;
+}
+export declare function createProvider(config: ProviderRuntimeConfig, debugLogger?: DebugLogger, options?: CreateProviderOptions): ProviderAdapter;
+export {};

package/dist/providers/create-provider.js

@@ -1,25 +1,144 @@
+import { FileChannelContextStore } from '../context/injection.js';
+import { createProviderConnectionsSessionStore } from '../connections-state-store.js';
+import { ProviderTurnPreparer } from '../context/turn-preparation.js';
+import { CLAUDE_PROVIDER_V2_COMPATIBILITY_GATE, CONNECTIONS_STATE_LAYER_COMPATIBILITY_GATE, CONTEXT_INJECTION_COMPATIBILITY_GATE, CODEX_PROVIDER_COMPATIBILITY_GATE, COPILOT_PROVIDER_V2_COMPATIBILITY_GATE, INTERNAL_PROVIDER_IMPLEMENTATIONS_ENV, LOCALHOST_GATEWAY_COMPATIBILITY_GATE, parseInternalProviderImplementationOverrides, POLICY_AUDIT_ENFORCEMENT_COMPATIBILITY_GATE, resolveInternalPolicyMode, resolveInternalCompatibilityGates, SKILL_RUNTIME_COMPATIBILITY_GATE, } from '../compatibility-gates.js';
 import { ClaudeCliClient } from './claude/cli-client.js';
 import { ClaudeProviderAdapter } from './claude/adapter.js';
 import { FileClaudeChannelSessionStore } from './claude/session-store.js';
+import { CodexCliClient } from './codex/cli-client.js';
+import { CodexProviderAdapter } from './codex/adapter.js';
+import { FileCodexChannelSessionStore } from './codex/session-store.js';
 import { CopilotCliClient } from './copilot/cli-client.js';
 import { CopilotProviderAdapter } from './copilot/adapter.js';
 import { FileCopilotChannelSessionStore } from './copilot/session-store.js';
-import { resolveClaudeSessionMapPath, resolveCopilotSessionMapPath } from '../state-paths.js';
-export function createProvider(config) {
+import { resolveClaudeSessionMapPath, resolveCodexSessionMapPath, resolveCopilotSessionMapPath, } from '../state-paths.js';
+import { createAwaitingUserProgressHandler, parseProviderReply } from './awaiting-user.js';
+class ProviderV2CompatibilityAdapter {
+    provider;
+    turnPreparer;
+    constructor(provider, turnPreparer) {
+        this.provider = provider;
+        this.turnPreparer = turnPreparer;
+    }
+    async generateReply(input, options) {
+        const preparedTurn = await this.turnPreparer.prepare(input);
+        return this.provider.generateReply({
+            turn: preparedTurn,
+        }, options);
+    }
+    async dispose() {
+        await this.provider.shutdown?.();
+    }
+}
+class CliBackedProviderV2 {
+    cli;
+    constructor(cli) {
+        this.cli = cli;
+    }
+    async generateReply(input, options) {
+        const text = await this.cli.generateReply(input.turn, {
+            onProgress: createAwaitingUserProgressHandler(options?.onProgress),
+        });
+        return parseProviderReply(text);
+    }
+    async shutdown() {
+        await this.cli.dispose();
+    }
+}
+class ClaudeProviderV2 extends CliBackedProviderV2 {
+}
+class CopilotProviderV2 extends CliBackedProviderV2 {
+}
+const TASK_WORKSPACE_ROOT_DIR_ENV = 'AGENTS_HOST_INTERNAL_TASK_WORKSPACE_ROOT_DIR';
+const PROVIDER_V2_COMPATIBILITY_GATES = {
+    claude: CLAUDE_PROVIDER_V2_COMPATIBILITY_GATE,
+    copilot: COPILOT_PROVIDER_V2_COMPATIBILITY_GATE,
+};
+function resolveProviderImplementation(provider, routingConfig) {
+    if (!routingConfig.compatibilityGates.has(PROVIDER_V2_COMPATIBILITY_GATES[provider])) {
+        return 'v1';
+    }
+    return routingConfig.implementationOverrides[provider] ?? 'v2';
+}
+function createClaudeProvider(config, debugLogger, connectionsStateGateEnabled, implementation, turnPreparer) {
+    const cli = new ClaudeCliClient(config.claudeCommand, config.claudeArgs, {}, createProviderConnectionsSessionStore({
+        provider: 'claude',
+        legacyStore: new FileClaudeChannelSessionStore({
+            resolvePath: (agentId) => resolveClaudeSessionMapPath(config.stateRootDir, agentId),
+        }),
+        stateRootDir: config.stateRootDir,
+        gateEnabled: connectionsStateGateEnabled,
+        logger: debugLogger,
+    }), config.resolveStableAgentId, debugLogger);
+    return implementation === 'v2'
+        ? new ProviderV2CompatibilityAdapter(new ClaudeProviderV2(cli), turnPreparer)
+        : new ClaudeProviderAdapter(cli, turnPreparer);
+}
+function createCopilotProvider(config, debugLogger, connectionsStateGateEnabled, implementation, turnPreparer, policyAuditGateEnabled, authorizationAuditSink) {
+    const policyMode = resolveInternalPolicyMode(policyAuditGateEnabled);
+    const cli = new CopilotCliClient(config.copilotCommand, config.copilotArgs, {
+        idleSessionTtlMs: config.copilotSessionTtlMinutes * 60 * 1000,
+    }, createProviderConnectionsSessionStore({
+        provider: 'copilot',
+        legacyStore: new FileCopilotChannelSessionStore({
+            resolvePath: (agentId) => resolveCopilotSessionMapPath(config.stateRootDir, agentId),
+        }),
+        stateRootDir: config.stateRootDir,
+        gateEnabled: connectionsStateGateEnabled,
+        logger: debugLogger,
+    }), config.resolveStableAgentId, debugLogger, {
+        gateEnabled: policyAuditGateEnabled,
+        policyMode,
+        auditSink: authorizationAuditSink,
+    });
+    return implementation === 'v2'
+        ? new ProviderV2CompatibilityAdapter(new CopilotProviderV2(cli), turnPreparer)
+        : new CopilotProviderAdapter(cli, turnPreparer);
+}
+function createCodexProvider(config, debugLogger, connectionsStateGateEnabled, turnPreparer) {
+    const cli = new CodexCliClient(config.codexCommand, config.codexArgs, {}, createProviderConnectionsSessionStore({
+        provider: 'codex',
+        legacyStore: new FileCodexChannelSessionStore({
+            resolvePath: (agentId) => resolveCodexSessionMapPath(config.stateRootDir, agentId),
+        }),
+        stateRootDir: config.stateRootDir,
+        gateEnabled: connectionsStateGateEnabled,
+        logger: debugLogger,
+    }), config.resolveStableAgentId, debugLogger);
+    return new CodexProviderAdapter(cli, turnPreparer);
+}
+export function createProvider(config, debugLogger, options = {}) {
+    const routingConfig = {
+        compatibilityGates: options.compatibilityGates ?? resolveInternalCompatibilityGates(),
+        implementationOverrides: parseInternalProviderImplementationOverrides(process.env[INTERNAL_PROVIDER_IMPLEMENTATIONS_ENV]),
+    };
+    const connectionsStateGateEnabled = routingConfig.compatibilityGates.has(CONNECTIONS_STATE_LAYER_COMPATIBILITY_GATE);
+    const contextInjectionGateEnabled = routingConfig.compatibilityGates.has(CONTEXT_INJECTION_COMPATIBILITY_GATE);
+    const skillRuntimeGateEnabled = routingConfig.compatibilityGates.has(SKILL_RUNTIME_COMPATIBILITY_GATE);
+    const localhostGatewayGateEnabled = routingConfig.compatibilityGates.has(LOCALHOST_GATEWAY_COMPATIBILITY_GATE);
+    const policyAuditGateEnabled = routingConfig.compatibilityGates.has(POLICY_AUDIT_ENFORCEMENT_COMPATIBILITY_GATE);
+    const channelContextStore = contextInjectionGateEnabled
+        ? new FileChannelContextStore(config.stateRootDir, {
+            skillRuntimeEnabled: skillRuntimeGateEnabled,
+            taskWorkspaceRootDir: process.env[TASK_WORKSPACE_ROOT_DIR_ENV],
+            localhostGateway: skillRuntimeGateEnabled && localhostGatewayGateEnabled
+                ? options.localhostGateway
+                : undefined,
+        })
+        : undefined;
+    const turnPreparer = new ProviderTurnPreparer(channelContextStore, debugLogger);
     switch (config.provider) {
         case 'claude': {
-            const cli = new ClaudeCliClient(config.claudeCommand, config.claudeArgs, {}, new FileClaudeChannelSessionStore({
-                resolvePath: (agentId) => resolveClaudeSessionMapPath(config.stateRootDir, agentId),
-            }), config.resolveStableAgentId);
-            return new ClaudeProviderAdapter(cli);
+            return createClaudeProvider(config, debugLogger, connectionsStateGateEnabled, resolveProviderImplementation('claude', routingConfig), turnPreparer);
+        }
+        case 'codex': {
+            if (!routingConfig.compatibilityGates.has(CODEX_PROVIDER_COMPATIBILITY_GATE)) {
+                throw new Error(`Unsupported provider: ${String(config.provider)} (enable ${CODEX_PROVIDER_COMPATIBILITY_GATE})`);
+            }
+            return createCodexProvider(config, debugLogger, connectionsStateGateEnabled, turnPreparer);
         }
         case 'copilot': {
-            const cli = new CopilotCliClient(config.copilotCommand, config.copilotArgs, {
-                idleSessionTtlMs: config.copilotSessionTtlMinutes * 60 * 1000,
-            }, new FileCopilotChannelSessionStore({
-                resolvePath: (agentId) => resolveCopilotSessionMapPath(config.stateRootDir, agentId),
-            }), config.resolveStableAgentId);
-            return new CopilotProviderAdapter(cli);
+            return createCopilotProvider(config, debugLogger, connectionsStateGateEnabled, resolveProviderImplementation('copilot', routingConfig), turnPreparer, policyAuditGateEnabled, options.authorizationAuditSink);
         }
         default:
             throw new Error(`Unsupported provider: ${String(config.provider)}`);

package/dist/run.d.ts

@@ -2,6 +2,7 @@ import { parseGenerateConfigSpec, resolveLocalConfigLayout } from './local-confi
 import type { LocalConfigGenerateResult, LocalConfigGenerateSpec, LocalConfigSnapshot } from './types.js';
 export interface RunMainOptions {
     configPath?: string;
+    debug?: boolean;
 }
 export interface ValidateLocalConfigDeps {
     loadSnapshot?: (configPath: string) => Promise<LocalConfigSnapshot>;

package/dist/run.js

@@ -43,9 +43,12 @@ export async function generateLocalConfig(rootPath, specJson, sourceLabelOrDeps
     writer.log(JSON.stringify(result, null, 2));
 }
 export async function runMain(options = {}) {
+    const runtimeOptions = {
+        debug: options.debug,
+    };
     const host = options.configPath
-        ? new AgentsHostSupervisor(options.configPath)
-        : new AgentsHost(loadConfigFromEnv());
+        ? new AgentsHostSupervisor(options.configPath, runtimeOptions)
+        : new AgentsHost(loadConfigFromEnv(), { runtimeOptions });
     const shutdown = (signal) => {
         console.log(`[agents-host] received ${signal}, shutting down`);
         host

package/dist/state-paths.d.ts

@@ -1,6 +1,18 @@
-export declare function resolveSingleAgentStateRoot(env?: NodeJS.ProcessEnv, resolvedHomeDir?: string): string;
+export declare function normalizeManagedRuntimeKey(serverUrl: string): string;
+export declare function resolveSingleAgentStateRoot(env?: NodeJS.ProcessEnv, resolvedHomeDir?: string, agentKey?: string): string;
+export declare function resolveManagedRuntimeRoot(serverUrl: string, env?: NodeJS.ProcessEnv, resolvedHomeDir?: string): string;
 export declare function resolveManagedStateRoot(rootPath: string): string;
+export declare function resolveManagedDaemonSocketPath(rootPath: string): string;
+export declare function resolveManagedDaemonLogPath(rootPath: string): string;
+export declare function resolveManagedRuntimeSettingsPath(rootPath: string): string;
+export declare function resolveManagedBootstrapLockPath(rootPath: string): string;
 export declare function resolveLocalConfigAgentStateRoot(rootPath: string, agentKey: string): string;
 export declare function resolveAgentCursorPath(stateRootDir: string, agentId: string): string;
+export declare function resolveSharedProtocolKickoffDecisionPath(stateRootDir: string, channelId: string, anchorMessageId: string): string;
+export declare function resolveSharedProtocolStatusPath(stateRootDir: string, channelId: string, anchorMessageId: string): string;
+export declare function resolveConnectionsStatePath(stateRootDir: string): string;
+export declare function resolveAuthorizationAuditPath(stateRootDir: string): string;
+export declare function resolvePreviousAuthorizationAuditPath(stateRootDir: string): string;
 export declare function resolveClaudeSessionMapPath(stateRootDir: string, agentId: string): string;
+export declare function resolveCodexSessionMapPath(stateRootDir: string, agentId: string): string;
 export declare function resolveCopilotSessionMapPath(stateRootDir: string, agentId: string): string;

package/dist/state-paths.js

@@ -1,11 +1,17 @@
 import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
-import { join, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 const SINGLE_AGENT_HOME_ROOT = '.borgee';
 const AGENTS_HOST_ROOT = 'agents-host';
 const SINGLE_AGENT_NAMESPACE = 'single-agent';
+const MANAGED_RUNTIME_NAMESPACE = 'managed';
 const MANAGED_STATE_DIRNAME = '.state';
+const MANAGED_DAEMON_SOCKET_FILENAME = 'ctl.sock';
+const MANAGED_DAEMON_LOG_FILENAME = 'daemon.log';
+const MANAGED_RUNTIME_SETTINGS_FILENAME = 'managed-runtime-settings.json';
+const MANAGED_BOOTSTRAP_LOCK_DIRNAME = '.bootstrap.lock';
 const STATE_ROOT_LABEL_MAX_LENGTH = 48;
+const MANAGED_RUNTIME_LABEL_MAX_LENGTH = 24;
 function encodeSegment(value) {
     return encodeURIComponent(value);
 }
@@ -22,25 +28,100 @@ function sanitizeStateRootLabel(agentKey) {
 function hashStateRootKey(agentKey) {
     return createHash('sha256').update(agentKey).digest('hex').slice(0, 12);
 }
-export function resolveSingleAgentStateRoot(env = process.env, resolvedHomeDir = homedir()) {
+export function normalizeManagedRuntimeKey(serverUrl) {
+    const trimmed = serverUrl.trim();
+    try {
+        const parsed = new URL(trimmed);
+        parsed.pathname = parsed.pathname.replace(/\/+$/u, '') || '/';
+        return parsed.toString();
+    }
+    catch {
+        return trimmed.replace(/\/+$/u, '');
+    }
+}
+function sanitizeManagedRuntimeLabel(serverUrl) {
+    const normalized = normalizeManagedRuntimeKey(serverUrl);
+    let labelSource = normalized;
+    try {
+        const parsed = new URL(normalized);
+        labelSource = `${parsed.hostname}${parsed.pathname === '/' ? '' : parsed.pathname}`;
+    }
+    catch {
+        labelSource = normalized;
+    }
+    const sanitized = encodeSegment(labelSource)
+        .toLowerCase()
+        .replace(/%/g, '-')
+        .replace(/[^a-z0-9._-]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, MANAGED_RUNTIME_LABEL_MAX_LENGTH);
+    return sanitized.length > 0 ? sanitized : 'server';
+}
+function hashManagedRuntimeKey(serverUrl) {
+    return createHash('sha256').update(normalizeManagedRuntimeKey(serverUrl)).digest('hex').slice(0, 12);
+}
+export function resolveSingleAgentStateRoot(env = process.env, resolvedHomeDir = homedir(), agentKey) {
+    const home = env.HOME?.trim() || resolvedHomeDir.trim();
+    if (!home) {
+        throw new Error('Unable to resolve a user home directory for agents-host state');
+    }
+    const baseRoot = join(home, SINGLE_AGENT_HOME_ROOT, AGENTS_HOST_ROOT, SINGLE_AGENT_NAMESPACE);
+    const normalizedAgentKey = agentKey?.trim();
+    if (!normalizedAgentKey) {
+        return baseRoot;
+    }
+    return join(baseRoot, `agent-${hashStateRootKey(normalizedAgentKey)}`);
+}
+export function resolveManagedRuntimeRoot(serverUrl, env = process.env, resolvedHomeDir = homedir()) {
     const home = env.HOME?.trim() || resolvedHomeDir.trim();
     if (!home) {
         throw new Error('Unable to resolve a user home directory for agents-host state');
     }
-    return join(home, SINGLE_AGENT_HOME_ROOT, AGENTS_HOST_ROOT, SINGLE_AGENT_NAMESPACE);
+    return join(home, SINGLE_AGENT_HOME_ROOT, AGENTS_HOST_ROOT, MANAGED_RUNTIME_NAMESPACE, `${sanitizeManagedRuntimeLabel(serverUrl)}-${hashManagedRuntimeKey(serverUrl)}`);
 }
 export function resolveManagedStateRoot(rootPath) {
     return join(resolve(rootPath), MANAGED_STATE_DIRNAME);
 }
+export function resolveManagedDaemonSocketPath(rootPath) {
+    return join(resolve(rootPath), MANAGED_DAEMON_SOCKET_FILENAME);
+}
+export function resolveManagedDaemonLogPath(rootPath) {
+    return join(resolve(rootPath), MANAGED_DAEMON_LOG_FILENAME);
+}
+export function resolveManagedRuntimeSettingsPath(rootPath) {
+    return join(resolve(rootPath), MANAGED_RUNTIME_SETTINGS_FILENAME);
+}
+export function resolveManagedBootstrapLockPath(rootPath) {
+    return join(resolve(rootPath), MANAGED_BOOTSTRAP_LOCK_DIRNAME);
+}
 export function resolveLocalConfigAgentStateRoot(rootPath, agentKey) {
     return join(resolveManagedStateRoot(rootPath), `${sanitizeStateRootLabel(agentKey)}-${hashStateRootKey(agentKey)}`);
 }
 export function resolveAgentCursorPath(stateRootDir, agentId) {
     return join(stateRootDir, `bpp-cursor-${encodeSegment(agentId)}.json`);
 }
+export function resolveSharedProtocolKickoffDecisionPath(stateRootDir, channelId, anchorMessageId) {
+    return join(dirname(resolve(stateRootDir)), 'protocol-kickoff-decisions', `${encodeSegment(channelId)}--${encodeSegment(anchorMessageId)}.json`);
+}
+export function resolveSharedProtocolStatusPath(stateRootDir, channelId, anchorMessageId) {
+    return join(dirname(resolve(stateRootDir)), 'protocol-status', `${encodeSegment(channelId)}--${encodeSegment(anchorMessageId)}.json`);
+}
+export function resolveConnectionsStatePath(stateRootDir) {
+    return join(stateRootDir, 'connections-state.sqlite');
+}
+export function resolveAuthorizationAuditPath(stateRootDir) {
+    return join(stateRootDir, 'authorization-audit.jsonl');
+}
+export function resolvePreviousAuthorizationAuditPath(stateRootDir) {
+    return join(stateRootDir, 'authorization-audit.previous.jsonl');
+}
 export function resolveClaudeSessionMapPath(stateRootDir, agentId) {
     return join(stateRootDir, `claude-channel-sessions-${encodeSegment(agentId)}.json`);
 }
+export function resolveCodexSessionMapPath(stateRootDir, agentId) {
+    return join(stateRootDir, `codex-channel-sessions-${encodeSegment(agentId)}.json`);
+}
 export function resolveCopilotSessionMapPath(stateRootDir, agentId) {
     return join(stateRootDir, `copilot-channel-sessions-${encodeSegment(agentId)}.json`);
 }

package/dist/task-thread-resolution.d.ts

@@ -0,0 +1,10 @@
+import type { ChatControlPlane } from './chat/chat-control-plane.js';
+import type { Task } from './types.js';
+interface WaitForTaskForThreadOptions {
+    preferredTaskId?: string;
+    attempts?: number;
+    delayMs?: number;
+}
+export declare function findTaskForThread(controlPlane: ChatControlPlane, threadId: string, preferredTaskId?: string): Promise<Task | null>;
+export declare function waitForTaskForThread(controlPlane: ChatControlPlane, threadId: string, options?: WaitForTaskForThreadOptions): Promise<Task | null>;
+export {};

package/dist/task-thread-resolution.js

@@ -0,0 +1,48 @@
+export async function findTaskForThread(controlPlane, threadId, preferredTaskId) {
+    if (preferredTaskId) {
+        try {
+            const task = await controlPlane.getTask({ taskId: preferredTaskId });
+            if (task.threadId === threadId) {
+                return task;
+            }
+        }
+        catch {
+            // Fall through to the visibility-based compatibility scan.
+        }
+    }
+    const channels = await controlPlane.listChannels();
+    let matchedTask = null;
+    for (const channel of channels) {
+        let tasks;
+        try {
+            tasks = await controlPlane.listTasks({ channelId: channel.id });
+        }
+        catch {
+            continue;
+        }
+        for (const task of tasks) {
+            if (task.threadId !== threadId) {
+                continue;
+            }
+            if (matchedTask && matchedTask.id !== task.id) {
+                throw new Error(`multiple tasks matched thread ${threadId}`);
+            }
+            matchedTask = task;
+        }
+    }
+    return matchedTask;
+}
+export async function waitForTaskForThread(controlPlane, threadId, options = {}) {
+    const attempts = Math.max(1, options.attempts ?? 1);
+    const delayMs = Math.max(0, options.delayMs ?? 0);
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        const task = await findTaskForThread(controlPlane, threadId, options.preferredTaskId);
+        if (task) {
+            return task;
+        }
+        if (attempt < attempts - 1 && delayMs > 0) {
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+    }
+    return null;
+}