agentfootprint 12.0.1 → 12.2.0

package/dist/esm/mcp/pool/boundTool.d.ts

@@ -0,0 +1,58 @@
+/**
+ * boundTool — a tool bound to its conversation, the list it came from and that
+ * list's generation, re-checked after every wait and at the send gate.
+ *
+ * Pattern: the shape every MCP tool takes (`mcpClient.ts` · `mcpToolShape`) +
+ *          one `execute` that runs the five steps of § 6.3.
+ * Role:    A bound tool carries its BINDING: the key it was listed for; the
+ *          context it was listed in (per client, the configuration; shared, the
+ *          entry's context); the list it came from (per client, the client
+ *          incarnation; shared, the entry); and that list's generation. Its
+ *          `execute`:
+ *
+ *   1. checks that the calling run's caller identity encodes to its key —
+ *      otherwise `identity-mismatch`, nothing sent;
+ *   2. checks its binding is current — otherwise `stale-tools`, nothing sent;
+ *   3. is admitted against `maxOperations` and takes a lease on its key's
+ *      client, opening one from a plan resolved now when the key has none. A
+ *      client whose plan's context differs from the binding's refuses with
+ *      `binding-changed` (the client stays for the next list). A client that is
+ *      not the incarnation the tool was listed from is checked against its OWN
+ *      fresh list — the call goes on only if that list holds the same
+ *      definition, compared as canonical JSON; otherwise `stale-tools`. Under
+ *      the app's sharing contract, a replacement whose context matches uses the
+ *      shared entry as it stands;
+ *   4. after every wait, checks step 2 again — and asks the app's `share`
+ *      again, so a changed authorization name refuses it (`binding-changed`);
+ *   5. sends through the send gate (`mcp/requestGuard.ts`), asked at every
+ *      boundary the request crosses — before every attempt, after a credential
+ *      arrives, after signing — classifies the outcome (a server's 404 for the
+ *      session is `SessionExpiredError`; a handle this process lost is
+ *      `LocalSessionHandleLostError`; neither is repeated), files its use, and
+ *      releases its lease once the request's own work has settled.
+ *
+ * Never another conversation's connection: the binding is to the KEY, and a
+ * client of any other key never serves it.
+ */
+import type { Tool } from '../../tools/tools.js';
+import type { Definition } from './definitions.js';
+import { type PoolKey } from './identityKey.js';
+import type { Pool } from './pool.js';
+import { UseFacts } from './record.js';
+/** What a bound tool was listed under. */
+export interface Binding {
+    readonly key: PoolKey;
+    /** The definitions context: `pc:<configHash>` per client, `sh:<context>` shared. */
+    readonly context: string;
+    readonly shared: boolean;
+    /** The list it came from: an incarnation's own, or a shared entry's. */
+    readonly listId: string;
+    readonly generation: number;
+    /** Per client: the incarnation it was listed from. */
+    readonly clientId?: string;
+    readonly definition: Definition;
+}
+/** A callable tool for `binding`, shaped as every MCP tool is. */
+export declare function boundTool(pool: Pool, binding: Binding): Tool;
+/** A refusal's word on the record. */
+export declare function noteRefusal(facts: UseFacts, error: unknown): void;

package/dist/esm/mcp/pool/boundTool.js

