@borgee/agents-host 0.2.1 → 0.2.26

package/dist/compatibility-gates.js

@@ -0,0 +1,127 @@
+import { createHash } from 'node:crypto';
+export const CLAUDE_PROVIDER_V2_COMPATIBILITY_GATE = 'claude-provider-v2';
+export const COPILOT_PROVIDER_V2_COMPATIBILITY_GATE = 'copilot-provider-v2';
+export const CODEX_PROVIDER_COMPATIBILITY_GATE = 'codex-provider';
+export const CONNECTIONS_STATE_LAYER_COMPATIBILITY_GATE = 'connections-state-layer';
+export const CONTEXT_INJECTION_COMPATIBILITY_GATE = 'context-injection';
+export const SKILL_RUNTIME_COMPATIBILITY_GATE = 'skill-runtime';
+export const LOCALHOST_GATEWAY_COMPATIBILITY_GATE = 'localhost-gateway';
+export const COLLABORATION_SKILL_FIRST_COMPATIBILITY_GATE = 'collaboration-skill-first';
+export const TOKEN_BINDING_COMPATIBILITY_GATE = 'token-binding';
+export const POLICY_AUDIT_ENFORCEMENT_COMPATIBILITY_GATE = 'policy-audit-enforcement';
+export const MANAGED_RUNTIME_CONVERGENCE_COMPATIBILITY_GATE = 'managed-runtime-convergence';
+export const COMPATIBILITY_GATES_ENV = 'AGENTS_HOST_INTERNAL_COMPATIBILITY_GATES';
+export const INTERNAL_POLICY_MODE_ENV = 'AGENTS_HOST_INTERNAL_POLICY_MODE';
+export const INTERNAL_PROVIDER_IMPLEMENTATIONS_ENV = 'AGENTS_HOST_INTERNAL_PROVIDER_IMPLEMENTATIONS';
+export const MANAGED_RUNTIME_SETTINGS_SCHEMA_VERSION = 1;
+const VALID_PROVIDER_IMPLEMENTATION_ENTRIES = '"claude:v1", "claude:v2", "copilot:v1", or "copilot:v2"';
+const PROVIDER_IMPLEMENTATION_COMPATIBILITY_GATES = {
+    claude: CLAUDE_PROVIDER_V2_COMPATIBILITY_GATE,
+    copilot: COPILOT_PROVIDER_V2_COMPATIBILITY_GATE,
+};
+function sortUniqueStrings(values) {
+    return [...new Set([...values].map((value) => value.trim()).filter((value) => value.length > 0))]
+        .sort((left, right) => left.localeCompare(right));
+}
+function isInternalProviderImplementationPath(value) {
+    return value === 'v1' || value === 'v2';
+}
+function isInternalProviderImplementationKey(value) {
+    return value === 'claude' || value === 'copilot';
+}
+function createInvalidProviderImplementationEntryError(assignment) {
+    return new Error(`Invalid ${INTERNAL_PROVIDER_IMPLEMENTATIONS_ENV} entry "${assignment}". Expected ${VALID_PROVIDER_IMPLEMENTATION_ENTRIES}.`);
+}
+export function parseCompatibilityGates(rawValue) {
+    if (!rawValue || rawValue.trim().length === 0) {
+        return new Set();
+    }
+    const gates = new Set();
+    for (const gateRaw of rawValue.split(',')) {
+        const gate = gateRaw.trim();
+        if (gate.length === 0) {
+            continue;
+        }
+        gates.add(gate);
+    }
+    return gates;
+}
+export function resolveInternalCompatibilityGates() {
+    return parseCompatibilityGates(process.env[COMPATIBILITY_GATES_ENV]);
+}
+export function normalizeInternalProviderImplementationOverrides(rawValue) {
+    if (!rawValue || rawValue.trim().length === 0) {
+        return [];
+    }
+    const implementationsByProvider = new Map();
+    for (const assignmentRaw of rawValue.split(',')) {
+        const assignment = assignmentRaw.trim();
+        if (assignment.length === 0) {
+            continue;
+        }
+        const [providerRaw, implementationRaw, ...extraParts] = assignment.split(':');
+        const provider = providerRaw?.trim();
+        const implementation = implementationRaw?.trim();
+        if (extraParts.length > 0 || !provider || !implementation) {
+            throw createInvalidProviderImplementationEntryError(assignment);
+        }
+        if (!isInternalProviderImplementationKey(provider)) {
+            throw createInvalidProviderImplementationEntryError(assignment);
+        }
+        if (!isInternalProviderImplementationPath(implementation)) {
+            throw createInvalidProviderImplementationEntryError(assignment);
+        }
+        implementationsByProvider.set(provider, implementation);
+    }
+    return sortUniqueStrings([...implementationsByProvider.entries()].map(([provider, implementation]) => `${provider}:${implementation}`));
+}
+export function parseInternalProviderImplementationOverrides(rawValue) {
+    const implementationOverrides = {};
+    for (const assignment of normalizeInternalProviderImplementationOverrides(rawValue)) {
+        const [provider, implementation] = assignment.split(':');
+        implementationOverrides[provider] = implementation;
+    }
+    return implementationOverrides;
+}
+export function resolveManagedRuntimeProviderImplementationOverrides(env = process.env, compatibilityGates = resolveManagedRuntimeCompatibilityGates(env)) {
+    const enabledGates = new Set(compatibilityGates);
+    return normalizeInternalProviderImplementationOverrides(env[INTERNAL_PROVIDER_IMPLEMENTATIONS_ENV]).filter((assignment) => {
+        const [provider] = assignment.split(':');
+        return enabledGates.has(PROVIDER_IMPLEMENTATION_COMPATIBILITY_GATES[provider]);
+    });
+}
+export function resolveManagedRuntimeCompatibilityGates(env = process.env) {
+    const compatibilityGates = new Set(parseCompatibilityGates(env[COMPATIBILITY_GATES_ENV]));
+    if (compatibilityGates.has(MANAGED_RUNTIME_CONVERGENCE_COMPATIBILITY_GATE)) {
+        compatibilityGates.add(CONNECTIONS_STATE_LAYER_COMPATIBILITY_GATE);
+        compatibilityGates.add(TOKEN_BINDING_COMPATIBILITY_GATE);
+    }
+    return sortUniqueStrings(compatibilityGates);
+}
+export function resolveInternalPolicyMode(gateEnabled, env = process.env) {
+    if (!gateEnabled) {
+        return 'audit-only';
+    }
+    const rawValue = env[INTERNAL_POLICY_MODE_ENV]?.trim();
+    if (rawValue === 'enforce') {
+        return 'enforce';
+    }
+    return 'audit-only';
+}
+export function resolveManagedRuntimeSettingsSnapshot(env = process.env) {
+    const compatibilityGates = resolveManagedRuntimeCompatibilityGates(env);
+    return {
+        schemaVersion: MANAGED_RUNTIME_SETTINGS_SCHEMA_VERSION,
+        compatibilityGates,
+        providerImplementationOverrides: resolveManagedRuntimeProviderImplementationOverrides(env, compatibilityGates),
+        internalPolicyMode: resolveInternalPolicyMode(compatibilityGates.includes(POLICY_AUDIT_ENFORCEMENT_COMPATIBILITY_GATE), env),
+    };
+}
+export function serializeManagedRuntimeSettingsSnapshot(snapshot) {
+    return JSON.stringify(snapshot);
+}
+export function createManagedRuntimeSettingsFingerprint(snapshot) {
+    return createHash('sha256')
+        .update(serializeManagedRuntimeSettingsSnapshot(snapshot))
+        .digest('hex');
+}

