@zeroroot-ai/gibson-mcp 0.1.0

package/dist/inbox.d.ts

@@ -0,0 +1,88 @@
+import type { TaskHarness } from "@zeroroot-ai/sdk";
+import type { Principal } from "@zeroroot-ai/sdk/gen/gibson/common/v1/gibson_common_pb.js";
+import type { Input } from "@zeroroot-ai/sdk/gen/gibson/job/v1/job_pb.js";
+import { InputKind, JobState } from "@zeroroot-ai/sdk/gen/gibson/job/v1/job_pb.js";
+import { type Log } from "./log.js";
+/**
+ * The member inbox (gibson#1706, decisions 6 and 11).
+ *
+ * Input to a long-lived member is one daemon-owned inbox, pulled outbound by
+ * the sandbox: the member subscribes and the daemon streams messages down
+ * it. The sandbox never accepts an inbound connection, so setec `Attach` is
+ * not used and no port is opened.
+ *
+ * The subscription is a lifetime RPC and runs under the base grant. Each
+ * message carries the grant of its own dispatch, which the driver then puts
+ * in force for that turn (see turn.ts).
+ */
+export { InputKind, JobState };
+/** One message from the inbox, flattened from `gibson.job.v1.Input`. */
+export interface JobInput {
+    id: string;
+    jobId: string;
+    message: string;
+    /** The task grant of the dispatch that sent this message. */
+    grant: string;
+    /** Who sent it, as `<kind>:<id>`: a person, an agent, a tool or a mission node. */
+    sender: string;
+    kind: InputKind;
+    /** Unix milliseconds, or 0 when the daemon sent no timestamp. */
+    sentAt: number;
+}
+export declare const MISSING_RPC: string;
+/** True when the harness client carries the inbox RPCs. */
+export declare function inboxAvailable(harness: TaskHarness): boolean;
+/** `<kind>:<id>`, e.g. `KIND_USER:u-1`. Empty when the daemon named nobody. */
+export declare function principalName(p: Principal | undefined): string;
+/** Flatten one wire `Input`. */
+export declare function toJobInput(input: Input | undefined): JobInput;
+export interface InboxOptions {
+    harness: TaskHarness;
+    log?: Log;
+    /** Backoff between reconnects, in ms. Doubles up to the cap. */
+    minBackoffMs?: number;
+    maxBackoffMs?: number;
+    signal?: AbortSignal;
+    /** Test seam. */
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare const MIN_BACKOFF_MS = 500;
+export declare const MAX_BACKOFF_MS = 30000;
+export interface Inbox {
+    /**
+     * Every message for this member, in order. Reconnects on its own, so a
+     * caller writes one `for await` and never handles a dropped stream.
+     */
+    messages(): AsyncIterable<JobInput>;
+    /** Send a message into a job. Returns the input the daemon recorded. */
+    send(jobId: string, message: string, kind: InputKind): Promise<JobInput>;
+    /** Tell the daemon a job moved to WORKING or WAITING. */
+    reportState(jobId: string, state: JobState, claudeSessionId?: string): Promise<void>;
+    /** Stop the subscription. */
+    stop(): void;
+}
+/**
+ * Subscribe to the inbox, reconnecting with backoff.
+ *
+ * A dropped stream is normal on a long-lived member: the daemon rolls, the
+ * edge recycles a connection. Reconnecting is the wrapper's job, because a
+ * driver that had to do it would either drop messages or stop pulling.
+ */
+export declare function openInbox(opts: InboxOptions): Inbox;
+/** Somewhere an answer can be delivered. {@link AnswerRouter} implements it. */
+export interface AnswerSink {
+    /** Take the message as an answer to an open question. */
+    offer(input: JobInput): boolean;
+}
+/**
+ * Read the inbox once and split it two ways.
+ *
+ * A message that answers an open `ask` belongs to that question, not to a
+ * new turn, so it is consumed here and never reaches the driver. Everything
+ * else is queued for the driver, which decides what turn it starts.
+ *
+ * The pump runs whether or not the driver is iterating. Waiting for the
+ * driver to pull would mean an answer only arrives once the driver asked for
+ * the next turn, and the turn cannot start until the question is answered.
+ */
+export declare function routeAnswers(inbox: Inbox, answers: AnswerSink, log?: Log): Inbox;

package/dist/inbox.js

@@ -0,0 +1,176 @@
+import { InputKind, JobState } from "@zeroroot-ai/sdk/gen/gibson/job/v1/job_pb.js";
+import { TAG } from "./log.js";
+/**
+ * The member inbox (gibson#1706, decisions 6 and 11).
+ *
+ * Input to a long-lived member is one daemon-owned inbox, pulled outbound by
+ * the sandbox: the member subscribes and the daemon streams messages down
+ * it. The sandbox never accepts an inbound connection, so setec `Attach` is
+ * not used and no port is opened.
+ *
+ * The subscription is a lifetime RPC and runs under the base grant. Each
+ * message carries the grant of its own dispatch, which the driver then puts
+ * in force for that turn (see turn.ts).
+ */
+export { InputKind, JobState };
+export const MISSING_RPC = "this daemon's harness has no SubscribeInput. The inbox RPCs ship with gibson.job.v1 " +
+    "(buf.build/zeroroot-ai/sdk v0.177.0); update the daemon.";
+/** True when the harness client carries the inbox RPCs. */
+export function inboxAvailable(harness) {
+    const client = harness.client;
+    return typeof client.subscribeInput === "function" && typeof client.sendInput === "function" && typeof client.reportJobState === "function";
+}
+function inboxClient(harness) {
+    if (!inboxAvailable(harness))
+        throw new Error(`gibson-mcp: ${MISSING_RPC}`);
+    return harness.client;
+}
+/** `<kind>:<id>`, e.g. `KIND_USER:u-1`. Empty when the daemon named nobody. */
+export function principalName(p) {
+    if (!p)
+        return "";
+    return `${p.kind}:${p.id}`;
+}
+/** Flatten one wire `Input`. */
+export function toJobInput(input) {
+    return {
+        id: input?.id ?? "",
+        jobId: input?.jobId ?? "",
+        message: input?.message ?? "",
+        grant: input?.grant ?? "",
+        sender: principalName(input?.sender),
+        kind: input?.kind ?? InputKind.UNSPECIFIED,
+        sentAt: input?.sentAt ? Number(input.sentAt.seconds) * 1000 : 0,
+    };
+}
+export const MIN_BACKOFF_MS = 500;
+export const MAX_BACKOFF_MS = 30_000;
+/**
+ * Subscribe to the inbox, reconnecting with backoff.
+ *
+ * A dropped stream is normal on a long-lived member: the daemon rolls, the
+ * edge recycles a connection. Reconnecting is the wrapper's job, because a
+ * driver that had to do it would either drop messages or stop pulling.
+ */
+export function openInbox(opts) {
+    const { harness } = opts;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms).unref?.()));
+    const minBackoff = opts.minBackoffMs ?? MIN_BACKOFF_MS;
+    const maxBackoff = opts.maxBackoffMs ?? MAX_BACKOFF_MS;
+    let stopped = false;
+    const controller = new AbortController();
+    opts.signal?.addEventListener("abort", () => controller.abort(), { once: true });
+    async function* messages() {
+        // Resolved once, outside the retry loop. A daemon with no SubscribeInput
+        // is a permanent condition, and retrying it every thirty seconds forever
+        // would bury the one line that says what is missing.
+        const client = inboxClient(harness);
+        let backoff = minBackoff;
+        while (!stopped && !controller.signal.aborted) {
+            try {
+                for await (const res of client.subscribeInput({ context: harness.context }, { signal: controller.signal })) {
+                    if (stopped)
+                        return;
+                    backoff = minBackoff; // a message proves the stream is healthy
+                    yield toJobInput(res.input);
+                }
+                // A clean end of stream is the daemon closing the subscription. Ask
+                // again after a pause rather than treating it as the end of the
+                // member's life.
+            }
+            catch (e) {
+                if (stopped || controller.signal.aborted)
+                    return;
+                opts.log?.(`${TAG} inbox: ${e.message}; reconnecting in ${backoff}ms`);
+            }
+            if (stopped || controller.signal.aborted)
+                return;
+            await sleep(backoff);
+            backoff = Math.min(maxBackoff, backoff * 2);
+        }
+    }
+    return {
+        messages,
+        send: async (jobId, message, kind) => {
+            const res = await inboxClient(harness).sendInput({ context: harness.context, jobId, message, kind });
+            if (res.error)
+                throw new Error(`SendInput refused: ${res.error.message}`);
+            return toJobInput(res.input);
+        },
+        reportState: async (jobId, state, claudeSessionId) => {
+            const res = await inboxClient(harness).reportJobState({ context: harness.context, jobId, state, claudeSessionId: claudeSessionId ?? "" });
+            if (res.error)
+                throw new Error(`ReportJobState refused: ${res.error.message}`);
+        },
+        stop: () => {
+            stopped = true;
+            controller.abort();
+        },
+    };
+}
+/**
+ * Read the inbox once and split it two ways.
+ *
+ * A message that answers an open `ask` belongs to that question, not to a
+ * new turn, so it is consumed here and never reaches the driver. Everything
+ * else is queued for the driver, which decides what turn it starts.
+ *
+ * The pump runs whether or not the driver is iterating. Waiting for the
+ * driver to pull would mean an answer only arrives once the driver asked for
+ * the next turn, and the turn cannot start until the question is answered.
+ */
+export function routeAnswers(inbox, answers, log) {
+    const queue = [];
+    const waiting = [];
+    let stopped = false;
+    const push = (input) => {
+        const next = waiting.shift();
+        if (next)
+            next(input);
+        else
+            queue.push(input);
+    };
+    void (async () => {
+        try {
+            for await (const input of inbox.messages()) {
+                if (stopped)
+                    return;
+                if (answers.offer(input))
+                    continue;
+                push(input);
+            }
+        }
+        catch (e) {
+            if (!stopped)
+                log?.(`${TAG} inbox pump stopped: ${e.message}`);
+        }
+    })();
+    async function* messages() {
+        while (!stopped) {
+            const first = queue.shift();
+            if (first) {
+                yield first;
+                continue;
+            }
+            const next = await new Promise((resolve) => {
+                waiting.push(resolve);
+                if (stopped)
+                    resolve(undefined);
+            });
+            if (!next)
+                return;
+            yield next;
+        }
+    }
+    return {
+        messages,
+        send: (jobId, message, kind) => inbox.send(jobId, message, kind),
+        reportState: (jobId, state, claudeSessionId) => inbox.reportState(jobId, state, claudeSessionId),
+        stop: () => {
+            stopped = true;
+            for (const resolve of waiting.splice(0))
+                resolve(undefined);
+            inbox.stop();
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+export { buildSurface, type BuildDeps, type Surface } from "./build.js";
+export { parseFlags, parseListen, usage, DEFAULT_LISTEN, DEFAULT_STREAM_LIMIT, type Flags, type Listen, type TransportKind } from "./flags.js";
+export { serveHttp, type HttpHandle, type HttpSurface, type TurnRoute } from "./http.js";
+export { createTurnController, dynamicTransport, TURN_GRANT_HEADER, type Turn, type TurnController } from "./turn.js";
+export { openInbox, routeAnswers, inboxAvailable, toJobInput, principalName, InputKind, JobState, MIN_BACKOFF_MS, MAX_BACKOFF_MS, type Inbox, type JobInput, type AnswerSink, } from "./inbox.js";
+export { askTool, decisionFrom, AnswerRouter, type AnswerSource, type PermissionDecision } from "./ask.js";
+export { attachServer, packageVersion, SERVER_NAME } from "./server.js";
+export { ToolRegistry, type JsonSchema, type ToolContext, type ToolDefinition, type ToolGroup, type ToolHandler } from "./registry.js";
+export { defineTool, jsonSchemaOf, type ToolSpec } from "./tool.js";
+export { openGibson, type Gibson, type OpenGibsonOptions } from "./session.js";
+export { rpcTools, snake, toolNameFor, transportFor, type RpcChannels, type RpcToolOptions } from "./rpc.js";
+export { messageSchema, requestSchema, MAX_DEPTH } from "./schema.js";
+export { startDiscovery, toolKey, pluginKey, DISCOVERY_INTERVAL_MS, type Discovery, type DiscoveryOutcome } from "./discovery.js";
+export { helperTools, helperToolsFor, helperContext, HELPER_TOOL_FOR_EXPORT, NOT_A_TOOL, TOOL_WITHOUT_EXPORT, type HelperContext } from "./helpers/index.js";
+export { GENERATED_SERVICES, GENERATED_RPC_COUNT } from "./generated/tools.js";
+export { decideSource, type CheckInSource, type SourceDecision, type SourceInputs } from "./source.js";
+export { decideMode, type Mode, type ModeDecision } from "./mode.js";
+export { loadSettings, readConfig, writeConfig, resolveSettings, DEFAULT_AGENT_NAME, type Settings, type ServerConfig } from "./config.js";
+export { stateDir, readAmbient, readLive, writeAmbient, writeLive, clearLive, type LiveState } from "./state.js";
+export { describeGibson } from "./tools/status.js";
+export { ambientPrompt, ambientSource, resources, sessionCoordinates, AMBIENT_URI, SESSION_URI, DEFAULT_AMBIENT_QUERY, type AmbientSource, type PromptDefinition, type ResourceDefinition, } from "./resources.js";
+export { ambientBlock } from "./ambient.js";
+export { text, failure, json } from "./tools/result.js";

package/dist/index.js

@@ -0,0 +1,25 @@
+// @zeroroot-ai/gibson-mcp: the Gibson MCP server as a library. The bin is
+// `gibson-mcp` (main.ts); a host adapter or a member driver embeds this.
+export { buildSurface } from "./build.js";
+export { parseFlags, parseListen, usage, DEFAULT_LISTEN, DEFAULT_STREAM_LIMIT } from "./flags.js";
+export { serveHttp } from "./http.js";
+export { createTurnController, dynamicTransport, TURN_GRANT_HEADER } from "./turn.js";
+export { openInbox, routeAnswers, inboxAvailable, toJobInput, principalName, InputKind, JobState, MIN_BACKOFF_MS, MAX_BACKOFF_MS, } from "./inbox.js";
+export { askTool, decisionFrom, AnswerRouter } from "./ask.js";
+export { attachServer, packageVersion, SERVER_NAME } from "./server.js";
+export { ToolRegistry } from "./registry.js";
+export { defineTool, jsonSchemaOf } from "./tool.js";
+export { openGibson } from "./session.js";
+export { rpcTools, snake, toolNameFor, transportFor } from "./rpc.js";
+export { messageSchema, requestSchema, MAX_DEPTH } from "./schema.js";
+export { startDiscovery, toolKey, pluginKey, DISCOVERY_INTERVAL_MS } from "./discovery.js";
+export { helperTools, helperToolsFor, helperContext, HELPER_TOOL_FOR_EXPORT, NOT_A_TOOL, TOOL_WITHOUT_EXPORT } from "./helpers/index.js";
+export { GENERATED_SERVICES, GENERATED_RPC_COUNT } from "./generated/tools.js";
+export { decideSource } from "./source.js";
+export { decideMode } from "./mode.js";
+export { loadSettings, readConfig, writeConfig, resolveSettings, DEFAULT_AGENT_NAME } from "./config.js";
+export { stateDir, readAmbient, readLive, writeAmbient, writeLive, clearLive } from "./state.js";
+export { describeGibson } from "./tools/status.js";
+export { ambientPrompt, ambientSource, resources, sessionCoordinates, AMBIENT_URI, SESSION_URI, DEFAULT_AMBIENT_QUERY, } from "./resources.js";
+export { ambientBlock } from "./ambient.js";
+export { text, failure, json } from "./tools/result.js";

package/dist/log.d.ts

@@ -0,0 +1,4 @@
+/** The server logs to stderr only: stdout is the stdio MCP channel. */
+export declare const TAG = "[gibson-mcp]";
+export type Log = (line: string) => void;
+export declare const log: Log;

package/dist/log.js

@@ -0,0 +1,5 @@
+/** The server logs to stderr only: stdout is the stdio MCP channel. */
+export const TAG = "[gibson-mcp]";
+export const log = (line) => {
+    process.stderr.write(`${line}\n`);
+};

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/main.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { buildSurface } from "./build.js";
+import { parseFlags, usage } from "./flags.js";
+import { serveHttp } from "./http.js";
+import { log, TAG } from "./log.js";
+import { packageVersion } from "./server.js";
+import { describeGibson } from "./tools/status.js";
+/**
+ * The bin. This file runs main() unconditionally: npm installs bins as
+ * symlinks named after the bin (`gibson-mcp`), so any "am I the entry point"
+ * check on argv[1] is false there and the process would exit before it
+ * serves anything. Library code lives in build.ts.
+ */
+async function main() {
+    let flags;
+    try {
+        flags = parseFlags(process.argv.slice(2));
+    }
+    catch (e) {
+        process.stderr.write(`${TAG} ${e.message}\n\n${usage()}\n`);
+        process.exit(2);
+    }
+    if (flags.help) {
+        process.stdout.write(`${usage()}\n`);
+        return;
+    }
+    if (flags.version) {
+        process.stdout.write(`${packageVersion()}\n`);
+        return;
+    }
+    const cwd = process.cwd();
+    const surface = await buildSurface(process.env, cwd, { streamLimit: flags.streamLimit });
+    log(`${TAG} ${describeGibson(surface.current()).replaceAll("\n", "; ")}`);
+    log(`${TAG} ${surface.registry.size()} tool(s) registered`);
+    let closing = false;
+    const close = async (extra) => {
+        if (closing)
+            return;
+        closing = true;
+        if (extra)
+            await extra().catch((e) => log(`${TAG} close: ${e.message}`));
+        await surface.close().catch((e) => log(`${TAG} close: ${e.message}`));
+    };
+    if (flags.transport === "stdio") {
+        // The host ends the session by closing stdio. The mission ends with it.
+        process.stdin.on("close", () => void close().finally(() => process.exit(0)));
+        for (const sig of ["SIGINT", "SIGTERM"])
+            process.on(sig, () => void close().finally(() => process.exit(0)));
+        await surface.attach(new StdioServerTransport());
+        return;
+    }
+    const http = await serveHttp(surface, flags.listen, log);
+    log(`${TAG} listening on ${http.url}${surface.turn ? `; POST ${http.url.replace(/\/mcp$/, "/turn")} sets the per-turn grant` : ""}`);
+    for (const sig of ["SIGINT", "SIGTERM"])
+        process.on(sig, () => void close(http.close).finally(() => process.exit(0)));
+}
+main().catch((e) => {
+    log(`${TAG} fatal: ${e.message}`);
+    process.exit(1);
+});

package/dist/mode.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Which posture this process runs in. Pure: decided from what the
+ * environment says and whether the host key exists, so it is testable and the
+ * reasons are printed once at start instead of discovered per tool call.
+ *
+ *  - `standalone`: no platform. Findings go to a local log, componentize works.
+ *  - `component`: checked in, no live mission. Reads and findings run under the
+ *    component grant. No memory writes: a memory is a World observation and
+ *    the World is written under a mission (gibson ADR-0012).
+ *  - `live`: checked in, and this session is a mission (gibson#1593, decision 9).
+ *  - `task`: a dispatched run (gibson ADR-0016). The launch injected the
+ *    per-dispatch grant; there is no check-in and no live mission to create,
+ *    the mission already exists and this run is one of its nodes. Reads and
+ *    writes use that grant.
+ *
+ * The postures are one path with fewer tools at each step down, the same
+ * fail-open shape as the opencode plugin: a coding agent that cannot reach its
+ * platform is still a working coding agent.
+ */
+export type Mode = "standalone" | "component" | "live" | "task";
+export interface ModeDecision {
+    mode: Mode;
+    /** One line a person can act on. Empty when nothing is missing. */
+    reason: string;
+}
+export interface ModeInputs {
+    platformURL?: string;
+    bootstrapToken?: string;
+    hostKeyExists: boolean;
+    targetId?: string;
+}
+export declare function decideMode(env: ModeInputs, hostKeyPath: string): ModeDecision;

package/dist/mode.js

@@ -0,0 +1,21 @@
+export function decideMode(env, hostKeyPath) {
+    if (!env.platformURL) {
+        return { mode: "standalone", reason: "GIBSON_PLATFORM_URL is not set. Call gibson_login, then gibson_connect." };
+    }
+    if (!env.hostKeyExists && !env.bootstrapToken) {
+        return {
+            mode: "standalone",
+            reason: "GIBSON_PLATFORM_URL is set but this host has not checked in. Call gibson_login then gibson_connect, " +
+                "or run `gibson login` and `gibson agent enroll` and start once with GIBSON_BOOTSTRAP_TOKEN=<one-time token>. " +
+                `After that the host key at ${hostKeyPath} is enough.`,
+        };
+    }
+    if (!env.targetId) {
+        return {
+            mode: "component",
+            reason: "GIBSON_TARGET_ID is not set, so this session cannot be a live mission and cannot " +
+                "write memories. Create a target once (`gibson target create`) and set GIBSON_TARGET_ID, or call gibson_connect with create_target.",
+        };
+    }
+    return { mode: "live", reason: "" };
+}

package/dist/registry.d.ts

@@ -0,0 +1,83 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+/** A JSON Schema object for a tool's input. MCP requires `type: "object"` at the top. */
+export interface JsonSchema {
+    type: "object";
+    [key: string]: unknown;
+}
+/** What a tool call carries besides its arguments. */
+export interface ToolContext {
+    /** Request headers of the transport, when it has any (the HTTP transport). */
+    headers?: Record<string, string | string[] | undefined>;
+    signal?: AbortSignal;
+}
+export type ToolHandler = (args: Record<string, unknown>, ctx: ToolContext) => Promise<CallToolResult>;
+/**
+ * Wraps every tool call. The per-turn grant uses one: it reads the request's
+ * headers and runs the call under that turn's credential, so a tool built
+ * once needs no knowledge of which grant is in force.
+ */
+export type ToolMiddleware = (ctx: ToolContext, next: () => Promise<CallToolResult>) => Promise<CallToolResult>;
+export interface ToolAnnotations {
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+    handler: ToolHandler;
+    annotations?: ToolAnnotations;
+}
+/**
+ * A set of tools that leaves together: one posture, discovery included. A
+ * tool registered through a group is dropped by `clear()`, so an upgrade
+ * cannot leave a tool behind that points at the previous connection.
+ */
+export interface ToolGroup {
+    register(def: ToolDefinition): void;
+    /** Remove one tool this group registered. */
+    remove(name: string): boolean;
+    /** Whether ANY tool holds this name, in this group or not. */
+    has(name: string): boolean;
+    /** Coalesce the changes inside `fn` into one notification. */
+    batch<T>(fn: () => T): T;
+    /** Remove every tool this group registered. */
+    clear(): void;
+    names(): string[];
+}
+/** MCP tool names: letters, digits, underscore, hyphen, at most 64 characters. */
+export declare const TOOL_NAME: RegExp;
+/**
+ * The one tool table every attached MCP server reads. A transport session
+ * gets its own protocol `Server`, and all of them list and call the same
+ * tools, so a posture change or a discovery pass reaches every session at
+ * once through `tools/list_changed`.
+ */
+export declare class ToolRegistry {
+    private readonly tools;
+    private readonly listeners;
+    private readonly middleware;
+    private batching;
+    private dirty;
+    register(def: ToolDefinition): void;
+    remove(name: string): boolean;
+    has(name: string): boolean;
+    get(name: string): ToolDefinition | undefined;
+    /** Every tool, sorted by name so a listing is stable. */
+    list(): ToolDefinition[];
+    size(): number;
+    /** Add a wrapper around every tool call. Applied in the order added. */
+    use(fn: ToolMiddleware): void;
+    call(name: string, args: Record<string, unknown>, ctx: ToolContext): Promise<CallToolResult>;
+    group(): ToolGroup;
+    /** Coalesce every change inside `fn` into one notification. */
+    batch<T>(fn: () => T): T;
+    /** Same as {@link batch}, for async work. */
+    batchAsync<T>(fn: () => Promise<T>): Promise<T>;
+    onChange(fn: () => void): () => void;
+    private changed;
+    private notify;
+}

package/dist/registry.js

@@ -0,0 +1,133 @@
+import { failure } from "./tools/result.js";
+/** MCP tool names: letters, digits, underscore, hyphen, at most 64 characters. */
+export const TOOL_NAME = /^[A-Za-z0-9_-]{1,64}$/;
+/**
+ * The one tool table every attached MCP server reads. A transport session
+ * gets its own protocol `Server`, and all of them list and call the same
+ * tools, so a posture change or a discovery pass reaches every session at
+ * once through `tools/list_changed`.
+ */
+export class ToolRegistry {
+    tools = new Map();
+    listeners = new Set();
+    middleware = [];
+    batching = 0;
+    dirty = false;
+    register(def) {
+        if (!TOOL_NAME.test(def.name))
+            throw new Error(`tool name ${JSON.stringify(def.name)} is not [A-Za-z0-9_-]{1,64}`);
+        if (this.tools.has(def.name))
+            throw new Error(`tool ${def.name} is already registered`);
+        if (!def.description.trim())
+            throw new Error(`tool ${def.name} has no description`);
+        this.tools.set(def.name, def);
+        this.changed();
+    }
+    remove(name) {
+        const had = this.tools.delete(name);
+        if (had)
+            this.changed();
+        return had;
+    }
+    has(name) {
+        return this.tools.has(name);
+    }
+    get(name) {
+        return this.tools.get(name);
+    }
+    /** Every tool, sorted by name so a listing is stable. */
+    list() {
+        return [...this.tools.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    }
+    size() {
+        return this.tools.size;
+    }
+    /** Add a wrapper around every tool call. Applied in the order added. */
+    use(fn) {
+        this.middleware.push(fn);
+    }
+    async call(name, args, ctx) {
+        const def = this.tools.get(name);
+        if (!def)
+            return failure("unknown tool", `No tool named ${name}. Call tools/list for the current set.`);
+        let run = () => def.handler(args, ctx);
+        for (let i = this.middleware.length - 1; i >= 0; i -= 1) {
+            const fn = this.middleware[i];
+            const inner = run;
+            run = () => fn(ctx, inner);
+        }
+        try {
+            return await run();
+        }
+        catch (e) {
+            return failure(`${name} failed`, e.message);
+        }
+    }
+    group() {
+        const names = new Set();
+        return {
+            register: (def) => {
+                this.register(def);
+                names.add(def.name);
+            },
+            remove: (name) => {
+                if (!names.delete(name))
+                    return false;
+                return this.remove(name);
+            },
+            has: (name) => this.has(name),
+            batch: (fn) => this.batch(fn),
+            clear: () => {
+                this.batch(() => {
+                    for (const n of names)
+                        this.remove(n);
+                    names.clear();
+                });
+            },
+            names: () => [...names],
+        };
+    }
+    /** Coalesce every change inside `fn` into one notification. */
+    batch(fn) {
+        this.batching += 1;
+        try {
+            return fn();
+        }
+        finally {
+            this.batching -= 1;
+            if (this.batching === 0 && this.dirty) {
+                this.dirty = false;
+                this.notify();
+            }
+        }
+    }
+    /** Same as {@link batch}, for async work. */
+    async batchAsync(fn) {
+        this.batching += 1;
+        try {
+            return await fn();
+        }
+        finally {
+            this.batching -= 1;
+            if (this.batching === 0 && this.dirty) {
+                this.dirty = false;
+                this.notify();
+            }
+        }
+    }
+    onChange(fn) {
+        this.listeners.add(fn);
+        return () => this.listeners.delete(fn);
+    }
+    changed() {
+        if (this.batching > 0) {
+            this.dirty = true;
+            return;
+        }
+        this.notify();
+    }
+    notify() {
+        for (const fn of this.listeners)
+            fn();
+    }
+}