@borgee/agents-host 0.2.2 → 0.2.26

package/dist/providers/copilot/cli-client.js

@@ -1,6 +1,8 @@
 import { Readable, Writable } from 'node:stream';
 import spawn from 'cross-spawn';
 import { PROTOCOL_VERSION, client, methods, ndJsonStream, } from '@agentclientprotocol/sdk';
+import { HostLogger, summarizeChildStderr, summarizeError } from '../../debug.js';
+import { resolveCopilotPermissionResponse } from '../../policy/copilot-permission.js';
 const SESSION_TAINTED_ERRORS = new WeakSet();
 const DEFAULT_IDLE_SESSION_TTL_MS = 2 * 24 * 60 * 60 * 1000;
 const DEFAULT_SHUTDOWN_GRACE_PERIOD_MS = 250;
@@ -102,7 +104,7 @@ class CopilotProgressCollector {
         this.onProgress({ text });
     }
 }
-function createDeferredTurn(prompt, options) {
+function createDeferredTurn(channelId, prompt, sessionPersistence, promptContext, options) {
     let settled = false;
     let resolvePromise;
     let rejectPromise;
@@ -111,7 +113,10 @@ function createDeferredTurn(prompt, options) {
         rejectPromise = reject;
     });
     return {
+        channelId,
         prompt,
+        sessionPersistence,
+        promptContext,
         options,
         promise,
         resolve(value) {
@@ -131,6 +136,34 @@ function createDeferredTurn(prompt, options) {
 function normalizeError(error) {
     return error instanceof Error ? error : new Error(String(error));
 }
+function parsePersistedSessionRecord(rawValue) {
+    const trimmed = rawValue.trim();
+    if (trimmed.startsWith('{')) {
+        const parsed = JSON.parse(trimmed);
+        if (typeof parsed.sessionId === 'string' && parsed.sessionId.trim().length > 0) {
+            return {
+                sessionId: parsed.sessionId,
+                cwd: typeof parsed.cwd === 'string' && parsed.cwd.trim().length > 0
+                    ? parsed.cwd
+                    : undefined,
+            };
+        }
+    }
+    return { sessionId: rawValue };
+}
+function serializePersistedSessionRecord(record) {
+    return JSON.stringify({
+        sessionId: record.sessionId,
+        ...(record.cwd ? { cwd: record.cwd } : {}),
+    });
+}
+function resolveSessionRouting(turn) {
+    return {
+        channelId: turn.channelId,
+        key: turn.providerSessionRouting?.key ?? turn.channelId,
+        persistence: turn.providerSessionRouting?.persistence ?? 'persistent',
+    };
+}
 function asObject(value) {
     return typeof value === 'object' && value !== null ? value : null;
 }
@@ -157,14 +190,6 @@ function markSessionTainted(error) {
 function isSessionTainted(error) {
     return error instanceof Error && SESSION_TAINTED_ERRORS.has(error);
 }
-function selectPermissionOption(options) {
-    const option = options.find((candidate) => candidate.kind === 'allow_always') ??
-        options.find((candidate) => candidate.kind === 'allow_once');
-    if (!option) {
-        throw new Error('Copilot ACP requested permission but did not offer an allow option');
-    }
-    return option.optionId;
-}
 /**
  * Persistent ACP-backed client for the GitHub Copilot CLI (`copilot --acp`).
  *
@@ -177,12 +202,15 @@ export class CopilotCliClient {
     command;
     sessionStore;
     resolveSessionStoreAgentId;
+    logger;
+    permissionPolicy;
     runtime;
     channels = new Map();
     persistedSessions = new Map();
     closingSessions = new WeakSet();
     pendingSessionStarts = new Set();
     pendingSessionCloses = new Set();
+    pendingSessionStoreOperations = new Set();
     fatalPromise;
     rejectFatalPromise;
     child;
@@ -198,33 +226,63 @@ export class CopilotCliClient {
     sessionStoreLoadPromise = null;
     sessionStoreWriteQueue = Promise.resolve();
     sessionCapabilities = DEFAULT_SESSION_CAPABILITIES;
-    constructor(command, _ignoredArgs = [], runtimeOverrides = {}, sessionStore, resolveSessionStoreAgentId = () => undefined) {
+    constructor(command, _ignoredArgs = [], runtimeOverrides = {}, sessionStore, resolveSessionStoreAgentId = () => undefined, logger = new HostLogger(), permissionPolicy = {}) {
         this.command = command;
         this.sessionStore = sessionStore;
         this.resolveSessionStoreAgentId = resolveSessionStoreAgentId;
+        this.logger = logger;
+        this.permissionPolicy = permissionPolicy;
         this.runtime = { ...DEFAULT_RUNTIME, ...runtimeOverrides };
         this.fatalPromise = new Promise((_, reject) => {
             this.rejectFatalPromise = reject;
         });
         void this.fatalPromise.catch(() => { });
     }
-    async generateReply(channelId, prompt, options) {
+    async generateReply(channelIdOrTurn, promptOrOptions, maybeOptions) {
         if (this.fatalError) {
             throw this.fatalError;
         }
-        const state = this.getOrCreateChannelState(channelId);
+        const preparedTurn = typeof channelIdOrTurn === 'string'
+            ? {
+                channelId: channelIdOrTurn,
+                prompt: typeof promptOrOptions === 'string' ? promptOrOptions : '',
+            }
+            : channelIdOrTurn;
+        const options = typeof channelIdOrTurn === 'string'
+            ? maybeOptions
+            : promptOrOptions;
+        const sessionRouting = resolveSessionRouting(preparedTurn);
+        const state = this.getOrCreateChannelState(sessionRouting.key, preparedTurn.channelId, sessionRouting.persistence);
         this.clearIdleTimer(state);
-        const turn = createDeferredTurn(prompt, options);
+        const turn = createDeferredTurn(preparedTurn.channelId, preparedTurn.prompt, sessionRouting.persistence, preparedTurn.promptContext, options);
         state.queue.push(turn);
-        this.processChannelQueue(channelId, state);
+        this.processChannelQueue(sessionRouting.key, state);
         return turn.promise;
     }
     async dispose() {
         const error = new Error('Copilot ACP backend stopped');
         this.disposing = true;
+        this.logger?.debug('stopping Copilot ACP backend');
         const closed = this.connection?.closed ?? Promise.resolve();
         this.failAll(error);
-        await Promise.all([closed, this.shutdownPromise ?? Promise.resolve()]);
+        let thrown;
+        try {
+            await Promise.all([closed, this.shutdownPromise ?? Promise.resolve()]);
+        }
+        catch (disposeError) {
+            thrown = disposeError;
+        }
+        try {
+            await Promise.allSettled(this.pendingSessionStoreOperations);
+            await this.sessionStoreWriteQueue;
+            await this.sessionStore?.close?.();
+        }
+        catch (closeError) {
+            thrown ??= closeError;
+        }
+        if (thrown) {
+            throw thrown;
+        }
     }
     async ensureStarted() {
         if (this.fatalError) {
@@ -242,18 +300,32 @@ export class CopilotCliClient {
         }
     }
     async startBackend() {
+        this.logger?.debug('starting Copilot ACP process', {
+            command: this.command,
+            args: ['--acp'],
+            cwd: this.runtime.cwd,
+        });
         const child = this.runtime.spawn(this.command, ['--acp'], {
             stdio: ['pipe', 'pipe', 'pipe'],
         });
         this.child = child;
+        child.stderr.setEncoding('utf8');
+        child.stderr.on('data', (chunk) => {
+            this.logger?.childStderr('copilot stderr', summarizeChildStderr(chunk));
+        });
         child.stderr.resume();
+        this.logger?.debug('spawned Copilot ACP process', { pid: child.pid });
         child.once('error', (error) => {
+            this.logger?.debugError('Copilot ACP process error', error);
             this.failAll(new Error(`Copilot ACP process error: ${normalizeError(error).message}`));
         });
         child.once('exit', (code, signal) => {
             this.resolveChildExit?.();
-            if (this.disposing)
+            if (this.disposing) {
+                this.logger?.debug('Copilot ACP process exited during shutdown', { code, signal });
                 return;
+            }
+            this.logger?.debugError('Copilot ACP process exited unexpectedly', { code, signal });
             const suffix = signal ? `signal ${signal}` : `code ${String(code ?? 'unknown')}`;
             this.failAll(new Error(`Copilot ACP process exited unexpectedly (${suffix})`));
         });
@@ -265,16 +337,12 @@ export class CopilotCliClient {
         const stream = this.runtime.ndJsonStream(output, input);
         const app = this.runtime
             .client({ name: 'borgee-agents-host' })
-            .onRequest(this.runtime.methods.client.session.requestPermission, ({ params }) => ({
-            outcome: {
-                outcome: 'selected',
-                optionId: selectPermissionOption(params.options),
-            },
-        }));
+            .onRequest(this.runtime.methods.client.session.requestPermission, ({ params }) => (this.handlePermissionRequest(params)));
         const connection = app.connect(stream);
         this.connection = connection;
         void connection.closed.then(() => {
             if (!this.disposing) {
+                this.logger?.debugError('Copilot ACP connection closed unexpectedly');
                 this.failAll(new Error('Copilot ACP connection closed unexpectedly'));
             }
         });
@@ -288,23 +356,34 @@ export class CopilotCliClient {
                 },
             });
             this.sessionCapabilities = readSessionCapabilities(initializeResponse);
+            this.logger?.debug('initialized Copilot ACP connection', {
+                loadSession: this.sessionCapabilities.loadSession,
+                resumeSession: this.sessionCapabilities.resumeSession,
+            });
         }
         catch (error) {
             const normalized = new Error(`Copilot ACP initialize failed: ${normalizeError(error).message}`);
+            this.logger?.debugError('Copilot ACP initialize failed', normalized);
             this.failAll(normalized);
             throw normalized;
         }
     }
-    getOrCreateChannelState(channelId) {
+    getOrCreateChannelState(channelId, resolvedChannelId, sessionPersistence) {
         let state = this.channels.get(channelId);
         if (!state) {
             state = {
+                channelId: resolvedChannelId,
+                sessionPersistence,
                 idleTimerGeneration: 0,
                 processing: false,
                 queue: [],
             };
             this.channels.set(channelId, state);
         }
+        else if (state.channelId !== resolvedChannelId
+            || state.sessionPersistence !== sessionPersistence) {
+            throw new Error(`Copilot session routing changed for key "${channelId}"`);
+        }
         return state;
     }
     processChannelQueue(channelId, state) {
@@ -321,7 +400,9 @@ export class CopilotCliClient {
                     }
                     state.activeTurn = turn;
                     try {
+                        state.cwd = await this.resolveSessionCwd(turn.promptContext);
                         await this.ensureStarted();
+                        await this.recycleSessionIfCwdChanged(channelId, state);
                         const session = await this.getOrCreateSession(channelId, state);
                         let reply;
                         try {
@@ -329,7 +410,7 @@ export class CopilotCliClient {
                         }
                         catch (error) {
                             if (isSessionTainted(error)) {
-                                this.invalidateSession(state, session);
+                                this.invalidateSession(channelId, state, session);
                                 this.rejectQueuedTurnsAfterSessionTaint(state, error);
                             }
                             throw error;
@@ -360,11 +441,13 @@ export class CopilotCliClient {
         if (!this.connection) {
             throw new Error('Copilot ACP connection is not available');
         }
-        await this.ensureSessionStoreLoaded();
-        const persistedSessionId = this.persistedSessions.get(channelId);
+        const cwd = state.cwd ?? this.runtime.cwd;
+        const persistedSessionId = state.sessionPersistence === 'persistent'
+            ? await this.readPersistedSessionId(channelId, cwd)
+            : undefined;
         const sessionPromise = persistedSessionId
-            ? this.restoreOrCreateSession(channelId, persistedSessionId)
-            : this.startFreshSession(channelId);
+            ? this.restoreOrCreateSession(channelId, persistedSessionId, cwd)
+            : this.startFreshSession(channelId, cwd);
         this.pendingSessionStarts.add(sessionPromise);
         state.sessionPromise = sessionPromise;
         let sessionAdopted = false;
@@ -387,10 +470,12 @@ export class CopilotCliClient {
             }
             sessionAdopted = true;
             state.session = session;
+            state.sessionCwd = cwd;
             return session;
         }
         catch (error) {
             state.session = undefined;
+            state.sessionCwd = undefined;
             throw error;
         }
         finally {
@@ -399,30 +484,41 @@ export class CopilotCliClient {
             }
         }
     }
-    async startFreshSession(channelId) {
+    async startFreshSession(channelId, cwd) {
         if (!this.connection) {
             throw new Error('Copilot ACP connection is not available');
         }
-        const session = await this.connection.agent.buildSession(this.runtime.cwd).start();
-        await this.persistSessionBestEffort(channelId, session.sessionId);
+        const session = await this.connection.agent.buildSession(cwd).start();
+        this.logger?.debug('started fresh Copilot ACP session', { channelId });
+        const state = this.channels.get(channelId);
+        if (state?.sessionPersistence === 'persistent') {
+            await this.persistSessionBestEffort(channelId, session.sessionId, cwd);
+        }
         return session;
     }
-    async restoreOrCreateSession(channelId, sessionId) {
+    async restoreOrCreateSession(channelId, sessionId, cwd) {
         if (!this.sessionCapabilities.resumeSession && !this.sessionCapabilities.loadSession) {
-            return this.startFreshSession(channelId);
+            this.logger?.debug('Copilot ACP restore unsupported; starting fresh session', { channelId });
+            return this.startFreshSession(channelId, cwd);
         }
         try {
-            return await this.restoreSession(sessionId);
+            const session = await this.restoreSession(sessionId, cwd);
+            this.logger?.debug('restored Copilot ACP session', {
+                channelId,
+                restoreMethod: this.sessionCapabilities.resumeSession ? 'session/resume' : 'session/load',
+            });
+            return session;
         }
         catch (error) {
             if (!isStaleRestoreFailure(error)) {
                 throw normalizeError(error);
             }
+            this.logger?.debug('discarded stale Copilot ACP session and started fresh', { channelId });
             await this.clearPersistedSessionBestEffort(channelId);
-            return this.startFreshSession(channelId);
+            return this.startFreshSession(channelId, cwd);
         }
     }
-    async restoreSession(sessionId) {
+    async restoreSession(sessionId, cwd) {
         if (!this.connection) {
             throw new Error('Copilot ACP connection is not available');
         }
@@ -435,7 +531,7 @@ export class CopilotCliClient {
             if (this.sessionCapabilities.resumeSession) {
                 await this.connection.agent.request(this.runtime.methods.agent.session.resume, {
                     sessionId,
-                    cwd: this.runtime.cwd,
+                    cwd,
                     mcpServers: [],
                 });
                 return session;
@@ -443,7 +539,7 @@ export class CopilotCliClient {
             if (this.sessionCapabilities.loadSession) {
                 await this.connection.agent.request(this.runtime.methods.agent.session.load, {
                     sessionId,
-                    cwd: this.runtime.cwd,
+                    cwd,
                     mcpServers: [],
                 });
                 this.clearBufferedSessionReplay(session);
@@ -462,6 +558,31 @@ export class CopilotCliClient {
             updates.values = [];
         }
     }
+    async resolveSessionCwd(promptContext) {
+        return promptContext?.taskWorkspace?.rootPath ?? this.runtime.cwd;
+    }
+    async recycleSessionIfCwdChanged(channelId, state) {
+        const session = state.session;
+        if (!session) {
+            return;
+        }
+        const nextCwd = state.cwd ?? this.runtime.cwd;
+        if (state.sessionCwd === nextCwd) {
+            return;
+        }
+        this.logger?.debug('recycling Copilot ACP session after cwd changed', {
+            channelId,
+            previousCwd: state.sessionCwd,
+            nextCwd,
+        });
+        state.session = undefined;
+        state.sessionCwd = undefined;
+        this.clearIdleTimer(state);
+        if (!this.disposing && !this.backendClosed && state.sessionPersistence === 'persistent') {
+            await this.clearPersistedSessionBestEffort(channelId);
+        }
+        this.closeSession(session);
+    }
     async runTurn(session, prompt, options) {
         const promptPromise = this.raceWithFatal(session.prompt(prompt));
         const promptFailure = new Promise((_, reject) => {
@@ -505,6 +626,17 @@ export class CopilotCliClient {
         }
         return Promise.race([promise, this.fatalPromise]);
     }
+    handlePermissionRequest(params) {
+        return resolveCopilotPermissionResponse({
+            gateEnabled: this.permissionPolicy.gateEnabled ?? false,
+            policyMode: this.permissionPolicy.policyMode ?? 'audit-only',
+            params,
+            logger: this.logger,
+            auditSink: this.permissionPolicy.auditSink,
+            agentId: this.resolveSessionStoreAgentId()?.trim() || undefined,
+            channelId: this.findChannelIdBySessionId(params.sessionId),
+        });
+    }
     failAll(error) {
         if (this.fatalError) {
             return;
@@ -522,6 +654,7 @@ export class CopilotCliClient {
                 this.closeSession(state.session);
             }
             state.session = undefined;
+            state.sessionCwd = undefined;
             state.sessionPromise = undefined;
             state.activeTurn = undefined;
             if (!state.processing) {
@@ -531,17 +664,16 @@ export class CopilotCliClient {
         this.channels.clear();
         this.shutdownPromise = this.shutdownBackend(error);
     }
-    invalidateSession(state, session) {
+    invalidateSession(channelId, state, session) {
         this.clearIdleTimer(state);
         if (state.session === session) {
             state.session = undefined;
+            state.sessionCwd = undefined;
         }
+        this.logger?.debug('discarding tainted Copilot ACP session', { channelId });
         this.closeSession(session);
-        for (const [channelId, candidate] of this.channels.entries()) {
-            if (candidate === state) {
-                void this.clearPersistedSessionBestEffort(channelId);
-                break;
-            }
+        if (!this.disposing && !this.backendClosed && state.sessionPersistence === 'persistent') {
+            void this.clearPersistedSessionBestEffort(channelId);
         }
     }
     closeSession(session) {
@@ -589,6 +721,14 @@ export class CopilotCliClient {
         clearTimeout(state.idleTimer);
         state.idleTimer = undefined;
     }
+    findChannelIdBySessionId(sessionId) {
+        for (const state of this.channels.values()) {
+            if (state.session?.sessionId === sessionId) {
+                return state.channelId;
+            }
+        }
+        return undefined;
+    }
     reconcileIdleChannelState(channelId, state) {
         if (this.channels.get(channelId) !== state) {
             return;
@@ -606,6 +746,15 @@ export class CopilotCliClient {
             this.channels.delete(channelId);
             return;
         }
+        if (state.sessionPersistence === 'ephemeral') {
+            this.clearIdleTimer(state);
+            const session = state.session;
+            state.session = undefined;
+            state.sessionCwd = undefined;
+            this.closeSession(session);
+            this.channels.delete(channelId);
+            return;
+        }
         this.clearIdleTimer(state);
         const generation = state.idleTimerGeneration;
         state.idleTimer = setTimeout(() => {
@@ -627,8 +776,8 @@ export class CopilotCliClient {
             this.sessionStoreLoadPromise = (async () => {
                 const loaded = await this.sessionStore.load(agentId);
                 this.persistedSessions.clear();
-                for (const [channelId, sessionId] of Object.entries(loaded)) {
-                    this.persistedSessions.set(channelId, sessionId);
+                for (const [channelId, sessionValue] of Object.entries(loaded)) {
+                    this.persistedSessions.set(channelId, parsePersistedSessionRecord(sessionValue));
                 }
                 this.loadedSessionStoreAgentId = agentId;
             })().finally(() => {
@@ -637,23 +786,37 @@ export class CopilotCliClient {
         }
         await this.sessionStoreLoadPromise;
     }
-    async persistSession(channelId, sessionId) {
+    async readPersistedSessionId(channelId, cwd) {
         await this.ensureSessionStoreLoaded();
-        this.persistedSessions.set(channelId, sessionId);
-        await this.flushSessionStore();
-    }
-    async persistSessionBestEffort(channelId, sessionId) {
-        try {
-            await this.persistSession(channelId, sessionId);
+        const record = this.persistedSessions.get(channelId);
+        if (!record) {
+            return undefined;
         }
-        catch (error) {
-            console.error('[agents-host] failed to persist Copilot session map; keeping reply delivery', {
-                agentId: this.loadedSessionStoreAgentId,
-                channelId,
-                sessionId,
-                error,
-            });
+        if (!record.cwd || record.cwd !== cwd) {
+            await this.clearPersistedSessionBestEffort(channelId);
+            return undefined;
         }
+        return record.sessionId;
+    }
+    async persistSession(channelId, sessionId, cwd) {
+        await this.ensureSessionStoreLoaded();
+        this.persistedSessions.set(channelId, { sessionId, cwd });
+        await this.flushSessionStore();
+    }
+    async persistSessionBestEffort(channelId, sessionId, cwd) {
+        await this.trackSessionStoreOperation((async () => {
+            try {
+                await this.persistSession(channelId, sessionId, cwd);
+            }
+            catch (error) {
+                this.logger.error('failed to persist Copilot session map; keeping reply delivery', {
+                    agentId: this.loadedSessionStoreAgentId,
+                    channelId,
+                    sessionId,
+                    error: summarizeError(error),
+                });
+            }
+        })());
     }
     async clearPersistedSession(channelId) {
         await this.ensureSessionStoreLoaded();
@@ -663,27 +826,39 @@ export class CopilotCliClient {
         await this.flushSessionStore();
     }
     async clearPersistedSessionBestEffort(channelId) {
-        try {
-            await this.clearPersistedSession(channelId);
-        }
-        catch (error) {
-            console.error('[agents-host] failed to clear Copilot session map; retrying in-memory only', {
-                agentId: this.loadedSessionStoreAgentId,
-                channelId,
-                error,
-            });
-        }
+        await this.trackSessionStoreOperation((async () => {
+            try {
+                await this.clearPersistedSession(channelId);
+            }
+            catch (error) {
+                this.logger.error('failed to clear Copilot session map; retrying in-memory only', {
+                    agentId: this.loadedSessionStoreAgentId,
+                    channelId,
+                    error: summarizeError(error),
+                });
+            }
+        })());
     }
     async flushSessionStore() {
         if (!this.sessionStore || !this.loadedSessionStoreAgentId) {
             return;
         }
         const agentId = this.loadedSessionStoreAgentId;
-        const snapshot = Object.fromEntries(this.persistedSessions.entries());
+        const snapshot = Object.fromEntries([...this.persistedSessions.entries()].map(([channelId, record]) => [
+            channelId,
+            serializePersistedSessionRecord(record),
+        ]));
         const write = this.sessionStoreWriteQueue.then(() => this.sessionStore.save(agentId, snapshot));
         this.sessionStoreWriteQueue = write.catch(() => { });
         await write;
     }
+    async trackSessionStoreOperation(operation) {
+        const tracked = operation.finally(() => {
+            this.pendingSessionStoreOperations.delete(tracked);
+        });
+        this.pendingSessionStoreOperations.add(tracked);
+        return tracked;
+    }
     evictIdleChannel(channelId, state, generation) {
         if (this.disposing || this.fatalError || this.backendClosed) {
             return;
@@ -697,7 +872,9 @@ export class CopilotCliClient {
         }
         const session = state.session;
         state.session = undefined;
+        state.sessionCwd = undefined;
         if (session) {
+            this.logger?.debug('evicting idle Copilot ACP session', { channelId });
             this.closeSession(session);
         }
         this.channels.delete(channelId);
@@ -718,12 +895,15 @@ export class CopilotCliClient {
             return;
         }
         const childExitPromise = this.childExitPromise ?? Promise.resolve();
+        this.logger?.debug('sending SIGTERM to Copilot ACP process');
         child.kill('SIGTERM');
         const exitedAfterTerm = await this.waitForChildExit(childExitPromise, this.runtime.shutdownGracePeriodMs);
         if (exitedAfterTerm) {
+            this.logger?.debug('Copilot ACP process exited after SIGTERM');
             this.child = undefined;
             return;
         }
+        this.logger?.debug('sending SIGKILL to Copilot ACP process after SIGTERM grace timeout');
         child.kill('SIGKILL');
         await this.waitForChildExit(childExitPromise, this.runtime.shutdownForceKillWaitMs);
         this.child = undefined;

package/dist/providers/copilot/session-store.d.ts

@@ -1,6 +1,7 @@
 export interface CopilotChannelSessionStore {
     load(agentId: string): Promise<Record<string, string>>;
     save(agentId: string, sessions: Record<string, string>): Promise<void>;
+    close?(): Promise<void> | void;
 }
 export interface FileCopilotChannelSessionStoreOptions {
     resolvePath(agentId: string): string;

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