@animalabs/agent-framework 0.26.2 → 0.28.0

package/dist/src/mcpl/tool-presence.js

@@ -0,0 +1,697 @@
+/**
+ * MCPL RFC-014 (tool presence, toolsets and surfaces): one server's tool
+ * presence as the host keeps it.
+ *
+ * The server's tool list stays its whole truth (RFC §2 principle 1); hints say
+ * which tools are static (the API tool list, as before) and which are dynamic
+ * (announced in the conversation as they come and go, and called through the
+ * host's `act`). Per server this keeps:
+ *
+ *  - the tool definitions (tools/list) and the toolset declarations (manifest);
+ *  - which declared toolsets and instances are open (toolsets/open results,
+ *    toolsets/list, hint `toolsets` entries), and which undeclared groups the
+ *    host opened itself (RFC §5.4: the server is never told);
+ *  - the server's visibility statements per instance, and definition
+ *    overrides, from hint changes applied in `rev` order, each at most once.
+ *    One apply path serves every carrier: a call's, an open's or a close's
+ *    result, a push's `hints`, a standalone `tools/hints`. `tools/list`
+ *    (`mcpl/rev`) and `toolsets/list` are statements later changes build on;
+ *  - which definitions the model has been shown, so a tool's first sentence
+ *    is said once.
+ *
+ * Every mutation is bracketed by view() snapshots, and diff() turns the
+ * difference into what the model reads. Nothing here does I/O: the
+ * controller (toolset-host.ts) feeds it what the connection read.
+ *
+ * Ported from mcpl-cc-bridge's presence.ts, the reference host.
+ */
+import { objectSignature, renderToolLines, toolDigest } from './tool-signature.js';
+/** Toolset-less dynamic tools live under this key: always "open", visible per the server. */
+export const NO_TOOLSET = '';
+export const keyOf = (toolset, instance) => `${toolset}\u0000${instance ?? ''}`;
+export const splitKey = (key) => {
+    const [toolset, instance] = key.split('\u0000');
+    return { toolset: toolset ?? '', ...(instance ? { instance } : {}) };
+};
+export const emptyChange = () => ({ changes: [], suggest: [], notes: [] });
+export const isEmptyChange = (c) => !c.changes.length && !c.suggest.length && !c.notes.length && !c.ended?.length;
+/** Whether a change to one key shows that key's tools in a block: what render prints and markShown counts as shown. */
+const showsBlock = (c) => !c.closed && (c.opened || c.appeared.length > 0 || c.redefined.length > 0 || c.gone.length > 0);
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const arr = (v) => (Array.isArray(v) ? v : []);
+const str = (v) => (typeof v === 'string' && v ? v : undefined);
+/** The fields a hint definition may change (RFC §6.1); `name` and all of `_meta` are ignored. */
+export function overrideOf(d) {
+    return {
+        ...(typeof d.description === 'string' ? { description: d.description } : {}),
+        ...(isObj(d.inputSchema) ? { inputSchema: d.inputSchema } : {}),
+        ...(isObj(d.annotations) ? { annotations: d.annotations } : {}),
+    };
+}
+export class ToolPresence {
+    server;
+    names;
+    allowed;
+    listedName;
+    published;
+    /** Hints are in effect on the current connection: the host advertised toolHints and the server did too. */
+    active = false;
+    declared = {};
+    surface = null;
+    /** The last rev read on this connection (RFC §6.1); 0 at each connect. */
+    rev = 0;
+    tools = new Map();
+    open = new Map();
+    groups = new Set();
+    visible = new Map();
+    /** Definition overrides from hints: per key (an instance's own, or a toolset's), per tool. */
+    defs = new Map();
+    /** `ended` ids told to the agent, kept while the server still reports them (RFC §5.3). */
+    toldEnded = new Set();
+    /** Moves a tools/list made that the model's tool list doesn't show yet: told once a rebuild has published them. */
+    pendingMoves = new Map();
+    /** Digests of definitions the model has been shown with their first sentence. */
+    shown = new Set();
+    constructor(server, 
+    /** The meta-tools' names, for the hints rendered text gives. */
+    names, 
+    /** The host's tool policy (enabledTools/disabledTools): a tool it refuses is as if unlisted. */
+    allowed = () => true, 
+    /** How a static tool is named in the API tool list, for `look`. */
+    listedName = (tool) => tool, 
+    /** Where the model's published tool list last put a tool, if it's there (shownAs). */
+    published = () => undefined) {
+        this.server = server;
+        this.names = names;
+        this.allowed = allowed;
+        this.listedName = listedName;
+        this.published = published;
+    }
+    // ── connection lifecycle ──
+    /** A new connection: revs start over; hints count only when both sides advertised toolHints. */
+    beginConnection(mcpl, hostHints) {
+        this.rev = 0;
+        // RFC §6.1: hint _meta and tools/hints from a server that did not advertise toolHints are ignored.
+        const active = hostHints && !!mcpl && mcpl.toolHints === true;
+        if (!active) {
+            if (this.active)
+                this.deactivate();
+            return;
+        }
+        this.active = true;
+        this.setManifest(mcpl);
+    }
+    /** Toolset declarations and the surface hint, from initialize or a manifest re-fetch. */
+    setManifest(mcpl) {
+        const prev = this.declared;
+        const decl = {};
+        if (mcpl && isObj(mcpl.toolsets)) {
+            for (const [name, d] of Object.entries(mcpl.toolsets)) {
+                if (!isObj(d) || !name)
+                    continue;
+                decl[name] = {
+                    ...(str(d.title) ? { title: str(d.title) } : {}),
+                    ...(str(d.summary) ? { summary: str(d.summary) } : {}),
+                    default: d.default === 'open' ? 'open' : 'closed',
+                    ...(d.instances === true ? { instances: true } : {}),
+                    ...(isObj(d.options) ? { options: d.options } : {}),
+                };
+            }
+        }
+        this.declared = decl;
+        for (const name of Object.keys(decl))
+            this.groups.delete(name);
+        this.surface = mcpl && isObj(mcpl.surface) ? { title: str(mcpl.surface.title), summary: str(mcpl.surface.summary) } : null;
+        // RFC §5.1: removing a toolset, or turning its instances on or off, ends
+        // its open instances; one that becomes undeclared starts closed under the
+        // host's gating.
+        for (const [k, r] of [...this.open]) {
+            if (!decl[r.toolset] || !!decl[r.toolset].instances !== !!prev[r.toolset]?.instances)
+                this.dropKey(k);
+        }
+        for (const name of Object.keys(prev)) {
+            if (decl[name])
+                continue;
+            this.groups.delete(name);
+            for (const k of new Set([...this.visible.keys(), ...this.defs.keys()]))
+                if (splitKey(k).toolset === name)
+                    this.dropKey(k);
+        }
+    }
+    /** RFC §5.1: a server that withdraws toolHints is hint-less from then on: every tool static, nothing dynamic presented. */
+    deactivate() {
+        this.active = false;
+        this.declared = {};
+        this.surface = null;
+        this.open.clear();
+        this.groups.clear();
+        this.visible.clear();
+        this.defs.clear();
+        this.pendingMoves.clear();
+    }
+    /** tools/list: every definition, visible or not (RFC §4.1). A tool the host's policy refuses is left out. */
+    setTools(list) {
+        const seen = new Map([...this.tools.keys()].map((name) => [name, this.presenceOf(name)]));
+        const named = list.filter((t) => isObj(t) && typeof t.name === 'string');
+        this.tools = new Map();
+        for (const t of named)
+            if (this.allowed(t.name) && !this.tools.has(t.name))
+                this.tools.set(t.name, t);
+        for (const set of this.visible.values())
+            for (const n of [...set])
+                if (!this.tools.has(n))
+                    set.delete(n);
+        // RFC §4.1: the list states each tool's presence, and presence follows
+        // it. A changed presence is a move the model's tool list shows at its
+        // next rebuild (§4.2; applyMoves); one the list reverses before then
+        // never reached that list.
+        for (const name of [...this.pendingMoves.keys()])
+            if (!this.tools.has(name))
+                this.pendingMoves.delete(name);
+        for (const name of this.active ? this.tools.keys() : []) {
+            const was = seen.get(name);
+            const listed = this.listedPresence(name);
+            if (this.pendingMoves.has(name)) {
+                if (this.pendingMoves.get(name) !== listed)
+                    this.pendingMoves.delete(name);
+            }
+            else if (was !== undefined && was !== listed) {
+                this.pendingMoves.set(name, listed);
+            }
+        }
+        // The list's `mcpl/visible` is the server's word only where nothing else
+        // speaks: toolset-less dynamic tools and undeclared groups. For a declared
+        // toolset it's an aggregate ("visible in some open instance"); per-instance
+        // state comes from toolsets/list and hint changes (RFC §4.1, §5.3).
+        for (const t of this.tools.values()) {
+            if (this.listedPresence(t.name) !== 'dynamic')
+                continue;
+            const ts = this.toolsetOf(t.name);
+            if (ts && this.isDeclared(ts))
+                continue;
+            this.setVisible(keyOf(ts ?? NO_TOOLSET), t.name, t._meta?.['mcpl/visible'] !== false);
+        }
+    }
+    // ── reading ──
+    /** Whether the meta-tools speak for this server: hints in effect and something dynamic. */
+    get presents() {
+        if (!this.active)
+            return false;
+        if (Object.keys(this.declared).length)
+            return true;
+        for (const n of this.tools.keys())
+            if (this.presenceOf(n) === 'dynamic')
+                return true;
+        return false;
+    }
+    get allTools() {
+        return [...this.tools.values()];
+    }
+    tool(name) {
+        return this.tools.get(name);
+    }
+    toolsetOf(name) {
+        const m = this.tools.get(name)?._meta;
+        return m && typeof m['mcpl/toolset'] === 'string' && m['mcpl/toolset'] ? m['mcpl/toolset'] : undefined;
+    }
+    /** As the list states it: a toolset's tool is dynamic whatever a hint says (RFC §4.1). */
+    presenceOf(name) {
+        if (!this.active)
+            return 'static';
+        return this.listedPresence(name);
+    }
+    /** RFC §4.2: "Until it applies the move, the tool keeps working where it
+     *  is." Whether a tool is at `place` in the tool list last published, or
+     *  in the server's latest tools/list (its presence). Until a rebuild
+     *  applies a move the two differ, and a call is taken at either. */
+    shownAs(name, place) {
+        if (!this.active)
+            return place === 'static';
+        return this.published(name) === place || this.listedPresence(name) === place;
+    }
+    listedPresence(name) {
+        if (this.toolsetOf(name))
+            return 'dynamic';
+        return this.tools.get(name)?._meta?.['mcpl/presence'] === 'dynamic' ? 'dynamic' : 'static';
+    }
+    isDeclared(toolset) {
+        return Object.hasOwn(this.declared, toolset);
+    }
+    /** Undeclared toolset names the server's tools are tagged with (RFC §5.4). */
+    get undeclaredGroups() {
+        const out = new Set();
+        for (const n of this.tools.keys()) {
+            const ts = this.toolsetOf(n);
+            if (ts && !this.isDeclared(ts))
+                out.add(ts);
+        }
+        return [...out];
+    }
+    openRecords(toolset) {
+        return [...this.open.values()].filter((r) => toolset === undefined || r.toolset === toolset);
+    }
+    isOpen(toolset, instance) {
+        return this.isDeclared(toolset) ? this.open.has(keyOf(toolset, instance)) : this.groups.has(toolset);
+    }
+    get openGroups() {
+        return [...this.groups];
+    }
+    /**
+     * The definition the model sees, and the host checks arguments against, for
+     * `name` in `key`: the instance's own (a hint definition with `instance`),
+     * else the toolset's (one without), else the listed one (RFC §6.1).
+     */
+    defOf(key, name) {
+        const listed = this.tools.get(name);
+        const { toolset } = splitKey(key);
+        const o = this.defs.get(key)?.get(name) ?? (toolset ? this.defs.get(keyOf(toolset))?.get(name) : undefined);
+        return o ? { ...listed, ...o } : listed;
+    }
+    view() {
+        const v = new Map();
+        for (const [key, r] of this.open)
+            v.set(key, { title: r.title, tools: new Map() });
+        for (const g of this.groups)
+            if (!this.isDeclared(g))
+                v.set(keyOf(g), { tools: new Map() });
+        for (const name of this.tools.keys()) {
+            if (this.presenceOf(name) !== 'dynamic')
+                continue;
+            const ts = this.toolsetOf(name);
+            if (ts && this.isDeclared(ts)) {
+                for (const [key, r] of this.open)
+                    if (r.toolset === ts && this.visible.get(key)?.has(name))
+                        v.get(key).tools.set(name, this.defOf(key, name));
+            }
+            else if (ts) {
+                // Two controllers (RFC §4.1, §5.4): the host has the group open AND the server says visible.
+                const key = keyOf(ts);
+                if (this.groups.has(ts) && this.visible.get(key)?.has(name))
+                    v.get(key).tools.set(name, this.defOf(key, name));
+            }
+            else {
+                const key = keyOf(NO_TOOLSET);
+                if (this.visible.get(key)?.has(name)) {
+                    if (!v.has(key))
+                        v.set(key, { tools: new Map() });
+                    v.get(key).tools.set(name, this.defOf(key, name));
+                }
+            }
+        }
+        return v;
+    }
+    diff(before, after) {
+        const out = emptyChange();
+        for (const key of new Set([...before.keys(), ...after.keys()])) {
+            const b = before.get(key);
+            const a = after.get(key);
+            const isGroupKey = splitKey(key).toolset !== NO_TOOLSET;
+            const appeared = [];
+            const redefined = [];
+            for (const [n, d] of a?.tools ?? []) {
+                const was = b?.tools.get(n);
+                if (!was)
+                    appeared.push(d);
+                else if (toolDigest(was) !== toolDigest(d))
+                    redefined.push(d);
+            }
+            const gone = [...(b?.tools.keys() ?? [])].filter((n) => !a?.tools.has(n));
+            const opened = isGroupKey && !b && !!a;
+            const closed = isGroupKey && !!b && !a;
+            const retitled = !!a && !!b && !!a.title && a.title !== b.title;
+            if (!appeared.length && !redefined.length && !gone.length && !opened && !closed && !retitled)
+                continue;
+            out.changes.push({ key, ...splitKey(key), title: a?.title ?? b?.title, opened, closed, retitled, appeared, gone, redefined, now: [...(a?.tools.values() ?? [])] });
+        }
+        return out;
+    }
+    // ── the one apply path ──
+    /** Apply a HintChanges (RFC §6.1) from any of its carriers, as it is read (see ApplyOutcome). */
+    apply(h) {
+        const none = { applied: false, skipped: false, behind: false, suggest: [], unlisted: false };
+        if (!isObj(h) || typeof h.rev !== 'number' || !Number.isFinite(h.rev))
+            return none;
+        if (h.rev <= this.rev)
+            return { ...none, behind: true };
+        const skipped = h.rev !== this.rev + 1;
+        this.rev = h.rev;
+        return { ...none, applied: true, skipped, ...this.applyBody(h) };
+    }
+    /**
+     * tools/list's `_meta["mcpl/rev"]` (RFC §4.1): the last rev the server had
+     * sent when it wrote the list, which takes none itself. Read in order it
+     * equals the last rev read; a higher one means a message was lost (true).
+     */
+    noteListRev(rev) {
+        if (typeof rev !== 'number' || !Number.isFinite(rev))
+            return false;
+        const lost = rev > this.rev;
+        this.rev = Math.max(this.rev, rev);
+        return lost;
+    }
+    applyBody(h) {
+        let unlisted = false;
+        for (const e of arr(h.toolsets)) {
+            if (!isObj(e) || !str(e.toolset) || !this.isDeclared(e.toolset))
+                continue; // undeclared toolsets are host-local
+            const ts = e.toolset;
+            const withInstances = !!this.declared[ts].instances;
+            const instance = withInstances ? str(e.instance) : undefined;
+            if (withInstances && !instance)
+                continue; // an instance-less statement about a toolset with instances names nothing
+            const key = keyOf(ts, instance);
+            // "open" opens, confirms, or (with a new title) retitles (RFC §6.1);
+            // it may come from another connection of the same principal (§5.6).
+            if (e.state === 'open')
+                this.open.set(key, { toolset: ts, ...(instance ? { instance } : {}), title: str(e.title) ?? this.open.get(key)?.title });
+            else if (e.state === 'closed')
+                this.dropKey(key);
+        }
+        for (const e of arr(h.tools)) {
+            if (!isObj(e) || !str(e.name))
+                continue;
+            const name = e.name;
+            if (!this.tools.has(name)) {
+                if (this.allowed(name))
+                    unlisted = true;
+                continue;
+            }
+            // A hint's presence stages nothing: a hinted move takes effect when
+            // the server's tools/list states it (RFC §4.1), as the rebuild's own
+            // list does. A definition it gives is the tool's current one, kept
+            // whatever its presence now, for when it's shown dynamic (§6.1).
+            if (isObj(e.definition)) {
+                const key = this.defKeyFor(name, str(e.instance));
+                if (!this.defs.has(key))
+                    this.defs.set(key, new Map());
+                this.defs.get(key).set(name, overrideOf(e.definition));
+            }
+            if (typeof e.visible === 'boolean')
+                for (const key of this.keysFor(name, str(e.instance)))
+                    this.setVisible(key, name, e.visible);
+        }
+        const suggest = [];
+        for (const s of arr(h.suggest)) {
+            if (!isObj(s) || !str(s.toolset) || (s.action !== 'open' && s.action !== 'close'))
+                continue;
+            suggest.push({ toolset: s.toolset, ...(str(s.instance) ? { instance: str(s.instance) } : {}), action: s.action, reason: str(s.reason) ?? '' });
+        }
+        return { suggest, unlisted };
+    }
+    /**
+     * Where a definition lands (RFC §6.1): with `instance`, that instance's own;
+     * without, the toolset's (for a toolset without instances, its only one's).
+     */
+    defKeyFor(name, instance) {
+        const ts = this.toolsetOf(name);
+        if (!ts)
+            return keyOf(NO_TOOLSET);
+        return keyOf(ts, this.declared[ts]?.instances ? instance : undefined);
+    }
+    /** Where a visibility statement lands. For a toolset with instances, `instance` is required; a statement without one is ignored. */
+    keysFor(name, instance) {
+        const ts = this.toolsetOf(name);
+        if (!ts)
+            return [keyOf(NO_TOOLSET)];
+        const decl = this.declared[ts];
+        if (!decl?.instances)
+            return [keyOf(ts)];
+        return instance ? [keyOf(ts, instance)] : [];
+    }
+    setVisible(key, name, on) {
+        let s = this.visible.get(key);
+        if (!s)
+            this.visible.set(key, (s = new Set()));
+        if (on)
+            s.add(name);
+        else
+            s.delete(name);
+    }
+    dropKey(key) {
+        this.open.delete(key);
+        this.visible.delete(key);
+        this.defs.delete(key);
+    }
+    /** The result of a toolsets/open: the instance is open whatever its hints say. */
+    noteOpened(toolset, instance, title) {
+        if (!this.isDeclared(toolset))
+            return;
+        const withInstances = !!this.declared[toolset].instances;
+        if (withInstances && !instance)
+            return;
+        const key = keyOf(toolset, withInstances ? instance : undefined);
+        this.open.set(key, { toolset, ...(withInstances && instance ? { instance } : {}), title: title ?? this.open.get(key)?.title });
+    }
+    /** toolsets/close succeeded: closed, whatever the hints said. */
+    noteClosed(toolset, instance) {
+        this.dropKey(keyOf(toolset, this.declared[toolset]?.instances ? instance : undefined));
+    }
+    /**
+     * toolsets/list (RFC §5.3): what the principal has open, with the full hint
+     * state of its dynamic tools, the truth for declared toolsets and dynamic
+     * tools outside them. Anything the host believed open and the server doesn't
+     * report is closed, never re-opened here: opening can start a new game.
+     * Returns what was lost, what the server says ended while no connection was
+     * told, its suggestions, and whether its rev skipped one.
+     */
+    adopt(result) {
+        const had = [...this.open.values()];
+        // A full statement: a dynamic tool not stated visible is invisible.
+        // Undeclared groups stay as the host has them open or closed.
+        for (const k of new Set([...this.open.keys(), ...this.visible.keys(), ...this.defs.keys()])) {
+            if (this.isDeclared(splitKey(k).toolset))
+                this.dropKey(k);
+            else {
+                this.visible.delete(k);
+                this.defs.delete(k);
+            }
+        }
+        const r = isObj(result) ? result : {};
+        for (const o of arr(r.open)) {
+            if (!isObj(o) || !str(o.toolset))
+                continue;
+            this.noteOpened(o.toolset, str(o.instance), str(o.title));
+        }
+        let suggest = [];
+        let skipped = false;
+        let unlisted = false;
+        const h = isObj(r._meta) ? r._meta['mcpl/hints'] : undefined;
+        if (isObj(h)) {
+            ({ suggest, unlisted } = this.applyBody(h));
+            // Its own rev, at its place in order (RFC §6.1).
+            if (typeof h.rev === 'number' && Number.isFinite(h.rev)) {
+                skipped = h.rev !== this.rev + 1;
+                this.rev = Math.max(this.rev, h.rev);
+            }
+        }
+        const ended = [];
+        for (const e of arr(r.ended)) {
+            if (!isObj(e) || !str(e.toolset))
+                continue;
+            ended.push({ ...(str(e.id) ? { id: str(e.id) } : {}), toolset: e.toolset, ...(str(e.instance) ? { instance: str(e.instance) } : {}), reason: str(e.reason) ?? '' });
+        }
+        // RFC §5.3: a record is reported on every toolsets/list until it expires, and its id is never
+        // reused, so an id the server no longer reports needn't be remembered.
+        const reported = new Set(ended.flatMap((e) => (e.id ? [e.id] : [])));
+        for (const id of [...this.toldEnded])
+            if (!reported.has(id))
+                this.toldEnded.delete(id);
+        return { lost: had.filter((o) => !this.open.has(keyOf(o.toolset, o.instance))), ended, suggest, skipped, unlisted };
+    }
+    /**
+     * What the agent should hear about an adoption: what ended while it was
+     * away, each `ended` id until it has been told (RFC §5.3; markTold), and
+     * what is closed now. An ended record with an id is in `ended`, rendered
+     * while its id is untold.
+     */
+    adoptionNotes(lost, ended) {
+        const notes = [];
+        const told = [];
+        const endedKeys = new Set();
+        for (const e of ended) {
+            if (!e.id || !this.toldEnded.has(e.id))
+                endedKeys.add(keyOf(e.toolset, e.instance));
+            const note = `${this.label(keyOf(e.toolset, e.instance))} ended${e.reason ? `: ${e.reason}` : ''}.`;
+            if (e.id) {
+                if (!this.toldEnded.has(e.id))
+                    told.push({ id: e.id, note });
+            }
+            else
+                notes.push(note);
+        }
+        for (const o of lost) {
+            if (endedKeys.has(keyOf(o.toolset, o.instance)))
+                continue;
+            notes.push(`${this.label(keyOf(o.toolset, o.instance))} is closed: ${this.server} no longer has it open. ${this.openHint(o.toolset)} starts a new one.`);
+        }
+        return { notes, ended: told };
+    }
+    /** The agent has been told these ended records (a notice written, a result it reads); the next statement forgets any it no longer reports. */
+    markTold(ended) {
+        for (const { id } of ended ?? [])
+            this.toldEnded.add(id);
+    }
+    /** The definitions a change set's tool blocks describe have reached the model. */
+    markShown(cs) {
+        for (const c of cs.changes)
+            if (showsBlock(c))
+                for (const t of c.now)
+                    this.shown.add(toolDigest(t));
+    }
+    /** A set's ended notes whose ids are still untold, each once. */
+    untoldNotes(cs) {
+        const seen = new Set();
+        return (cs.ended ?? []).filter(({ id }) => !this.toldEnded.has(id) && !seen.has(id) && !!seen.add(id)).map(({ note }) => note);
+    }
+    // ── host-made opens of undeclared groups (RFC §5.4) ──
+    openGroup(g) {
+        this.groups.add(g);
+    }
+    closeGroup(g) {
+        this.groups.delete(g);
+    }
+    // ── boundaries ──
+    /** The static↔dynamic moves the lists made since the last rebuild, still to be shown. */
+    moves() {
+        return [...this.pendingMoves].map(([name, to]) => ({ name, to }));
+    }
+    /** At a rebuild of the model's tool list (RFC §4.2): those of `moves` still pending, now shown. */
+    applyMoves(moves = this.moves()) {
+        const out = moves.filter(({ name, to }) => this.pendingMoves.get(name) === to);
+        for (const { name } of out)
+            this.pendingMoves.delete(name);
+        return out;
+    }
+    // ── rendering ──
+    /** The marker a key's announcements begin with, `[server/toolset:instance]`, which a reminder looks for. */
+    label(key) {
+        const { toolset, instance } = splitKey(key);
+        return `[${this.server}${toolset ? `/${toolset}` : ''}${instance ? `:${instance}` : ''}]`;
+    }
+    callHint(key) {
+        const { instance } = splitKey(key);
+        return `${this.names.act} {server:"${this.server}"${instance ? `, instance:"${instance}"` : ''}, tool, args}`;
+    }
+    closeHint(key) {
+        const { toolset, instance } = splitKey(key);
+        if (!toolset)
+            return null;
+        return `${this.names.close} {server:"${this.server}", toolset:"${toolset}"${instance ? `, instance:"${instance}"` : ''}}`;
+    }
+    openHint(toolset, instance) {
+        return `${this.names.open} {server:"${this.server}", toolset:"${toolset}"${instance ? `, instance:"${instance}"` : ''}}`;
+    }
+    /** The tool block for one key: its label, how to call, and the visible tools (new or changed ones described). */
+    toolBlock(key, tools, opts = {}) {
+        const head = opts.headed === false ? '' : `${this.label(key)}${opts.title ? ` ${opts.title}` : ''} `;
+        if (!tools.length)
+            return [`${head}no tools available right now.`];
+        return [`${head}tools now — ${this.callHint(key)}:`, ...renderToolLines(tools, opts.seen ?? this.shown, { describeAll: opts.describeAll })];
+    }
+    /**
+     * What the model reads for a change set. `bare`: a key whose header the
+     * caller already printed. `mark: false` renders without counting the
+     * definitions it describes as shown, for text that may not reach the model
+     * (markShown counts them once it has). `describeAll`: every tool with its
+     * first sentence, as for a result that may reach no agent.
+     */
+    render(cs, opts = {}) {
+        const local = new Set();
+        const seen = opts.mark === false ? { has: (d) => this.shown.has(d) || local.has(d), add: (d) => { local.add(d); } } : this.shown;
+        const lines = [];
+        for (const c of cs.changes) {
+            const bare = opts.bare === c.key;
+            if (c.closed) {
+                lines.push(`${this.label(c.key)} closed.${c.gone.length ? ` Now unavailable: ${c.gone.join(', ')}.` : ''}`);
+                continue;
+            }
+            const title = (c.opened || c.retitled) && !bare ? c.title : undefined;
+            if (showsBlock(c))
+                lines.push(...this.toolBlock(c.key, c.now, { headed: !bare, title, seen, describeAll: opts.describeAll }));
+            else if (title)
+                lines.push(`${this.label(c.key)} ${title}`);
+            if (c.gone.length)
+                lines.push(`now unavailable: ${c.gone.join(', ')}`);
+            if (c.opened && !bare) {
+                const close = this.closeHint(c.key);
+                if (close)
+                    lines.push(`${close} closes it.`);
+            }
+        }
+        for (const s of cs.suggest)
+            lines.push(this.renderSuggestion(s));
+        lines.push(...this.untoldNotes(cs), ...cs.notes);
+        return lines.join('\n');
+    }
+    /** RFC §6.2: a suggestion is shown, never acted on. */
+    renderSuggestion(s) {
+        const what = `${s.toolset}${s.instance ? `:${s.instance}` : ''}`;
+        const how = s.action === 'open' ? this.openHint(s.toolset, s.instance) : this.closeHint(keyOf(s.toolset, s.instance));
+        return `${this.server} suggests ${s.action === 'open' ? 'opening' : 'closing'} ${what}${s.reason ? `: ${s.reason}` : ''} — ${how} if you want to (nothing was done).`;
+    }
+    /** The keys a reminder restates: every open key of this server's view. */
+    openKeys() {
+        return [...this.view().keys()];
+    }
+    /** RFC §8.3 reminder: what is open, its current tools (described), how to call and close it. Null when nothing is open. */
+    reminder() {
+        const v = this.view();
+        if (!v.size)
+            return null;
+        const lines = [];
+        for (const [key, e] of v) {
+            lines.push(...this.toolBlock(key, [...e.tools.values()], { describeAll: true, title: e.title }));
+            const close = this.closeHint(key);
+            if (close)
+                lines.push(`  ${close} closes it.`);
+        }
+        return lines.join('\n');
+    }
+    /** look naming this server: what is open (with tools) and what can be
+     *  opened. `mark: false`, as for render, for a look whose result may
+     *  reach no agent. */
+    catalog(opts = {}) {
+        const lines = [];
+        lines.push(this.surface ? `${this.server} — ${[this.surface.title, this.surface.summary].filter(Boolean).join(': ')}` : this.server);
+        const v = this.view();
+        if (v.size) {
+            for (const [key, e] of v) {
+                lines.push(...this.toolBlock(key, [...e.tools.values()], { describeAll: true, title: e.title, seen: opts.mark === false ? new Set() : undefined }).map((l) => `  ${l}`));
+                const close = this.closeHint(key);
+                if (close)
+                    lines.push(`    ${close} closes it.`);
+            }
+        }
+        else {
+            lines.push('  nothing open');
+        }
+        const openable = [];
+        for (const [name, d] of Object.entries(this.declared)) {
+            if (!d.instances && this.isOpen(name))
+                continue;
+            openable.push(`  ${name}${d.title ? ` — ${d.title}` : ''}${d.summary ? `: ${d.summary}` : ''}` +
+                (d.instances ? ' (several can be open at once; name each with instance)' : '') +
+                (d.options ? ` · options ${objectSignature(d.options)}` : ''));
+        }
+        for (const g of this.undeclaredGroups) {
+            if (this.groups.has(g))
+                continue;
+            const names = this.allTools.filter((t) => this.toolsetOf(t.name) === g).map((t) => t.name);
+            openable.push(`  ${g}: ${names.join(', ')}`);
+        }
+        if (openable.length)
+            lines.push(`can open — ${this.names.open} {server:"${this.server}", toolset, instance?, options?}:`, ...openable);
+        return lines.join('\n');
+    }
+    /** Where a tool can be called from now, for `look` naming it. */
+    toolStatus(tool) {
+        if (this.presenceOf(tool) === 'static')
+            return `static — called by name, as ${this.listedName(tool)}`;
+        const where = [...this.view().entries()].filter(([, e]) => e.tools.has(tool)).map(([k]) => k);
+        const ts = this.toolsetOf(tool);
+        return where.length
+            ? `available now in ${where.map((k) => this.label(k)).join(', ')} — ${this.names.act} {server:"${this.server}", tool:"${tool}"${where.length > 1 ? ', instance' : ''}, args}`
+            : `not available right now${ts ? ` (toolset ${ts})` : ''}`;
+    }
+}
+//# sourceMappingURL=tool-presence.js.map