@edukors/ai-cli 0.0.0-stage → 0.1.1

package/dist/providers.d.ts

@@ -0,0 +1,9 @@
+import type { ProviderAdapter } from "./provider.js";
+/**
+ * The adapters the bundled executables (`edukors-ai`, `edukors-ai-host`)
+ * offer, in the order a provider menu shows them. `--fake` adds the
+ * deterministic test provider.
+ */
+export declare function bundledProviders(options?: {
+    fake?: boolean;
+}): ProviderAdapter[];

package/dist/providers.js

@@ -0,0 +1,15 @@
+import { createClaudeProvider } from "./providers/claude/adapter.js";
+import { createCodexProvider } from "./providers/codex/adapter.js";
+import { createFakeProvider } from "./testing/fakeProvider.js";
+/**
+ * The adapters the bundled executables (`edukors-ai`, `edukors-ai-host`)
+ * offer, in the order a provider menu shows them. `--fake` adds the
+ * deterministic test provider.
+ */
+export function bundledProviders(options = {}) {
+    const providers = [createClaudeProvider(), createCodexProvider()];
+    if (options.fake)
+        providers.push(createFakeProvider());
+    return providers;
+}
+//# sourceMappingURL=providers.js.map

package/dist/providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../src/providers.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAA8B,EAAE;IAC/D,MAAM,SAAS,GAAsB,CAAC,oBAAoB,EAAE,EAAE,mBAAmB,EAAE,CAAC,CAAC;IACrF,IAAI,OAAO,CAAC,IAAI;QAAE,SAAS,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC,CAAC;IACvD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/redact.d.ts

@@ -0,0 +1,7 @@
+export interface RedactOptions {
+    /** Replaced with `~`. Defaults to the current OS user's home. */
+    home?: string;
+}
+export declare function redactText(text: string, options?: RedactOptions): string;
+/** Deep copy with sensitive keys dropped and every string redacted. */
+export declare function redactValue(value: unknown, options?: RedactOptions, depth?: number): unknown;

package/dist/redact.js

@@ -0,0 +1,48 @@
+import { homedir } from "node:os";
+/** Keys whose values are never written to diagnostics. */
+const SENSITIVE_KEY = /(token|secret|password|passwd|authorization|cookie|api[_-]?key|credential|session[_-]?key|private[_-]?key)/i;
+const PATTERNS = [
+    // Bearer and Basic authorization values.
+    [/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{8,}/gi, "$1 [redacted]"],
+    // Provider-style API keys (sk-..., sk-ant-..., ghp_..., xox?-...).
+    [/\b(sk|rk|pk)-[A-Za-z0-9_-]{16,}/g, "[redacted-key]"],
+    [/\b(ghp|gho|ghu|ghs|github_pat)_[A-Za-z0-9_]{16,}/g, "[redacted-key]"],
+    [/\bxox[abposr]-[A-Za-z0-9-]{10,}/g, "[redacted-key]"],
+    // JSON Web Tokens.
+    [/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g, "[redacted-jwt]"],
+    // key=value and "key": "value" forms with a sensitive key.
+    [
+        /((?:api[_-]?key|access[_-]?token|refresh[_-]?token|token|secret|password|authorization)["']?\s*[:=]\s*["']?)([^\s"',;}]{4,})/gi,
+        "$1[redacted]",
+    ],
+    // Long opaque strings that look like credentials.
+    [/\b[A-Za-z0-9+/_-]{64,}={0,2}/g, "[redacted-long]"],
+];
+export function redactText(text, options = {}) {
+    let out = text;
+    for (const [pattern, replacement] of PATTERNS)
+        out = out.replace(pattern, replacement);
+    const home = options.home ?? homedir();
+    if (home && home.length > 1)
+        out = out.split(home).join("~");
+    return out;
+}
+/** Deep copy with sensitive keys dropped and every string redacted. */
+export function redactValue(value, options = {}, depth = 0) {
+    if (depth > 12)
+        return "[truncated]";
+    if (typeof value === "string")
+        return redactText(value, options);
+    if (Array.isArray(value))
+        return value.map((v) => redactValue(v, options, depth + 1));
+    if (value instanceof Error)
+        return { name: value.name, message: redactText(value.message, options) };
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [key, v] of Object.entries(value))
+            out[key] = SENSITIVE_KEY.test(key) ? "[redacted]" : redactValue(v, options, depth + 1);
+        return out;
+    }
+    return value;
+}
+//# sourceMappingURL=redact.js.map

