operon-agents 0.1.0-alpha.2 → 0.1.0-alpha.21

package/dist/providers.js

@@ -0,0 +1,280 @@
+/**
+ * Model providers configured by the host, as opposed to the ones the engine ships with.
+ *
+ * The built-in catalog knows every major provider, but each of those is a fixed list at a fixed
+ * URL. A self-hosted endpoint — vLLM, Ollama, LiteLLM, a gateway, a proxy in front of a vendor —
+ * is neither: its address is local knowledge, and which models it serves is a question only that
+ * endpoint can answer. So a provider here is a URL plus how to authenticate, and its model list is
+ * fetched from the endpoint (`GET {baseUrl}/models`, the OpenAI-compatible shape every one of them
+ * speaks) rather than declared.
+ *
+ * The file is `<homeDir>/providers.toml`, so every local host — the TUI, the app server, a script
+ * that builds its own harness — sees the same providers without each inventing a config format.
+ * Nothing else in the framework reads it: this is the provider registry, not a general config.
+ *
+ * ```toml
+ * # A self-hosted endpoint. Models come from GET http://localhost:8000/v1/models.
+ * [providers.local]
+ * base_url = "http://localhost:8000/v1"
+ * api_key_env = "LOCAL_API_KEY"      # optional; omit for a keyless server
+ * context_window = 128000            # the default applied to every model it reports
+ *
+ * # Per-model facts the endpoint does not report.
+ * [providers.local.models."qwen3-coder"]
+ * name = "Qwen3 Coder"
+ * context_window = 256000
+ * reasoning = true
+ *
+ * # A provider whose models are declared rather than fetched.
+ * [providers.corp]
+ * base_url = "https://llm.corp.internal/v1"
+ * api_key_env = "CORP_API_KEY"
+ * fetch_models = false
+ * [providers.corp.models."gpt-4o-mini"]
+ * context_window = 128000
+ * ```
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseToml } from "smol-toml";
+import { z } from "zod";
+import { createModelRuntime, createProvider, lazyApi, } from "operon-agents-core";
+/** The wire dialects a configured endpoint can speak. Almost everything speaks the first. */
+export const PROVIDER_APIS = ["openai-completions", "openai-responses", "anthropic-messages"];
+const ModelOverrideSchema = z.object({
+    name: z.string().optional(),
+    context_window: z.number().int().positive().optional(),
+    max_output_tokens: z.number().int().positive().optional(),
+    reasoning: z.boolean().optional(),
+    /** Whether the model accepts image input alongside text. */
+    vision: z.boolean().optional(),
+    api: z.enum(PROVIDER_APIS).optional(),
+});
+const ProviderEntrySchema = z.object({
+    base_url: z.string().min(1),
+    /** Display name for pickers; defaults to the provider id. */
+    name: z.string().optional(),
+    api: z.enum(PROVIDER_APIS).default("openai-completions"),
+    /** Environment variable holding the key. Preferred over `api_key`, which lands in the file. */
+    api_key_env: z.string().optional(),
+    api_key: z.string().optional(),
+    /** Ask the endpoint what it serves. Set false to use only the declared `models`. */
+    fetch_models: z.boolean().default(true),
+    /** Defaults applied to every model this provider reports. */
+    context_window: z.number().int().positive().default(128_000),
+    max_output_tokens: z.number().int().positive().default(8_192),
+    reasoning: z.boolean().default(false),
+    vision: z.boolean().default(false),
+    headers: z.record(z.string(), z.string()).optional(),
+    /** Per-model facts, keyed by the id the endpoint reports. */
+    models: z.record(z.string(), ModelOverrideSchema).default({}),
+});
+export const ProvidersFileSchema = z.object({
+    providers: z.record(z.string(), ProviderEntrySchema).default({}),
+});
+export function providersConfigPath(homeDir) {
+    return join(homeDir, "providers.toml");
+}
+/**
+ * Read `<homeDir>/providers.toml`. A missing file is the normal case and yields no providers; a
+ * malformed one yields none plus a warning, because refusing to start over a config file the host
+ * may not even use would be worse than running with the built-in providers alone.
+ */
+export async function loadProviderConfigs(homeDir) {
+    let text;
+    try {
+        text = await readFile(providersConfigPath(homeDir), "utf-8");
+    }
+    catch {
+        return { providers: {}, warnings: [] };
+    }
+    try {
+        const parsed = ProvidersFileSchema.parse(parseToml(text));
+        return { providers: parsed.providers, warnings: [] };
+    }
+    catch (error) {
+        return {
+            providers: {},
+            warnings: [`Ignoring ${providersConfigPath(homeDir)}: ${error instanceof Error ? error.message : String(error)}`],
+        };
+    }
+}
+/**
+ * What a keyless endpoint sends as its bearer token. The engine's OpenAI dialect refuses to build a
+ * client without one, and a local server that wants no key ignores whatever arrives; pi uses the
+ * same literal for the same reason.
+ */
+const NO_KEY_PLACEHOLDER = "unused";
+/** The key this provider authenticates with, or undefined when its env var is declared but unset. */
+function configuredKey(entry) {
+    if (entry.api_key !== undefined)
+        return entry.api_key;
+    if (entry.api_key_env !== undefined)
+        return process.env[entry.api_key_env];
+    return NO_KEY_PLACEHOLDER;
+}
+/**
+ * Auth for an endpoint described by a config file rather than by the engine.
+ *
+ * The built-in `envApiKeyAuth` resolves from environment variables only, which makes a keyless
+ * local server permanently unconfigured — and an unconfigured provider is one the engine never
+ * refreshes and never lists, so its models would not exist. Here the config is the credential: an
+ * inline key, the named environment variable, or, for a server that wants none, the address alone.
+ */
+function configAuth(providerId, entry) {
+    return {
+        name: `${entry.name ?? providerId} API key`,
+        resolve: async ({ ctx, credential, signal }) => {
+            signal.throwIfAborted();
+            if (credential?.key !== undefined && credential.key.length > 0) {
+                return { auth: { apiKey: credential.key }, source: "stored credential" };
+            }
+            if (entry.api_key !== undefined) {
+                return { auth: { apiKey: entry.api_key }, source: "providers.toml" };
+            }
+            if (entry.api_key_env !== undefined) {
+                const value = await ctx.env(entry.api_key_env);
+                signal.throwIfAborted();
+                // A declared variable that is not set means "configured, but not usable yet" — reporting it
+                // as configured would only move the failure to the first request.
+                return value ? { auth: { apiKey: value }, source: entry.api_key_env } : undefined;
+            }
+            return { auth: { apiKey: NO_KEY_PLACEHOLDER }, source: entry.base_url };
+        },
+    };
+}
+/** Zero cost: a self-hosted endpoint has no per-token price, and a wrong number is worse than none. */
+const NO_COST = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+function modelFrom(providerId, entry, modelId) {
+    const override = entry.models[modelId];
+    return {
+        id: modelId,
+        name: override?.name ?? modelId,
+        api: (override?.api ?? entry.api),
+        provider: providerId,
+        baseUrl: entry.base_url,
+        reasoning: override?.reasoning ?? entry.reasoning,
+        input: (override?.vision ?? entry.vision) ? ["text", "image"] : ["text"],
+        cost: NO_COST,
+        contextWindow: override?.context_window ?? entry.context_window,
+        maxTokens: override?.max_output_tokens ?? entry.max_output_tokens,
+        ...(entry.headers !== undefined ? { headers: entry.headers } : {}),
+    };
+}
+/** The model ids an OpenAI-compatible `/models` response lists, in the order the endpoint gave. */
+export function parseModelsResponse(body) {
+    const data = body?.data;
+    if (!Array.isArray(data))
+        return [];
+    const ids = [];
+    for (const item of data) {
+        const id = item?.id;
+        if (typeof id === "string" && id.length > 0)
+            ids.push(id);
+    }
+    return ids;
+}
+function modelsUrl(baseUrl) {
+    return `${baseUrl.replace(/\/+$/, "")}/models`;
+}
+async function fetchEndpointModels(providerId, entry, context) {
+    const declared = Object.keys(entry.models).map((id) => modelFrom(providerId, entry, id));
+    if (!entry.fetch_models || !context.allowNetwork)
+        return declared;
+    const key = configuredKey(entry);
+    const response = await fetch(modelsUrl(entry.base_url), {
+        headers: {
+            ...(key !== undefined ? { authorization: `Bearer ${key}` } : {}),
+            ...entry.headers,
+        },
+        signal: context.signal,
+    });
+    if (!response.ok) {
+        throw new Error(`${modelsUrl(entry.base_url)} answered ${String(response.status)} ${response.statusText}`);
+    }
+    const ids = parseModelsResponse(await response.json());
+    // The endpoint is authoritative on what it serves; a declared model it does not list stays,
+    // because an endpoint that reports nothing (some proxies do) should not empty the picker.
+    const fetched = ids.map((id) => modelFrom(providerId, entry, id));
+    const seen = new Set(fetched.map((model) => model.id));
+    return [...fetched, ...declared.filter((model) => !seen.has(model.id))];
+}
+/**
+ * Turn one config entry into a provider the engine can stream through. Its model list starts at
+ * whatever the config declared and is replaced by the endpoint's on the first refresh.
+ */
+export function providerFromConfig(providerId, entry) {
+    return createProvider({
+        id: providerId,
+        name: entry.name ?? providerId,
+        baseUrl: entry.base_url,
+        ...(entry.headers !== undefined ? { headers: entry.headers } : {}),
+        auth: { apiKey: configAuth(providerId, entry) },
+        models: Object.keys(entry.models).map((id) => modelFrom(providerId, entry, id)),
+        fetchModels: (context) => fetchEndpointModels(providerId, entry, context),
+        api: dialectStreams(entry.api),
+    });
+}
+/** pi's API implementations load on first use, so an unused dialect is never imported. */
+function dialectStreams(api) {
+    switch (api) {
+        case "anthropic-messages":
+            return lazyApi(() => import("@earendil-works/pi-ai/api/anthropic-messages"));
+        case "openai-responses":
+            return lazyApi(() => import("@earendil-works/pi-ai/api/openai-responses"));
+        case "openai-completions":
+            return lazyApi(() => import("@earendil-works/pi-ai/api/openai-completions"));
+    }
+}
+/**
+ * One model runtime carrying the engine's built-in providers plus everything in
+ * `<homeDir>/providers.toml`, with each configured endpoint asked what it serves.
+ *
+ * Hand the same runtime to `defineModel({ provider, model, runtime })` and to
+ * `createLocalHarness({ modelRuntime })`, so the model a host resolves and the models its sessions
+ * can switch to come from one registry.
+ */
+export async function createModelRuntimeFromConfig(options) {
+    const runtime = createModelRuntime();
+    const { providers, warnings } = await loadProviderConfigs(options.homeDir);
+    for (const warning of warnings)
+        options.onWarning?.(warning);
+    const ids = [];
+    for (const [id, entry] of Object.entries(providers)) {
+        if (entry.api_key_env !== undefined && !process.env[entry.api_key_env]) {
+            options.onWarning?.(`Provider "${id}" reads its key from ${entry.api_key_env}, which is not set; its models will not be listed.`);
+        }
+        try {
+            runtime.models.setProvider(providerFromConfig(id, entry));
+            ids.push(id);
+        }
+        catch (error) {
+            options.onWarning?.(`Provider "${id}" was not registered: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (ids.length === 0 || options.refresh === false)
+        return runtime;
+    // An unreachable endpoint is reported, not fatal: the rest of the providers still work, and a
+    // model named directly still resolves from whatever the config declared.
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+        controller.abort();
+    }, options.refreshTimeoutMs ?? 5_000);
+    try {
+        const result = await runtime.models.refresh({ providers: ids, signal: controller.signal });
+        for (const [providerId, error] of result.errors) {
+            options.onWarning?.(`Could not read models from provider "${providerId}": ${error.message}`);
+        }
+        if (result.aborted) {
+            options.onWarning?.(`Reading models from configured providers timed out after ${String(options.refreshTimeoutMs ?? 5_000)}ms.`);
+        }
+    }
+    catch (error) {
+        options.onWarning?.(`Could not refresh configured providers: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    return runtime;
+}
+//# sourceMappingURL=providers.js.map

package/dist/telemetry-posthog.d.ts

@@ -0,0 +1,88 @@
+/**
+ * PostHogAppender — the framework's default telemetry sink (docs/telemetry.md §7).
+ *
+ * Two ways in, one path after:
+ *
+ *   (a) `{ apiKey, host, getDistinctId }` — the appender builds a `posthog-node` client. For
+ *       products without their own analytics plumbing. `getDistinctId` is REQUIRED here and is a
+ *       callback, not a value: sign-in / sign-out change it mid-process. Returning `undefined`
+ *       DROPS the event — the framework never substitutes an id of its own.
+ *
+ *   (b) `{ client }` — the product injects anything with a `capture()`; identity, consent and
+ *       buffering stay wherever the product already keeps them (operon desktop wraps its
+ *       consent-gated main-process sink this way, so there is exactly one PostHog channel).
+ *
+ * Per event: redact → drop non-primitives (types forbid them; a cast can still sneak one in) →
+ * enrich with app/framework identity → capture. Batching, retry and backoff are the client's.
+ */
+import { type TelemetryAppender, type TelemetryEvent, type TelemetryPrimitive } from "operon-agents-core/telemetry";
+/** The minimum a sink has to look like. `posthog-node`'s `PostHog` satisfies it as-is. */
+export interface PostHogClientLike {
+    capture(message: {
+        readonly distinctId?: string;
+        readonly event: string;
+        readonly properties: Record<string, TelemetryPrimitive>;
+        readonly timestamp?: Date;
+    }): void;
+    flush?(): Promise<void> | void;
+    shutdown?(timeoutMs?: number): Promise<void> | void;
+}
+export interface PostHogAppIdentity {
+    /** Product name stamped on every event as `app_name` (e.g. `operon`). */
+    readonly name: string;
+    /** Product version stamped as `app_version`. */
+    readonly version?: string;
+}
+interface PostHogAppenderBaseOptions {
+    readonly app: PostHogAppIdentity;
+    /** Who the event is about. Required in mode (a); optional in mode (b) where the client decides. */
+    readonly getDistinctId?: () => string | undefined;
+    /** Extra properties stamped on every event (a channel tag, say). Same red lines apply. */
+    readonly commonProperties?: Readonly<Record<string, TelemetryPrimitive>>;
+    /** Where dropped-event and client errors go. Default: `console.warn`, once per reason. */
+    readonly warn?: (message: string) => void;
+}
+/** Mode (a): the appender owns a `posthog-node` client. */
+export interface PostHogAppenderClientOptions extends PostHogAppenderBaseOptions {
+    readonly apiKey: string;
+    /** PostHog ingestion host, e.g. `https://us.i.posthog.com`. */
+    readonly host: string;
+    readonly getDistinctId: () => string | undefined;
+    /** Client batching knobs; passed through. */
+    readonly flushAt?: number;
+    readonly flushIntervalMs?: number;
+    /** Test seam: build the client from resolved options instead of `new PostHog(...)`. */
+    readonly createClient?: (apiKey: string, options: {
+        host: string;
+        flushAt?: number;
+        flushInterval?: number;
+    }) => PostHogClientLike;
+}
+/** Mode (b): the product injects the sink. */
+export interface PostHogAppenderInjectedOptions extends PostHogAppenderBaseOptions {
+    readonly client: PostHogClientLike;
+}
+export type PostHogAppenderOptions = PostHogAppenderClientOptions | PostHogAppenderInjectedOptions;
+export declare class PostHogAppender implements TelemetryAppender {
+    private client;
+    private readonly ready;
+    private readonly getDistinctId;
+    private readonly requireDistinctId;
+    private readonly common;
+    private readonly warn;
+    private readonly warned;
+    /** Events that arrived before the lazy client resolved (mode (a) only). Bounded. */
+    private pending;
+    private closed;
+    private droppedCount;
+    constructor(options: PostHogAppenderOptions);
+    /** Events dropped for lack of a distinct id, a closed appender, or a failed client. */
+    get dropped(): number;
+    track(event: TelemetryEvent): void;
+    private send;
+    private warnOnce;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=telemetry-posthog.d.ts.map

package/dist/telemetry-posthog.js

@@ -0,0 +1,142 @@
+/**
+ * PostHogAppender — the framework's default telemetry sink (docs/telemetry.md §7).
+ *
+ * Two ways in, one path after:
+ *
+ *   (a) `{ apiKey, host, getDistinctId }` — the appender builds a `posthog-node` client. For
+ *       products without their own analytics plumbing. `getDistinctId` is REQUIRED here and is a
+ *       callback, not a value: sign-in / sign-out change it mid-process. Returning `undefined`
+ *       DROPS the event — the framework never substitutes an id of its own.
+ *
+ *   (b) `{ client }` — the product injects anything with a `capture()`; identity, consent and
+ *       buffering stay wherever the product already keeps them (operon desktop wraps its
+ *       consent-gated main-process sink this way, so there is exactly one PostHog channel).
+ *
+ * Per event: redact → drop non-primitives (types forbid them; a cast can still sneak one in) →
+ * enrich with app/framework identity → capture. Batching, retry and backoff are the client's.
+ */
+import { createRequire } from "node:module";
+import { redactTelemetryProperties } from "operon-agents-core/telemetry";
+const SHUTDOWN_TIMEOUT_MS = 5_000;
+function frameworkVersion() {
+    try {
+        const require = createRequire(import.meta.url);
+        const pkg = require("../package.json");
+        return pkg.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+function isInjected(options) {
+    return "client" in options;
+}
+async function createNodeClient(apiKey, options) {
+    // Loaded lazily so a product in mode (b) never pays for the module, and so the import lives
+    // in one place if the client ever changes.
+    const mod = await import("posthog-node");
+    return new mod.PostHog(apiKey, { host: options.host, flushAt: options.flushAt, flushInterval: options.flushInterval, disableGeoip: true });
+}
+export class PostHogAppender {
+    client;
+    ready;
+    getDistinctId;
+    requireDistinctId;
+    common;
+    warn;
+    warned = new Set();
+    /** Events that arrived before the lazy client resolved (mode (a) only). Bounded. */
+    pending = [];
+    closed = false;
+    droppedCount = 0;
+    constructor(options) {
+        this.getDistinctId = options.getDistinctId;
+        this.requireDistinctId = !isInjected(options);
+        this.common = Object.freeze({
+            app_name: options.app.name,
+            app_version: options.app.version ?? null,
+            framework_version: frameworkVersion(),
+            platform: process.platform,
+            ...(options.commonProperties ?? {}),
+        });
+        this.warn = options.warn ?? ((message) => console.warn(`[telemetry/posthog] ${message}`));
+        if (isInjected(options)) {
+            this.client = options.client;
+            this.ready = Promise.resolve();
+        }
+        else {
+            const create = options.createClient;
+            const resolved = { host: options.host, flushAt: options.flushAt, flushInterval: options.flushIntervalMs };
+            this.ready = (create === undefined ? createNodeClient(options.apiKey, resolved) : Promise.resolve(create(options.apiKey, resolved)))
+                .then((client) => {
+                this.client = client;
+                const queued = this.pending;
+                this.pending = [];
+                for (const event of queued)
+                    this.send(event);
+            })
+                .catch((error) => {
+                this.warnOnce("client-init", `client failed to initialise; events will be dropped: ${String(error)}`);
+                this.pending = [];
+            });
+        }
+    }
+    /** Events dropped for lack of a distinct id, a closed appender, or a failed client. */
+    get dropped() {
+        return this.droppedCount;
+    }
+    track(event) {
+        if (this.closed) {
+            this.droppedCount += 1;
+            return;
+        }
+        if (this.client === undefined) {
+            if (this.pending.length >= 200) {
+                this.droppedCount += 1;
+                return;
+            }
+            this.pending.push(event);
+            return;
+        }
+        this.send(event);
+    }
+    send(event) {
+        const client = this.client;
+        if (client === undefined)
+            return;
+        const distinctId = this.getDistinctId?.();
+        if (this.requireDistinctId && distinctId === undefined) {
+            this.droppedCount += 1;
+            this.warnOnce("no-distinct-id", "getDistinctId() returned undefined; event dropped (the framework never mints an id)");
+            return;
+        }
+        const properties = { ...this.common, ...redactTelemetryProperties(event.properties) };
+        try {
+            client.capture({
+                ...(distinctId === undefined ? {} : { distinctId }),
+                event: event.name,
+                properties,
+                timestamp: new Date(event.timestamp),
+            });
+        }
+        catch (error) {
+            this.warnOnce("capture", `client.capture threw: ${String(error)}`);
+        }
+    }
+    warnOnce(key, message) {
+        if (this.warned.has(key))
+            return;
+        this.warned.add(key);
+        this.warn(message);
+    }
+    async flush() {
+        await this.ready;
+        await Promise.resolve(this.client?.flush?.());
+    }
+    async shutdown() {
+        await this.ready;
+        this.closed = true;
+        await Promise.resolve(this.client?.shutdown?.(SHUTDOWN_TIMEOUT_MS));
+    }
+}
+//# sourceMappingURL=telemetry-posthog.js.map

package/dist/telemetry.d.ts

@@ -0,0 +1,4 @@
+export * from "operon-agents-core/telemetry";
+export { PostHogAppender } from "./telemetry-posthog.ts";
+export type { PostHogAppenderOptions, PostHogAppenderClientOptions, PostHogAppenderInjectedOptions, PostHogClientLike, PostHogAppIdentity } from "./telemetry-posthog.ts";
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.js

@@ -0,0 +1,3 @@
+export * from "operon-agents-core/telemetry";
+export { PostHogAppender } from "./telemetry-posthog.js";
+//# sourceMappingURL=telemetry.js.map

package/dist/workspace-mcp.d.ts

@@ -0,0 +1,62 @@
+import { type Capability, type McpServerConfig, type McpServersCapabilityOptions, type McpServersHandle } from "operon-agents-core";
+/** How long a directory's connections outlive its last session by default: five minutes. */
+export declare const DEFAULT_WORKSPACE_MCP_IDLE_MS: number;
+export interface WorkspaceMcpPoolOptions extends Omit<McpServersCapabilityOptions, "sharedServers"> {
+    /**
+     * How long a directory's connections stay up after the last session using them closes, in ms.
+     * A session opened there within the window reuses them. `0` closes them at once. Defaults to
+     * {@link DEFAULT_WORKSPACE_MCP_IDLE_MS}.
+     */
+    readonly idleMs?: number;
+}
+/** One session's hold on a directory's connections. `release` is idempotent. */
+export interface WorkspaceMcpLease {
+    readonly servers: McpServersHandle;
+    release(): Promise<void>;
+}
+export declare class WorkspaceMcpPool {
+    private readonly options;
+    /** The generation a NEW borrow in each directory gets. */
+    private readonly current;
+    /** Every generation not yet shut down — current ones and retired ones still on loan. */
+    private readonly live;
+    private closing;
+    constructor(options?: WorkspaceMcpPoolOptions);
+    /** Directories whose connections are currently up (on loan or idling). */
+    get size(): number;
+    /**
+     * Borrow the connections for `workDir`, building them if this directory has none for exactly
+     * these `configs`. Resolves once they have connected — fault-isolated, so a server that failed
+     * is a status on the handle, never a rejection. Rejects for what `createMcpServers` refuses
+     * up front (a transport this host does not run), before anything is built.
+     */
+    acquire(workDir: string, configs: Record<string, McpServerConfig>): Promise<WorkspaceMcpLease>;
+    /** Shut every directory's connections down, on loan or not. Later borrows throw. Idempotent. */
+    close(): Promise<void>;
+    /** The last lease came back: close a retired generation now, a current one after the grace. */
+    private idle;
+    private shutdown;
+    private assertOpen;
+}
+export interface WorkspaceMcpCapabilityOptions {
+    readonly pool: WorkspaceMcpPool;
+    /** The session's working directory — the key the connections are shared under. */
+    readonly workDir: string;
+    /** The servers every session in `workDir` shares. */
+    readonly servers: Record<string, McpServerConfig>;
+    /** The session's own servers, layered over the shared ones (same name: the session's wins). */
+    readonly overlay?: Record<string, McpServerConfig>;
+    /**
+     * Options for the overlay's connections; the pooled ones were configured on the pool. Its
+     * `allowedTransports` is enforced on BOTH — the host's statement of what it runs does not get
+     * weaker because a server happens to be shared.
+     */
+    readonly overlayOptions?: Omit<McpServersCapabilityOptions, "sharedServers">;
+}
+/**
+ * The `mcp` capability over a directory's pooled connections: borrows them at `openSession`,
+ * gives them back at `closeSession` (session close or detach alike). In between it is exactly
+ * `mcpServersCapability` viewing a shared set — same tools, same `session.mcp`, same overlay.
+ */
+export declare function workspaceMcpCapability(options: WorkspaceMcpCapabilityOptions): Capability;
+//# sourceMappingURL=workspace-mcp.d.ts.map