@leuduan/lagent 0.0.0-stage → 44.0.0

package/dist/plugins/fileTools/textEdit.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The text side of `edit_files`: decoding a file as text and encoding it back exactly as it was
+ * kept, and locating a hunk's old text in it.
+ *
+ * A hunk is matched exactly first, then in the three looser passes Codex's `apply_patch` uses
+ * (`codex-rs/apply-patch/src/seek_sequence.rs`): line by line ignoring trailing whitespace, then
+ * surrounding whitespace, then also typographic punctuation. Unlike Codex, which takes the first
+ * place a pass finds, a pass here decides only when it finds exactly one: a second place fails the
+ * hunk as ambiguous, and so does a second exact match.
+ *
+ * A pass that ignores surrounding whitespace can match lines indented differently from the old text.
+ * The new text is then shifted by the same difference, so what replaces the lines sits where they
+ * did; see {@link reindent}.
+ */
+/** A text file as `edit_files` keeps it: its text, and what it writes back around the text unchanged. */
+export type TextFile = {
+    /** Whether the file starts with a UTF-8 byte-order mark, which `text` leaves out. */
+    readonly bom: boolean;
+    readonly text: string;
+    /** The file's line ending, from its first line; `\n` for a file with none. */
+    readonly eol: '\n' | '\r\n';
+    /** Whether the file ends with a line ending. */
+    readonly finalNewline: boolean;
+};
+/** Why a file is not text `edit_files` will edit, or `null` and the file. */
+export declare function decodeText(bytes: Buffer): {
+    file: TextFile;
+    refusal: null;
+} | {
+    file: null;
+    refusal: string;
+};
+/** `text` as the file's bytes, with the BOM the file had. */
+export declare function encodeText(file: Pick<TextFile, 'bom'>, text: string): Buffer;
+/** `text` with its line endings made the file's. */
+export declare function withLineEndings(text: string, eol: TextFile['eol']): string;
+/**
+ * New text for a file whose old text was `file`, ending in a newline exactly when the old text
+ * did: one is added when it had one, and every trailing line ending removed when it had none. An
+ * empty file has no ending to keep, so its new text is taken as given.
+ */
+export declare function keepFinalNewline(file: TextFile, text: string): string;
+export type Hunk = {
+    readonly old_text: string;
+    readonly new_text: string;
+};
+/** How a hunk's old text was found, or why it was not. */
+export type HunkMatch = {
+    readonly found: true;
+    readonly text: string;
+    readonly pass: MatchPass;
+    /** Whether the new text was shifted to the file's indentation. */
+    readonly reindented: boolean;
+} | {
+    readonly found: false;
+    readonly reason: string;
+};
+export type MatchPass = 'exact' | 'trailing-whitespace' | 'whitespace' | 'punctuation';
+export declare const PASS_WORDING: Record<Exclude<MatchPass, 'exact'>, string>;
+/**
+ * `text` with `hunk` applied, in the file's line endings. The old text must be found in exactly
+ * one place; when it is found nowhere, the reason shows what was looked for and the lines of the
+ * file nearest to it.
+ */
+export declare function applyHunk(text: string, hunk: Hunk, eol: TextFile['eol']): HunkMatch;
+/** Codex's normalization: trimmed, with dashes, quotes and odd spaces made ASCII. */
+export declare function normalized(line: string): string;

package/dist/plugins/fileTools/tools.d.ts

@@ -0,0 +1,6 @@
+import type { Tool } from '../../loop/index.js';
+import type { FileToolsConfig } from './config.js';
+/** What the model is told about the tools that need more than their description. */
+export declare const guidance: Map<string, string>;
+/** The file tools `config` provides: without `rg`, neither search tool; nothing searches by another means. */
+export declare const fileToolsFor: (config: FileToolsConfig) => readonly Tool[];

package/dist/plugins/historyRecall/history.d.ts

@@ -0,0 +1,9 @@
+import type { Journal } from '../../journal/index.js';
+import type { Seq } from '../../records/journal.js';
+/**
+ * Every message that has ever been on a thread's surface, numbered from 1 in lineage order, by the
+ * row behind it. Stand-ins are not numbered, so a number never moves: not across compactions,
+ * reopening or forks, which share their source's numbers up to the cut. The one numbering a
+ * checkpoint's footer names messages by and recall reads them back by, so the two always agree.
+ */
+export declare function historyNumbers(journal: Pick<Journal, 'lineage'>, threadId: string): Map<Seq, number>;

package/dist/plugins/historyRecall/index.d.ts

@@ -0,0 +1,31 @@
+import type { Plugin } from '@leuduan/cordis';
+import { z } from 'zod';
+import { HISTORY_RECALL_TOOLS } from './tools.js';
+export { HISTORY_RECALL_TOOLS };
+/** Message numbering, which compaction's checkpoints and stand-ins cite as recall reads it back. */
+export { historyNumbers } from './history.js';
+/**
+ * The line a stand-in ends on when its agent has both tools: where to read the `count` replaced
+ * messages back, `first` being the number of the first of them. Written here, beside the tools it
+ * names, so the pointer and what it points at change together. The form for several is the longer.
+ */
+export declare const renderRecall: (first: number, count: number) => string;
+export declare const HistoryRecallConfigSchema: z.ZodObject<{
+    agents: z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodLiteral<"global">, z.ZodLiteral<"all">]>;
+}, z.core.$strict>;
+export type HistoryRecallConfig = z.input<typeof HistoryRecallConfigSchema>;
+/**
+ * Registers `history_read` and `history_search`: read-only tools over the journal that bring back
+ * what a replacement condensed, by the message numbers a checkpoint names. Each reads the calling
+ * thread's own lineage, a fork's inherited rows included, and nothing of any other thread. They are
+ * advertised to the selected agents from a thread's first request, and answer that nothing has been
+ * condensed until something has. Independent of any strategy: it reads the journal, not how the
+ * surface was replaced. A strategy that sees `history_read` granted points its checkpoints at it.
+ *
+ * Mounted on the untagged application context only: the tools are one grant for every thread.
+ *
+ * ```ts
+ * await root.plugin(historyRecall, { agents: ['main_agent'] })
+ * ```
+ */
+export declare const historyRecall: Plugin.Object<HistoryRecallConfig>;

package/dist/plugins/historyRecall/index.js

@@ -0,0 +1 @@
+import{a,b,c,d,e}from"../../chunks/2GCIWSOA.js";import"../../chunks/JFX2MXBA.js";import"../../chunks/S34ZA2R6.js";import"../../chunks/CUK7CGC7.js";import"../../chunks/BPRCULZH.js";import"../../chunks/FJLU4UH3.js";import"../../chunks/DDANMY45.js";import"../../chunks/BBCW2FZK.js";import"../../chunks/MMNNZCBO.js";import"../../chunks/G44LG6VL.js";import"../../chunks/D4PQP5MA.js";export{b as HISTORY_RECALL_TOOLS,d as HistoryRecallConfigSchema,a as historyNumbers,e as historyRecall,c as renderRecall};

