@datalayer/agent-runtimes 1.5.20 → 1.5.22

package/lib/{protocols → portable}/agUiRefusal.d.ts

@@ -16,7 +16,7 @@
  * Pure, so the hook, the adapter and the tests read a refusal the same way
  * (the repo's jest/vitest rule: rules live outside components).
  *
- * @module protocols/agUiRefusal
+ * @module portable/agUiRefusal
  */
 /** What the page says when an agent's AG-UI address answers nothing. */
 export declare const AG_UI_NOT_ON_RUNTIME: string;

package/lib/{protocols → portable}/agUiRefusal.js

@@ -20,7 +20,7 @@
  * Pure, so the hook, the adapter and the tests read a refusal the same way
  * (the repo's jest/vitest rule: rules live outside components).
  *
- * @module protocols/agUiRefusal
+ * @module portable/agUiRefusal
  */
 /** What the page says when an agent's AG-UI address answers nothing. */
 export const AG_UI_NOT_ON_RUNTIME = 'This agent is not on the runtime the page is addressing: its AG-UI address answered nothing. ' +

package/lib/portable/agui.d.ts

@@ -0,0 +1,72 @@
+/**
+ * An AG-UI run stream as any JavaScript runtime reads it: the
+ * `text/event-stream` frames a run answers, read into AG-UI events, and how a
+ * run is known to have ended. The web chat's `AGUIAdapter` and Datalayer
+ * Mobile read a stream with these, so that a stream is read one way.
+ *
+ * No React, DOM, Node or Reactor module: a phone passes a `fetch` whose
+ * response body streams (Expo's `expo/fetch`).
+ *
+ * @module portable/agui
+ */
+/** One AG-UI event, as a run stream carries it (`type` first, its fields beside it). */
+export type AgUiEvent = {
+    type: string;
+    [field: string]: unknown;
+};
+/** What the page says when a run's stream closes before the run said how it ended. */
+export declare const RUN_CUT_SHORT = "The run stopped before it finished, without an answer or an error: send it again.";
+/**
+ * The name of `reactor.ui` (Reactor's `AGUI_NAME`): its ops come over the
+ * conversation's ui socket, never a run stream (REACTOR_UI RU-W). Held here
+ * so that a reader of a run needs no Reactor module; a test holds it to
+ * Reactor's.
+ */
+export declare const REACTOR_UI_NAME = "reactor.ui";
+/** What the page says when a `reactor.ui` op comes on a run stream. */
+export declare const UI_ON_RUN = "A reactor.ui op came on the run stream: it comes over the ui socket (REACTOR_UI RU-W).";
+/** What is said when the `fetch` given cannot read a response as it streams. */
+export declare const NOT_STREAMING = "This fetch does not stream a response: give one whose response body has getReader (expo/fetch on a phone).";
+/** Whether an event ends a run: the run said how it ended. */
+export declare const endsRun: (event: AgUiEvent) => boolean;
+/**
+ * The `text/event-stream` of a run, read as it arrives: text in, one AG-UI
+ * event out per frame. A frame is its `data:` lines up to a blank line; a
+ * frame whose data is not JSON is handed to `malformed`, never guessed at.
+ */
+export declare class AgUiFrames {
+    private readonly malformed;
+    private buffer;
+    private data;
+    constructor(malformed?: (data: string) => void);
+    /** The events the text completes. */
+    push(text: string): AgUiEvent[];
+    /** The events left when the stream closes: a last frame without its blank line. */
+    end(): AgUiEvent[];
+    private line;
+    private dispatch;
+}
+/** Every event a complete stream's text holds: a stream already read whole. */
+export declare function eventsOfStream(text: string): AgUiEvent[];
+/**
+ * Read a run's stream to its end, each event handed to `onEvent` as it
+ * arrives. Throws `RUN_CUT_SHORT` when the stream closes before the run said
+ * how it ended, and `NOT_STREAMING` for a response that cannot be read as it
+ * streams. An abort ends the reading with the caller's `AbortError`.
+ */
+export declare function readRunStream(response: {
+    body?: unknown;
+}, onEvent: (event: AgUiEvent) => void, malformed?: (data: string) => void): Promise<void>;
+/** A tool's result as a run says it (`TOOL_CALL_RESULT`): what it gave, and whether it failed. */
+export type ToolResultSaid = {
+    /** The result: its JSON read when it is JSON, else its text. */
+    result: unknown;
+    success: boolean;
+    error?: string;
+};
+/**
+ * A tool result's content, read as the chat reads it: JSON when it is JSON,
+ * and failed when the execution result says so (`execution_ok: false`, a
+ * `code_error`, or an `error` without `success`).
+ */
+export declare function toolResultOf(content: unknown): ToolResultSaid;

package/lib/portable/agui.js

@@ -0,0 +1,174 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** What the page says when a run's stream closes before the run said how it ended. */
+export const RUN_CUT_SHORT = 'The run stopped before it finished, without an answer or an error: send it again.';
+/**
+ * The name of `reactor.ui` (Reactor's `AGUI_NAME`): its ops come over the
+ * conversation's ui socket, never a run stream (REACTOR_UI RU-W). Held here
+ * so that a reader of a run needs no Reactor module; a test holds it to
+ * Reactor's.
+ */
+export const REACTOR_UI_NAME = 'reactor.ui';
+/** What the page says when a `reactor.ui` op comes on a run stream. */
+export const UI_ON_RUN = 'A reactor.ui op came on the run stream: it comes over the ui socket (REACTOR_UI RU-W).';
+/** What is said when the `fetch` given cannot read a response as it streams. */
+export const NOT_STREAMING = 'This fetch does not stream a response: give one whose response body has getReader (expo/fetch on a phone).';
+/** Whether an event ends a run: the run said how it ended. */
+export const endsRun = (event) => event.type === 'RUN_FINISHED' || event.type === 'RUN_ERROR';
+/**
+ * The `text/event-stream` of a run, read as it arrives: text in, one AG-UI
+ * event out per frame. A frame is its `data:` lines up to a blank line; a
+ * frame whose data is not JSON is handed to `malformed`, never guessed at.
+ */
+export class AgUiFrames {
+    malformed;
+    buffer = '';
+    data = [];
+    constructor(malformed = () => { }) {
+        this.malformed = malformed;
+    }
+    /** The events the text completes. */
+    push(text) {
+        this.buffer += text;
+        const lines = this.buffer.split(/\r?\n/);
+        this.buffer = lines.pop() ?? '';
+        const events = [];
+        for (const line of lines) {
+            this.line(line, events);
+        }
+        return events;
+    }
+    /** The events left when the stream closes: a last frame without its blank line. */
+    end() {
+        const events = [];
+        if (this.buffer) {
+            this.line(this.buffer, events);
+            this.buffer = '';
+        }
+        this.dispatch(events);
+        return events;
+    }
+    line(line, events) {
+        if (line === '') {
+            this.dispatch(events);
+            return;
+        }
+        if (line.startsWith('data:')) {
+            const value = line.slice('data:'.length);
+            this.data.push(value.startsWith(' ') ? value.slice(1) : value);
+        }
+        // `event:`, `id:`, `retry:` and comments name nothing AG-UI reads.
+    }
+    dispatch(events) {
+        if (!this.data.length) {
+            return;
+        }
+        const data = this.data.join('\n');
+        this.data = [];
+        let parsed;
+        try {
+            parsed = JSON.parse(data);
+        }
+        catch {
+            this.malformed(data);
+            return;
+        }
+        if (parsed &&
+            typeof parsed === 'object' &&
+            typeof parsed.type === 'string') {
+            events.push(parsed);
+        }
+        else {
+            this.malformed(data);
+        }
+    }
+}
+/** Every event a complete stream's text holds: a stream already read whole. */
+export function eventsOfStream(text) {
+    const frames = new AgUiFrames();
+    return [...frames.push(text), ...frames.end()];
+}
+/** A text decoder that keeps a character split between two chunks whole. */
+function decoderOf() {
+    if (typeof TextDecoder === 'undefined') {
+        throw new Error('This JavaScript runtime has no TextDecoder to read a run stream with.');
+    }
+    const decoder = new TextDecoder();
+    return chunk => typeof chunk === 'string' ? chunk : decoder.decode(chunk, { stream: true });
+}
+/**
+ * Read a run's stream to its end, each event handed to `onEvent` as it
+ * arrives. Throws `RUN_CUT_SHORT` when the stream closes before the run said
+ * how it ended, and `NOT_STREAMING` for a response that cannot be read as it
+ * streams. An abort ends the reading with the caller's `AbortError`.
+ */
+export async function readRunStream(response, onEvent, malformed) {
+    const body = response.body;
+    if (!body || typeof body.getReader !== 'function') {
+        throw new Error(NOT_STREAMING);
+    }
+    const reader = body.getReader();
+    const decode = decoderOf();
+    const frames = new AgUiFrames(malformed);
+    let ended = false;
+    const handle = (events) => {
+        for (const event of events) {
+            if (endsRun(event)) {
+                ended = true;
+            }
+            onEvent(event);
+        }
+    };
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            if (value !== undefined) {
+                handle(frames.push(decode(value)));
+            }
+        }
+        handle(frames.end());
+    }
+    finally {
+        reader.releaseLock();
+    }
+    if (!ended) {
+        throw new Error(RUN_CUT_SHORT);
+    }
+}
+/**
+ * A tool result's content, read as the chat reads it: JSON when it is JSON,
+ * and failed when the execution result says so (`execution_ok: false`, a
+ * `code_error`, or an `error` without `success`).
+ */
+export function toolResultOf(content) {
+    let result = content;
+    if (typeof result === 'string') {
+        try {
+            result = JSON.parse(result);
+        }
+        catch {
+            // Words, kept as they are.
+        }
+    }
+    const said = result && typeof result === 'object'
+        ? result
+        : undefined;
+    const failed = said?.execution_ok === false ||
+        said?.code_error != null ||
+        (said?.error != null && !said?.success);
+    if (!failed) {
+        return { result, success: true };
+    }
+    const codeError = said?.code_error;
+    const error = (typeof said?.execution_error === 'string' && said.execution_error) ||
+        (typeof said?.error === 'string' && said.error) ||
+        (codeError
+            ? `${codeError.name || 'Error'}: ${codeError.value || ''}`
+            : undefined);
+    return { result, success: false, error };
+}

