@animalabs/agent-framework 0.26.2 → 0.28.0

package/dist/src/tool-result-history.d.ts

@@ -9,24 +9,101 @@
  * `maxChars` slice and re-introduces, one turn deferred, exactly the silent
  * hallucination this feature exists to kill.
  *
- * For MCP-shaped content arrays, this helper keeps text blocks verbatim,
- * apart from a lone UTF-16 surrogate, which becomes U+FFFD (#695), and
- * replaces image blocks with a short `[image: mimeType, ~NKB]` placeholder.
- * A string is already text and is kept as it is. For anything else it falls
- * back to JSON, written by RFC-005's rules at every depth (historyJson): a
- * reference is shown as its stub wherever it sits in the data, so its uri
- * never reaches history, and inline data that claims a uri or a disposition
- * is withheld.
+ * A content array (toolResultBlocks) is shown block by block, each block as
+ * both copies show it: text verbatim, apart from a lone UTF-16 surrogate,
+ * which becomes U+FFFD (#695), an image as a short
+ * `[image: mimeType, ~NKB]` placeholder, a reference as its stub, and any
+ * other block as a marker saying what it was and why it isn't shown. Anything
+ * else falls back to JSON, written by RFC-005's rules at every depth
+ * (historyJson): a reference is shown as its stub wherever it sits in the
+ * data, so its uri reaches history only as a link's line shows it where the
+ * host can't fetch the link and its uri can't carry a credential
+ * (shownLinkUri), and inline data that claims a uri or a disposition is
+ * withheld. A string is already text and is kept as it is.
  */
+import { type ResultClaims, type ScriptLine } from './mcpl/references.js';
 /** Where one block of a content array sits in its history text, and what
  *  kind of block it was: text, an inline image (its placeholder), an RFC-005
- *  reference (its stub), or inline data withheld for a contradiction. */
+ *  reference (its stub), inline data withheld for a contradiction, or a
+ *  marker in place of a block the lane can't show. */
 export interface HistoryBlockSpan {
-    kind: 'text' | 'image' | 'reference' | 'withheld';
+    kind: ToolResultBlock['kind'];
     start: number;
     end: number;
 }
+/**
+ * Whether a tool result's live copy goes as native blocks, an image among
+ * them, rather than as its stored text. It does when the result holds an
+ * image and its links' blocks and markers come to no more than `maxChars`
+ * together. Past that, the live copy is the stored text, cut at the cap, so
+ * no number of links and markers carries a result past it. A reference's
+ * stub and a withheld line go whole beside an image whatever their length,
+ * and past its cut the stored copy keeps the newest 64 image slots the live
+ * copy showed (#403). Text blocks don't count either: the native copy cuts
+ * each at the cap on its own. Both copies decide by this, from each block's
+ * kind and the length of its text.
+ */
+export declare function goesNative(blocks: ReadonlyArray<{
+    kind: ToolResultBlock['kind'];
+    length: number;
+}>, maxChars: number | undefined): boolean;
+/**
+ * One block of a tool result's content array as both of its copies show it
+ * (toolResultBlocks): a text block's text, an inline image, which the stored
+ * copy shows as its placeholder and the live copy as itself, or the text that
+ * stands in its place, the same in both. That text is a reference's stub, a
+ * link's stub or line (MCP's resource_link, `link`), inline data withheld for
+ * a contradiction, or a marker saying what kind of block it was and why the
+ * lane can't show it.
+ */
+export type ToolResultBlock = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'image';
+    data: string;
+    mimeType: string;
+} | {
+    kind: 'reference' | 'link' | 'withheld' | 'marker';
+    text: string;
+};
+/**
+ * Each element of `data` as both copies of a tool result show it, or null
+ * when `data` isn't a content array, so the result is data, written as JSON.
+ * An array is content when the result says so (`dataIsContent`, which the
+ * framework sets on an MCPL tool's result: every element of a protocol
+ * result's content is a block, of a type the host shows or not). Otherwise
+ * it's content only when every element is a block of one of MCP's own types,
+ * so a list of records of other types stays data. A module's array of
+ * records that all carry MCP's type names, such as `[{ type: 'image', url }]`,
+ * is read as content, and shows a marker for each record that isn't a block
+ * the lane can show.
+ */
+export declare function toolResultBlocks(data: unknown, dataIsContent?: boolean, claims?: ResultClaims): ToolResultBlock[] | null;
+/** Whether a tool result's data is a content array, which toolResultBlocks
+ *  shows block by block. */
+export declare function isContentArray(data: unknown, dataIsContent?: boolean): data is unknown[];
+/**
+ * The claims of a tool result's data (ResultClaims), as showing it reads
+ * them: a content array's from its elements (contentClaims), and any other
+ * data's by the walk serialization takes (claimsInHistory). For a decision
+ * made about the result outside showing it, such as which of its references
+ * to fetch, or for showing part of it as the rest of it claims. Null where a
+ * value stops the walk, so what the data claims is unknown (claimsInHistory).
+ */
+export declare function resultClaimsOf(data: unknown, dataIsContent?: boolean): ResultClaims | null;
+/** resultClaimsOf, throwing what stops the walk, for a caller that answers
+ *  a stop itself: a script's text route, which fails then, as its view does
+ *  (Ada-1017, room-203 #200374). */
+export declare function resultClaimsOrThrow(data: unknown, dataIsContent?: boolean): ResultClaims;
 export interface HistorySerializeOptions {
+    /**
+     * Whether the result's data is a protocol result's content
+     * (ToolResult.dataIsContent), so an array is shown block by block whatever
+     * its blocks' types (toolResultBlocks). nonErrorResultText takes it from
+     * the result instead, whatever this says.
+     */
+    dataIsContent?: boolean;
     /**
      * Called for every image block the serializer replaces with a placeholder
      * (issue #104). Returns the retention ref to embed in the placeholder —
@@ -40,10 +117,23 @@ export interface HistorySerializeOptions {
     /**
      * Called once a content array has been serialized block by block, rather
      * than given up on for the fallback, with where each block sits in the
-     * joined text, before any cut at `maxChars`. The framework reads from it
-     * what a result's live copy showed (#403).
+     * joined text, before any cut at `maxChars`, and the blocks themselves as
+     * this text was made from them. The framework reads from it what a
+     * result's live copy shows (#403), and builds that copy from these very
+     * blocks, so the two copies come from one classification.
+     */
+    onBlocks?: (spans: HistoryBlockSpan[], blocks: ToolResultBlock[]) => void;
+    /**
+     * The claims to read (ResultClaims) in place of the data's own, where the
+     * data shown is part of a larger result whose claims these are
+     * (resultClaimsOf), such as the fields a withheld result keeps.
      */
-    onBlocks?: (spans: HistoryBlockSpan[]) => void;
+    claims?: ResultClaims;
+    /**
+     * Whose result this is, as nonErrorResultText's log line names it where it
+     * shows UNCHECKED_RESULT_TEXT for a result it couldn't read or show.
+     */
+    toolName?: string;
 }
 /**
  * House-safe default inline cap (chars) for tool results, error results, and
@@ -72,6 +162,11 @@ export declare function toolResultDataToHistoryString(data: unknown, maxChars?:
  *
  * Each field is read once: the direct Agent API passes its caller's own
  * result here, unchecked, and a getter needn't answer the same way twice.
+ * Whatever stops reading or showing the data is UNCHECKED_RESULT_TEXT, with
+ * a log line naming the tool (`options.toolName`) and the error: the model's
+ * lane has no failure answer that doesn't wedge the round.
+ * Whether an array is content is the result's own `dataIsContent`, read for
+ * its truth as a result's flags are, whatever `options` says.
  *
  * Each text a tool result's copies carry is made well formed where it's
  * taken from the result: a lone UTF-16 surrogate becomes U+FFFD, as the
@@ -84,6 +179,18 @@ export declare function toolResultDataToHistoryString(data: unknown, maxChars?:
 export declare function nonErrorResultText(result: {
     data?: unknown;
     error?: string;
+    dataIsContent?: boolean;
+}, maxChars?: number, options?: HistorySerializeOptions): string;
+/**
+ * nonErrorResultText's text, throwing whatever stops reading or showing the
+ * result, such as a stopped claims walk (historyJson), for a caller that
+ * answers a stop itself: a script's routes, which fail naming the tool
+ * (Ada-1017, room-203 #200374), never the model lane's notice.
+ */
+export declare function nonErrorResultTextOrThrow(result: {
+    data?: unknown;
+    error?: string;
+    dataIsContent?: boolean;
 }, maxChars?: number, options?: HistorySerializeOptions): string;
 /** Bounded copy of an arbitrary string with the standard truncation notice,
  *  cut at the cap where a tool result's stored copy is cut at that cap
@@ -98,16 +205,40 @@ export declare function truncateForHistory(str: string, maxChars: number): strin
  * A value of a tool result's data as a script reads it, by history's rules
  * (shownInHistory), as a JSON replacer applies them at every depth: what
  * RFC-005 governs is shown as the script lane shows it, a reference as its
- * stub's facts without its uri and an invalid one as the notice
- * (referenceBlockForScript), and inline data that also claims a uri of any
- * type or a disposition as the withheld notice, each as a text block. A
- * null, absent or empty uri claims none (hasUri), so inline data beside one
- * is itself. Any
- * other value is itself. What it gives is either a stub or a notice, which
- * RFC-005 doesn't govern, or the value itself, which it gives again, so
- * applying it twice gives what applying it once gave.
+ * stub's facts, a link's uri among them only where the model's line for it
+ * would show it, an invalid one as the notice, and MCP's embedded resource as
+ * the block its contents make (referenceBlockForScript), and inline data
+ * that also claims a uri of any type or a disposition as the withheld
+ * notice, each notice as a text block. A null, absent or empty uri claims
+ * none (hasUri), so inline data beside one is itself. Any other value is
+ * itself. `claims` are those of everything the script's view shows
+ * (scriptViewClaims), and `line` the model's line for the result, its claims
+ * and its records as it reads them (ScriptLine), which decide where a link's
+ * uri is shown. What it gives is either a stub, a notice or a text block,
+ * which RFC-005 doesn't govern, or inline data that claims nothing, or the
+ * value itself, each of which it gives again, so applying it twice gives
+ * what applying it once gave.
+ */
+export declare function shownToScript(value: unknown, claims?: ResultClaims, line?: ScriptLine): unknown;
+/**
+ * The claims (ResultClaims) of everything a script's view of a content array
+ * shows, nested fields included (Ada-1017, room-203 #200094), by the walk
+ * history's JSON takes (claimsInHistory): a script is shown the references
+ * nested in a block's fields, each as its stub, so a `never` among them
+ * withholds that uri from every block in the view. A link's uri is still
+ * shown only where the model's line shows it, by the claims the line reads
+ * (contentClaims, which reads a block and not its fields): reading more
+ * claims can loosen as well as tighten, since an expiry makes a link one the
+ * host can't fetch (referenceBlockForScript's `line`). An MCPL peer's
+ * top-level block the classifier rejects is
+ * its notice, its fields unshown, so they don't count (`fromServer`). It
+ * throws what stops the walk, such as a value too deep to convert or a
+ * getter that throws, and the script's view then isn't written: the
+ * treatment never runs without the claims it reads (Ada-1017, room-203
+ * #200250), whether or not its own walk, with other replacers and so other
+ * stack depths, would stop at the same value.
  */
-export declare function shownToScript(value: unknown): unknown;
+export declare function scriptViewClaims(content: readonly unknown[], fromServer: boolean): ResultClaims;
 /**
  * A value nested in an MCPL peer's content block as a script reads it, as a
  * JSON replacer applies it inside the blocks: what RFC-005 governs
@@ -117,12 +248,33 @@ export declare function shownToScript(value: unknown): unknown;
  * peer's block (referenceBlockForScript), its reference bound to the server
  * that sent it, and any other value is itself. A stub or a notice isn't
  * governed, so a block the top-level pass already treated is left as it is.
+ * `claims` are those of the script's whole view (scriptViewClaims).
  */
-export declare function shownToScriptFromServer(value: unknown, serverId: string): unknown;
+export declare function shownToScriptFromServer(value: unknown, serverId: string, claims?: ResultClaims, line?: ScriptLine): unknown;
 /**
  * The text RFC-005 shows a value of a tool result's data as, when it shows it
  * as text rather than as its fields: a reference's stub, an invalid one's
- * unrecognized-block line, or inline data withheld. Null for any other value.
+ * marker, inline data withheld, or what an embedded resource's stored copy
+ * shows. Null for any other value.
  */
 export declare function rfc005TextOf(value: unknown): string | null;
+/**
+ * What the model's lane shows for a tool result it couldn't read through,
+ * check for references and show (nonErrorResultText, the lane's one catch,
+ * which logs the tool and the error): the tool ran, and its result isn't
+ * shown, rather than shown with fewer claims, where a link could show a uri a
+ * reference in the result withholds, and rather than a throw, which would
+ * leave the round unstored and unsent. Where the walk of its claims stops
+ * (historyJson throws then), the claims walk meets data no JSON can hold,
+ * such as a cycle or a BigInt, or data too deep to write, before the render
+ * does, so such data shows this, where the render threw (Desmond-2579's
+ * run); so does a render that stops after the walk, or a getter that throws
+ * (Ada-1017, room-203 #200344, #201013). The round completes, as a withheld
+ * result's kept fields keep nothing then (keptWhenWithheld). A script never
+ * gets it: its routes call the serializer, or nonErrorResultTextOrThrow,
+ * directly, whose walk throws where it stops, and fail naming the tool
+ * (#200374). An error result's own error field is read as before, and so
+ * are the fields the tool-result guard keeps of a result it withholds.
+ */
+export declare const UNCHECKED_RESULT_TEXT = "[Result not shown: the tool ran, but its result couldn't be read through, checked for references and shown, so this host withheld it.]";
 //# sourceMappingURL=tool-result-history.d.ts.map

package/dist/src/tool-result-history.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-result-history.d.ts","sourceRoot":"","sources":["../../src/tool-result-history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH;;yEAEyE;AACzE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,WAAW,GAAG,UAAU,CAAC;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,MAAM,GAAG,IAAI,CAAC;IAC5F;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,EAAE,KAAK,IAAI,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,oCAAoC,QAAQ,CAAC;AAE1D,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,OAAO,EACb,QAAQ,CAAC,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,uBAAuB,GAChC,MAAM,CAgBR;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EAC1C,QAAQ,CAAC,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,uBAAuB,GAChC,MAAM,CAUR;AAED;;;;;;;iCAOiC;AACjC,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGxE;AAwGD;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAQrD;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAIjF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAG1D"}
+{"version":3,"file":"tool-result-history.d.ts","sourceRoot":"","sources":["../../src/tool-result-history.ts"],"names":[],"mappings":"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"}