package/dist/plugins/historyRecall/render.d.ts

@@ -0,0 +1,34 @@
+import type { PluginJournal } from '../../journal/index.js';
+import { type MessageRole } from '../../llm/primitives.js';
+/** One message that has been on a thread's surface, as recall shows it. */
+export type HistoryMessage = {
+    /** Its history number: 1 for the first message the thread's conversation ever held. */
+    readonly number: number;
+    readonly role: MessageRole;
+    /** The tool a result answers; `null` for any other message. */
+    readonly name: string | null;
+    /** The message as rendered, without its header. */
+    readonly body: string;
+    /**
+     * Whether the surface no longer holds this message as itself: a replacement stands for it, as a
+     * span's checkpoint or a rewrite's shorter text.
+     */
+    readonly condensed: boolean;
+};
+/**
+ * Every message that has ever been on a thread's surface, in lineage order, numbered as
+ * `historyNumbers` numbers them and rendered as the model saw it: the same row-to-message logic the
+ * surface fold uses, with replacements ignored. A pure read over the journal: nothing here depends
+ * on how, or whether, the surface was ever replaced, except which messages `condensed` marks.
+ *
+ * A fork reads its source's rows up to its cut as its own, so it shares their numbers and text.
+ */
+export declare function history(journal: Pick<PluginJournal, 'lineage' | 'state'>, threadId: string): HistoryMessage[];
+/**
+ * A message in a transcript: its body in an envelope the code writes, which names its number, role
+ * and, for a result, its tool. A body cannot end the envelope or fake another, since every closing
+ * `</message` in it is turned into `<\/message`: nothing a message said speaks as the harness.
+ */
+export declare const renderMessage: (message: HistoryMessage) => string;
+/** A message named in a listing: `Message 5 (user)`, `Message 6 (tool read_file)`. */
+export declare const describeMessage: (message: HistoryMessage) => string;

package/dist/plugins/historyRecall/tools.d.ts

@@ -0,0 +1,4 @@
+/** The tools the plugin grants, for a host's allowlist or an agent's tool list. */
+export declare const HISTORY_RECALL_TOOLS: readonly ["history_read", "history_search"];
+export declare const historyReadTool: import("../../loop/tool.js").Tool;
+export declare const historySearchTool: import("../../loop/tool.js").Tool;

package/dist/plugins/mcp/catalog.d.ts

@@ -0,0 +1,36 @@
+import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { type Tool as RemoteTool } from '@modelcontextprotocol/sdk/types.js';
+import { type ToolSpec } from '../../llm/primitives.js';
+import type { McpConfig } from './config.js';
+import type { UnexposableTool } from './errors.js';
+/** One exposable tool: its lagent name, the definition the server listed, and the spec built from it. */
+export type CatalogEntry = {
+    readonly name: string;
+    readonly remoteName: string;
+    readonly definition: RemoteTool;
+    readonly spec: ToolSpec;
+    /** Equal for equal definitions; a changed definition is a different tool. */
+    readonly fingerprint: string;
+};
+/** A complete, immutable snapshot of what a server offers, as lagent can expose it. */
+export type Catalog = {
+    readonly entries: ReadonlyMap<string, CatalogEntry>;
+    readonly unexposable: readonly UnexposableTool[];
+};
+export declare const EMPTY_CATALOG: Catalog;
+/**
+ * Every page of `tools/list`, requested directly. The SDK's `listTools()` replaces the client's
+ * validator and task caches on every page, and its list-changed refresh fetches only the first one.
+ */
+export declare function listAllTools(client: Client, signal: AbortSignal): Promise<RemoteTool[]>;
+/**
+ * What lagent can expose of a complete listing. With an allowlist only the listed tools are
+ * considered, under their aliases, and a listed tool the server does not offer is unexposable.
+ * Collisions are found over the whole listing, so the outcome never depends on how the server
+ * paged: every tool of a colliding group is unexposable.
+ */
+export declare function buildCatalog(config: Pick<McpConfig, 'name' | 'tools'>, listed: readonly RemoteTool[]): Catalog;
+/** Unexposable tools in one order, by tool and then reason, whatever order they were found in. */
+export declare const sortUnexposable: (tools: readonly UnexposableTool[]) => UnexposableTool[];
+/** Whether two reports of unexposable tools say the same thing. */
+export declare const sameUnexposable: (left: readonly UnexposableTool[], right: readonly UnexposableTool[]) => boolean;

package/dist/plugins/mcp/config.d.ts

@@ -0,0 +1,63 @@
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { z } from 'zod';
+/**
+ * The longest server name: `mcp__` and `__` around it still leave 33 of the 64 characters a tool
+ * name may have for the tool segment.
+ */
+export declare const MAX_SERVER_NAME_LENGTH = 24;
+/**
+ * A factory for any SDK transport. A transport is single-use, so every connection asks for a new one.
+ * `signal` aborts when the opening is abandoned (its deadline, the owner's signal, disposal): stop
+ * working then. A transport that arrives after that is closed by the mount.
+ */
+export type McpTransportFactory = (signal: AbortSignal) => Transport | Promise<Transport>;
+export declare const McpTransportSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"stdio">;
+    command: z.ZodTuple<[z.ZodString], z.ZodString>;
+    cwd: z.ZodString;
+    env: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"streamable-http">;
+    url: z.ZodURL;
+    headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"custom">;
+    create: z.ZodCustom<McpTransportFactory, McpTransportFactory>;
+}, z.core.$strict>], "kind">;
+export type McpTransportConfig = z.output<typeof McpTransportSchema>;
+export declare const McpConfigSchema: z.ZodObject<{
+    name: z.ZodString;
+    transport: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"stdio">;
+        command: z.ZodTuple<[z.ZodString], z.ZodString>;
+        cwd: z.ZodString;
+        env: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"streamable-http">;
+        url: z.ZodURL;
+        headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"custom">;
+        create: z.ZodCustom<McpTransportFactory, McpTransportFactory>;
+    }, z.core.$strict>], "kind">;
+    agents: z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodLiteral<"global">, z.ZodLiteral<"all">]>;
+    confirm: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodLiteral<"none">, z.ZodObject<{
+        except: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>]>;
+    onInterrupted: z.ZodUnion<readonly [z.ZodLiteral<"report">, z.ZodLiteral<"annotations">, z.ZodObject<{
+        rerun: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>]>;
+    maxConcurrentCalls: z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"unbounded">]>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        name: z.ZodString;
+        as: z.ZodString;
+    }, z.core.$strict>]>>>;
+    instructions: z.ZodDefault<z.ZodBoolean>;
+    connectTimeoutSeconds: z.ZodDefault<z.ZodNumber>;
+    callTimeoutSeconds: z.ZodDefault<z.ZodNumber>;
+    maxCallSeconds: z.ZodDefault<z.ZodNumber>;
+    maxContentBytes: z.ZodDefault<z.ZodNumber>;
+    signal: z.ZodOptional<z.ZodCustom<AbortSignal, AbortSignal>>;
+}, z.core.$strict>;
+export type McpConfig = z.output<typeof McpConfigSchema>;
+export type McpConfigInput = z.input<typeof McpConfigSchema>;