@@ -0,0 +1,218 @@
+/**
+ * boundTool — a tool bound to its conversation, the list it came from and that
+ * list's generation, re-checked after every wait and at the send gate.
+ *
+ * Pattern: the shape every MCP tool takes (`mcpClient.ts` · `mcpToolShape`) +
+ *          one `execute` that runs the five steps of § 6.3.
+ * Role:    A bound tool carries its BINDING: the key it was listed for; the
+ *          context it was listed in (per client, the configuration; shared, the
+ *          entry's context); the list it came from (per client, the client
+ *          incarnation; shared, the entry); and that list's generation. Its
+ *          `execute`:
+ *
+ *   1. checks that the calling run's caller identity encodes to its key —
+ *      otherwise `identity-mismatch`, nothing sent;
+ *   2. checks its binding is current — otherwise `stale-tools`, nothing sent;
+ *   3. is admitted against `maxOperations` and takes a lease on its key's
+ *      client, opening one from a plan resolved now when the key has none. A
+ *      client whose plan's context differs from the binding's refuses with
+ *      `binding-changed` (the client stays for the next list). A client that is
+ *      not the incarnation the tool was listed from is checked against its OWN
+ *      fresh list — the call goes on only if that list holds the same
+ *      definition, compared as canonical JSON; otherwise `stale-tools`. Under
+ *      the app's sharing contract, a replacement whose context matches uses the
+ *      shared entry as it stands;
+ *   4. after every wait, checks step 2 again — and asks the app's `share`
+ *      again, so a changed authorization name refuses it (`binding-changed`);
+ *   5. sends through the send gate (`mcp/requestGuard.ts`), asked at every
+ *      boundary the request crosses — before every attempt, after a credential
+ *      arrives, after signing — classifies the outcome (a server's 404 for the
+ *      session is `SessionExpiredError`; a handle this process lost is
+ *      `LocalSessionHandleLostError`; neither is repeated), files its use, and
+ *      releases its lease once the request's own work has settled.
+ *
+ * Never another conversation's connection: the binding is to the KEY, and a
+ * client of any other key never serves it.
+ */
+import { mcpClientUseOf } from '../../tools/mcpClientUse.js';
+import { LocalSessionHandleLostError } from '../../tools/toolSessions.js';
+import { ServerEndedSessionError } from './sessionEnded.js';
+import { mcpToolShape } from '../mcpClient.js';
+import { withCallGuard } from '../requestGuard.js';
+import { McpPoolRefusedError, PoolFullError } from './errors.js';
+import { poolKeyOf } from './identityKey.js';
+import { UseFacts } from './record.js';
+/** A callable tool for `binding`, shaped as every MCP tool is. */
+export function boundTool(pool, binding) {
+    return {
+        ...mcpToolShape(pool.settings.name, binding.definition.listed),
+        execute: (args, ctx) => executeBound(pool, binding, args, ctx),
+    };
+}
+/** The five steps. */
+async function executeBound(pool, binding, args, ctx) {
+    const facts = new UseFacts(pool.settings.name, 'call');
+    facts.keyHash = binding.key.keyHash;
+    let operation;
+    try {
+        // 1 — the calling run's caller identity, encoded the one way.
+        const caller = poolKeyOf(ctx?.identity, { requirePrincipal: false, requireTenant: false });
+        if (typeof caller === 'string' || caller.key !== binding.key.key) {
+            throw pool.refused('identity-mismatch');
+        }
+        pool.interact();
+        // 2 — the binding, before anything is admitted.
+        if (beforeLease(pool, binding) === 'stale')
+            throw pool.refused('stale-tools');
+        // 3 — admitted, leased, opened when the key has none; the app's names asked
+        // again, so a changed authorization refuses what was listed under the old.
+        operation = pool.admit('call', 'call', ctx?.signal);
+        const client = await pool.leaseClient(binding.key, operation, facts);
+        if (pool.refreshContext(client).context !== binding.context) {
+            throw pool.refused('binding-changed');
+        }
+        const { inner, effective } = await toolOn(pool, binding, client, operation, facts);
+        // 4 — after every wait, the binding again.
+        operation.check();
+        checkHolds(pool, client, effective);
+        // 5 — the send gate, asked at every boundary the request crosses.
+        operation.guardWith(() => checkHolds(pool, client, effective));
+        operation.phase = 'call';
+        const callCtx = withCallGuard({ ...(ctx ?? {}), signal: operation.signal }, operation);
+        try {
+            return await inner.execute(args, callCtx);
+        }
+        catch (error) {
+            throw classified(pool, client, operation, facts, error);
+        }
+    }
+    catch (error) {
+        noteRefusal(facts, error);
+        throw error;
+    }
+    finally {
+        operation?.finish();
+        mcpClientUseOf(ctx)?.file(facts.toUse());
+    }
+}
+/** The tool to run on `client`, and the binding the send gate checks it against. */
+async function toolOn(pool, binding, client, operation, facts) {
+    const name = binding.definition.listed.name;
+    const port = client.port;
+    if (port === undefined)
+        throw pool.refused('init-failed');
+    if (binding.shared) {
+        // The shared entry as it stands: a definition this client may never have
+        // listed, so the tool carries its own checks (`ClientPort.bind`).
+        return { inner: port.bind(binding.definition.listed), effective: binding };
+    }
+    if (client.clientId === binding.clientId) {
+        const own = client.list.tool(name);
+        if (own === undefined)
+            throw pool.refused('stale-tools');
+        return { inner: own, effective: binding };
+    }
+    // A replacement: its own fresh list, under the context of now, then the
+    // same definition or nothing.
+    const listed = await pool.ensureListed(client, operation);
+    if (listed.context !== binding.context)
+        throw pool.refused('binding-changed');
+    const fresh = listed.list.definition(name);
+    const own = listed.list.tool(name);
+    if (fresh === undefined ||
+        own === undefined ||
+        fresh.canonical !== binding.definition.canonical) {
+        facts.revalidated = 'refused';
+        throw pool.refused('stale-tools');
+    }
+    facts.revalidated = 'kept';
+    return {
+        inner: own,
+        effective: {
+            ...binding,
+            clientId: client.clientId,
+            listId: listed.list.id,
+            generation: listed.list.generation,
+        },
+    };
+}
+/**
+ * Step 2, before a lease: a shared binding against its entry; a per-client
+ * binding against its incarnation when that incarnation is still the key's
+ * current client. An incarnation that is gone is not stale yet — step 3 checks
+ * the replacement's own list.
+ */
+function beforeLease(pool, binding) {
+    if (binding.shared)
+        return sharedHolds(pool, binding) ? 'ok' : 'stale';
+    const current = pool.clients.currentFor(binding.key.key);
+    if (current === undefined || current.clientId !== binding.clientId)
+        return 'ok';
+    return listHolds(current, binding) ? 'ok' : 'stale';
+}
+/**
+ * The binding holds on `client` — the one the call runs on: the app's names
+ * still give its context, and its list has not moved. Otherwise the refusal:
+ * `binding-changed` for a changed context, `stale-tools` for a moved list.
+ */
+function checkHolds(pool, client, binding) {
+    if (!pool.contextHolds(client, binding.context))
+        throw pool.refused('binding-changed');
+    const holds = binding.shared ? sharedHolds(pool, binding) : listHolds(client, binding);
+    if (!holds)
+        throw pool.refused('stale-tools');
+}
+function sharedHolds(pool, binding) {
+    const entry = pool.shared.peek(binding.context);
+    return (entry !== undefined &&
+        entry.list.id === binding.listId &&
+        entry.list.generation === binding.generation);
+}
+function listHolds(client, binding) {
+    return client.list.id === binding.listId && client.list.generation === binding.generation;
+}
+/**
+ * What the call failed with, as the pool read it: a server's 404 for the
+ * session it issued is `SessionExpiredError`; a handle this process lost is
+ * `LocalSessionHandleLostError` (the transport's own object). Either way the
+ * client leaves its key, and the call is not repeated. Anything else is the
+ * error as it came.
+ */
+function classified(pool, client, operation, facts, error) {
+    const lost = pool.classifyFailure(client, operation, error);
+    if (lost === 'expired') {
+        facts.client = 'expired';
+        facts.evidence = 'server-404';
+        return new ServerEndedSessionError(pool.settings.name, client.clientId, error);
+    }
+    if (lost === 'handle-lost') {
+        facts.client = 'handle-lost';
+        facts.evidence = 'transport-forgot-handle';
+        return error instanceof LocalSessionHandleLostError
+            ? error
+            : new LocalSessionHandleLostError({ cause: error });
+    }
+    return error;
+}
+/** A refusal's word on the record. */
+export function noteRefusal(facts, error) {
+    if (error instanceof McpPoolRefusedError) {
+        facts.refusal = error.reason;
+    }
+    else if (error instanceof PoolFullError) {
+        facts.refusal = LIMIT_WORDS[error.limit];
+    }
+    else {
+        return;
+    }
+    // No client was touched: the pool refused to give one.
+    if (facts.clientId === undefined)
+        facts.client = 'refused';
+}
+const LIMIT_WORDS = {
+    pool: 'pool-full',
+    principal: 'principal-full',
+    ending: 'ending-full',
+    operations: 'operations-full',
+};
+//# sourceMappingURL=boundTool.js.map