package/dist/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.js","sourceRoot":"","sources":["../src/redact.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAElC,0DAA0D;AAC1D,MAAM,aAAa,GAAG,6GAA6G,CAAC;AAEpI,MAAM,QAAQ,GAAuB;IACnC,yCAAyC;IACzC,CAAC,6CAA6C,EAAE,eAAe,CAAC;IAChE,mEAAmE;IACnE,CAAC,kCAAkC,EAAE,gBAAgB,CAAC;IACtD,CAAC,mDAAmD,EAAE,gBAAgB,CAAC;IACvE,CAAC,kCAAkC,EAAE,gBAAgB,CAAC;IACtD,mBAAmB;IACnB,CAAC,+DAA+D,EAAE,gBAAgB,CAAC;IACnF,2DAA2D;IAC3D;QACE,gIAAgI;QAChI,cAAc;KACf;IACD,kDAAkD;IAClD,CAAC,+BAA+B,EAAE,iBAAiB,CAAC;CACrD,CAAC;AAOF,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,UAAyB,EAAE;IAClE,IAAI,GAAG,GAAG,IAAI,CAAC;IACf,KAAK,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC,IAAI,QAAQ;QAAE,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IACvF,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,OAAO,EAAE,CAAC;IACvC,IAAI,IAAI,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7D,OAAO,GAAG,CAAC;AACb,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,WAAW,CAAC,KAAc,EAAE,UAAyB,EAAE,EAAE,KAAK,GAAG,CAAC;IAChF,IAAI,KAAK,GAAG,EAAE;QAAE,OAAO,aAAa,CAAC;IACrC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACjE,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;IACtF,IAAI,KAAK,YAAY,KAAK;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC;IACrG,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvC,MAAM,GAAG,GAA4B,EAAE,CAAC;QACxC,KAAK,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;QACrI,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/registry/lock.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A cross-process lock: a directory that exists while it is held. `mkdir` is
+ * atomic on every supported filesystem. The holder refreshes its timestamp
+ * while it works; a lock whose owner process is gone, or that has not been
+ * refreshed within `staleMs`, is taken over.
+ */
+export interface LockOptions {
+    timeoutMs?: number;
+    staleMs?: number;
+    /** The error thrown when the lock cannot be acquired in time. */
+    onTimeout?: () => Error;
+}
+export declare function withLock<T>(dir: string, fn: () => Promise<T>, options?: LockOptions): Promise<T>;
+/** Serializes async work within this process, by key. */
+export declare class KeyedMutex {
+    private readonly tails;
+    run<T>(key: string, fn: () => Promise<T>): Promise<T>;
+}

package/dist/registry/lock.js