package/dist/plugins/mcp/connection.d.ts

@@ -0,0 +1,53 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { McpTransportConfig } from './config.js';
+/** One successful initialization: a client, its transport, and the server's instructions. */
+export type Generation = {
+    readonly number: number;
+    readonly client: Client;
+    readonly transport: Transport;
+    readonly instructions: string | null;
+    /** False once the transport closed or the session ended; a dead generation is never reused. */
+    alive: boolean;
+};
+export type ConnectionOptions = {
+    readonly server: string;
+    readonly transport: McpTransportConfig;
+    /** The mount's lifetime: aborting it stops a stdio server's group. */
+    readonly lifetime: AbortSignal;
+    /** The live generation's server says its tools changed. */
+    readonly onToolsChanged: (generation: Generation) => void;
+    /** The live generation went away on its own. */
+    readonly onLost: (generation: Generation, reason: string) => void;
+};
+/**
+ * The transport, initialization and lifetime of one server's connection. Each successful
+ * initialization is a new generation; whoever holds one can tell whether it is still the live one.
+ * The client declares no capabilities, so the server can ask it for nothing: no sampling,
+ * elicitation or roots.
+ */
+export declare class McpConnection {
+    private live;
+    private count;
+    private disposed;
+    private readonly options;
+    constructor(options: ConnectionOptions);
+    /** The live generation, if there is one. */
+    get current(): Generation | null;
+    /**
+     * Connects and initializes a new generation, which becomes the live one. `signal` bounds the whole
+     * opening: creating the transport (a custom factory gets the signal), starting it, `initialize` and
+     * the `initialized` notification. The SDK bounds only `initialize`; the rest could wait for ever.
+     * On expiry the client is closed, which closes the transport and deletes an HTTP session the server
+     * already granted (`closeOnce`); a factory that answers after that has its result closed.
+     */
+    open(signal: AbortSignal, timeoutMs: number): Promise<Generation>;
+    /** Ends a generation the server no longer recognizes, such as a session it answered 404 for. */
+    invalidate(generation: Generation): Promise<void>;
+    /** Ends the live generation: closing shuts a stdio server down and deletes an HTTP session (`closeOnce`). */
+    dispose(): Promise<void>;
+    private createTransport;
+    private describeClose;
+}
+/** Whether an error is the HTTP 404 a server answers for a session it ended. */
+export declare const isSessionGone: (error: unknown) => boolean;

package/dist/plugins/mcp/errors.d.ts

@@ -0,0 +1,32 @@
+/**
+ * What an `mcp` mount reports. A rejected mount throws one, and every `ctx.reportError` raises one,
+ * so a host filters them from Cordis `internal/error` by class and `kind`. Named apart from the
+ * SDK's own `McpError`, which is a protocol error.
+ */
+export type McpServerErrorKind = 
+/** A mount or reconnection that could not connect or initialize. */
+'connect'
+/** A listing that failed; the last complete catalog stays published. */
+ | 'refresh'
+/** Tools left out, each with its reason. */
+ | 'unexposable'
+/** A connection that went away. */
+ | 'disconnect';
+/** A remote tool that cannot be exposed, and why. */
+export type UnexposableTool = {
+    readonly tool: string;
+    readonly reason: string;
+};
+export declare class McpServerError extends Error {
+    readonly name = "McpServerError";
+    readonly server: string;
+    readonly kind: McpServerErrorKind;
+    /** Set for `unexposable`. */
+    readonly tools: readonly UnexposableTool[];
+    constructor(server: string, kind: McpServerErrorKind, message: string, options?: {
+        cause?: unknown;
+        tools?: readonly UnexposableTool[];
+    });
+}
+/** A reason in one line, for messages and results. */
+export declare const describeError: (error: unknown) => string;

package/dist/plugins/mcp/index.d.ts

@@ -0,0 +1,33 @@
+import { type Plugin } from '@leuduan/cordis';
+import { type McpConfigInput } from './config.js';
+export { MAX_SERVER_NAME_LENGTH, McpConfigSchema, McpTransportSchema } from './config.js';
+export type { McpConfig, McpConfigInput, McpTransportConfig, McpTransportFactory } from './config.js';
+export { McpServerError } from './errors.js';
+export type { McpServerErrorKind, UnexposableTool } from './errors.js';
+export { MAX_TOOL_NAME_LENGTH, mcpToolName } from './names.js';
+export { CALL_META_KEY, SESSION_RESET_NOTE } from './tools.js';
+/**
+ * Connects to one MCP server and exposes its tools as ordinary lagent tools named
+ * `mcp__<server>__<tool>`, granted to `agents`. One mount is one server: a server that cannot be
+ * reached, or a tool listed in `tools` that cannot be exposed, rejects the mount with an
+ * `McpServerError` and leaves nothing registered. Tools found by discovery that cannot be exposed,
+ * a refresh that fails and a connection that goes away are reported through `ctx.reportError`.
+ *
+ * The plugin mounts no service, so the same mount works on the root, where one connection serves
+ * every thread, through `thread.ctx`, or inside a host preset. A failed mount stays in its owner's
+ * tree: an optional server is disposed when it fails, or a thread activation never becomes ready.
+ *
+ * ```ts
+ * await root.plugin(mcp, {
+ *   name: 'docs',
+ *   transport: { kind: 'stdio', command: ['node', 'server.js'], cwd: '/srv/docs', env: { PATH: '/usr/bin' } },
+ *   agents: ['main'],
+ *   confirm: 'all',
+ *   onInterrupted: 'report',
+ *   maxConcurrentCalls: 1,
+ * })
+ * ```
+ *
+ * The design and its reasons are in `docs/records/mcp.md`.
+ */
+export declare const mcp: Plugin.Object<McpConfigInput>;

package/dist/plugins/mcp/index.js