package/dist/esm/mcp/pool/boundTool.js.map

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

package/dist/esm/mcp/pool/clientSet.d.ts

@@ -0,0 +1,73 @@
+/**
+ * clientSet — which clients the pool holds, and in which of its two sets.
+ *
+ * Pattern: two sets and their indexes, mutated only together.
+ * Role:    § 5.3 of the design. The OPEN set holds every client that counts
+ *          toward `maxClients` — opening, busy, idle, deferred, or an abandoned
+ *          open that has not settled. The ENDING set holds every client from the
+ *          decision to end it until that ending's work has settled, and counts
+ *          toward `maxEnding`. A client leaves the open set only into the ending
+ *          set — a lost handle too: its ending is its local close — or, when its
+ *          open failed and left nothing to end, by being dropped. So the pool
+ *          holds at most `maxClients + maxEnding` client objects.
+ *
+ * Each key has at most one CURRENT client — the one new leases go to. A client
+ * named by `terminate`, or whose session expired, stops being current at once
+ * while it stays in the open set, counted, until it can end.
+ *
+ * What the pool remembers of a key after its client left — the incarnation
+ * count and why the last one left — is bounded (`KEY_MEMORY`), least recently
+ * used forgotten first: after that a key's count starts again at 1. The record
+ * reads it; no binding depends on it.
+ */
+import type { EndReason, PooledClient } from './pooledClient.js';
+/** How many keys' incarnation counts the pool remembers. */
+export declare const KEY_MEMORY = 4096;
+/** Why a key's previous client left, as the record names it. */
+export type PreviousEnd = 'idle' | 'evicted' | 'expired' | 'handle-lost' | 'terminated';
+export declare class ClientSet {
+    private readonly open;
+    private readonly ending;
+    private readonly current;
+    private readonly perPrincipal;
+    private readonly memory;
+    /** Clients in the open set. */
+    get openCount(): number;
+    /** Clients in the ending set. */
+    get endingCount(): number;
+    /** Every client in the open set. */
+    openClients(): readonly PooledClient[];
+    /** Clients of the open set that count for `principal`. */
+    principalCount(principal: string): number;
+    /** The key's current client — opening or open, taking new leases — if it has one. */
+    currentFor(key: string): PooledClient | undefined;
+    /** The next incarnation number for `key`, and why its previous client left. */
+    nextIncarnation(key: string): {
+        readonly generation: number;
+        readonly previous?: PreviousEnd;
+    };
+    /** A new client joins the open set as its key's current client. */
+    admit(client: PooledClient): void;
+    /**
+     * The client stops taking new leases: its key has no current client until the
+     * next open, and that open's record says `why`. A client that is no longer
+     * its key's current one has already left it, so nothing is recorded again —
+     * a later client of the key keeps its own reason.
+     */
+    retire(client: PooledClient, why: PreviousEnd): void;
+    /** The client moves from the open set into the ending set. */
+    moveToEnding(client: PooledClient, why: PreviousEnd | undefined): void;
+    /** The client's ending settled: it leaves the ending set. */
+    ended(client: PooledClient): void;
+    /** The client leaves the open set without ending — a failed open, a lost handle. */
+    drop(client: PooledClient, why?: PreviousEnd): void;
+    /**
+     * The least recently used idle client of the open set — among those `pick`
+     * accepts — or `undefined` when every one is busy.
+     */
+    leastRecentlyUsedIdle(pick: (client: PooledClient) => boolean): PooledClient | undefined;
+    private leaveOpen;
+    private remember;
+}
+/** The record's `previous` for an end reason, when it names one. */
+export declare function previousOf(reason: EndReason): PreviousEnd | undefined;

