@animalabs/agent-framework 0.26.1 → 0.27.0

package/dist/src/mcpl/toolset-host.d.ts

@@ -0,0 +1,200 @@
+/**
+ * MCPL RFC-014, host side: per server, the controller that feeds the
+ * server's tool presence (tool-presence.ts) from what its connection reads,
+ * sends toolsets/open, close and list, recovers from a lost rev, and renders
+ * what changed; and the hub that holds every server's controller for the
+ * meta-tools (toolsets-module.ts) and for reminders.
+ *
+ * Hint changes apply as their message is read (RFC §6.1): the connection's
+ * read tap hands the controller every result of a hinted request (awaited or
+ * not), every push/event and every tools/hints, of the current transport,
+ * synchronously and in arrival order, before anything routes the message.
+ * What a message's changes did to the model's view is kept by the object
+ * that carried them (`readChanges`), so whoever later handles that object
+ * (the tool result, the push, the meta-tool) renders it next to the content.
+ *
+ * Reminders (RFC §8.3): after each compile built to send, the hub reads
+ * which open toolsets' markers (`[server/toolset:instance]`) the request
+ * carried. A marker an agent has had in view, gone from a later request
+ * (compressed, or out of the window), makes a reminder due for that agent,
+ * which the toolsets module gathers at its next start as a stored
+ * `afterUser` injection.
+ */
+import type { McplServerConnection } from './server-connection.js';
+import type { McplServerConfig } from './types.js';
+import { ToolPresence, type ChangeSet, type MetaToolNames } from './tool-presence.js';
+/** The meta-tools' module, whose tools are `toolsets--open` and so on. */
+export declare const TOOLSETS_MODULE = "toolsets";
+export declare const META_TOOL_NAMES: MetaToolNames;
+/** How long an open, close or call is waited for. A late result still applies when it's read. */
+export declare const TOOLSET_REQUEST_TIMEOUT_MS = 60000;
+export interface ToolsetHostDeps {
+    /** A standalone notice into the conversation: a tools/hints change, a late
+     *  result's, a reconnect's adoption, a recovery's. `invite`: it suggests an
+     *  open. The host applies its usual rules for events. */
+    notify(serverId: string, text: string, opts: {
+        invite: boolean;
+    }): void;
+    /** The operator's log. */
+    log(line: string): void;
+    /** How a static tool is named in the tool list (`prefix--tool`). */
+    listedName(serverId: string, tool: string): string;
+}
+/** One server's RFC-014 state and traffic. Lives as long as the server's
+ *  configuration, across reconnects and restarts (its `ended` ids and what
+ *  the model was shown carry over). */
+export declare class ToolsetController {
+    readonly serverId: string;
+    private config;
+    private readonly deps;
+    readonly presence: ToolPresence;
+    private connection;
+    /** The transport epoch the presence's revs belong to. */
+    private epoch;
+    /** What applying a message's hints changed, by the object that carried them. */
+    private readonly readChanges;
+    /** Results whose change no one has rendered yet (tellUnlessClaimed). */
+    private readonly unclaimed;
+    /** eventIds of pushes read on this transport (bounded): a repeat's hints are ignored (RFC §6.1). */
+    private seenEvents;
+    /** A paged tools/list being read. */
+    private listPages;
+    /** Lists this controller asked for itself, whose change it delivers. */
+    private ownLists;
+    /** What lists read while one of its own was out changed, for it to tell. */
+    private ownListChange;
+    private recoveryTimer;
+    private recovering;
+    private recoverAgain;
+    constructor(serverId: string, config: McplServerConfig, deps: ToolsetHostDeps);
+    private log;
+    /** A restart can bring a new configuration under the same id. */
+    setConfig(config: McplServerConfig): void;
+    /** Tap this connection (a connect or a restart's new one). */
+    attach(connection: McplServerConnection): void;
+    /** The server's connection is gone for good (disconnected, removed). */
+    detach(connection: McplServerConnection): void;
+    /** Whether the meta-tools speak for this server now. */
+    get presents(): boolean;
+    /** The live connection, for a request. */
+    private live;
+    /**
+     * A new transport: revs start over (RFC §6.1), and its advertisement says
+     * whether hints are in effect. Read from the connection, which holds the
+     * advertisement before its transport can deliver anything.
+     */
+    private sync;
+    private onRead;
+    private readResult;
+    /**
+     * The one apply path (RFC §6.1) for a HintChanges from any carrier, as its
+     * message is read. Revs are consecutive: anything but the last + 1 means a
+     * message was lost or misordered, and the host recovers.
+     */
+    private applyHints;
+    /** tools/list, as read: definitions and presence as of its `mcpl/rev`, which takes no rev of its own (RFC §4.1). */
+    private readToolList;
+    /** toolsets/list, as read: a full statement of dynamic-tool state under its own rev (RFC §5.3, §6.1). */
+    private readToolsetList;
+    /** A change with nothing else to ride on, told as a notice. */
+    private deliver;
+    /**
+     * A dynamic tool called by its namespaced name, as if it were listed (a
+     * model imitating an earlier call, a module): refused, so every call into
+     * a toolset goes through act, which knows its instance and gates closed
+     * groups (RFC §5.4, §5.5). Null for any other tool.
+     */
+    dynamicCallRefusal(tool: string, calledAs: string): string | null;
+    /**
+     * An awaited result's change is told by whoever renders that result, when
+     * the result goes to the agent: the model's own call of a tool (its tool
+     * result), a meta-tool. One no one renders by the time the awaiting code has
+     * run (the next macrotask), such as the result of a call the framework makes
+     * itself (a reaction, a send, an accounted side effect), is told as a notice
+     * instead, as a standalone tools/hints is (RFC §6.1: every change reaches the
+     * agent once).
+     */
+    private tellUnlessClaimed;
+    /** What applying `carrier`'s hints changed (a tool result, a push's params),
+     *  rendered, for its handler to show with it; '' for nothing. Taking it
+     *  means it's told there, not as a notice. */
+    changeText(carrier: unknown): string;
+    /** The change a carrier's hints made, or an empty one; taken as changeText's is. */
+    changeOf(carrier: unknown): ChangeSet;
+    private scheduleRecovery;
+    /**
+     * Recovering: re-read tools/list (presence, declared definitions), then
+     * toolsets/list (dynamic-tool state in full), so every tool the statement
+     * names is already known; each applies where it's read. What changed is
+     * told. (stdio and WebSocket deliver in order, so no early rev is held.)
+     */
+    private recover;
+    private ownToolList;
+    private ownToolsetList;
+    /**
+     * After every (re)connect, once its policy has settled (RFC §5.3): tools/list
+     * then toolsets/list, the truth. What the server reports open is adopted
+     * (a game kept across the reconnect); what the host believed open and it
+     * doesn't report is closed, never re-opened here, since opening can start a
+     * new game. What ended meanwhile is told, each `ended` id once.
+     */
+    connected(connection: McplServerConnection): Promise<void>;
+    /**
+     * Re-read what the server holds open (titles, visibility) without telling
+     * it: for look, which restates everything anyway. Returns notes for what
+     * the server no longer holds.
+     */
+    refreshOpen(): Promise<string[]>;
+    /** toolsets/open (RFC §5.2). The server's refusal rejects. */
+    open(toolset: string, instance: string | undefined, options: Record<string, unknown> | undefined): Promise<{
+        key: string;
+        title?: string;
+        content: unknown[];
+        change: ChangeSet;
+        adopted: boolean;
+    }>;
+    /** toolsets/close (RFC §5.2). */
+    close(toolset: string, instance: string | undefined): Promise<{
+        content: unknown[];
+        change: ChangeSet;
+    }>;
+    /** Open or close an undeclared group (RFC §5.4): the host's own act; the server isn't told. */
+    setGroupOpen(group: string, open: boolean): ChangeSet;
+    /**
+     * A manifest re-fetch (RFC §5.1): the `toolsets` domain's declarations, as
+     * the server sent them. A toolset removed ends its instances; a server
+     * that withdraws toolHints is hint-less from then on. What changed is told.
+     */
+    manifestChanged(declarations: Record<string, unknown> | null): void;
+    /** Apply pending static↔dynamic moves (RFC §4.2) at a tool-list boundary, and say where they went. */
+    applyMoves(): string[];
+}
+/** Every server's controller, for the meta-tools and reminders. */
+export declare class ToolsetHub {
+    private readonly deps;
+    private readonly controllers;
+    /** Per agent: the markers it has had in view (seen), and whether a reminder is due. */
+    private readonly seen;
+    private readonly due;
+    constructor(deps: ToolsetHostDeps);
+    /** The controller for a server, made at its first connect. */
+    controllerFor(config: McplServerConfig): ToolsetController;
+    get(serverId: string): ToolsetController | undefined;
+    /** A server's configuration went (removed): forget its controller. */
+    forget(serverId: string): void;
+    all(): ToolsetController[];
+    /** The servers the meta-tools speak for now. */
+    presenting(): ToolsetController[];
+    /** Every open key's marker, across servers. */
+    private openMarkers;
+    /**
+     * A compile built to send for `agentName` (RFC §8.3): which open toolsets'
+     * announcements the request carries. One the agent has had in view and the
+     * request no longer carries (compressed, or out of the window) makes a
+     * reminder due.
+     */
+    observeCompile(agentName: string, messages: readonly unknown[]): void;
+    /** The reminder due for `agentName`, or null when none is. */
+    reminderFor(agentName: string): string | null;
+}
+//# sourceMappingURL=toolset-host.d.ts.map

package/dist/src/mcpl/toolset-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolset-host.d.ts","sourceRoot":"","sources":["../../../src/mcpl/toolset-host.ts"],"names":[],"mappings":"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"}