@@ -0,0 +1,5 @@
+import{a as Y}from"../../chunks/ASSQZH3F.js";import{a as N,c as H}from"../../chunks/7LI64H5X.js";import{a as w}from"../../chunks/PUSUPTAT.js";import{a as v}from"../../chunks/34KW6VNQ.js";import"../../chunks/DDZ7YF26.js";import{b as z}from"../../chunks/EPYQ5M3B.js";import{b as B,c as W}from"../../chunks/JFX2MXBA.js";import"../../chunks/6FRNHMCV.js";import{c as U}from"../../chunks/CUK7CGC7.js";import"../../chunks/BPRCULZH.js";import"../../chunks/FJLU4UH3.js";import"../../chunks/DDANMY45.js";import{c as g}from"../../chunks/BBCW2FZK.js";import"../../chunks/MMNNZCBO.js";import"../../chunks/G44LG6VL.js";import{h as A}from"../../chunks/D4PQP5MA.js";import{scopeOf as Fe}from"@leuduan/cordis";import{z as c}from"zod";var S=64,Z=/^(?!.*__)[A-Za-z0-9](?:[A-Za-z0-9_-]*[A-Za-z0-9-])?$/,V=/^[A-Za-z0-9_-]+$/,me=n=>n.replace(/[^A-Za-z0-9_-]/g,"_"),O=(n,e,t)=>`mcp__${n}__${t??me(e)}`;var D=24,pe=c.strictObject({kind:c.literal("stdio"),command:c.tuple([c.string().min(1)],c.string()),cwd:c.string().min(1),env:c.record(c.string(),c.string())}),fe=c.strictObject({kind:c.literal("streamable-http"),url:c.url({protocol:/^https?$/,error:"url must be an http or https URL"}),headers:c.record(c.string(),c.string()).default({})}),ge=c.strictObject({kind:c.literal("custom"),create:c.custom(n=>typeof n=="function","create must be a function")}),X=c.discriminatedUnion("kind",[pe,fe,ge]),we=c.union([c.string().min(1),c.strictObject({name:c.string().min(1),as:c.string().regex(V,"as must use A-Z a-z 0-9 _ -")})]),P=n=>c.number().positive().finite().default(n),k=c.strictObject({name:c.string().max(D).regex(Z,"name must use A-Z a-z 0-9 _ -, start with a letter or digit, never end with _, and never contain __"),transport:X,agents:U,confirm:c.union([c.literal("all"),c.literal("none"),c.strictObject({except:c.array(c.string())})]),onInterrupted:c.union([c.literal("report"),c.literal("annotations"),c.strictObject({rerun:c.array(c.string())})]),maxConcurrentCalls:c.union([c.number().int().positive(),c.literal("unbounded")]),tools:c.array(we).optional(),instructions:c.boolean().default(!1),connectTimeoutSeconds:P(30),callTimeoutSeconds:P(120),maxCallSeconds:P(600),maxContentBytes:c.number().int().nonnegative().default(1024*1024),signal:c.custom(n=>n instanceof AbortSignal,"signal must be an AbortSignal").optional()}).superRefine((n,e)=>{if(n.maxCallSeconds<n.callTimeoutSeconds&&e.addIssue({code:"custom",path:["maxCallSeconds"],message:"must be at least callTimeoutSeconds"}),n.tools===void 0)return;let t=n.tools.map(s=>typeof s=="string"?s:s.name),r=t.find((s,a)=>t.indexOf(s)!==a);if(r!==void 0&&e.addIssue({code:"custom",path:["tools"],message:`lists ${r} more than once`}),typeof n.confirm=="object")for(let s of n.confirm.except)t.includes(s)||e.addIssue({code:"custom",path:["confirm","except"],message:`${s} is not in tools`});if(typeof n.onInterrupted=="object")for(let s of n.onInterrupted.rerun)t.includes(s)||e.addIssue({code:"custom",path:["onInterrupted","rerun"],message:`${s} is not in tools`})});import{ListToolsResultSchema as be}from"@modelcontextprotocol/sdk/types.js";var K={entries:new Map,unexposable:[]};async function Q(n,e){let t=[],r=new Set,s;do{let a=await n.request({method:"tools/list",params:s===void 0?{}:{cursor:s}},be,{signal:e});if(t.push(...a.tools),s=a.nextCursor,s!==void 0){if(r.has(s))throw new Error(`the server repeated the pagination cursor ${s}`);r.add(s)}}while(s!==void 0);return t}function ee(n,e){let t=n.tools===void 0?void 0:new Map(n.tools.map(o=>typeof o=="string"?[o,void 0]:[o.name,o.as])),r=[],s=[];for(let o of e){if(t!==void 0&&!t.has(o.name))continue;let u=O(n.name,o.name,t?.get(o.name));s.push({remote:o,name:u,problem:ve(o,u)})}if(t!==void 0){let o=new Set(e.map(u=>u.name));for(let u of t.keys())o.has(u)||r.push({tool:u,reason:"the server does not offer it"})}let a=new Map;for(let o of s)a.set(o.name,[...a.get(o.name)??[],o]);let i=new Map;for(let o of s){let u=a.get(o.name);if(u.length>1){let p=u.filter(l=>l!==o).map(l=>l.remote.name);r.push({tool:o.remote.name,reason:`${o.name} collides with ${p.join(", ")}`});continue}if(o.problem!==null){r.push({tool:o.remote.name,reason:o.problem});continue}i.set(o.name,{name:o.name,remoteName:o.remote.name,definition:o.remote,spec:A.parse(te(o.remote,o.name)),fingerprint:g(o.remote)})}return{entries:i,unexposable:L(r)}}var J=(n,e)=>n<e?-1:n>e?1:0,te=(n,e)=>({name:e,description:n.description??n.title??"",input_schema:n.inputSchema});function ve(n,e){return e.length>64?`${e} is ${e.length} characters, over the ${64} a tool name may have`:n.execution?.taskSupport==="required"?"it requires task-augmented execution":A.safeParse(te(n,e)).success?null:"its input schema is not an object schema"}var L=n=>[...n].sort((e,t)=>J(e.tool,t.tool)||J(e.reason,t.reason)),ne=(n,e)=>g(n)===g(e);import{Client as Ee}from"@modelcontextprotocol/sdk/client/index.js";import{StreamableHTTPClientTransport as oe,StreamableHTTPError as _e}from"@modelcontextprotocol/sdk/client/streamableHttp.js";import{ToolListChangedNotificationSchema as Me}from"@modelcontextprotocol/sdk/types.js";import Te from"@leuduan/lagent/package.json"with{type:"json"};function re(){return Te.version}import{ReadBuffer as xe,serializeMessage as Se}from"@modelcontextprotocol/sdk/shared/stdio.js";var ye=8*1024,b=class{onclose;onerror;onmessage;spawned=null;buffer=new xe;stderr="";exit=null;closed=!1;closedEarly=!1;options;constructor(e){this.options=e}get pid(){return this.spawned?.pid}get stderrTail(){return this.stderr}get exited(){return this.exit}async start(){if(this.spawned!==null)throw new Error("ContainedStdioTransport already started");let e=await H({command:this.options.command,cwd:this.options.cwd,env:this.options.env,signal:this.options.signal,killGraceMs:this.options.killGraceMs??N,stdio:"pipes"});if(this.spawned=e,this.closedEarly)throw await e.stop(),new Error("ContainedStdioTransport closed while starting");e.stdout.on("data",t=>this.receive(t)),e.stderr.setEncoding("utf8"),e.stderr.on("data",t=>{this.stderr=(this.stderr+t).slice(-ye),w.debug("MCP server '%s' stderr: %s",this.options.server,t.trimEnd())}),e.stdin.on("error",t=>this.onerror?.(t)),e.result.then(t=>{this.exit=t,this.closed=!0,this.onclose?.()})}receive(e){try{this.buffer.append(e)}catch(t){this.onerror?.(t instanceof Error?t:new Error(String(t)));return}for(;;){let t;try{t=this.buffer.readMessage()}catch(r){this.onerror?.(r instanceof Error?r:new Error(String(r)));continue}if(t===null)return;this.onmessage?.(t)}}async send(e){let t=this.spawned?.stdin;if(t===void 0||this.closed||t.destroyed)throw new Error("The MCP server is not running");t.write(Se(e))||await new Promise((r,s)=>{let a=()=>{t.off("close",i),r()},i=()=>{t.off("drain",a),s(new Error("The MCP server closed its input"))};t.once("drain",a),t.once("close",i)})}async close(){let e=this.spawned;if(e===null){this.closedEarly=!0;return}e.stdin.end();let t=this.options.killGraceMs??N,r,s=await Promise.race([e.result.then(()=>!0),new Promise(a=>r=setTimeout(()=>a(!1),t))]);clearTimeout(r),s?await e.result:await e.stop()}};var $e=5e3,y=class{live=null;count=0;disposed=!1;options;constructor(e){this.options=e}get current(){return this.live?.alive?this.live:null}async open(e,t){if(this.disposed)throw new Error("the mount is disposed");e.throwIfAborted();let r=new Ee({name:"lagent",version:re()},{capabilities:{}}),s={alive:!0},a={transport:null},i=null;r.onerror=l=>w.debug("MCP server '%s': %s",this.options.server,l),r.onclose=()=>{s.alive&&(s.alive=!1,i!==null&&(i.alive=!1),i!==null&&a.transport!==null&&!this.disposed&&this.options.onLost(i,this.describeClose(a.transport)))};let o=!1;r.setNotificationHandler(Me,async()=>{i===null?o=!0:i===this.current&&this.options.onToolsChanged(i)});let u=(async()=>{let l=Ce(await this.createTransport(e));if(a.transport=l,e.aborted)throw await T(l.close()),e.reason;await r.connect(l,{signal:e,timeout:t})})();try{if(await v(u,e),e.throwIfAborted(),this.disposed)throw new Error("the mount is disposed")}catch(l){throw s.alive=!1,await T(r.close()),se(l,a.transport)}let p=a.transport;if(i={number:this.count+1,client:r,transport:p,instructions:r.getInstructions()??null,get alive(){return s.alive},set alive(l){s.alive=l}},!s.alive)throw se(new Error("the connection closed during initialization"),p);return this.count=i.number,this.live=i,o&&this.options.onToolsChanged(i),i}async invalidate(e){e.alive&&(e.alive=!1,await T(e.client.close()))}async dispose(){this.disposed=!0;let e=this.live;this.live=null,!(e===null||!e.alive)&&(e.alive=!1,await T(e.client.close()))}async createTransport(e){let t=this.options.transport;switch(t.kind){case"stdio":return new b({server:this.options.server,command:t.command,cwd:t.cwd,env:t.env,signal:this.options.lifetime});case"streamable-http":return new oe(new URL(t.url),{requestInit:{headers:t.headers}});case"custom":return await t.create(e)}}describeClose(e){if(!(e instanceof b))return"the connection closed";let t=e.exited,r=t===null?"its connection closed":t.exitCode!==null?`it exited with code ${t.exitCode}`:`it was ended by ${t.exitSignal??"a signal"}`;return ae(`the server process ended: ${r}`,e)}},ie=n=>n instanceof _e&&n.code===404;function Ce(n){let e=n.close.bind(n),t;return n.close=()=>t??=(async()=>{try{n instanceof oe&&await T(n.terminateSession()),await e()}catch(r){w.debug("MCP transport close failed: %s",r)}})(),n}async function T(n){let e;await Promise.race([n.catch(t=>w.debug("MCP cleanup failed: %s",t)),new Promise(t=>e=setTimeout(t,$e))]),clearTimeout(e)}function ae(n,e){let t=e instanceof b?e.stderrTail.trim():"";return t?`${n}; its stderr ended with:
+${t}`:n}function se(n,e){let t=n instanceof Error?n:new Error(String(n)),r=e===null?t.message:ae(t.message||t.name,e);return r===t.message?t:new Error(r,{cause:t})}var h=class extends Error{name="McpServerError";server;kind;tools;constructor(e,t,r,s={}){super(`MCP server '${e}': ${r}`,s.cause===void 0?{}:{cause:s.cause}),this.server=e,this.kind=t,this.tools=s.tools??[]}},f=n=>n instanceof Error?n.message||n.name:String(n);var E=class{active=0;waiters=[];limit;constructor(e){this.limit=e}acquire(e){return e.throwIfAborted(),this.active<this.limit?(this.active+=1,Promise.resolve(this.releaser())):new Promise((t,r)=>{let s={grant:()=>{e.removeEventListener("abort",a),this.active+=1,t(this.releaser())}},a=()=>{let i=this.waiters.indexOf(s);i>=0&&this.waiters.splice(i,1),r(e.reason)};e.addEventListener("abort",a,{once:!0}),this.waiters.push(s)})}get waiting(){return this.waiters.length}releaser(){let e=!1;return()=>{e||(e=!0,this.active-=1,this.waiters.shift()?.grant())}}};import{CallToolResultSchema as Re,ErrorCode as le,McpError as I}from"@modelcontextprotocol/sdk/types.js";var Ae="The tool returned content addressed to the user only; nothing in it is for you.",Ne="The tool returned no content.",Oe=new Set(["image/png","image/jpeg","image/webp","image/gif"]),Pe=n=>{let e=n.trim().toLowerCase();return e==="image/jpg"?"image/jpeg":e};function ce(n,e){let t=[],r=[],s=[],a=[],i=e.maxContentBytes,o=l=>l>i?!1:(i-=l,!0);for(let l of n.content){if(!ke(l)){s.push(Le(l,o));continue}switch(l.type){case"text":a.push(l.text),t.push(l.text);break;case"image":{let m=_(l.data),d=Pe(l.mimeType);Oe.has(d)?o(m)?(r.push({type:"image",url:null,data:l.data,media_type:d,detail:"auto"}),t.push(`[image: ${d}, ${x(m)}]`)):t.push(`[image omitted: ${l.mimeType}, ${x(m)}, over this result's limit]`):t.push(`[image not shown: ${l.mimeType}, ${x(m)}; only PNG, JPEG, WebP and GIF are shown]`);break}case"audio":t.push(`[audio not shown: ${l.mimeType}, ${x(_(l.data))}]`);break;case"resource_link":t.push(`[resource link: ${l.name} <${l.uri}>${l.mimeType?` (${l.mimeType})`:""}]`);break;case"resource":{let m=l.resource;if("text"in m)t.push(`[resource: ${m.uri}]
+${m.text}`);else{let d=m.mimeType?`${m.mimeType}, `:"";t.push(`[resource not shown: ${m.uri}, ${d}${x(_(m.blob))}]`)}break}}}let u=n.structuredContent;return u!==void 0&&!a.some(l=>Ie(l,u))&&t.push(JSON.stringify(u,null,2)),{output:t.join(`
+`)||(s.length>0?Ae:Ne),...r.length>0?{content:r}:{},is_error:n.isError===!0,notes:null,metadata:{mcp_server:e.server,mcp_tool:e.remoteName,...s.length>0?{user_content:s}:{}}}}function ke(n){let e=n.annotations?.audience;return e===void 0||e.includes("assistant")}function Le(n,e){let t=(r,s)=>{let a=_(r);return e(a)?{...s,data:r}:{...s,bytes:a,omitted:!0}};switch(n.type){case"text":return{type:"text",text:n.text};case"image":case"audio":return t(n.data,{type:n.type,mime_type:n.mimeType});case"resource_link":return{type:"resource_link",uri:n.uri,name:n.name,mime_type:n.mimeType??null};case"resource":return"text"in n.resource?{type:"resource",uri:n.resource.uri,text:n.resource.text}:t(n.resource.blob,{type:"resource",uri:n.resource.uri,mime_type:n.resource.mimeType??null})}}function Ie(n,e){try{return g(JSON.parse(n))===g(e)}catch{return!1}}function _(n){let e=n.endsWith("==")?2:n.endsWith("=")?1:0;return Math.max(0,Math.floor(n.length*3/4)-e)}function x(n){return n<1024?`${n} B`:n<1024*1024?`${(n/1024).toFixed(1)} KB`:`${(n/(1024*1024)).toFixed(1)} MB`}var ue="work.leuduan.lagent/call",R="The connection to this MCP server was re-established; any session state the server held may have been reset.";function je(n,e){if(n==="report")return"report";if(n==="annotations"){let t=e.definition.annotations;return t?.readOnlyHint===!0||t?.idempotentHint===!0?"rerun":"report"}return n.rerun.includes(e.remoteName)?"rerun":"report"}var de=(n,e)=>B({name:e.name,description:e.spec.description,parameters:{jsonSchema:e.spec.input_schema},onInterrupted:je(n.config.onInterrupted,e),executionMode:"parallel",execute:(t,r)=>Ge(n,e,t,r)});async function Ge(n,e,t,r){let s=d=>({output:d,is_error:!0,metadata:{mcp_server:n.server,mcp_tool:e.remoteName}}),{maxCallSeconds:a,callTimeoutSeconds:i,maxContentBytes:o}=n.config,u=AbortSignal.timeout(a*1e3),p=AbortSignal.any([r.signal,u]),l=d=>s(r.signal.aborted?`The call was cancelled ${d}; it was never sent to the MCP server.`:`The call's ${a} s deadline passed ${d}; it was never sent to the MCP server.`),m;try{m=await n.slots.acquire(p)}catch{return l("while it waited for a free slot")}try{let d;try{d=await n.ready(p)}catch(C){return p.aborted?l("while the connection was being re-established"):s(`The call was not sent. ${f(C)}`)}let $=n.entry(e.name);if($===void 0||$.fingerprint!==e.fingerprint)return s($===void 0?`The MCP server no longer offers ${e.remoteName}, so the call was not sent.`:`The MCP server changed the definition of ${e.remoteName}, so the call was not sent. Review the new definition and call again if it still fits.`);if(!d.alive)return s("The connection to the MCP server closed before the call was sent.");let G;try{G=await d.client.request({method:"tools/call",params:{name:e.remoteName,arguments:t,_meta:{[ue]:`${r.threadId}#${r.callSeq}`}}},Re,{signal:p,timeout:i*1e3,resetTimeoutOnProgress:!0,onprogress:()=>{}})}catch(C){return s(qe(n,C,d,r.signal,u))}let q=ce(G,{server:n.server,remoteName:e.remoteName,maxContentBytes:o}),F=n.takeSessionNote(d);return F===null?q:{...q,notes:[F]}}finally{m()}}function qe(n,e,t,r,s){let a="The server may or may not have run it.";return r.aborted?`The call was cancelled after it was sent. ${a}`:s.aborted?`The call's ${n.config.maxCallSeconds} s deadline passed after it was sent. ${a}`:ie(e)?(n.invalidate(t),"The MCP server had ended its session, so the call did not run. A new session opens with the next call."):e instanceof I&&e.code===le.RequestTimeout?`The MCP server sent no response or progress for ${n.config.callTimeoutSeconds} s. ${a}`:e instanceof I&&e.code===le.ConnectionClosed?`The connection to the MCP server was lost while the call was in flight. ${a}`:e instanceof I?`The MCP server answered with an error: ${f(e)}`:`The request to the MCP server failed: ${f(e)}. ${a}`}var M=class{server;slots;connection;lifetime=new AbortController;catalog=K;listedFrom=null;published=new Map;known=new Map;reported=[];started=!1;changedWhileStarting=!1;runningFor=null;disposed=!1;running=null;queued=null;reconnecting=null;noteOwedTo=null;cachedInstructions=null;ctx;config;constructor(e,t){this.ctx=e,this.config=t,this.server=t.name,this.slots=new E(t.maxConcurrentCalls==="unbounded"?1/0:t.maxConcurrentCalls),this.connection=new y({server:t.name,transport:t.transport,lifetime:this.lifetime.signal,onToolsChanged:()=>{this.started?this.refresh():this.changedWhileStarting=!0},onLost:(r,s)=>this.report(new h(this.server,"disconnect",s))})}get connectTimeoutMs(){return this.config.connectTimeoutSeconds*1e3}async start(){let e=[this.lifetime.signal,AbortSignal.timeout(this.connectTimeoutMs)];this.config.signal!==void 0&&e.push(this.config.signal);let t=AbortSignal.any(e);try{let s=await this.connection.open(t,this.connectTimeoutMs);this.cachedInstructions=s.instructions}catch(s){throw new h(this.server,"connect",`could not connect: ${f(s)}`,{cause:s})}let r=await this.refresh(t);if(!r.ok)throw r.error;this.started=!0,this.changedWhileStarting&&this.refresh()}async ready(e){let t=this.connection.current;if(t===null){if(this.disposed)throw new Error("the mount is disposed");this.reconnecting??=this.reconnect().finally(()=>{this.reconnecting=null}),t=await v(this.reconnecting,e)}if(this.listedFrom!==t.number){let r=this.running!==null&&this.runningFor===t?this.running:this.refresh(),s=await v(r,e);if(!s.ok)throw s.error;if(this.listedFrom!==t.number||!t.alive)throw new h(this.server,"refresh","the connection changed while its tools were being listed")}return t}async reconnect(){let e;try{let t=AbortSignal.any([this.lifetime.signal,AbortSignal.timeout(this.connectTimeoutMs)]);e=await this.connection.open(t,this.connectTimeoutMs)}catch(t){let r=new h(this.server,"connect",`could not reconnect: ${f(t)}`,{cause:t});throw this.report(r),r}return this.cachedInstructions=e.instructions,this.noteOwedTo=e.number,e}entry(e){return this.catalog.entries.get(e)}takeSessionNote(e){return this.noteOwedTo!==e.number?null:(this.noteOwedTo=null,R)}invalidate(e){e.alive&&(this.report(new h(this.server,"disconnect","the server ended its session")),this.connection.invalidate(e))}remoteNameOf(e){return this.known.get(e)}get instructions(){return this.cachedInstructions}refresh(e){return this.queued!==null?this.queued:this.running===null?this.run(e):(this.queued=this.running.then(()=>(this.queued=null,this.run())),this.queued)}run(e){let t=this.refreshOnce(e);return this.running=t,this.runningFor=this.connection.current,t.finally(()=>{this.running===t&&(this.running=null,this.runningFor=null)}),t}async refreshOnce(e){try{return await this.listAndPublish(e)}catch(t){let r=new h(this.server,"refresh",`could not publish its tools: ${f(t)}`,{cause:t});return this.report(r),{ok:!1,error:r}}}async listAndPublish(e){let t=this.connection.current;if(t===null)return{ok:!1,error:new h(this.server,"refresh","not connected")};let r;try{let o=e??AbortSignal.any([this.lifetime.signal,AbortSignal.timeout(this.connectTimeoutMs)]);r=ee(this.config,await Q(t.client,o))}catch(o){let u=new h(this.server,"refresh",`could not list its tools: ${f(o)}`,{cause:o});return this.started&&this.live(t)&&this.report(u),{ok:!1,error:u}}if(!this.live(t))return{ok:!1,error:new h(this.server,"refresh","the listing is out of date")};if(this.config.tools!==void 0&&r.unexposable.length>0&&!this.started)return{ok:!1,error:new h(this.server,"unexposable",j(r.unexposable),{tools:r.unexposable})};let a=this.publish(r),i=this.catalog.unexposable;return a.length>0&&this.config.tools!==void 0&&!this.started?{ok:!1,error:new h(this.server,"unexposable",j(i),{tools:i})}:(this.listedFrom=t.number,ne(i,this.reported)||(this.reported=i,i.length>0&&this.report(new h(this.server,"unexposable",j(i),{tools:i}))),{ok:!0})}live(e){return!this.disposed&&this.ctx.fiber.uid!==null&&e===this.connection.current}publish(e){let t=[];for(let[i,o]of this.published)e.entries.get(i)?.fingerprint!==o.entry.fingerprint&&(this.published.delete(i),o.withdraw());let r=this.ctx,s=this.config.agents;for(let i of e.entries.values()){if(this.published.has(i.name))continue;let o;try{o=W(r,de(this,i),{agents:s})}catch(u){t.push({tool:i.remoteName,reason:`${i.name} cannot be registered: ${f(u)}`});continue}this.published.set(i.name,{entry:i,withdraw:o}),this.known.set(i.name,i.remoteName)}let a=new Map([...e.entries].filter(([i])=>this.published.has(i)));return this.catalog={entries:a,unexposable:L([...e.unexposable,...t])},t}report(e){this.disposed||this.ctx.fiber.uid===null||this.ctx.reportError(e)}async dispose(){this.disposed=!0,await this.connection.dispose(),this.lifetime.abort()}},j=n=>`cannot expose ${n.map(e=>`${e.tool} (${e.reason})`).join("; ")}`;var he=new WeakMap;function Ue(n,e){let t=Fe(n),r=he.get(n.tools);r===void 0&&he.set(n.tools,r=new Map);let s=r.get(t);if(s===void 0&&r.set(t,s=new Set),s.has(e))throw new Error(`Another mcp mount in this layer already uses the server name '${e}'`);let a=s;n.effect(()=>(a.add(e),()=>a.delete(e)))}function He(n,e){if(n.confirm==="all")return"confirm";if(n.confirm!=="none")return n.confirm.except.includes(e)?void 0:"confirm"}var Rt={name:"lagent:mcp",inject:["tools","prompts"],async apply(n,e){let t=k.parse(e);Ue(n,t.name);let r=new M(n,t);n.effect(()=>()=>r.dispose()),await n.plugin(Y,{confirm:s=>{let a=r.remoteNameOf(s);return a!==void 0&&He(t,a)==="confirm"}}),t.instructions&&z(n,{tag:`mcp:${t.name}`,slot:"instruction",agents:t.agents,render:()=>{let s=r.instructions?.trim();return s?`Instructions from the MCP server "${t.name}" about its tools:
+${s}`:null}}),await r.start()}};export{ue as CALL_META_KEY,D as MAX_SERVER_NAME_LENGTH,S as MAX_TOOL_NAME_LENGTH,k as McpConfigSchema,h as McpServerError,X as McpTransportSchema,R as SESSION_RESET_NOTE,Rt as mcp,O as mcpToolName};

