@animalabs/agent-framework 0.26.2 → 0.28.0

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

@@ -0,0 +1,251 @@
+/**
+ * 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); a static↔dynamic
+ * move takes effect when a tools/list states it (§4.1), and the model's tool
+ * list shows it at its next rebuild; until then the tool is called at either
+ * place (§4.2). The connection's read tap hands
+ * the controller every result of a hinted request (awaited or not, while no
+ * more than 1,000 hinted requests await an answer), each tools/list whole, every push/event and every tools/hints, of the
+ * current transport, synchronously and in arrival order, before anything
+ * routes the message or anything read after it is handled.
+ * 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, type Presence } 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 or close 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;
+    }): boolean;
+    /** Whether the server's changes may be put into the conversation unasked
+     *  (its `pushEvents` grant): notices and reminders. */
+    canNotify(serverId: string): boolean;
+    /** 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;
+    /** Where the model's published tool list last put a server's tool:
+     *  offered in it (static), listed but not offered (dynamic), or undefined
+     *  where it isn't published. RFC §4.2: until its move applies, a tool
+     *  keeps working where it is. */
+    published?(serverId: string, tool: string): Presence | undefined;
+}
+/** One server's RFC-014 state and traffic. Lives as long as the server's
+ *  configuration, across reconnects and the server's restarts (its `ended`
+ *  ids and what the model was shown carry over), in memory only. */
+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 taken yet, in the order they were read, with their method (tellUnlessClaimed). */
+    private readonly unclaimed;
+    /** eventIds of pushes read on this transport (bounded): a repeat's hints are ignored (RFC §6.1). */
+    private seenEvents;
+    private recoveryTimer;
+    private recovering;
+    private recoverAgain;
+    constructor(serverId: string, config: McplServerConfig, deps: ToolsetHostDeps);
+    private log;
+    private field;
+    private failure;
+    /** 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;
+    release(): 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, after every result's change still unclaimed. */
+    private deliver;
+    /**
+     * Unclaimed carriers' changes, told as notices in the order they were read,
+     * through `upTo` when given. When no notice can be written, a push keeps its
+     * change for the framework's push path, which takes it when the push gets
+     * there; a result's is dropped, whether or not its caller is still to
+     * resume.
+     */
+    private tellUnclaimed;
+    /** Whether a notice was written, there was nothing left to tell (`empty`), or one couldn't be written (`refused`). */
+    private notice;
+    /**
+     * 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, including one the tool
+     * list last published or the server's latest tools/list puts as static
+     * (shownAs: RFC §4.2, until its move applies).
+     */
+    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), or dropped as tellUnclaimed says when none can be written.
+     */
+    private tellUnlessClaimed;
+    /**
+     * The change a carrier's hints made (a tool result, a push's params), taken
+     * by a caller that shows it to an agent with the carrier: it isn't told as a
+     * notice, and the caller says when it has reached an agent (told). Call it
+     * synchronously as the carrier is read, before the next macrotask, when an
+     * unclaimed carrier's change goes out as a notice instead (tellUnclaimed
+     * says what happens when none can be written). A change already gone that
+     * way is empty here. Unclaimed carriers read before this one
+     * are told first, as notices, so no later change is shown before them.
+     */
+    takeChange(carrier: unknown): ChangeSet;
+    /** A change its taker showed to an agent: its ended records count as told, and the definitions it describes as shown, unless the taker showed it without its blocks (`blocksShown: false`). */
+    told(cs: ChangeSet): void;
+    /** A change its taker couldn't show, told as a notice instead, or dropped when none can be written. */
+    tell(cs: ChangeSet): void;
+    private changeOf;
+    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, unless tools/list failed: a tool the last list
+     * lacks then stays unknown until a later change or list starts a recovery.
+     * Each applies where it's read. What
+     * changed is told. (stdio and WebSocket deliver in order, so no early rev is
+     * held.)
+     */
+    private recover;
+    /** The tap applies the list and tells its change as it's read. */
+    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. Returns what the re-read changed, taken from the notice it
+     * would otherwise get when `shown` (its result reaches an agent): look then
+     * either shows it (told) or hands it back (tell). Otherwise the change is
+     * left to its notice, and returned to be shown to the caller alone. Null
+     * when nothing was read.
+     */
+    refreshOpen(opts: {
+        shown: boolean;
+    }): Promise<ChangeSet | null>;
+    /** toolsets/open (RFC §5.2). The server's refusal rejects. Its change is
+     *  taken when `shown` (its result reaches an agent), else left to its
+     *  notice and returned for the caller alone; close's is the same. */
+    open(toolset: string, instance: string | undefined, options: Record<string, unknown> | undefined, opts: {
+        shown: boolean;
+    }): Promise<{
+        key: string;
+        title?: string;
+        content: unknown[];
+        change: ChangeSet;
+        adopted: boolean;
+    }>;
+    /** toolsets/close (RFC §5.2). */
+    close(toolset: string, instance: string | undefined, opts: {
+        shown: boolean;
+    }): 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;
+    /** At a rebuild of the model's tool list (RFC §4.2), tell where the tools it moved went: `moves`, those still pending, or every one pending. A move a list has undone since the rebuild listed the server isn't told; the next rebuild publishes the undoing. */
+    applyMoves(moves?: Array<{
+        name: string;
+        to: Presence;
+    }>): void;
+}
+/** 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): its controller lets go of the
+     *  connection it holds, and is forgotten, so a server added later under
+     *  the same id starts from nothing. */
+    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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"}