@borgee/agents-host 0.2.2 → 0.2.26

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 {};

package/dist/context/injection.js

@@ -0,0 +1,350 @@
+import { promises as fs } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+const CHANNEL_CONTEXT_ROOT_DIRNAME = 'channel-context';
+const CHANNEL_CONTEXT_PAYLOAD_FILENAME = 'context.json';
+const CHANNEL_CONTEXT_GATEWAY_AUTH_FILENAME = '.localhost-gateway-auth.json';
+const TASK_WORKSPACE_ROOT_DIRNAME = '.borgee-task-workspaces';
+export class ChannelContextPreparationError extends Error {
+    partialContext;
+    constructor(message, partialContext, options) {
+        super(message, options);
+        this.partialContext = partialContext;
+        this.name = 'ChannelContextPreparationError';
+    }
+}
+const DEFAULT_FILE_SYSTEM = {
+    async mkdir(path, options) {
+        await fs.mkdir(path, options);
+    },
+    async readdir(path) {
+        return await fs.readdir(path);
+    },
+    async readFile(path, options) {
+        return await fs.readFile(path, options);
+    },
+    async writeFile(path, data, options) {
+        await fs.writeFile(path, data, options);
+    },
+    async unlink(path) {
+        await fs.unlink(path);
+    },
+    async access(path) {
+        await fs.access(path);
+    },
+};
+const BORGEE_AGENT_SKILL_DIRNAME = 'borgee-agent';
+const TASK_ASSIGNMENT_PREAMBLE_PATTERN = /^This is a task assignment \(task_id: (.+)\)\. The work belongs to this thread\b/u;
+function toSkillRuntimePayload(skillRuntime) {
+    if (!skillRuntime) {
+        return undefined;
+    }
+    return {
+        skillDirectoryPath: skillRuntime.skillDirectoryPath,
+        nodeCliPath: skillRuntime.nodeCliPath,
+        pythonCliPath: skillRuntime.pythonCliPath,
+    };
+}
+function buildLocalhostGatewayAuthPayload(channelId, localhostGateway) {
+    if (!localhostGateway) {
+        return undefined;
+    }
+    return {
+        schemaVersion: 1,
+        channelId,
+        localhostGateway: {
+            token: localhostGateway.token,
+        },
+    };
+}
+function buildChannelContextPayload(channelId, skillRuntime, localhostGateway, options) {
+    return {
+        schemaVersion: 1,
+        channelId,
+        ...(skillRuntime ? { skillRuntime: toSkillRuntimePayload(skillRuntime) } : {}),
+        ...(localhostGateway ? { localhostGateway } : {}),
+        ...(options?.taskAssignmentContext ? { taskAssignmentContext: options.taskAssignmentContext } : {}),
+        ...(options?.taskWorkspace ? { taskWorkspace: options.taskWorkspace } : {}),
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function canRoundTripThroughUriComponentEncoding(value) {
+    try {
+        return decodeURIComponent(encodeURIComponent(value)) === value;
+    }
+    catch (error) {
+        if (error instanceof URIError) {
+            return false;
+        }
+        throw error;
+    }
+}
+function isUsableTaskId(value) {
+    return value.length > 0
+        && !/[\u0000-\u001f\u007f\s]/u.test(value)
+        && canRoundTripThroughUriComponentEncoding(value);
+}
+function sanitizeTaskAssignmentContext(value) {
+    if (!isRecord(value) || value.active !== true) {
+        return undefined;
+    }
+    const currentTaskId = typeof value.currentTaskId === 'string'
+        ? value.currentTaskId.trim()
+        : '';
+    return currentTaskId && isUsableTaskId(currentTaskId)
+        ? { active: true, currentTaskId }
+        : { active: true };
+}
+export function extractTaskIdFromTaskAssignmentContent(incomingContent) {
+    if (typeof incomingContent !== 'string') {
+        return undefined;
+    }
+    const currentTaskId = incomingContent.match(TASK_ASSIGNMENT_PREAMBLE_PATTERN)?.[1]?.trim();
+    return currentTaskId && isUsableTaskId(currentTaskId)
+        ? currentTaskId
+        : undefined;
+}
+function buildTaskAssignmentContextForTurn(options, existingContext) {
+    if (options?.incomingMessageType === 'task_assignment') {
+        const currentTaskId = extractTaskIdFromTaskAssignmentContent(options.incomingContent);
+        return currentTaskId ? { active: true, currentTaskId } : { active: true };
+    }
+    return existingContext;
+}
+async function readExistingTaskAssignmentContext(payloadPath, fileSystem) {
+    try {
+        const raw = await fileSystem.readFile(payloadPath, { encoding: 'utf8' });
+        const payload = JSON.parse(raw);
+        return sanitizeTaskAssignmentContext(payload.taskAssignmentContext);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function encodeChannelPathSegment(channelId) {
+    const encoded = Buffer.from(channelId, 'utf8').toString('hex');
+    return encoded.length > 0 ? encoded : 'empty';
+}
+export function resolveChannelContextDirectory(stateRootDir, channelId) {
+    return resolve(stateRootDir, CHANNEL_CONTEXT_ROOT_DIRNAME, encodeChannelPathSegment(channelId));
+}
+export function resolveChannelContextPayloadPath(stateRootDir, channelId) {
+    return join(resolveChannelContextDirectory(stateRootDir, channelId), CHANNEL_CONTEXT_PAYLOAD_FILENAME);
+}
+export function resolveTaskWorkspaceRootDirectory(startupWorkspaceRootDir) {
+    return join(resolve(startupWorkspaceRootDir), TASK_WORKSPACE_ROOT_DIRNAME);
+}
+export function resolveTaskWorkspaceDirectory(startupWorkspaceRootDir, channelId, taskId) {
+    return join(resolveTaskWorkspaceRootDirectory(startupWorkspaceRootDir), encodeChannelPathSegment(channelId), encodeChannelPathSegment(taskId));
+}
+export function resolveChannelContextGatewayAuthPath(stateRootDir, channelId, turnExecutionId) {
+    const filename = turnExecutionId
+        ? `.localhost-gateway-auth.${Buffer.from(turnExecutionId, 'utf8').toString('hex')}.json`
+        : CHANNEL_CONTEXT_GATEWAY_AUTH_FILENAME;
+    return join(resolveChannelContextDirectory(stateRootDir, channelId), filename);
+}
+export function resolveGatewayAuthPathFromPayloadPath(payloadPath) {
+    return join(dirname(payloadPath), CHANNEL_CONTEXT_GATEWAY_AUTH_FILENAME);
+}
+const LEGACY_TURN_SCOPED_GATEWAY_AUTH_BASENAME_PREFIX = '.localhost-gateway-auth.';
+async function pruneLegacyGatewayAuthSidecars(fileSystem, directoryPath) {
+    let entries;
+    try {
+        entries = await fileSystem.readdir(directoryPath);
+    }
+    catch (error) {
+        const code = typeof error === 'object' && error && 'code' in error ? error.code : undefined;
+        if (code === 'ENOENT') {
+            return;
+        }
+        throw error;
+    }
+    await Promise.all(entries
+        .filter((entry) => entry.startsWith(LEGACY_TURN_SCOPED_GATEWAY_AUTH_BASENAME_PREFIX)
+        && entry.endsWith('.json'))
+        .map(async (entry) => {
+        await fileSystem.unlink(join(directoryPath, entry)).catch((error) => {
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
+        });
+    }));
+}
+async function resolvePackageRootFromModuleUrl(moduleUrl, fileSystem = DEFAULT_FILE_SYSTEM) {
+    let currentPath = dirname(fileURLToPath(moduleUrl));
+    for (;;) {
+        try {
+            await fileSystem.access(join(currentPath, 'package.json'));
+            return currentPath;
+        }
+        catch { }
+        const parentPath = resolve(currentPath, '..');
+        if (parentPath === currentPath) {
+            throw new Error(`Unable to resolve agents-host package root from ${moduleUrl}`);
+        }
+        currentPath = parentPath;
+    }
+}
+export async function resolveBorgeeAgentSkillRuntimeAssets(moduleUrl, fileSystem = DEFAULT_FILE_SYSTEM) {
+    const packageRootPath = await resolvePackageRootFromModuleUrl(moduleUrl, fileSystem);
+    const skillDirectoryPath = join(packageRootPath, 'skills', BORGEE_AGENT_SKILL_DIRNAME);
+    const skillMarkdownPath = join(skillDirectoryPath, 'SKILL.md');
+    const nodeCliPath = join(skillDirectoryPath, 'borgee-agent.mjs');
+    const pythonCliPath = join(skillDirectoryPath, 'borgee-agent.py');
+    await Promise.all([
+        fileSystem.access(skillDirectoryPath),
+        fileSystem.access(skillMarkdownPath),
+        fileSystem.access(nodeCliPath),
+        fileSystem.access(pythonCliPath),
+    ]);
+    return {
+        skillDirectoryPath,
+        skillMarkdownPath,
+        nodeCliPath,
+        pythonCliPath,
+    };
+}
+class PackageSkillAssetResolver {
+    moduleUrl;
+    fileSystem;
+    resolutionPromise = null;
+    constructor(moduleUrl, fileSystem = DEFAULT_FILE_SYSTEM) {
+        this.moduleUrl = moduleUrl;
+        this.fileSystem = fileSystem;
+    }
+    resolve() {
+        this.resolutionPromise ??= resolveBorgeeAgentSkillRuntimeAssets(this.moduleUrl, this.fileSystem);
+        return this.resolutionPromise;
+    }
+}
+export class FileChannelContextStore {
+    stateRootDir;
+    fileSystem;
+    skillRuntimeEnabled;
+    skillAssetResolver;
+    localhostGateway;
+    startupWorkspaceRootDir;
+    constructor(stateRootDir, options = {}) {
+        this.stateRootDir = stateRootDir;
+        this.fileSystem = options.fileSystem ?? DEFAULT_FILE_SYSTEM;
+        this.skillRuntimeEnabled = options.skillRuntimeEnabled ?? false;
+        this.skillAssetResolver = options.skillAssetResolver ?? new PackageSkillAssetResolver(import.meta.url, this.fileSystem);
+        this.localhostGateway = options.localhostGateway;
+        this.startupWorkspaceRootDir = resolve(options.taskWorkspaceRootDir ?? process.cwd());
+    }
+    async prepare(inputOrChannelId, options) {
+        const input = typeof inputOrChannelId === 'string'
+            ? { channelId: inputOrChannelId, ...options }
+            : inputOrChannelId;
+        const turnMode = input.collaboration?.turnMode ?? 'ordinary';
+        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 gatewayAuthPath = resolveGatewayAuthPathFromPayloadPath(payloadPath);
+        const existingTaskAssignmentContext = await readExistingTaskAssignmentContext(payloadPath, this.fileSystem);
+        const skillRuntime = this.skillRuntimeEnabled
+            ? await this.resolveSkillRuntimeBestEffort()
+            : undefined;
+        const issuedLocalhostGateway = skillRuntime
+            ? this.localhostGateway?.resolveBootstrap(input.channelId, {
+                collaboration: auxiliaryCollaborationEnabled && input.collaboration?.turnExecutionId
+                    ? {
+                        enabled: true,
+                        turnExecutionId: input.collaboration.turnExecutionId,
+                    }
+                    : undefined,
+            })
+            : undefined;
+        const localhostGateway = issuedLocalhostGateway
+            ? {
+                baseUrl: issuedLocalhostGateway.baseUrl,
+                ...(auxiliaryCollaborationEnabled
+                    ? {
+                        collaboration: {
+                            enabled: true,
+                        },
+                    }
+                    : {}),
+            }
+            : undefined;
+        const taskAssignmentContext = buildTaskAssignmentContextForTurn({
+            incomingMessageType: input.incomingMessageType,
+            incomingContent: input.incomingContent,
+        }, existingTaskAssignmentContext);
+        const taskWorkspace = taskAssignmentContext?.currentTaskId
+            ? {
+                currentTaskId: taskAssignmentContext.currentTaskId,
+                rootPath: resolveTaskWorkspaceDirectory(this.startupWorkspaceRootDir, input.channelId, taskAssignmentContext.currentTaskId),
+            }
+            : undefined;
+        const payload = buildChannelContextPayload(input.channelId, skillRuntime, localhostGateway, taskAssignmentContext || taskWorkspace
+            ? {
+                ...(taskAssignmentContext ? { taskAssignmentContext } : {}),
+                ...(taskWorkspace ? { taskWorkspace } : {}),
+            }
+            : undefined);
+        const gatewayAuthPayload = buildLocalhostGatewayAuthPayload(input.channelId, issuedLocalhostGateway);
+        let taskWorkspaceMaterialized = false;
+        let payloadWritten = false;
+        let gatewayAuthWritten = false;
+        const preparedContext = {
+            directoryPath,
+            payload,
+            payloadPath,
+            gatewayAuthPath: gatewayAuthPayload ? gatewayAuthPath : undefined,
+            skillRuntime,
+            localhostGateway,
+            taskWorkspace,
+        };
+        try {
+            await this.fileSystem.mkdir(directoryPath, { recursive: true, mode: 0o700 });
+            if (taskWorkspace) {
+                await this.fileSystem.mkdir(taskWorkspace.rootPath, { recursive: true, mode: 0o700 });
+                taskWorkspaceMaterialized = true;
+            }
+            await pruneLegacyGatewayAuthSidecars(this.fileSystem, directoryPath);
+            await this.fileSystem.writeFile(payloadPath, `${JSON.stringify(payload, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+            payloadWritten = true;
+            if (gatewayAuthPayload) {
+                await this.fileSystem.writeFile(gatewayAuthPath, `${JSON.stringify(gatewayAuthPayload, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+                gatewayAuthWritten = true;
+            }
+            else {
+                await this.fileSystem.unlink(gatewayAuthPath).catch((error) => {
+                    if (error.code !== 'ENOENT') {
+                        throw error;
+                    }
+                });
+                this.localhostGateway?.clearChannel(input.channelId);
+            }
+            if (issuedLocalhostGateway) {
+                this.localhostGateway?.publishPayload(input.channelId, payloadPath, payload);
+            }
+            return preparedContext;
+        }
+        catch (error) {
+            const partialContext = {
+                directoryPath,
+                payload,
+                payloadPath: payloadWritten ? payloadPath : undefined,
+                gatewayAuthPath: gatewayAuthWritten ? gatewayAuthPath : undefined,
+                skillRuntime: payloadWritten ? skillRuntime : undefined,
+                localhostGateway: payloadWritten ? localhostGateway : undefined,
+                taskWorkspace: taskWorkspaceMaterialized ? taskWorkspace : undefined,
+            };
+            throw new ChannelContextPreparationError('failed to persist channel context payload', partialContext, { cause: error });
+        }
+    }
+    async resolveSkillRuntimeBestEffort() {
+        try {
+            return await this.skillAssetResolver.resolve();
+        }
+        catch {
+            return undefined;
+        }
+    }
+}