package/dist/plugins/mcp/mount.d.ts

@@ -0,0 +1,98 @@
+import type { Context } from '@leuduan/cordis';
+import { type CatalogEntry } from './catalog.js';
+import type { McpConfig } from './config.js';
+import { type Generation } from './connection.js';
+import { McpServerError } from './errors.js';
+import { CallSlots } from './slots.js';
+import { type McpToolHost } from './tools.js';
+type RefreshOutcome = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly error: McpServerError;
+};
+/**
+ * One server's mount: its connection, its catalog, and the tools published from it.
+ *
+ * Refreshes are serialized: one runs at a time and at most one more waits, shared by everyone who
+ * asks meanwhile, so a burst of `list_changed` notifications never overlaps listings and the latest
+ * one wins. A refresh publishes only a complete listing, only for the generation it listed from,
+ * and only while the mount lives; a failed one keeps the last catalog. Reconnection is lazy and
+ * single-flight: the next call opens a new generation and refreshes before it is sent.
+ */
+export declare class McpMount implements McpToolHost {
+    readonly server: string;
+    readonly slots: CallSlots;
+    private readonly connection;
+    private readonly lifetime;
+    private catalog;
+    /** The generation the published catalog was listed from; calls never run against another's. */
+    private listedFrom;
+    private readonly published;
+    /** Every lagent name this mount ever published, with its remote name, for the confirmation vote. */
+    private readonly known;
+    private reported;
+    private started;
+    /** A `list_changed` arrived before the first listing finished, which may have missed it. */
+    private changedWhileStarting;
+    /** The generation the running refresh lists from, for a call to join instead of queueing another. */
+    private runningFor;
+    private disposed;
+    private running;
+    private queued;
+    private reconnecting;
+    /** The generation whose first result still owes the session-reset note. */
+    private noteOwedTo;
+    /** The instructions of the latest successful initialization, kept through an outage. */
+    private cachedInstructions;
+    private readonly ctx;
+    readonly config: McpConfig;
+    constructor(ctx: Context, config: McpConfig);
+    private get connectTimeoutMs();
+    /**
+     * Connects, lists every tool, and publishes them. Rejects, having published nothing, when the
+     * server cannot be reached or initialized, its listing fails, or a tool the host listed cannot be
+     * exposed.
+     */
+    start(): Promise<void>;
+    /**
+     * The live generation, with a catalog listed from it. A generation that went away is replaced
+     * once, single-flight; a catalog listed from another generation, after a reconnection whose
+     * listing failed, is listed again first. Either failing fails the call before it is sent.
+     */
+    ready(signal: AbortSignal): Promise<Generation>;
+    /** Opens a new generation. Listing its tools is `ready`'s, so a failed listing is retried by the next call. */
+    private reconnect;
+    entry(name: string): CatalogEntry | undefined;
+    takeSessionNote(generation: Generation): string | null;
+    invalidate(generation: Generation): void;
+    /** The remote name behind a lagent name this mount published at any time, for the confirmation vote. */
+    remoteNameOf(name: string): string | undefined;
+    /**
+     * The server's `initialize` instructions, from the latest successful initialization. Kept through
+     * an outage, so a prompt rendered while the server is unreachable still carries them.
+     */
+    get instructions(): string | null;
+    /**
+     * Lists again, serialized with every other refresh; the latest request always wins. `signal`
+     * bounds the listing when this call starts one; joining one already running or queued keeps its
+     * bound.
+     */
+    refresh(signal?: AbortSignal): Promise<RefreshOutcome>;
+    private run;
+    /** Never rejects: both callers, a notification and the queue, would leave a rejection unhandled. */
+    private refreshOnce;
+    private listAndPublish;
+    /** Whether `generation` is still the live one of a mount that has not been disposed. */
+    private live;
+    /**
+     * Replaces the published tools with `catalog`'s. Each tool is one `registerTool` effect holding its
+     * registration and its grant, so withdrawing it releases both. A name another tool in this layer
+     * already holds cannot be registered; that tool is returned as unexposable.
+     */
+    private publish;
+    private report;
+    /** Closes the connection; the published tools go with the mount's other effects. */
+    dispose(): Promise<void>;
+}
+export {};

