@animalabs/agent-framework 0.19.0 → 0.21.0

package/dist/src/mcpl/tool-lifecycle.d.ts

@@ -0,0 +1,253 @@
+/**
+ * Tool lifecycle (MCPL RFC-007): `tools/lifecycle` notifications about the
+ * agent's tool calls, and the `tools/observe` filter a server sets on them.
+ *
+ * Authority is the grant plus host narrowing; a server's filter is interest
+ * and only ever narrows. Per call and connection the host decides, in order
+ * (RFC-007 §6.4):
+ *
+ *   1. reported at all?     grant `toolLifecycle.observe` + its narrowing
+ *   2. reported to this server?  filter: first matching rule and its `report`
+ *                           (no filter → yes)
+ *   3. arguments requested? that rule's `input` (no filter → NO)
+ *   4. arguments allowed?   grant `toolLifecycle.inputs` + its narrowing,
+ *                           and never for `comms` or unclassed tools
+ *   5. which fields, how large?  the rule's field selection, then the bound
+ *
+ * Tool RESULTS are never carried — no field for them exists here.
+ *
+ * Delivery is best-effort like `inference/lifecycle` (SPEC §10.5): one
+ * terminal is attempted per opened call, to exactly the connections the
+ * opening went to, unless their grant or narrowing no longer covers the call
+ * (RFC-007 §4.5). A filter change never suppresses a terminal (§6.5).
+ */
+import { CapabilityGrant } from './capability-grant.js';
+import { type ToolClass } from './tool-classes.js';
+export declare const TOOL_LIFECYCLE_OBSERVE = "toolLifecycle.observe";
+export declare const TOOL_LIFECYCLE_INPUTS = "toolLifecycle.inputs";
+export type ToolPhase = 'pending' | 'started' | 'completed' | 'failed' | 'aborted';
+/** `tools/lifecycle` params (Host → Server, Notification). RFC-007 §3. */
+export interface ToolLifecycleParams {
+    toolCallId: string;
+    inferenceId: string;
+    conversationId: string;
+    tool: string;
+    class: ToolClass[];
+    serverId?: string;
+    serverTool?: string;
+    phase: ToolPhase;
+    input?: Record<string, unknown>;
+    inputAltered?: boolean;
+    inputWithheld?: boolean;
+    isError?: boolean;
+    durationMs?: number;
+}
+export interface ToolObserveMatch {
+    tool?: string;
+    serverTool?: string;
+    serverId?: string;
+    conversationId?: string;
+    class?: ToolClass;
+}
+/** One normalized `tools/observe` rule (RFC-007 §6.1). */
+export interface ToolObserveRule {
+    match: ToolObserveMatch;
+    report: boolean;
+    /** false = metadata only; true = all arguments; string[] = field paths. */
+    input: boolean | string[];
+}
+/**
+ * A narrowing attached to one `toolLifecycle.*` grant entry (RFC-007 §4.3).
+ * A call is inside it when it satisfies EVERY key stated. Patterns use the
+ * RFC-007 §6.2 grammar.
+ */
+export interface ToolLifecycleNarrowing {
+    /** Patterns over the model-facing tool name (`computer--*`). */
+    tools?: string[];
+    /** The tool's effective class must intersect this set. `'default'` is
+     *  DEFAULT_INPUT_CLASSES (computer, shell, files, web, media, body). */
+    classes?: ToolClass[] | 'default';
+    /** Patterns over `conversationId` (the agent name in this host). */
+    conversations?: string[];
+}
+/**
+ * Per-server tool-lifecycle policy (`McplServerConfig.toolLifecycle`).
+ *
+ * Both capability paths are DENIED BY DEFAULT. Stating `observe` (even as
+ * `{}`) or `inputs` here is the operator's explicit grant of that path, as
+ * is naming it in `enabledCapabilities`. `inputs` is never unconditional:
+ * without at least one `tools` or `classes` term it delivers no arguments
+ * (RFC-007 §4.3).
+ */
+export interface ToolLifecycleConfig {
+    observe?: ToolLifecycleNarrowing;
+    inputs?: ToolLifecycleNarrowing;
+    /** Serialized-size bound for `input` per notification. Default 16 KiB. */
+    maxInputBytes?: number;
+}
+export declare const DEFAULT_MAX_INPUT_BYTES: number;
+/** Accepted sizes for a `tools/observe` request (RFC-007 §6.6 asks hosts to
+ *  accept at least 64 rules, 64 paths per rule, 256-code-point strings). */
+export declare const TOOL_OBSERVE_LIMITS: {
+    readonly rules: 256;
+    readonly pathsPerRule: 256;
+    readonly stringLength: 256;
+};
+export type ToolObserveParseResult = {
+    ok: true;
+    rules: ToolObserveRule[] | null;
+} | {
+    ok: false;
+    message: string;
+    data?: Record<string, unknown>;
+};
+/**
+ * Validate `tools/observe` params. `rules` absent or null clears the filter
+ * (`{ok, rules: null}`); `[]` is a valid filter that reports nothing. Unknown
+ * members are REJECTED, not ignored: ignoring an unknown `match` member would
+ * make a rule match more than its author wrote.
+ */
+export declare function parseToolObserveParams(params: unknown): ToolObserveParseResult;
+/** What the host knows about one call, shared by every connection. */
+export interface ToolCallDescriptor {
+    /** Host-unique on every connection (RFC-007 §3). */
+    toolCallId: string;
+    inferenceId: string;
+    conversationId: string;
+    tool: string;
+    class: ToolClass[];
+    serverId?: string;
+    serverTool?: string;
+    input: unknown;
+}
+/**
+ * `observe` narrowing: absent means no narrowing (the grant is enough). A
+ * value that is not a narrowing object (`false`, `null`, a string) admits
+ * nothing: a setting that looks like "off" must never read as "everything".
+ */
+export declare function observeAdmits(config: ToolLifecycleConfig | undefined, call: ToolCallDescriptor): boolean;
+/**
+ * Does `inputs` narrowing say this call has no tool/class term at all? Such
+ * an entry is unconditional and therefore treated as narrowed to NO tools
+ * (RFC-007 §4.3 — the widest form is not producible by omission).
+ */
+export declare function inputsNarrowingIsUnconditional(n: ToolLifecycleNarrowing | undefined): boolean;
+/** Class exclusions that no narrowing overrides (RFC-007 §4.3, §5.4). */
+export declare function inputsExcludedByClass(call: ToolCallDescriptor): boolean;
+export declare function inputsAdmit(config: ToolLifecycleConfig | undefined, call: ToolCallDescriptor): boolean;
+export declare function ruleMatches(match: ToolObserveMatch, call: ToolCallDescriptor): boolean;
+/**
+ * Select field paths from an arguments object. `.` descends into nested
+ * objects; a path ending on an object or array selects it whole; a path that
+ * passes through a non-object or names a missing member selects nothing.
+ * Selected members keep their place in the structure. Only OWN properties
+ * are read and the output is built from null-prototype objects, so a path
+ * like `__proto__.x` can neither read nor write a prototype.
+ */
+export declare function selectFields(input: Record<string, unknown>, paths: readonly string[]): Record<string, unknown>;
+/**
+ * Bound `value` to `maxBytes` of serialized JSON (RFC-007 §5.2): first by
+ * replacing the longest strings with prefixes of themselves, then by removing
+ * the largest members. The result is always a JSON object. Returns null when
+ * nothing meaningful fits — the caller withholds instead.
+ */
+export declare function boundInput(value: Record<string, unknown>, maxBytes: number): {
+    value: Record<string, unknown>;
+    altered: boolean;
+} | null;
+/** What the emitter needs from a connection. */
+export interface ToolLifecycleObserver {
+    id: string;
+    grant?: CapabilityGrant;
+    toolObserveFilter?: ToolObserveRule[] | null;
+    /** Increments at every transport boundary (reconnect). Terminals go only
+     *  to the epoch the opening went to. Absent = 0. */
+    transportEpoch?: number;
+    sendToolLifecycle(params: ToolLifecycleParams): void;
+}
+/**
+ * The opening notification (`pending` or `started`) this connection should
+ * receive for `call`, or null when it receives nothing. Steps 1–5 of
+ * RFC-007 §6.4.
+ */
+export declare function openingFor(observer: ToolLifecycleObserver, config: ToolLifecycleConfig | undefined, call: ToolCallDescriptor, phase: 'pending' | 'started'): ToolLifecycleParams | null;
+/** Does this connection still get the terminal for a call it was opened to? */
+export declare function terminalStillAllowed(observer: ToolLifecycleObserver, config: ToolLifecycleConfig | undefined, call: ToolCallDescriptor): boolean;
+export interface ToolLifecycleHost {
+    /** Every live connection that might observe. */
+    observers(): Iterable<ToolLifecycleObserver>;
+    /** Host policy for one connection. */
+    configFor(serverId: string): ToolLifecycleConfig | undefined;
+    /** Class and provider for a model-facing tool name. */
+    describe(tool: string): {
+        class: ToolClass[];
+        serverId?: string;
+        serverTool?: string;
+    };
+}
+export declare class ToolLifecycleEmitter {
+    private readonly host;
+    private readonly now;
+    /** Opened calls awaiting their terminal, keyed by (agent, model call id). */
+    private readonly calls;
+    private readonly recentIds;
+    private readonly recentOrder;
+    private mintSeq;
+    constructor(host: ToolLifecycleHost, now?: () => number);
+    /** Nothing observes: skip all work on the hot path. */
+    private anyObserver;
+    /**
+     * A host-unique id for a call (RFC-007 §3): the model's own only where the
+     * provider guarantees it unique and it was not reported recently; minted
+     * otherwise. Minted ids carry a per-process counter, so they never repeat.
+     */
+    private hostCallId;
+    /**
+     * A model-issued call is about to be dispatched. Recorded, keyed by
+     * (agent, model call id) — never matched through the trace stream, so two
+     * agents' identical short ids cannot cross — but nothing is sent yet: the
+     * host may still refuse it (refuse()) before it executes.
+     */
+    register(agentName: string, inferenceId: string, call: {
+        id: string;
+        name: string;
+        input: unknown;
+    }): void;
+    /**
+     * The host refused the call before executing it — its provider is gone,
+     * host tool policy denies it, a conversation-bound agent reached outside
+     * its channel. Called from the refusal site itself, synchronously within
+     * dispatch, so the call is forgotten before open() would send anything:
+     * a refused call produces no events (RFC-007 §3).
+     */
+    refuse(agentName: string, callId: string): void;
+    /**
+     * Dispatch returned and the call was not refused: execution has begun.
+     * Send `started` to every connection that should see it. Refusal sites
+     * run synchronously inside dispatch, before this.
+     */
+    open(agentName: string, callId: string): void;
+    /**
+     * The host could not obtain a result for this call (its dispatch threw,
+     * the provider's transport failed, the request timed out). Its terminal
+     * will be `failed`. An error RESULT returned by the tool is not this: it
+     * is `completed` with `isError` (RFC-007 §3).
+     */
+    markDispatchFailure(agentName: string, callId: string): void;
+    private terminate;
+    /** A tool result reached the host: the call's terminal. */
+    onResult(agentName: string, callId: string, result: {
+        success?: boolean;
+        isError?: boolean;
+    } | undefined): void;
+    /**
+     * A stream ended: its calls still open were cancelled before a result.
+     * Scoped to the inference ids that stream minted, so a successor stream
+     * for the same agent (a budget restart overlapping this one's teardown)
+     * keeps its live calls. A result arriving later finds nothing.
+     */
+    abortOpen(agentName: string, inferenceIds: Iterable<string>): void;
+    /** For tests and diagnostics. */
+    get openCount(): number;
+}
+//# sourceMappingURL=tool-lifecycle.d.ts.map