package/dist/esm/mcp/pool/clientSet.js

@@ -0,0 +1,152 @@
+/**
+ * clientSet — which clients the pool holds, and in which of its two sets.
+ *
+ * Pattern: two sets and their indexes, mutated only together.
+ * Role:    § 5.3 of the design. The OPEN set holds every client that counts
+ *          toward `maxClients` — opening, busy, idle, deferred, or an abandoned
+ *          open that has not settled. The ENDING set holds every client from the
+ *          decision to end it until that ending's work has settled, and counts
+ *          toward `maxEnding`. A client leaves the open set only into the ending
+ *          set — a lost handle too: its ending is its local close — or, when its
+ *          open failed and left nothing to end, by being dropped. So the pool
+ *          holds at most `maxClients + maxEnding` client objects.
+ *
+ * Each key has at most one CURRENT client — the one new leases go to. A client
+ * named by `terminate`, or whose session expired, stops being current at once
+ * while it stays in the open set, counted, until it can end.
+ *
+ * What the pool remembers of a key after its client left — the incarnation
+ * count and why the last one left — is bounded (`KEY_MEMORY`), least recently
+ * used forgotten first: after that a key's count starts again at 1. The record
+ * reads it; no binding depends on it.
+ */
+/** How many keys' incarnation counts the pool remembers. */
+export const KEY_MEMORY = 4096;
+export class ClientSet {
+    open = new Set();
+    ending = new Set();
+    current = new Map();
+    perPrincipal = new Map();
+    memory = new Map();
+    /** Clients in the open set. */
+    get openCount() {
+        return this.open.size;
+    }
+    /** Clients in the ending set. */
+    get endingCount() {
+        return this.ending.size;
+    }
+    /** Every client in the open set. */
+    openClients() {
+        return [...this.open];
+    }
+    /** Clients of the open set that count for `principal`. */
+    principalCount(principal) {
+        return this.perPrincipal.get(principal) ?? 0;
+    }
+    /** The key's current client — opening or open, taking new leases — if it has one. */
+    currentFor(key) {
+        return this.current.get(key);
+    }
+    /** The next incarnation number for `key`, and why its previous client left. */
+    nextIncarnation(key) {
+        const remembered = this.remember(key);
+        remembered.incarnations += 1;
+        const previous = remembered.previous;
+        remembered.previous = undefined;
+        return { generation: remembered.incarnations, ...(previous !== undefined && { previous }) };
+    }
+    /** A new client joins the open set as its key's current client. */
+    admit(client) {
+        this.open.add(client);
+        this.current.set(client.key.key, client);
+        this.perPrincipal.set(client.key.principal, this.principalCount(client.key.principal) + 1);
+    }
+    /**
+     * The client stops taking new leases: its key has no current client until the
+     * next open, and that open's record says `why`. A client that is no longer
+     * its key's current one has already left it, so nothing is recorded again —
+     * a later client of the key keeps its own reason.
+     */
+    retire(client, why) {
+        if (this.current.get(client.key.key) !== client)
+            return;
+        this.current.delete(client.key.key);
+        this.remember(client.key.key).previous = why;
+    }
+    /** The client moves from the open set into the ending set. */
+    moveToEnding(client, why) {
+        if (why !== undefined)
+            this.retire(client, why);
+        else if (this.current.get(client.key.key) === client)
+            this.current.delete(client.key.key);
+        this.leaveOpen(client);
+        this.ending.add(client);
+    }
+    /** The client's ending settled: it leaves the ending set. */
+    ended(client) {
+        this.ending.delete(client);
+    }
+    /** The client leaves the open set without ending — a failed open, a lost handle. */
+    drop(client, why) {
+        if (why !== undefined)
+            this.retire(client, why);
+        else if (this.current.get(client.key.key) === client)
+            this.current.delete(client.key.key);
+        this.leaveOpen(client);
+    }
+    /**
+     * The least recently used idle client of the open set — among those `pick`
+     * accepts — or `undefined` when every one is busy.
+     */
+    leastRecentlyUsedIdle(pick) {
+        let oldest;
+        for (const client of this.open) {
+            if (client.busy || client.state !== 'open' || !pick(client))
+                continue;
+            if (oldest === undefined || client.usedAt < oldest.usedAt)
+                oldest = client;
+        }
+        return oldest;
+    }
+    leaveOpen(client) {
+        if (!this.open.delete(client))
+            return;
+        const left = this.principalCount(client.key.principal) - 1;
+        if (left > 0)
+            this.perPrincipal.set(client.key.principal, left);
+        else
+            this.perPrincipal.delete(client.key.principal);
+    }
+    remember(key) {
+        let remembered = this.memory.get(key);
+        if (remembered !== undefined)
+            this.memory.delete(key);
+        else
+            remembered = { incarnations: 0, previous: undefined };
+        this.memory.set(key, remembered);
+        while (this.memory.size > KEY_MEMORY) {
+            const oldest = this.memory.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.memory.delete(oldest);
+        }
+        return remembered;
+    }
+}
+/** The record's `previous` for an end reason, when it names one. */
+export function previousOf(reason) {
+    switch (reason) {
+        case 'idle':
+        case 'evicted':
+        case 'expired':
+        case 'handle-lost':
+            return reason;
+        case 'terminated':
+        case 'closed':
+            return 'terminated';
+        case 'abandoned-open':
+            return undefined;
+    }
+}
+//# sourceMappingURL=clientSet.js.map

