@leuria/cli 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,819 @@
+import * as http from 'node:http';
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { AuthMethod, InitializeResponse, McpServer } from '@agentclientprotocol/sdk';
+import { Duplex } from 'node:stream';
+
+/**
+ * What a site says its features need, so Leuria can guide the visitor to
+ * an AI and model that fit, and no bigger (bigger costs more). A closed,
+ * small vocabulary: capabilities and how hard the tasks are, never model
+ * names. Guidance only: the visitor decides.
+ */
+type Effort = "light" | "standard" | "deep";
+interface SiteNeeds {
+    /** The site's features use page tools. */
+    tools?: boolean;
+    /** The site sends images. */
+    images?: boolean;
+    /** How hard the tasks are: `light` (answer, extract, summarize), `standard` (several steps with tools), `deep` (long reasoning, agentic work). */
+    effort?: Effort;
+    /** About how much text one turn sends, in tokens. */
+    context?: number;
+}
+
+/**
+ * Sites the visitor approved. One grant per origin; the site holds the
+ * token, the engine keeps only its SHA-256. Revoking a grant makes the
+ * site ask again.
+ */
+
+interface Grant {
+    origin: string;
+    /** Name the site gave when it asked to connect. */
+    app?: string;
+    tokenHash: string;
+    createdAt: string;
+    lastUsedAt?: string;
+    /** Registry id of the AI this site uses; the default AI when absent. */
+    agent?: string;
+    /** The model this site uses, for the AI it was chosen with; that AI's model choice otherwise. */
+    model?: {
+        agent: string;
+        id: string;
+    };
+    /** What the site said its features need, when it connected (guidance for choosing its AI). */
+    needs?: SiteNeeds;
+}
+declare class GrantStore {
+    private readonly path;
+    private grants;
+    private loadedMtime;
+    private readonly removedListeners;
+    private readonly changedListeners;
+    /** `path: null` keeps grants in memory only (tests, `leuria test`). */
+    constructor(path?: string | null);
+    /** Called with each origin whose grant disappears, here or in another process. */
+    onRemoved(listener: (origin: string) => void): void;
+    /** Called with each origin whose AI or model changes. */
+    onChanged(listener: (origin: string) => void): void;
+    list(): Grant[];
+    has(origin: string): boolean;
+    get(origin: string): Grant | undefined;
+    /** Use `agent` for this site, or the default AI when `undefined`. */
+    setAgent(origin: string, agent: string | undefined): boolean;
+    /** Use `model` of `agent` for this site, or that AI's own choice when `undefined`. */
+    setModel(origin: string, model: {
+        agent: string;
+        id: string;
+    } | undefined): boolean;
+    /** Create or replace the origin's grant; returns the new token. Keeps the site's AI and model choice; `needs` replaces what it declared. */
+    create(origin: string, app?: string, needs?: SiteNeeds): string;
+    /** True when `token` is the origin's current token. */
+    verify(origin: string, token: string | undefined): boolean;
+    revoke(origin: string): boolean;
+    /** Pick up changes made by another process, such as `leuria sites revoke`. */
+    private reload;
+    private save;
+}
+/** `scheme://host[:port]`, lowercase, no trailing slash. Throws if not http(s). */
+declare function normalizeOrigin(origin: string): string;
+
+/**
+ * Leuria's state on the visitor's machine, under `~/.leuria` (or
+ * `LEURIA_HOME`):
+ *
+ *   config.json   engine settings (port, agent, the model chosen for each agent,
+ *                 the agents known to work)
+ *   models.json   the models each agent offered, so none is started just to list them
+ *   grants.json   sites the visitor approved, with hashed tokens
+ *   agents/       agent adapters installed by `leuria setup`
+ */
+declare const DEFAULT_PORT = 19570;
+
+/**
+ * LLM providers: LM Studio and Ollama on this computer, and any
+ * OpenAI-compatible API (the visitor's own key, a company gateway…).
+ *
+ * An AI id for an LLM is `llm:<providerId>` (the service is the AI; its
+ * model is chosen like an agent's, in config.json `models`), or, from
+ * before, `llm:<providerId>/<model>` with the model fixed, e.g.
+ * `llm:ollama/qwen3:8b`. `lmstudio` and `ollama` exist without
+ * configuration, at their default local URLs.
+ */
+type LlmKind = "lmstudio" | "ollama" | "openai";
+interface LlmProvider {
+    id: string;
+    kind: LlmKind;
+    /** Shown to the visitor: "LM Studio", "Ollama", or the name they gave. */
+    name: string;
+    /** OpenAI-compatible base URL, ending in `/v1`. */
+    baseUrl: string;
+    apiKey?: string;
+}
+
+/**
+ * Embeddings for sites, from an embedding model on this computer (LM
+ * Studio or Ollama). Only local services: a site indexing its pages must
+ * not send them to a cloud service or spend the visitor's API credits.
+ *
+ *   POST /embed   { texts: string[], kind?: "query" | "document" }  →  { model, vectors }
+ */
+
+interface Embedder {
+    provider: LlmProvider;
+    model: string;
+}
+interface Embeddings {
+    /** The embedding model sites get now, if any. Cheap: cached for a few seconds. */
+    find: () => Promise<Embedder | undefined>;
+    embed: (texts: string[], kind: "query" | "document") => Promise<{
+        model: string;
+        vectors: number[][];
+    }>;
+}
+
+interface Logger {
+    info: (msg: string, meta?: Record<string, unknown>) => void;
+    warn: (msg: string, meta?: Record<string, unknown>) => void;
+    error: (msg: string, meta?: Record<string, unknown>) => void;
+}
+/** Line-per-event logger on stderr, so stdout stays free. */
+declare function createLogger(verbose?: boolean): Logger;
+
+/**
+ * Pairing: how a site gets a grant, without the engine ever answering a
+ * site that the visitor didn't ask about.
+ *
+ *   1. On the visitor's click, the page makes a secret nonce and opens
+ *      `leuria://connect?origin=…&app=…&nonce=…`. The desktop app gets the
+ *      link, registers it (`link()`, through its admin API) and asks the
+ *      visitor in its own window.
+ *   2. The page long-polls `POST /connect/claim { nonce }`. The engine
+ *      answers only the browser's `Origin` that a link named (a page cannot
+ *      forge it), and only with the nonce of that link. On Allow, the token
+ *      goes out once.
+ *
+ * A site that forges a link naming another site gets nothing: it can't
+ * claim with the other site's Origin, and the other site doesn't know the
+ * nonce. Until a link names it, a site gets no answer at all (see
+ * `server.ts`: no CORS), so it can't tell that Leuria is installed.
+ *
+ * The CLI engine (no app, so no links) serves the same claim: the first
+ * claim creates the request, and the visitor answers on the engine's own
+ * approval page, opened in their browser. Only a click there, posted from
+ * the engine's origin, decides.
+ */
+
+interface PairingOptions {
+    grants: GrantStore;
+    logger: Logger;
+    /** Engine's own origins, e.g. `http://127.0.0.1:19570`. */
+    selfOrigins: Set<string>;
+    port: number;
+    /**
+     * Requests come only from links the desktop app received (`link()`).
+     * Off for the CLI: the first claim creates the request.
+     */
+    linksOnly: boolean;
+    /** Plain-language name of the configured agent, shown on the page. */
+    agentName: () => string;
+    /** Called when a request is created (or a link repeated), e.g. to open the approval page or show the app. */
+    onRequest?: (request: PairingRequestInfo) => void;
+    /** Called when the visitor decided, wherever they clicked. */
+    onDecided?: (request: {
+        requestId: string;
+        origin: string;
+        allowed: boolean;
+    }) => void;
+}
+interface PairingRequestInfo {
+    requestId: string;
+    origin: string;
+    app?: string;
+    needs?: SiteNeeds;
+    approveUrl: string;
+}
+declare class Pairing {
+    private readonly options;
+    private readonly requests;
+    private readonly deniedAt;
+    constructor(options: PairingOptions);
+    /** A link named this origin and it hasn't collected its answer yet: it may be answered. */
+    hasRequest(origin: string): boolean;
+    /**
+     * A `leuria://connect` link reached the desktop app. Returns the request,
+     * or why it was refused. A repeated link for the same site replaces the
+     * nonce (the page tried again) instead of asking twice.
+     */
+    link(input: {
+        origin?: unknown;
+        app?: unknown;
+        nonce?: unknown;
+        needs?: unknown;
+    }): {
+        requestId: string;
+    } | {
+        error: string;
+    };
+    /** Returns true when the request was a pairing route. */
+    handle(req: http.IncomingMessage, res: http.ServerResponse, pathname: string): Promise<boolean>;
+    /** The page collects the visitor's answer, with the nonce of its link. */
+    private claim;
+    /** Ask the visitor about `origin`, or update the question already asked. */
+    private open;
+    private info;
+    /** Requests waiting for the visitor, e.g. for the desktop app. */
+    pending(): PairingRequestInfo[];
+    /**
+     * Decide from a trusted place (the desktop app's native window).
+     * `granted` runs on Allow once the grant exists, before the site gets
+     * its token: e.g. to set the site's AI and model from the first message.
+     */
+    decideById(requestId: string, allow: boolean, granted?: (origin: string) => void): boolean;
+    private decide;
+    private wait;
+    private expire;
+    private renderPage;
+}
+
+/**
+ * Harness policy for agents started on behalf of a website.
+ *
+ * Two layers, because the agent is an untrusted component:
+ *
+ *   1. Session options sent to the adapter on `session/new`
+ *      ({@link buildSessionMeta}). For claude-agent-acp these are spread
+ *      into the Claude Agent SDK options: no built-in tools, no user or
+ *      project settings (so no plugins, hooks or extra MCP servers), no
+ *      bypass mode, and the WebMCP server's tools pre-allowed.
+ *
+ *   2. The ACP `session/request_permission` handler
+ *      ({@link decidePermission}). Anything that still asks for
+ *      permission is denied unless it is one of the page's WebMCP
+ *      tools. This holds even if an adapter ignores layer 1.
+ */
+/** MCP server name the bridge registers for the browser tools. */
+declare const WEBMCP_SERVER_NAME = "webmcp";
+interface SessionConfig {
+    /** System prompt. Replaces the adapter's coding-agent preset. */
+    systemPrompt?: string;
+    model?: string;
+    maxTurns?: number;
+}
+/** Build the `_meta` payload for ACP `session/new`. */
+declare function buildSessionMeta(config?: SessionConfig): Record<string, unknown>;
+interface PermissionDecision {
+    allow: boolean;
+    toolName: string;
+    /** ACP response for `session/request_permission`. */
+    response: {
+        outcome: {
+            outcome: "selected";
+            optionId: string;
+        } | {
+            outcome: "cancelled";
+        };
+    };
+}
+/** Decide an ACP `session/request_permission` request. Deny by default. */
+declare function decidePermission(params: unknown): PermissionDecision;
+
+/**
+ * Persistent multi-turn ACP client session.
+ *
+ * No one-shot runs, no usage accounting, no interactive permission UI.
+ * Permission requests go through the harness policy
+ * (deny unless WebMCP tool), and session options come from
+ * `buildSessionMeta`.
+ */
+
+interface ToolCallEvent {
+    toolCallId: string;
+    title?: string;
+    kind?: string;
+    status?: string;
+    toolName?: string;
+}
+/** A file sent with a prompt. Images are base64; other files are text. */
+type PromptAttachment = {
+    type: "image";
+    mimeType: string;
+    data: string;
+    name?: string;
+} | {
+    type: "text";
+    text: string;
+    name?: string;
+    mimeType?: string;
+};
+/** What the agent said about itself in `initialize`. */
+interface AgentInfo {
+    authMethods: AuthMethod[];
+    agentCapabilities: NonNullable<InitializeResponse["agentCapabilities"]>;
+    agentInfo?: InitializeResponse["agentInfo"];
+}
+/** The models an agent offers in `session/new`, and how to pick one. */
+interface AgentModels {
+    current?: string;
+    options: Array<{
+        id: string;
+        name: string;
+        description?: string;
+    }>;
+    /** ACP v1 config option id (category "model"); absent for the older `models` field. */
+    configId?: string;
+}
+
+/**
+ * In-process WebMCP relay for the bridge daemon.
+ *
+ * Two surfaces, one server:
+ *
+ *   - **Browser → bridge (WebSocket)**: the browser console connects to
+ *     `ws://127.0.0.1:<port>/webmcp/register`, exchanges its registration
+ *     token for a channel WS at `/webmcp/channel/:id?token=…`, then
+ *     declares the tools / resources / prompts it wants to expose.
+ *
+ *   - **Agent → bridge (HTTP MCP)**: the spawned ACP agent calls JSON-RPC
+ *     2.0 against `POST /webmcp/mcp` with `Authorization: Bearer
+ *     <channelToken>`. `tools/list` and friends read the channel's
+ *     registry; `tools/call` etc. forward the request to the browser via
+ *     the channel WS and await the response.
+ *
+ * Long-blocking calls (`tools/call`, `resources/read`, `prompts/get`)
+ * switch to chunked HTTP encoding and emit periodic newline keep-alives
+ * so the agent's HTTP client doesn't abort while the user is interacting
+ * in the browser.
+ *
+ * Origin checks happen in `server.ts` before requests reach this class.
+ */
+
+interface ToolDescriptor {
+    name: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+    annotations?: Record<string, unknown>;
+}
+interface WebMcpChannelSummary {
+    id: string;
+    sessionId: string;
+    connected: boolean;
+    tools: Array<{
+        name: string;
+        description?: string;
+    }>;
+    resources: Array<{
+        uri: string;
+        name: string;
+        description?: string;
+    }>;
+    prompts: Array<{
+        name: string;
+        description?: string;
+    }>;
+}
+interface WebMcpLogger {
+    info: (msg: string, meta?: Record<string, unknown>) => void;
+    warn: (msg: string, meta?: Record<string, unknown>) => void;
+    error: (msg: string, meta?: Record<string, unknown>) => void;
+}
+declare class WebMcpServer {
+    private readonly logger;
+    private readonly port;
+    private readonly channels;
+    private readonly registrationTokens;
+    private readonly sessionChannels;
+    private readonly tokenToChannel;
+    private readonly registerWss;
+    private readonly channelWss;
+    constructor(logger: WebMcpLogger, port: number);
+    /**
+     * Allocate a channel for an ACP session. Returns:
+     *   - `registrationToken` — base64-encoded `{ server, token }` blob the
+     *     browser presents on the `/webmcp/register` WS to claim the channel.
+     *   - `channelToken` — Bearer credential the agent presents on the
+     *     `/webmcp/mcp` HTTP endpoint.
+     *   - `channelId` — server-side handle (used in the channel WS path).
+     */
+    createChannel(sessionId: string): {
+        registrationToken: string;
+        channelToken: string;
+        channelId: string;
+    };
+    getChannelSummaries(): WebMcpChannelSummary[];
+    /**
+     * Tear everything down — close the two WebSocketServers, kill every
+     * ping timer, reject every pending request, force-close every browser
+     * channel WS. Called from `daemon.ts`'s `shutdown` so the process can
+     * exit on Ctrl-C; without it the WS servers keep the event loop alive
+     * indefinitely.
+     */
+    close(): void;
+    removeChannel(sessionId: string): void;
+    /** The page tools a session's browser has declared. */
+    listTools(sessionId: string): ToolDescriptor[];
+    /** Run a page tool in the browser; resolves with its JSON result. Throws on tool errors. */
+    callTool(sessionId: string, name: string, args: Record<string, unknown>): Promise<unknown>;
+    /** Returns true when the request path belongs to WebMCP. */
+    matches(pathname: string): boolean;
+    handleUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): void;
+    handleHttp(req: IncomingMessage, res: ServerResponse): Promise<void>;
+    private handleRegistrationConnection;
+    private handleChannelConnection;
+    private handleChannelMessage;
+    private parseTool;
+    private parseResource;
+    private parsePrompt;
+    private sendAck;
+    private resolveRequest;
+    private dispatch;
+    private forwardToBrowser;
+    private parseBody;
+    private sendJsonRpcResult;
+    private sendJsonRpcError;
+}
+
+/**
+ * Agent sessions opened by websites.
+ *
+ * Every session belongs to the origin that prepared it,
+ * has a WebMCP channel, and runs the visitor's agent in an empty sandbox
+ * directory under the harness policy. The page chooses the prompts; the
+ * visitor's config chooses the agent.
+ *
+ *   prepare    -> `pending_approval`, WebMCP channel allocated, nothing spawned
+ *   approve    -> spawn the ACP agent, send the first prompt if any
+ *                 (without one the session goes `idle` and emits `ready`,
+ *                 which lets a page warm the agent up ahead of time)
+ *   promptTurn -> follow-up prompt on an idle session (same agent context)
+ *   cancelTurn -> stop the current turn, keep the session
+ *   close      -> kill the agent; terminal `completed`
+ *
+ * SSE events: `webmcp_ready`, `ready`, `turn_start`, `chunk`, `thought`, `tool_call`,
+ * `permission`, `log`, `turn_completed`, `completed`, `failed`,
+ * `cancelled`.
+ */
+
+type SessionStatus = "pending_approval" | "running" | "idle" | "completed" | "failed" | "cancelled";
+interface PrepareParams {
+    /** First turn. Without it, `approve` only starts the agent. */
+    prompt?: string;
+    attachments?: PromptAttachment[];
+    systemPrompt?: string;
+    maxTurns?: number;
+    /** Origin that owns the session; `local` for requests without `Origin`. */
+    origin: string;
+}
+interface SessionInfo {
+    id: string;
+    status: SessionStatus;
+    origin: string;
+    createdAt: string;
+    error?: string;
+    registrationToken: string;
+    webmcpUrl: string;
+}
+type SessionListener = (event: string, data: unknown) => void;
+/** What an agent profile needs to set up one session. */
+interface SessionSetup {
+    /** The session's empty sandbox directory (also the agent's cwd). */
+    sandbox: string;
+    /** MCP endpoint and bearer token for the page tools. */
+    mcpUrl: string;
+    mcpToken: string;
+    systemPrompt?: string;
+    maxTurns?: number;
+}
+/** What the session manager needs from a running agent, ACP or LLM. */
+interface LiveAgent {
+    readonly isAlive: boolean;
+    /** `authRequired`: the agent is signed out (ACP `auth_required`). */
+    start(): Promise<{
+        error?: string;
+        authRequired?: boolean;
+    }>;
+    /** Models the agent offered in `session/new` (ACP agents). */
+    readonly models?: AgentModels | null;
+    prompt(text: string, attachments: PromptAttachment[]): Promise<{
+        error?: string;
+    }>;
+    cancelTurn(): Promise<void>;
+    close(): void;
+}
+interface AgentLaunch {
+    /** Registry or LLM id, so the engine can remember whether this AI works. */
+    id?: string;
+    /**
+     * An LLM provider instead of an ACP agent: the engine runs the tool
+     * loop itself (`LlmSession`); `command` and `args` are unused.
+     */
+    llm?: {
+        provider: LlmProvider;
+        model: string;
+    };
+    command: string;
+    args: string[];
+    /** Environment from the agent's registry entry. */
+    env?: Record<string, string>;
+    /** The model the visitor chose for this agent; the agent's default otherwise. */
+    model?: string;
+    /**
+     * Agent-specific session setup (environment, MCP servers, `_meta`).
+     * Without it, the Claude policy applies: page tools as an ACP MCP
+     * server and `buildSessionMeta`.
+     */
+    configure?: (setup: SessionSetup) => {
+        env?: Record<string, string>;
+        mcpServers?: McpServer[];
+        meta?: Record<string, unknown>;
+    };
+}
+interface Session {
+    id: string;
+    status: SessionStatus;
+    params: PrepareParams;
+    cwd: string;
+    createdAt: Date;
+    error?: string;
+    /** Text of the current turn, replayed to late SSE subscribers. */
+    turnChunks: string[];
+    listeners: Set<SessionListener>;
+    live?: LiveAgent;
+    registrationToken: string;
+    channelToken: string;
+}
+interface SessionManagerOptions {
+    webMcpServer: WebMcpServer;
+    port: number;
+    logger: Logger;
+    /** Command for the agent serving `origin`: its own choice, or the default AI. */
+    resolveAgent: (origin: string) => Promise<AgentLaunch>;
+    /** ACP handshake timeout. */
+    startTimeoutMs?: number;
+    /**
+     * What a real session learned about an AI: it started (with the models it
+     * offers), or it is signed out. Startup trusts this instead of checking.
+     */
+    onAgentState?: (id: string, state: {
+        ok: boolean;
+        models?: AgentModels | null;
+    }) => void;
+    /**
+     * Command that relays MCP over stdio to the engine (`leuria mcp-stdio`),
+     * for agents without HTTP MCP support. ACP requires every agent to
+     * support stdio MCP servers; HTTP is optional.
+     */
+    stdioMcpCommand?: {
+        command: string;
+        args: string[];
+    };
+}
+declare class SessionManager {
+    private readonly options;
+    private readonly sessions;
+    constructor(options: SessionManagerOptions);
+    prepare(params: PrepareParams): SessionInfo;
+    approve(sessionId: string): SessionInfo;
+    promptTurn(sessionId: string, prompt: string, attachments?: PromptAttachment[]): SessionInfo;
+    cancelTurn(sessionId: string): Promise<SessionInfo>;
+    cancel(sessionId: string): SessionInfo;
+    close(sessionId: string): SessionInfo;
+    get(sessionId: string): SessionInfo | null;
+    /** Current-turn text, for SSE replay. */
+    turnChunks(sessionId: string): string[];
+    webmcpReady(session: Session | string): {
+        registrationToken: string;
+        webmcpUrl: string;
+    };
+    addListener(sessionId: string, listener: SessionListener): void;
+    removeListener(sessionId: string, listener: SessionListener): void;
+    /** End every session of an origin, e.g. when its grant is revoked. */
+    /** End the sessions of the origins that match (their AI or model changed): the next message starts a new one. */
+    closeWhere(match: (origin: string) => boolean): void;
+    closeOrigin(origin: string): void;
+    shutdown(): void;
+    private execute;
+    /** An LLM provider, driven by the engine with the page's tools. */
+    private llmSession;
+    /** An ACP agent process under its policy. */
+    private acpSession;
+    private runTurn;
+    private fail;
+    /**
+     * Fresh empty directory per session, so the agent finds no project
+     * files (CLAUDE.md, repo) to act on.
+     */
+    private allocateSandbox;
+    private teardown;
+    private notify;
+    private require;
+    private toInfo;
+}
+
+/** Injected by tsup at build time; `dev` when run from source. */
+declare const VERSION: string;
+
+/**
+ * Loopback HTTP + WebSocket server: the engine's only door.
+ *
+ *   - Binds to 127.0.0.1 and rejects any `Host` other than
+ *     127.0.0.1/localhost on our port (blocks DNS rebinding).
+ *   - Requests without `Origin` come from local processes (the agent
+ *     calling `/webmcp/mcp`, the CLI, curl) and are trusted: they already
+ *     run as the visitor.
+ *   - Silent (the desktop app): a web origin the visitor never connected,
+ *     and that no `leuria://connect` link named, gets nothing it can read,
+ *     on any route. It can't tell that Leuria is here.
+ *   - A web origin claims its token with `/connect/claim`; everything else
+ *     needs the origin's grant token in `Authorization: Bearer`, and
+ *     WebSocket upgrades need a grant.
+ *   - The engine's own origin may only use `/connect` (the CLI's approval page).
+ */
+
+interface EngineOptions {
+    port?: number;
+    grants: GrantStore;
+    logger: Logger;
+    /** Plain-language agent name, e.g. "Claude Code"; a function when it can change. */
+    agentName: string | (() => string);
+    /** What a connected site uses, for its status line ("Claude · Sonnet 5"); the default AI's name otherwise. */
+    siteAgentName?: (origin: string) => string;
+    /** Command for the agent serving `origin` (a site's own choice or the default); called once per session. */
+    resolveAgent: (origin: string) => Promise<AgentLaunch>;
+    /** Called when a site asks to connect. */
+    onPairingRequest?: (request: PairingRequestInfo) => void;
+    onPairingDecided?: (request: {
+        requestId: string;
+        origin: string;
+        allowed: boolean;
+    }) => void;
+    /**
+     * Silent to sites the visitor didn't connect: no answer they can read,
+     * so they can't tell that Leuria is here. Pairing then starts from a
+     * `leuria://connect` link. Default: on with the desktop app (`admin`).
+     */
+    silent?: boolean;
+    /**
+     * Admin API for the desktop app, under `/admin/`. Every request must
+     * carry `Authorization: Bearer <token>`, and come from the app's webview
+     * (`tauri://` origin) or a local process.
+     */
+    admin?: {
+        token: string;
+        handle: (req: http.IncomingMessage, res: http.ServerResponse, pathname: string, pairing: Pairing, sessions: Pick<SessionManager, "closeWhere">) => Promise<boolean>;
+    };
+    startTimeoutMs?: number;
+    /** See `SessionManagerOptions.stdioMcpCommand`. */
+    stdioMcpCommand?: {
+        command: string;
+        args: string[];
+    };
+    /** See `SessionManagerOptions.onAgentState`. */
+    onAgentState?: SessionManagerOptions["onAgentState"];
+    /** Embeddings for connected sites. Default: an embedding model in LM Studio or Ollama on this computer. */
+    embeddings?: Embeddings;
+}
+interface EngineHandle {
+    port: number;
+    pairing: Pairing;
+    sessions: SessionManager;
+    /** Revoke an origin's grant and end its sessions. */
+    revoke: (origin: string) => boolean;
+    close: () => Promise<void>;
+}
+declare function startEngine(options: EngineOptions): Promise<EngineHandle>;
+
+/**
+ * The ACP agent registry (https://agentclientprotocol.com/registry,
+ * source and FORMAT.md at https://github.com/agentclientprotocol/registry):
+ * one JSON document listing agents and how to run them.
+ *
+ *   distribution.npx     { package: "name@version", args?, env? }
+ *   distribution.uvx     { package, args?, env? }
+ *   distribution.binary  { "<os>-<arch>": { archive, cmd, args?, env?, sha256? } }
+ */
+interface PackageDistribution {
+    package: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+interface BinaryTarget {
+    archive: string;
+    cmd: string;
+    args?: string[];
+    env?: Record<string, string>;
+    sha256?: string;
+}
+interface RegistryEntry {
+    id: string;
+    name: string;
+    version: string;
+    description?: string;
+    repository?: string;
+    website?: string;
+    license?: string;
+    icon?: string;
+    distribution: {
+        npx?: PackageDistribution;
+        uvx?: PackageDistribution;
+        binary?: Record<string, BinaryTarget>;
+    };
+}
+/** The registry's agents; `[]` when it cannot be reached. Cached for 10 minutes. */
+declare function fetchRegistry(): Promise<RegistryEntry[]>;
+declare function getRegistryEntry(id: string): Promise<RegistryEntry | null>;
+
+/**
+ * Agents, straight from the ACP registry. Any registry agent can be used:
+ * it is installed once from its registry entry (npx package, uvx package
+ * or binary archive) under `~/.leuria/agents/<id>@<version>`, so later
+ * sessions start without a download and work offline.
+ *
+ * Sign-in follows ACP too (see `auth.ts`): `authenticate` with a method
+ * the agent advertises.
+ *
+ * A few agents get an extra hardening profile on top (`profiles.ts`),
+ * keyed by registry id.
+ */
+
+/** An agent installed from the registry, ready to spawn. */
+interface InstalledAgent {
+    id: string;
+    name: string;
+    version: string;
+    dir: string;
+    command: string;
+    /** What runs the agent before its registry args, e.g. the package's JS entry. */
+    launchArgs: string[];
+    /** The registry's args; terminal auth methods replace these. */
+    args: string[];
+    env: Record<string, string>;
+}
+/** The newest installed version of `id`, if any. */
+declare function installedAgent(id: string): InstalledAgent | null;
+/**
+ * The agent to run: the installed version, or a fresh install from the
+ * registry. `update` installs the registry's current version if newer.
+ */
+declare function ensureAgent(id: string, options?: {
+    update?: boolean;
+    onProgress?: (message: string) => void;
+}): Promise<InstalledAgent>;
+/**
+ * How the engine launches `id` for a session: an ACP agent or an LLM
+ * provider. `model` overrides the model chosen for the agent (a site's own choice).
+ */
+declare function resolveAgentCommand(id: string, model?: string): Promise<AgentLaunch & {
+    name: string;
+}>;
+/** Plain-language name for the configured agent. */
+declare function agentName(id: string): string;
+declare function listAgents(): Promise<Array<RegistryEntry & {
+    installed?: string;
+}>>;
+
+/**
+ * Sign-in, the ACP v1 way. The agent advertises `authMethods` in
+ * `initialize`; whether the visitor is signed in is known from
+ * `session/new`, which fails with `auth_required` otherwise.
+ *
+ * ACP v1 (and the registry's AUTHENTICATION.md) has two method kinds:
+ *   - agent methods (no `type`): the client calls `authenticate` and the
+ *     agent runs its own flow, usually OAuth in the browser;
+ *   - `type: "terminal"`: the client re-runs the agent with the method's
+ *     `args`/`env` (replacing the registry's) in an interactive terminal.
+ *     It MUST NOT be passed to `authenticate`. Agents only offer it when
+ *     the client sets `auth.terminal`, which `leuria login` does in a TTY
+ *     and the desktop app never does.
+ */
+
+interface SignInStatus {
+    ok: boolean;
+    detail: string;
+    methods: AgentInfo["authMethods"];
+    /** Models the agent offers once signed in (from `session/new`), with the visitor's choice as `current`. */
+    models?: AgentModels;
+}
+/** Is the visitor signed in to this agent? Opens (and closes) a real ACP session, within a time limit. */
+declare function checkSignIn(id: string, onProgress?: (message: string) => void): Promise<SignInStatus>;
+/** Sign in with an advertised method, then confirm with `session/new`. */
+declare function signIn(id: string, options?: {
+    methodId?: string;
+    /** The caller can run an interactive terminal method (a TTY). */
+    terminal?: boolean;
+    onProgress?: (message: string) => void;
+    /** Cancel a sign-in in progress: the agent is stopped (which frees its login callback). */
+    signal?: AbortSignal;
+    /** The sign-in page the agent opened in the browser, for a "didn't see it?" link. */
+    onUrl?: (url: string) => void;
+}): Promise<SignInStatus>;
+
+/**
+ * Which agent CLIs are already on this computer, to suggest one in
+ * onboarding ("You already have Codex"). The CLI → registry id map is the
+ * only hardcoded knowledge; everything else comes from the registry.
+ */
+/** Registry ids whose CLI is installed on this machine. */
+declare function detectInstalledClis(): string[];
+
+export { type AgentLaunch, DEFAULT_PORT, type EngineHandle, type EngineOptions, type Grant, GrantStore, type InstalledAgent, type Logger, type PrepareParams, type RegistryEntry, type SessionInfo, type SessionStatus, type ToolCallEvent, VERSION, WEBMCP_SERVER_NAME, agentName, buildSessionMeta, checkSignIn, createLogger, decidePermission, detectInstalledClis, ensureAgent, fetchRegistry, getRegistryEntry, installedAgent, listAgents, normalizeOrigin, resolveAgentCommand, signIn, startEngine };