package/lib/portable/conversation.d.ts

@@ -0,0 +1,124 @@
+/**
+ * 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.
+ *
+ * It reads the stream as the web 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`).
+ *
+ * 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.
+ *
+ * @module portable/conversation
+ */
+import { type AgUiEvent } from './agui';
+/** How many rows a conversation keeps: its newest. */
+export declare const ITEM_LIMIT = 400;
+/** How many characters of an answer are kept. */
+export declare const MESSAGE_TEXT_LIMIT = 100000;
+/** How many characters of a tool's arguments, and of its result, are kept. */
+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 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';
+/** One row of a conversation. */
+export type ConversationItem = {
+    kind: 'message';
+    id: string;
+    role: 'user' | 'assistant';
+    text: string;
+    /** Its words are still arriving. */
+    streaming: boolean;
+} | {
+    kind: 'tool';
+    id: string;
+    name: string;
+    /** Its arguments as they streamed: JSON, cut at its limit. */
+    args: string;
+    status: 'running' | 'complete' | 'error';
+    /** Its result in words, cut at its limit. */
+    result: string;
+    error: string;
+} | {
+    kind: 'step';
+    id: string;
+    name: string;
+    status: 'running' | 'complete';
+} | {
+    kind: 'end';
+    id: string;
+    end: TurnEnd;
+    words: string;
+} | {
+    kind: 'error';
+    id: string;
+    text: string;
+};
+/** What an application asks the person (`loop.ask`): its kind and what answers it. */
+export type ConversationQuestion = {
+    kind: 'text' | 'choice' | 'form' | 'file';
+    prompt: string;
+    /** A choice's options. */
+    options: string[];
+    /** A form's JSON Schema. */
+    schema: Record<string, unknown> | null;
+    /** A file's kinds. */
+    accept: string[];
+};
+/** A conversation, as the stream and the person built it. */
+export type ConversationState = {
+    items: ConversationItem[];
+    /** A turn is streaming. */
+    running: boolean;
+    /** The session as `loop.session` said it last, or `null` (an agent's run). */
+    session: Record<string, unknown> | null;
+    /** What the application waits for an answer to, or `null`. */
+    asking: ConversationQuestion | null;
+    /** How many of its oldest rows were not kept. */
+    dropped: number;
+    /** The events it does not draw, by type and name only. */
+    diagnostics: {
+        type: string;
+        name: string;
+    }[];
+    /** How many rows the turn streaming added: whether it said anything. */
+    turnRows: number;
+};
+/** A conversation with nothing in it yet. */
+export declare const emptyConversation: () => 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 turn ended without the stream saying so: the person stopped it
+ * (`stopped`), or its client went before the answer (`gone`). What streamed
+ * stops streaming; a turn that said nothing is said by how it ended.
+ */
+export declare function withTurnEnded(state: ConversationState, end: Exclude<TurnEnd, 'answered'>): ConversationState;
+/** A failure said in the conversation (a refusal, a stream cut short): the turn stops with it. */
+export declare function withError(state: ConversationState, words: string): ConversationState;
+/** A conversation with one more event of its stream. */
+export declare function reduceConversation(state: ConversationState, event: AgUiEvent): ConversationState;
+/** The question in words with what answers it, for a screen reader or a row. */
+export declare function questionWords(question: ConversationQuestion): string;
+/** The fields a form question asks, in order, with their titles: what a native form draws. */
+export declare function formFieldsOf(schema: Record<string, unknown> | null): {
+    name: string;
+    title: string;
+    type: string;
+    options: string[];
+    required: boolean;
+}[];