@@ -0,0 +1,83 @@
+import { mkdir, readFile, rm, stat, utimes, writeFile } from "node:fs/promises";
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { AiCliError } from "../errors.js";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === "EPERM";
+    }
+}
+async function isStale(dir, staleMs) {
+    try {
+        const info = await stat(dir);
+        if (Date.now() - info.mtimeMs > staleMs)
+            return true;
+        const owner = JSON.parse(await readFile(join(dir, "owner.json"), "utf8"));
+        return owner.host === hostname() && typeof owner.pid === "number" && !processAlive(owner.pid);
+    }
+    catch {
+        // Owner file not written yet: give the holder the benefit of the doubt until staleMs.
+        return false;
+    }
+}
+export async function withLock(dir, fn, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const staleMs = options.staleMs ?? 30_000;
+    const deadline = Date.now() + timeoutMs;
+    for (let attempt = 0;; attempt++) {
+        try {
+            await mkdir(dir);
+            break;
+        }
+        catch (e) {
+            const code = e.code;
+            if (code === "ENOENT") {
+                await mkdir(join(dir, ".."), { recursive: true });
+                continue;
+            }
+            if (code !== "EEXIST")
+                throw e;
+            if (await isStale(dir, staleMs)) {
+                await rm(dir, { recursive: true, force: true });
+                continue;
+            }
+            if (Date.now() > deadline)
+                throw options.onTimeout?.() ?? new AiCliError("REGISTRY_LOCKED", "the shared account registry is busy", { meta: { lock: dir } });
+            await sleep(Math.min(200, 5 * 2 ** Math.min(attempt, 5)) + Math.random() * 10);
+        }
+    }
+    const heartbeat = setInterval(() => {
+        const now = new Date();
+        utimes(dir, now, now).catch(() => undefined);
+    }, Math.max(250, staleMs / 3));
+    heartbeat.unref();
+    try {
+        await writeFile(join(dir, "owner.json"), JSON.stringify({ pid: process.pid, host: hostname(), at: new Date().toISOString() }));
+        return await fn();
+    }
+    finally {
+        clearInterval(heartbeat);
+        await rm(dir, { recursive: true, force: true });
+    }
+}
+/** Serializes async work within this process, by key. */
+export class KeyedMutex {
+    tails = new Map();
+    run(key, fn) {
+        const previous = this.tails.get(key) ?? Promise.resolve();
+        const next = previous.then(fn, fn);
+        const tail = next.catch(() => undefined);
+        this.tails.set(key, tail);
+        void tail.then(() => {
+            if (this.tails.get(key) === tail)
+                this.tails.delete(key);
+        });
+        return next;
+    }
+}
+//# sourceMappingURL=lock.js.map

package/dist/registry/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../src/registry/lock.ts"],"names":[],"mappings":"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"}

package/dist/registry/registry.d.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+/**
+ * The shared account registry: non-secret account metadata, read and written
+ * by every EDUKORS application on this computer, possibly running different
+ * library versions.
+ *
+ * Versioning: `schemaVersion` is the format the file was last written in;
+ * `minReaderVersion` is the oldest library format that can still read it.
+ * A library reads a file whose `minReaderVersion` it meets, and writes only
+ * a file whose `schemaVersion` it knows, so an older application never
+ * rewrites a newer file. Unknown fields are preserved on write.
+ */
+export declare const REGISTRY_SCHEMA_VERSION = 1;
+export declare const AccountRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    providerId: z.ZodString;
+    label: z.ZodString;
+    home: z.ZodString;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$loose>;
+export type AccountRecord = z.infer<typeof AccountRecordSchema>;
+export declare class AccountRegistry {
+    readonly file: string;
+    private readonly lockDir;
+    private readonly mutex;
+    constructor(file: string, lockDir: string);
+    list(): Promise<AccountRecord[]>;
+    get(id: string): Promise<AccountRecord | undefined>;
+    /**
+     * Reads, changes and writes the registry under the cross-process lock. `change`
+     * mutates the draft; whatever it returns is returned.
+     */
+    update<T>(change: (accounts: AccountRecord[]) => T): Promise<T>;
+    private read;
+    /** Write to a temporary file, flush, then rename over the original. */
+    private write;
+}

package/dist/registry/registry.js

