@datalayer/agent-runtimes 1.5.26 → 1.5.28

package/lib/portable/conversation.d.ts

@@ -1,39 +1,73 @@
 /**
- * A conversation as a run stream builds it, for a client that draws it
- * natively (Datalayer Mobile): one pure reducer over the AG-UI events of an
- * application's session or an agent's run, and the person's own actions.
+ * A conversation as a run stream builds it, for every client that draws one:
+ * the web chat (`ChatBase`) and Datalayer Mobile. One pure reducer over the
+ * AG-UI events of an application's session or an agent's run, the events
+ * every other protocol adapter is normalised into (`portable/adapterEvents`),
+ * and the person's own actions.
  *
- * It reads the stream as the web chat reads it — `TEXT_MESSAGE_*` into one
+ * It reads the stream as the chat reads it — `TEXT_MESSAGE_*` into one
  * message streamed in place, `TOOL_CALL_*` into a collapsed row whose result
  * is read by `toolResultOf`, `STEP_*` into a step row, a `MESSAGES_SNAPSHOT`
- * through `messagesOfThread`, a `reactor.ui` op on the run refused — and adds
- * what a session says besides: `loop.session`, the question its application
- * asks (`RUN_FINISHED` with `result.asking`, LOOP `loop.ask`), and a turn
- * that ended without words said by how it ended (`answered`, `stopped`,
- * `gone`).
+ * (its tool calls and their results too) through `messagesOfThread`, a
+ * `reactor.ui` op on the run refused — and adds what a session says besides:
+ * `loop.session`, the question its application asks (`RUN_FINISHED` with
+ * `result.asking`, LOOP `loop.ask`), and a turn that ended without words said
+ * by how it ended (`answered`, `stopped`, `gone`).
+ *
+ * An adapter that tells a message or a tool call whole rather than by its
+ * deltas — A2A, Vercel AI, ACP, the in-page agent, and the web's AG-UI
+ * adapter, which accumulates — says it with three events of this reducer's
+ * own, never AG-UI's: `MESSAGE_SAID` (a message's words so far),
+ * `TOOL_CALL_SAID` (a call's arguments as an object) and `TOOL_CALL_DONE`
+ * (its result as a value). They are refused when malformed.
  *
  * Bounded: a long tool run cannot grow it without end. Each tool's arguments
- * and result keep their first `TOOL_TEXT_LIMIT` characters, an answer its
- * first `MESSAGE_TEXT_LIMIT`, the conversation its last `ITEM_LIMIT` rows
- * (`dropped` counts the rest), and an event it does not draw is kept only as
- * its type and name, the last `DIAGNOSTIC_LIMIT` of them — never its payload.
+ * and result keep their first `limits.toolText` characters (their values only
+ * when kept whole), an answer its first `limits.messageText`, the
+ * conversation its last `limits.items` rows (`dropped` counts the rest), and
+ * an event it does not draw is kept only as its type and name, the last
+ * `limits.diagnostics` of them — never its payload. A phone keeps
+ * `DEVICE_LIMITS`, a browser `BROWSER_LIMITS`.
  *
  * @module portable/conversation
  */
 import { type AgUiEvent } from './agui';
 import { type ProtocolDisplay } from './displays';
-/** How many rows a conversation keeps: its newest. */
+/** How many rows a conversation on a phone keeps: its newest. */
 export declare const ITEM_LIMIT = 400;
-/** How many characters of an answer are kept. */
+/** How many characters of an answer a phone keeps. */
 export declare const MESSAGE_TEXT_LIMIT = 100000;
-/** How many characters of a tool's arguments, and of its result, are kept. */
+/** How many characters of a tool's arguments, and of its result, a phone keeps. */
 export declare const TOOL_TEXT_LIMIT = 4000;
 /** How many events it does not draw are kept, by type and name. */
 export declare const DIAGNOSTIC_LIMIT = 50;
+/** What a conversation keeps: the bounds of the device that holds it. */
+export type ConversationLimits = {
+    /** Rows: its newest. */
+    items: number;
+    /** Characters of an answer. */
+    messageText: number;
+    /** Characters of a tool's arguments, and of its result. */
+    toolText: number;
+    /** Events it does not draw, by type and name. */
+    diagnostics: number;
+};
+/** A phone's bounds (Datalayer Mobile). */
+export declare const DEVICE_LIMITS: ConversationLimits;
+/** A browser's bounds (the web chat): a long working session, still bounded. */
+export declare const BROWSER_LIMITS: ConversationLimits;
 /** What is said after a text cut at its limit. */
 export declare const CUT_MARK = "\u2026 (cut: too long to keep on this device)";
 /** How a turn ended without words of its own: `RUN_END_WORDS`'s. */
 export type TurnEnd = 'answered' | 'stopped' | 'gone';
+/** What a running tool call waits for: a decision on its approval, or the person's answer. */
+export type ToolAwaiting = 'approval' | 'person';
+/** A Python exception a tool's code raised. */
+export type ToolCodeError = {
+    name: string;
+    value: string;
+    traceback: string;
+};
 /** One row of a conversation. */
 export type ConversationItem = {
     kind: 'message';
@@ -48,10 +82,22 @@ export type ConversationItem = {
     name: string;
     /** Its arguments as they streamed: JSON, cut at its limit. */
     args: string;
+    /** Its arguments read whole, or `null`: not yet whole, or cut. */
+    input: Record<string, unknown> | null;
     status: 'running' | 'complete' | 'error';
+    /** While running, what it waits for; else `null`. */
+    awaiting: ToolAwaiting | null;
     /** Its result in words, cut at its limit. */
     result: string;
+    /** Its result as given, what a renderer draws: `undefined` when none, or when its words were cut. */
+    value: unknown;
     error: string;
+    /** What failed around its code (its sandbox), in words, or `''`. */
+    executionError: string;
+    /** The exception its code raised, or `null`. */
+    codeError: ToolCodeError | null;
+    /** The exit code its code ended with (`sys.exit`), or `null`. */
+    exitCode: number | null;
     /** The protocol display its result carries, read strictly (`portable/displays`, MOBILE M-037). */
     display: ProtocolDisplay | null;
 } | {
@@ -98,13 +144,20 @@ export type ConversationState = {
     }[];
     /** How many rows the turn streaming added: whether it said anything. */
     turnRows: number;
+    /** What it keeps: its device's bounds. */
+    limits: ConversationLimits;
 };
-/** A conversation with nothing in it yet. */
-export declare const emptyConversation: () => ConversationState;
+/** A conversation with nothing in it yet, kept within `limits` (a phone's by default). */
+export declare const emptyConversation: (limits?: ConversationLimits) => ConversationState;
 /** The question an application asks, as `RUN_FINISHED`'s `result.asking` or a session says it. */
 export declare function questionOf(raw: unknown): ConversationQuestion | null;
 /** The person's prompt, added before it is sent: its own row. */
 export declare function withPrompt(state: ConversationState, id: string, words: string): ConversationState;
+/**
+ * The conversation without some of its rows: those the person removed (a
+ * turn taken away), or a message its application took back.
+ */
+export declare function withoutItems(state: ConversationState, ids: Iterable<string>): ConversationState;
 /**
  * The turn ended without the stream saying so: the person stopped it
  * (`stopped`), or its client went before the answer (`gone`). What streamed