package/dist/plugins/mcp/names.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Lagent names for MCP tools: `mcp__<server>__<tool>`. The MCP spec allows `A-Z a-z 0-9 _ - .` and
+ * up to 128 characters in a tool name; OpenAI function names allow `A-Z a-z 0-9 _ -` and at most 64.
+ * A remote name is mapped onto the narrower set, never truncated or hashed: the model, the journal
+ * and the policy lists all read it, so it must stay readable and identical across restarts.
+ */
+/** The longest tool name every supported provider accepts. */
+export declare const MAX_TOOL_NAME_LENGTH = 64;
+/**
+ * A server name: in the narrow set already, never containing `__`, and neither starting nor ending
+ * with `_`. The first `__` after `mcp__` then always ends the server name, so two servers can never
+ * map tools onto the same lagent name: `docs` with `_search` and `docs_` with `search` would both
+ * be `mcp__docs___search`.
+ */
+export declare const SERVER_NAME: RegExp;
+/** An alias for a tool segment, which must already be in the narrow set. */
+export declare const TOOL_SEGMENT: RegExp;
+/** The tool segment a remote name maps to: every character outside the narrow set becomes `_`. */
+export declare const toolSegment: (remoteName: string) => string;
+/**
+ * The lagent name of a server's tool, for a tool policy's lists and host UIs. `alias`
+ * replaces the tool segment only; the server prefix always applies, so an alias never lands on a
+ * builtin. The result may be longer than {@link MAX_TOOL_NAME_LENGTH}, which makes it unexposable.
+ */
+export declare const mcpToolName: (server: string, remoteName: string, alias?: string) => string;