@@ -0,0 +1,119 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, open, readFile, rename, rm } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { z } from "zod";
+import { AiCliError } from "../errors.js";
+import { KeyedMutex, withLock } from "./lock.js";
+/**
+ * The shared account registry: non-secret account metadata, read and written
+ * by every EDUKORS application on this computer, possibly running different
+ * library versions.
+ *
+ * Versioning: `schemaVersion` is the format the file was last written in;
+ * `minReaderVersion` is the oldest library format that can still read it.
+ * A library reads a file whose `minReaderVersion` it meets, and writes only
+ * a file whose `schemaVersion` it knows, so an older application never
+ * rewrites a newer file. Unknown fields are preserved on write.
+ */
+export const REGISTRY_SCHEMA_VERSION = 1;
+export const AccountRecordSchema = z.looseObject({
+    /** Immutable; session identity derives from it, never from the label. */
+    id: z.string().regex(/^[A-Za-z0-9_-]{8,64}$/),
+    providerId: z.string().min(1),
+    label: z.string().min(1).max(80),
+    /** Application-managed storage, relative to the data directory. */
+    home: z.string().min(1),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+});
+const RegistryFileSchema = z.looseObject({
+    schemaVersion: z.number().int().positive(),
+    minReaderVersion: z.number().int().positive(),
+    accounts: z.array(AccountRecordSchema),
+});
+const empty = () => ({ schemaVersion: REGISTRY_SCHEMA_VERSION, minReaderVersion: 1, accounts: [] });
+export class AccountRegistry {
+    file;
+    lockDir;
+    mutex = new KeyedMutex();
+    constructor(file, lockDir) {
+        this.file = file;
+        this.lockDir = lockDir;
+    }
+    async list() {
+        return (await this.read()).accounts;
+    }
+    async get(id) {
+        return (await this.list()).find((a) => a.id === id);
+    }
+    /**
+     * Reads, changes and writes the registry under the cross-process lock. `change`
+     * mutates the draft; whatever it returns is returned.
+     */
+    update(change) {
+        return this.mutex.run("registry", () => withLock(this.lockDir, async () => {
+            const current = await this.read();
+            if (current.schemaVersion > REGISTRY_SCHEMA_VERSION) {
+                throw new AiCliError("REGISTRY_TOO_NEW", "the account registry was written by a newer EDUKORS version", {
+                    meta: { found: current.schemaVersion, supported: REGISTRY_SCHEMA_VERSION },
+                });
+            }
+            const accounts = current.accounts.map((a) => ({ ...a }));
+            const result = change(accounts);
+            const next = { ...current, schemaVersion: REGISTRY_SCHEMA_VERSION, minReaderVersion: Math.max(1, current.minReaderVersion), accounts };
+            for (const account of next.accounts)
+                AccountRecordSchema.parse(account);
+            await this.write(next);
+            return result;
+        }));
+    }
+    async read() {
+        let raw;
+        try {
+            raw = await readFile(this.file, "utf8");
+        }
+        catch (e) {
+            if (e.code === "ENOENT")
+                return empty();
+            throw e;
+        }
+        let json;
+        try {
+            json = JSON.parse(raw);
+        }
+        catch (e) {
+            throw new AiCliError("REGISTRY_CORRUPT", "the account registry is not valid JSON", { cause: e, meta: { file: this.file } });
+        }
+        const version = json?.minReaderVersion;
+        if (typeof version === "number" && version > REGISTRY_SCHEMA_VERSION) {
+            throw new AiCliError("REGISTRY_TOO_NEW", "the account registry was written by a newer EDUKORS version", {
+                meta: { requires: version, supported: REGISTRY_SCHEMA_VERSION },
+            });
+        }
+        const parsed = RegistryFileSchema.safeParse(json);
+        if (!parsed.success)
+            throw new AiCliError("REGISTRY_CORRUPT", "the account registry has an invalid structure", { meta: { file: this.file, issue: z.prettifyError(parsed.error) } });
+        return parsed.data;
+    }
+    /** Write to a temporary file, flush, then rename over the original. */
+    async write(data) {
+        await mkdir(dirname(this.file), { recursive: true });
+        const tmp = join(dirname(this.file), `.${basename(this.file)}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`);
+        const handle = await open(tmp, "w", 0o600);
+        try {
+            await handle.writeFile(JSON.stringify(data, null, 2) + "\n");
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        try {
+            await rename(tmp, this.file);
+        }
+        catch (e) {
+            await rm(tmp, { force: true });
+            throw e;
+        }
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/registry/registry.ts"],"names":[],"mappings":"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"}

package/dist/session.d.ts

@@ -0,0 +1,126 @@
+import { type SerializedError } from "./errors.js";
+import type { AiEvent, AiEventListener, EventScope, SessionCloseReason } from "./events.js";
+import type { ScopedLog } from "./diagnostics.js";
+import type { Capabilities, ProviderAdapter, SessionContext, SessionOptions } from "./provider.js";
+import type { ToolDefinition, ToolResult } from "./tools.js";
+/**
+ * One conversation: one application, one document, one account.
+ *
+ * The session owns the identity rules the plan requires. Every request gets
+ * its own sink; once the request is interrupted, finished or replaced, that
+ * sink drops whatever the provider still sends, so late output never reaches
+ * the document. A provider that crashes is restarted on the next request,
+ * resuming its conversation when the provider supports it.
+ */
+export type SessionState = "opening" | "idle" | "busy" | "interrupting" | "failed" | "closed";
+export interface TurnResult {
+    requestId: string;
+    status: "completed" | "cancelled" | "failed";
+    error?: SerializedError;
+}
+export interface SendOptions {
+    /** Supplied by the application to correlate events with its own records. */
+    requestId?: string;
+    /** Latest document state, including unsaved manual edits. */
+    context?: string;
+}
+/** What the application decides about a call to one of the user's MCP servers. */
+export interface AuthorizationRequest {
+    kind: "mcp";
+    /** The `callId` of this call's toolStarted/toolCompleted events. */
+    callId: string;
+    server: string;
+    tool: string;
+    input: Record<string, unknown>;
+    documentId: string;
+    requestId: string;
+    signal: AbortSignal;
+}
+export type AuthorizationDecision = {
+    allow: true;
+} | {
+    allow: false;
+    message?: string;
+};
+export type Authorizer = (request: AuthorizationRequest) => Promise<AuthorizationDecision> | AuthorizationDecision;
+/** The user's MCP servers as the session reaches them (see mcp/external.ts). */
+export interface ExternalCaller {
+    has(server: string, tool: string): boolean;
+    call(server: string, tool: string, args: Record<string, unknown>): Promise<ToolResult>;
+}
+export interface SessionDeps {
+    adapter: ProviderAdapter;
+    capabilities: Capabilities;
+    scope: Omit<EventScope, "requestId">;
+    /** Builds a fresh provider context (account home, work dir, tools). */
+    context: () => Promise<SessionContext>;
+    tools: ReadonlyMap<string, ToolDefinition>;
+    external?: ExternalCaller;
+    /** Without one, every call to a user's MCP server is denied. */
+    authorize?: Authorizer;
+    options: SessionOptions;
+    publish: (event: Omit<AiEvent, "seq" | "at">) => AiEvent;
+    log: ScopedLog;
+    interruptGraceMs: number;
+    onClosed: (session: AiSession) => void;
+}
+export declare class AiSession {
+    private readonly deps;
+    readonly id: string;
+    readonly appId: string;
+    readonly documentId: string;
+    readonly accountId: string;
+    readonly providerId: string;
+    private _state;
+    private provider;
+    /** Identifies the current provider instance; hooks from older ones are ignored. */
+    private providerToken;
+    private _resumeId;
+    private turn;
+    private closing;
+    private options;
+    private readonly listeners;
+    private droppedEvents;
+    constructor(deps: SessionDeps);
+    get state(): SessionState;
+    /** The provider's own conversation id, for applications that persist it to resume later. */
+    get resumeId(): string | undefined;
+    /** Events of this session only. Returns an unsubscribe function. */
+    on(listener: AiEventListener): () => void;
+    /** Opens (or reopens) the provider session. Called by the library; reopening happens on demand. */
+    start(resumeId?: string): Promise<void>;
+    /**
+     * Sends a request and resolves when it ends. Failures resolve with
+     * `status: "failed"` and are also emitted as `error` events; only misuse
+     * (a closed or busy session) rejects.
+     */
+    send(text: string, options?: SendOptions): Promise<TurnResult>;
+    /**
+     * Stops the current request. Resolves once it has settled: already
+     * committed tool calls stay committed, nothing after this point is applied.
+     * A provider that does not stop within the grace period is shut down and
+     * restarted (resumed) on the next request.
+     */
+    interrupt(): Promise<void>;
+    /** Answers a `question` event. */
+    answer(questionId: string, answer: string): void;
+    updateOptions(options: SessionOptions): Promise<void>;
+    close(reason?: SessionCloseReason): Promise<void>;
+    /** Counts provider output that arrived for a request no longer current. */
+    get lateEventsDropped(): number;
+    private newTurn;
+    private finish;
+    private dropProvider;
+    private providerExited;
+    private sinkFor;
+    private callTool;
+    private callExternal;
+    /** Reports the user's MCP servers once the session is open. */
+    reportServers(statuses: {
+        server: string;
+        status: "connected" | "failed";
+        tools?: number;
+        error?: string;
+    }[]): void;
+    private emit;
+}