package/dist/src/mcpl/tool-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-lifecycle.d.ts","sourceRoot":"","sources":["../../../src/mcpl/tool-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,OAAO,EAAsC,KAAK,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEvF,eAAO,MAAM,sBAAsB,0BAA0B,CAAC;AAC9D,eAAO,MAAM,qBAAqB,yBAAyB,CAAC;AAM5D,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEnF,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAED,0DAA0D;AAC1D,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,gBAAgB,CAAC;IACxB,MAAM,EAAE,OAAO,CAAC;IAChB,2EAA2E;IAC3E,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAAC;CAC3B;AAMD;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;4EACwE;IACxE,OAAO,CAAC,EAAE,SAAS,EAAE,GAAG,SAAS,CAAC;IAClC,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,sBAAsB,CAAC;IACjC,MAAM,CAAC,EAAE,sBAAsB,CAAC;IAChC,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,eAAO,MAAM,uBAAuB,QAAY,CAAC;AAEjD;4EAC4E;AAC5E,eAAO,MAAM,mBAAmB;;;;CAItB,CAAC;AAMX,MAAM,MAAM,sBAAsB,GAC9B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,eAAe,EAAE,GAAG,IAAI,CAAA;CAAE,GAC7C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC;AAmBnE;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,OAAO,GAAG,sBAAsB,CAiF9E;AAMD,sEAAsE;AACtE,MAAM,WAAW,kBAAkB;IACjC,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;CAChB;AA2BD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,SAAS,EAAE,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAKxG;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAAC,CAAC,EAAE,sBAAsB,GAAG,SAAS,GAAG,OAAO,CAK7F;AAED,yEAAyE;AACzE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAEvE;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,mBAAmB,GAAG,SAAS,EAAE,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAKtG;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAWtF;AAYD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA+B9G;AAiCD;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,QAAQ,EAAE,MAAM,GACf;IAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CA+B7D;AAMD,gDAAgD;AAChD,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,iBAAiB,CAAC,EAAE,eAAe,EAAE,GAAG,IAAI,CAAC;IAC7C;wDACoD;IACpD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAAC;CACtD;AAcD;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,qBAAqB,EAC/B,MAAM,EAAE,mBAAmB,GAAG,SAAS,EACvC,IAAI,EAAE,kBAAkB,EACxB,KAAK,EAAE,SAAS,GAAG,SAAS,GAC3B,mBAAmB,GAAG,IAAI,CAkC5B;AAED,+EAA+E;AAC/E,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,qBAAqB,EAC/B,MAAM,EAAE,mBAAmB,GAAG,SAAS,EACvC,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAET;AAMD,MAAM,WAAW,iBAAiB;IAChC,gDAAgD;IAChD,SAAS,IAAI,QAAQ,CAAC,qBAAqB,CAAC,CAAC;IAC7C,sCAAsC;IACtC,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAAC;IAC7D,uDAAuD;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,SAAS,EAAE,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACxF;AA0BD,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoB;IACzC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,6EAA6E;IAC7E,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkC;IACxD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgB;IAC5C,OAAO,CAAC,OAAO,CAAK;gBAER,IAAI,EAAE,iBAAiB,EAAE,GAAG,GAAE,MAAM,MAAiB;IAKjE,uDAAuD;IACvD,OAAO,CAAC,WAAW;IAOnB;;;;OAIG;IACH,OAAO,CAAC,UAAU;IAalB;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IA0B1G;;;;;;OAMG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAM/C;;;;OAIG;IACH,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAyB7C;;;;;OAKG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAK5D,OAAO,CAAC,SAAS;IAoBjB,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,SAAS,GAAG,IAAI;IAa/G;;;;;OAKG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,IAAI;IAWlE,iCAAiC;IACjC,IAAI,SAAS,IAAI,MAAM,CAEtB;CACF"}