package/dist/esm/mcp/pool/clientSet.js.map

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

package/dist/esm/mcp/pool/definitions.d.ts

@@ -0,0 +1,103 @@
+/**
+ * definitions — the tool lists a pool serves, and when each stops being served.
+ *
+ * Pattern: one list type, two owners — a client incarnation, or a shared entry.
+ * Role:    § 6 of the design. A definition is what one `tools/list` entry says:
+ *          name, description, input schema, and the declarations its `_meta`
+ *          carries. The executable half (the connection) is never shared.
+ *
+ *   - PER CLIENT (the default): a conversation's list is its own client's, and
+ *     it belongs to that client INCARNATION alone — a replacement client, even
+ *     one opened from the same plan, is a new session whose list may differ,
+ *     so it lists again.
+ *   - SHARED, only under the app's declared contract: one entry per context
+ *     (`plan.ts`), listed on the client of whichever conversation needs it,
+ *     bounded at `MAX_DEFINITION_ENTRIES` entries; a list longer than
+ *     `MAX_SHARED_TOOLS` is used by its own client and not shared.
+ *
+ * A list stops being served in four ways, plus a time limit: the configuration
+ * (a new context is a new list), the server's tools-changed notice, the app's
+ * `permissionsChanged`, and `toolsChanged`. Invalidation moves the list's
+ * GENERATION at once — every tool bound to an older one is refused — and marks
+ * it to be listed again. A lapsed time limit lists again at the next list, and
+ * moves the generation only if the new list differs. A generation counts within
+ * one list: a replacement client and a new entry start counts of their own, and
+ * a binding names the list it came from, so no number of an old list can match
+ * a new one. A listing still in flight when its list's generation moved is
+ * discarded, never written.
+ *
+ * Every list is a frozen plain-data copy (`mcp/plainData.ts` · `copyJsonObject`),
+ * written once per generation, by one listing at a time.
+ */
+import type { Tool } from '../../tools/tools.js';
+import type { McpListedTool } from '../types.js';
+/** One definition, frozen, and its canonical JSON — what "the same definition" compares. */
+export interface Definition {
+    readonly listed: McpListedTool;
+    readonly canonical: string;
+}
+/** A frozen copy of `listed`, or `undefined` when it is not plain JSON data. */
+export declare function definitionOf(listed: McpListedTool): Definition | undefined;
+/**
+ * One list: an incarnation's own or a shared entry. Its `id` is stable for its
+ * life; its `generation` moves on invalidation, and on a time-limit relisting
+ * that changed it.
+ */
+export declare class DefinitionList {
+    readonly id: string;
+    private current;
+    private tools;
+    /** Has any listing been written? */
+    private written;
+    /** 0 until the first listing is written. */
+    generation: number;
+    /** Invalidated: listed again before it is served. */
+    stale: boolean;
+    /** When it was last written, on the pool's clock. */
+    listedAt: number;
+    /** The listing in flight, joined by anyone who needs the same list. */
+    listing: Promise<void> | undefined;
+    /** Can it be served at `now`, as it stands? */
+    servable(now: number, ttlMs: number): boolean;
+    /**
+     * Invalidate: every older binding is refused, the next list lists again, and
+     * a listing in flight is discarded — even a first one, before anything was
+     * written. Generations only ever increase.
+     */
+    invalidate(): void;
+    /** The definition named `name`, at the current generation. */
+    definition(name: string): Definition | undefined;
+    /** The client's own wrapped tool named `name` (per-client lists only). */
+    tool(name: string): Tool | undefined;
+    /** Every definition, in listing order. */
+    all(): readonly Definition[];
+    /**
+     * Write a listing that began at generation `began`. Refused — `false`, nothing
+     * written — when the generation moved while it ran. A first write moves the
+     * generation to a number no binding has seen; a write after invalidation keeps
+     * the moved one; a time-limit rewrite moves it only when the list differs.
+     */
+    write(began: number, definitions: readonly Definition[], tools: readonly Tool[] | undefined, now: number): boolean;
+}
+/** A shared entry: a list and the tenant its context carries. */
+export interface SharedEntry {
+    readonly list: DefinitionList;
+    readonly tenant: string;
+}
+/**
+ * The shared definition entries, by context — bounded at
+ * `MAX_DEFINITION_ENTRIES`, the least recently used dropped first. A dropped
+ * entry's bindings are refused as stale: the entry they name is gone.
+ */
+export declare class SharedDefinitions {
+    private readonly maxEntries;
+    private readonly entries;
+    constructor(maxEntries?: number);
+    get size(): number;
+    /** The entry for `context`, created empty when there is none; most recently used. */
+    entryFor(context: string, tenant: string): SharedEntry;
+    /** The entry for `context` if it still exists — never created. */
+    peek(context: string): SharedEntry | undefined;
+    /** Invalidate every entry `matches` selects. */
+    invalidate(matches: (entry: SharedEntry) => boolean): void;
+}