package/dist/plugins/mcp/render.d.ts

@@ -0,0 +1,29 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { ToolResultPayload } from '../../records/toolResult.js';
+/** Said when nothing is left for the model because every item was addressed to the user. */
+export declare const USER_ONLY_OUTPUT = "The tool returned content addressed to the user only; nothing in it is for you.";
+export declare const EMPTY_OUTPUT = "The tool returned no content.";
+/**
+ * The image types every provider lagent supports accepts as input: OpenAI takes PNG, JPEG, WebP
+ * and non-animated GIF. A part in any other type would be refused, and since the journal keeps it,
+ * every later request in the thread would be refused with it.
+ */
+export declare const MODEL_IMAGE_TYPES: ReadonlySet<string>;
+/** A MIME type as a part stores it: lowercased, and the common `image/jpg` as `image/jpeg`. */
+export declare const imageMediaType: (mimeType: string) => string;
+export type RenderOptions = {
+    readonly server: string;
+    readonly remoteName: string;
+    /** The most decoded bytes of non-text content the result keeps, for the model and the host. */
+    readonly maxContentBytes: number;
+};
+/**
+ * Renders a `tools/call` result as lagent's text-first payload. `output` is the canonical text;
+ * images become content parts within the byte budget; items whose audience excludes the assistant
+ * go to `metadata` for hosts and never reach the model. A result is not checked against the tool's
+ * output schema.
+ */
+export declare function renderCallResult(result: CallToolResult, options: RenderOptions): ToolResultPayload;
+/** The size of base64 data once decoded. */
+export declare function decodedBytes(base64: string): number;
+export declare function formatBytes(bytes: number): string;

package/dist/plugins/mcp/slots.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The calls one server takes at once, in arrival order, shared by every thread its mount serves.
+ * A waiter whose signal aborts leaves the queue without ever holding a slot.
+ */
+export declare class CallSlots {
+    private active;
+    private readonly waiters;
+    private readonly limit;
+    constructor(limit: number);
+    /** Resolves with the slot's release; rejects with the signal's reason if it aborts first. */
+    acquire(signal: AbortSignal): Promise<() => void>;
+    /** Calls queued for a slot. */
+    get waiting(): number;
+    private releaser;
+}