package/dist/config.d.ts

@@ -8,5 +8,6 @@ export declare function parseArgs(value: string): string[];
 export declare function optionalStringArray(value: unknown, fieldName: string, sourceLabel: string): string[] | undefined;
 export declare function parseCopilotSessionTtlMinutesValue(value: unknown, sourceLabel: string): number;
 export declare function resolveProvider(rawValue: string, sourceLabel: string): ProviderKind;
+export declare function assertProviderCompatibility(provider: ProviderKind, sourceLabel: string, env?: NodeJS.ProcessEnv): void;
 export declare function resolveProviderCommandConfig(overrides?: Partial<ProviderCommandConfig>): ProviderCommandConfig;
 export declare function loadConfigFromEnv(env?: NodeJS.ProcessEnv): AgentsHostConfig;

package/dist/config.js

@@ -1,10 +1,13 @@
 import { resolveSingleAgentStateRoot } from './state-paths.js';
+import { CODEX_PROVIDER_COMPATIBILITY_GATE, COMPATIBILITY_GATES_ENV, parseCompatibilityGates, } from './compatibility-gates.js';
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
 export const MAX_COPILOT_SESSION_TTL_MINUTES = MAX_TIMER_DELAY_MS / 60_000;
 export const DEFAULT_COPILOT_SESSION_TTL_MINUTES = 2 * 24 * 60;
 export const DEFAULT_PROVIDER_COMMAND_CONFIG = {
     claudeCommand: 'claude',
-    claudeArgs: ['--print'],
+    claudeArgs: ['--print', '--permission-mode', 'bypassPermissions'],
+    codexCommand: 'codex-acp',
+    codexArgs: [],
     copilotCommand: 'copilot',
     copilotArgs: ['-s', '--no-color', '--allow-all-tools', '--output-format', 'text'],
     copilotSessionTtlMinutes: DEFAULT_COPILOT_SESSION_TTL_MINUTES,
@@ -57,15 +60,26 @@ export function parseCopilotSessionTtlMinutesValue(value, sourceLabel) {
 }
 export function resolveProvider(rawValue, sourceLabel) {
     const raw = rawValue.trim().toLowerCase();
-    if (raw === 'claude' || raw === 'copilot') {
+    if (raw === 'claude' || raw === 'codex' || raw === 'copilot') {
         return raw;
     }
-    throw new Error(`${sourceLabel}: expected "claude" or "copilot", got "${rawValue}"`);
+    throw new Error(`${sourceLabel}: expected "claude", "codex", or "copilot", got "${rawValue}"`);
+}
+export function assertProviderCompatibility(provider, sourceLabel, env = process.env) {
+    if (provider !== 'codex') {
+        return;
+    }
+    const compatibilityGates = parseCompatibilityGates(env[COMPATIBILITY_GATES_ENV]);
+    if (!compatibilityGates.has(CODEX_PROVIDER_COMPATIBILITY_GATE)) {
+        throw new Error(`${sourceLabel}: provider "codex" requires ${COMPATIBILITY_GATES_ENV} to include ${CODEX_PROVIDER_COMPATIBILITY_GATE}`);
+    }
 }
 export function resolveProviderCommandConfig(overrides = {}) {
     return {
         claudeCommand: overrides.claudeCommand ?? DEFAULT_PROVIDER_COMMAND_CONFIG.claudeCommand,
         claudeArgs: [...(overrides.claudeArgs ?? DEFAULT_PROVIDER_COMMAND_CONFIG.claudeArgs)],
+        codexCommand: overrides.codexCommand ?? DEFAULT_PROVIDER_COMMAND_CONFIG.codexCommand,
+        codexArgs: [...(overrides.codexArgs ?? DEFAULT_PROVIDER_COMMAND_CONFIG.codexArgs)],
         copilotCommand: overrides.copilotCommand ?? DEFAULT_PROVIDER_COMMAND_CONFIG.copilotCommand,
         copilotArgs: [...(overrides.copilotArgs ?? DEFAULT_PROVIDER_COMMAND_CONFIG.copilotArgs)],
         copilotSessionTtlMinutes: overrides.copilotSessionTtlMinutes ?? DEFAULT_PROVIDER_COMMAND_CONFIG.copilotSessionTtlMinutes,
@@ -73,12 +87,16 @@ export function resolveProviderCommandConfig(overrides = {}) {
 }
 export function loadConfigFromEnv(env = process.env) {
     const provider = resolveProvider(envOr('RUNTIME_PROVIDER', 'claude', env), 'Unsupported RUNTIME_PROVIDER');
+    assertProviderCompatibility(provider, 'Unsupported RUNTIME_PROVIDER', env);
+    const agentApiKey = requireEnv('BORGEE_AGENT_API_KEY', env);
     return {
         borgeeBaseUrl: requireEnv('BORGEE_BASE_URL', env),
-        stateRootDir: resolveSingleAgentStateRoot(env),
+        stateRootDir: resolveSingleAgentStateRoot(env, undefined, agentApiKey),
         ...resolveProviderCommandConfig({
             claudeCommand: envOr('CLAUDE_COMMAND', DEFAULT_PROVIDER_COMMAND_CONFIG.claudeCommand, env),
             claudeArgs: parseArgs(envOr('CLAUDE_ARGS', DEFAULT_PROVIDER_COMMAND_CONFIG.claudeArgs.join(' '), env)),
+            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),
             copilotArgs: parseArgs(envOr('COPILOT_ARGS', DEFAULT_PROVIDER_COMMAND_CONFIG.copilotArgs.join(' '), env)),
             copilotSessionTtlMinutes: env.COPILOT_SESSION_TTL_MINUTES && env.COPILOT_SESSION_TTL_MINUTES.trim().length > 0
@@ -86,7 +104,7 @@ export function loadConfigFromEnv(env = process.env) {
                 : DEFAULT_PROVIDER_COMMAND_CONFIG.copilotSessionTtlMinutes,
         }),
         agent: {
-            agentApiKey: requireEnv('BORGEE_AGENT_API_KEY', env),
+            agentApiKey,
             agentName: envOr('BORGEE_AGENT_NAME', 'Assistant', env),
             provider,
         },

package/dist/connections-state-store.d.ts

@@ -0,0 +1,81 @@
+import { type DebugLogger } from './debug.js';
+import type { ProviderKind } from './types.js';
+export interface ChannelSessionStoreLike {
+    load(agentId: string): Promise<Record<string, string>>;
+    save(agentId: string, sessions: Record<string, string>): Promise<void>;
+    close?(): Promise<void> | void;
+}
+export interface ChannelTokenBinding {
+    token: string;
+    agentId: string;
+    channelId: string;
+}
+export interface ConnectionsStateStore {
+    loadProviderSessions(provider: ProviderKind, agentId: string): Record<string, string>;
+    saveProviderSessions(provider: ProviderKind, agentId: string, sessions: Record<string, string>): void;
+    hasTokenBinding(token: string): boolean;
+    loadTokenBinding(token: string): ChannelTokenBinding | null;
+    loadTokenBindingForChannel(agentId: string, channelId: string): ChannelTokenBinding | null;
+    replaceTokenBinding(binding: ChannelTokenBinding): void;
+    deleteTokenBinding(token: string): void;
+    revokeTokenBinding(token: string): void;
+    revokeAllTokenBindings(): void;
+    close(): void;
+}
+export interface SqliteConnectionsStateStoreOptions {
+    stateRootDir: string;
+    busyTimeoutMs?: number;
+    resolveDatabasePath?: (stateRootDir: string) => string;
+    openDatabase?: (path: string) => SqliteDatabaseLike;
+}
+export interface ConnectionsStateBackedChannelSessionStoreOptions {
+    provider: ProviderKind;
+    legacyStore: ChannelSessionStoreLike;
+    sqliteStateStore?: ConnectionsStateStore;
+    logger?: DebugLogger;
+}
+export interface ProviderConnectionsSessionStoreOptions {
+    provider: ProviderKind;
+    legacyStore: ChannelSessionStoreLike;
+    stateRootDir: string;
+    gateEnabled: boolean;
+    logger?: DebugLogger;
+}
+interface SqliteStatementLike {
+    run(...params: unknown[]): unknown;
+    get(...params: unknown[]): unknown;
+    all(...params: unknown[]): unknown[];
+}
+interface SqliteDatabaseLike {
+    exec(sql: string): void;
+    prepare(sql: string): SqliteStatementLike;
+    close(): void;
+}
+export declare class SqliteConnectionsStateStore implements ConnectionsStateStore {
+    private readonly options;
+    private database;
+    private closed;
+    constructor(options: SqliteConnectionsStateStoreOptions);
+    loadProviderSessions(provider: ProviderKind, agentId: string): Record<string, string>;
+    saveProviderSessions(provider: ProviderKind, agentId: string, sessions: Record<string, string>): void;
+    hasTokenBinding(token: string): boolean;
+    loadTokenBinding(token: string): ChannelTokenBinding | null;
+    loadTokenBindingForChannel(agentId: string, channelId: string): ChannelTokenBinding | null;
+    replaceTokenBinding(binding: ChannelTokenBinding): void;
+    deleteTokenBinding(token: string): void;
+    revokeTokenBinding(token: string): void;
+    revokeAllTokenBindings(): void;
+    close(): void;
+    private ensureDatabase;
+    private loadStoredTokenBinding;
+}
+export declare class ConnectionsStateBackedChannelSessionStore implements ChannelSessionStoreLike {
+    private readonly options;
+    private readonly logger;
+    constructor(options: ConnectionsStateBackedChannelSessionStoreOptions);
+    load(agentId: string): Promise<Record<string, string>>;
+    save(agentId: string, sessions: Record<string, string>): Promise<void>;
+    close(): void;
+}
+export declare function createProviderConnectionsSessionStore(options: ProviderConnectionsSessionStoreOptions): ChannelSessionStoreLike;
+export {};

package/dist/connections-state-store.js

@@ -0,0 +1,228 @@
+import { chmodSync, mkdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname } from 'node:path';
+import { HostLogger, summarizeError } from './debug.js';
+import { resolveConnectionsStatePath } from './state-paths.js';
+const DEFAULT_BUSY_TIMEOUT_MS = 5_000;
+const PRIVATE_STATE_FILE_MODE = 0o600;
+const require = createRequire(import.meta.url);
+function loadDatabaseSync() {
+    const sqliteModule = require('node:sqlite');
+    if (typeof sqliteModule.DatabaseSync !== 'function') {
+        throw new Error('node:sqlite DatabaseSync is unavailable');
+    }
+    return sqliteModule.DatabaseSync;
+}
+export class SqliteConnectionsStateStore {
+    options;
+    database = null;
+    closed = false;
+    constructor(options) {
+        this.options = options;
+    }
+    loadProviderSessions(provider, agentId) {
+        const rows = this.ensureDatabase().prepare(`SELECT channel_id, session_id
+         FROM provider_channel_sessions
+        WHERE provider = ? AND agent_id = ?
+        ORDER BY channel_id ASC`).all(provider, agentId);
+        return Object.fromEntries(rows.map((row) => [row.channel_id, row.session_id]));
+    }
+    saveProviderSessions(provider, agentId, sessions) {
+        const database = this.ensureDatabase();
+        const entries = Object.entries(sessions).sort(([left], [right]) => left.localeCompare(right));
+        database.exec('BEGIN IMMEDIATE');
+        try {
+            database.prepare(`DELETE FROM provider_channel_sessions
+          WHERE provider = ? AND agent_id = ?`).run(provider, agentId);
+            if (entries.length > 0) {
+                const insert = database.prepare(`INSERT INTO provider_channel_sessions (provider, agent_id, channel_id, session_id)
+           VALUES (?, ?, ?, ?)`);
+                for (const [channelId, sessionId] of entries) {
+                    insert.run(provider, agentId, channelId, sessionId);
+                }
+            }
+            database.exec('COMMIT');
+        }
+        catch (error) {
+            database.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    hasTokenBinding(token) {
+        const row = this.ensureDatabase().prepare(`SELECT 1
+         FROM channel_token_bindings
+        WHERE token = ?
+        LIMIT 1`).get(token);
+        return row != null;
+    }
+    loadTokenBinding(token) {
+        const row = this.ensureDatabase().prepare(`SELECT token, agent_id, channel_id
+         FROM channel_token_bindings
+        WHERE token = ? AND revoked_at IS NULL`).get(token);
+        if (!row) {
+            return null;
+        }
+        return {
+            token: row.token,
+            agentId: row.agent_id,
+            channelId: row.channel_id,
+        };
+    }
+    loadTokenBindingForChannel(agentId, channelId) {
+        const row = this.ensureDatabase().prepare(`SELECT token, agent_id, channel_id
+         FROM channel_token_bindings
+        WHERE agent_id = ? AND channel_id = ? AND revoked_at IS NULL
+        ORDER BY rowid DESC
+        LIMIT 1`).get(agentId, channelId);
+        if (!row) {
+            return null;
+        }
+        return {
+            token: row.token,
+            agentId: row.agent_id,
+            channelId: row.channel_id,
+        };
+    }
+    replaceTokenBinding(binding) {
+        const database = this.ensureDatabase();
+        database.exec('BEGIN IMMEDIATE');
+        try {
+            const bindingByToken = this.loadStoredTokenBinding(binding.token);
+            if (bindingByToken) {
+                if (bindingByToken.revokedAt != null) {
+                    throw new Error(`channel token ${binding.token} was revoked and cannot be reused`);
+                }
+                if (bindingByToken.agentId !== binding.agentId || bindingByToken.channelId !== binding.channelId) {
+                    throw new Error(`channel token is already bound to ${bindingByToken.agentId}/${bindingByToken.channelId}`);
+                }
+            }
+            database.prepare(`UPDATE channel_token_bindings
+            SET revoked_at = unixepoch()
+          WHERE agent_id = ? AND channel_id = ? AND token <> ? AND revoked_at IS NULL`).run(binding.agentId, binding.channelId, binding.token);
+            database.prepare(`INSERT INTO channel_token_bindings (token, agent_id, channel_id, revoked_at)
+         VALUES (?, ?, ?, NULL)
+         ON CONFLICT(token) DO UPDATE SET
+           agent_id = excluded.agent_id,
+           channel_id = excluded.channel_id,
+           revoked_at = NULL`).run(binding.token, binding.agentId, binding.channelId);
+            database.exec('COMMIT');
+        }
+        catch (error) {
+            database.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    deleteTokenBinding(token) {
+        this.ensureDatabase().prepare(`DELETE FROM channel_token_bindings
+        WHERE token = ?`).run(token);
+    }
+    revokeTokenBinding(token) {
+        this.ensureDatabase().prepare(`UPDATE channel_token_bindings
+          SET revoked_at = unixepoch()
+        WHERE token = ? AND revoked_at IS NULL`).run(token);
+    }
+    revokeAllTokenBindings() {
+        this.ensureDatabase().exec('UPDATE channel_token_bindings SET revoked_at = unixepoch() WHERE revoked_at IS NULL');
+    }
+    close() {
+        this.database?.close();
+        this.database = null;
+        this.closed = true;
+    }
+    ensureDatabase() {
+        if (this.closed) {
+            throw new Error('connections state store is closed');
+        }
+        if (this.database) {
+            return this.database;
+        }
+        const path = (this.options.resolveDatabasePath ?? resolveConnectionsStatePath)(this.options.stateRootDir);
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        const database = (this.options.openDatabase ?? ((databasePath) => new (loadDatabaseSync())(databasePath)))(path);
+        try {
+            chmodSync(path, PRIVATE_STATE_FILE_MODE);
+            database.exec(`PRAGMA busy_timeout = ${this.options.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS}`);
+            database.exec('PRAGMA journal_mode = DELETE');
+            database.exec(`CREATE TABLE IF NOT EXISTS provider_channel_sessions (
+           provider TEXT NOT NULL,
+           agent_id TEXT NOT NULL,
+           channel_id TEXT NOT NULL,
+           session_id TEXT NOT NULL,
+           PRIMARY KEY (provider, agent_id, channel_id)
+         )`);
+            database.exec(`CREATE TABLE IF NOT EXISTS channel_token_bindings (
+           token TEXT PRIMARY KEY,
+           agent_id TEXT NOT NULL,
+           channel_id TEXT NOT NULL,
+           revoked_at INTEGER
+         )`);
+            const columns = database.prepare(`SELECT name
+           FROM pragma_table_info('channel_token_bindings')
+          WHERE name = 'revoked_at'
+          LIMIT 1`).all();
+            if (columns.length === 0) {
+                database.exec('ALTER TABLE channel_token_bindings ADD COLUMN revoked_at INTEGER');
+            }
+        }
+        catch (error) {
+            database.close();
+            throw error;
+        }
+        this.database = database;
+        return database;
+    }
+    loadStoredTokenBinding(token) {
+        const row = this.ensureDatabase().prepare(`SELECT token, agent_id, channel_id, revoked_at
+         FROM channel_token_bindings
+        WHERE token = ?`).get(token);
+        if (!row) {
+            return null;
+        }
+        return {
+            token: row.token,
+            agentId: row.agent_id,
+            channelId: row.channel_id,
+            revokedAt: row.revoked_at,
+        };
+    }
+}
+export class ConnectionsStateBackedChannelSessionStore {
+    options;
+    logger;
+    constructor(options) {
+        this.options = options;
+        this.logger = options.logger ?? new HostLogger();
+    }
+    async load(agentId) {
+        return this.options.legacyStore.load(agentId);
+    }
+    async save(agentId, sessions) {
+        await this.options.legacyStore.save(agentId, sessions);
+        if (!this.options.sqliteStateStore) {
+            return;
+        }
+        try {
+            this.options.sqliteStateStore.saveProviderSessions(this.options.provider, agentId, sessions);
+        }
+        catch (error) {
+            this.logger.error(`failed to mirror ${this.options.provider} session map into connections state`, {
+                provider: this.options.provider,
+                error: summarizeError(error),
+            });
+        }
+    }
+    close() {
+        this.options.sqliteStateStore?.close();
+        this.options.legacyStore.close?.();
+    }
+}
+export function createProviderConnectionsSessionStore(options) {
+    return new ConnectionsStateBackedChannelSessionStore({
+        provider: options.provider,
+        legacyStore: options.legacyStore,
+        sqliteStateStore: options.gateEnabled
+            ? new SqliteConnectionsStateStore({ stateRootDir: options.stateRootDir })
+            : undefined,
+        logger: options.logger,
+    });
+}

package/dist/context/injection.d.ts

@@ -0,0 +1,109 @@
+import type { LocalhostGatewayBootstrapMetadata, ProviderCollaborationContext, SkillRuntimeBootstrapMetadata, TaskAssignmentThreadContext, TaskWorkspaceContext } from '../types.js';
+export interface SkillRuntimeBootstrapPayload {
+    skillDirectoryPath: string;
+    nodeCliPath: string;
+    pythonCliPath: string;
+}
+export interface ChannelContextPayload {
+    schemaVersion: 1;
+    channelId: string;
+    skillRuntime?: SkillRuntimeBootstrapPayload;
+    localhostGateway?: LocalhostGatewayBootstrapMetadata;
+    taskAssignmentContext?: TaskAssignmentThreadContext;
+    taskWorkspace?: TaskWorkspaceContext;
+}
+export interface PreparedChannelContext {
+    directoryPath: string;
+    payload: ChannelContextPayload;
+    payloadPath?: string;
+    gatewayAuthPath?: string;
+    skillRuntime?: SkillRuntimeBootstrapMetadata;
+    localhostGateway?: LocalhostGatewayBootstrapMetadata;
+    taskWorkspace?: TaskWorkspaceContext;
+}
+export declare class ChannelContextPreparationError extends Error {
+    readonly partialContext: PreparedChannelContext;
+    constructor(message: string, partialContext: PreparedChannelContext, options?: ErrorOptions);
+}
+export interface ChannelContextStore {
+    prepare(input: {
+        channelId: string;
+        collaboration?: ProviderCollaborationContext;
+        incomingMessageType?: string;
+        incomingContent?: string;
+    }): Promise<PreparedChannelContext>;
+    prepare(channelId: string, options?: {
+        collaboration?: ProviderCollaborationContext;
+        incomingMessageType?: string;
+        incomingContent?: string;
+    }): Promise<PreparedChannelContext>;
+}
+export interface SkillAssetResolver {
+    resolve(): Promise<SkillRuntimeBootstrapMetadata>;
+}
+export interface LocalhostGatewayContextPublisher {
+    resolveBootstrap(channelId: string, options?: {
+        collaboration?: {
+            enabled: boolean;
+            turnExecutionId: string;
+        };
+    }): LocalhostGatewayBootstrapMetadata & {
+        token: string;
+        turnExecutionId?: string;
+    };
+    publishPayload(channelId: string, payloadPath: string, payload: ChannelContextPayload): void;
+    clearChannel(channelId: string): void;
+}
+interface ContextFileSystem {
+    mkdir(path: string, options?: {
+        mode?: number;
+        recursive?: boolean;
+    }): Promise<void>;
+    readdir(path: string): Promise<string[]>;
+    readFile(path: string, options: {
+        encoding: BufferEncoding;
+    } | BufferEncoding): Promise<string>;
+    writeFile(path: string, data: string, options?: {
+        encoding?: BufferEncoding;
+        mode?: number;
+    }): Promise<void>;
+    unlink(path: string): Promise<void>;
+    access(path: string): Promise<void>;
+}
+interface FileChannelContextStoreOptions {
+    fileSystem?: ContextFileSystem;
+    skillRuntimeEnabled?: boolean;
+    skillAssetResolver?: SkillAssetResolver;
+    localhostGateway?: LocalhostGatewayContextPublisher;
+    taskWorkspaceRootDir?: string;
+}
+export declare function extractTaskIdFromTaskAssignmentContent(incomingContent: string | undefined): string | undefined;
+export declare function encodeChannelPathSegment(channelId: string): string;
+export declare function resolveChannelContextDirectory(stateRootDir: string, channelId: string): string;
+export declare function resolveChannelContextPayloadPath(stateRootDir: string, channelId: string): string;
+export declare function resolveTaskWorkspaceRootDirectory(startupWorkspaceRootDir: string): string;
+export declare function resolveTaskWorkspaceDirectory(startupWorkspaceRootDir: string, channelId: string, taskId: string): string;
+export declare function resolveChannelContextGatewayAuthPath(stateRootDir: string, channelId: string, turnExecutionId?: string): string;
+export declare function resolveGatewayAuthPathFromPayloadPath(payloadPath: string): string;
+export declare function resolveBorgeeAgentSkillRuntimeAssets(moduleUrl: string, fileSystem?: Pick<ContextFileSystem, 'access'>): Promise<SkillRuntimeBootstrapMetadata>;
+export declare class FileChannelContextStore implements ChannelContextStore {
+    private readonly stateRootDir;
+    private readonly fileSystem;
+    private readonly skillRuntimeEnabled;
+    private readonly skillAssetResolver;
+    private readonly localhostGateway?;
+    private readonly startupWorkspaceRootDir;
+    constructor(stateRootDir: string, options?: FileChannelContextStoreOptions);
+    prepare(inputOrChannelId: {
+        channelId: string;
+        collaboration?: ProviderCollaborationContext;
+        incomingMessageType?: string;
+        incomingContent?: string;
+    } | string, options?: {
+        collaboration?: ProviderCollaborationContext;
+        incomingMessageType?: string;
+        incomingContent?: string;
+    }): Promise<PreparedChannelContext>;
+    private resolveSkillRuntimeBestEffort;
+}
+export {};