@datalayer/agent-runtimes 1.5.20 → 1.5.22

package/lib/portable/conversation.js

@@ -0,0 +1,357 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * 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 { REACTOR_UI_NAME, toolResultOf, UI_ON_RUN, } from './agui';
+import { RUN_END_WORDS } from './records';
+import { messagesOfThread } from './thread';
+/** How many rows a conversation keeps: its newest. */
+export const ITEM_LIMIT = 400;
+/** How many characters of an answer are kept. */
+export const MESSAGE_TEXT_LIMIT = 100_000;
+/** How many characters of a tool's arguments, and of its result, are kept. */
+export const TOOL_TEXT_LIMIT = 4_000;
+/** How many events it does not draw are kept, by type and name. */
+export const DIAGNOSTIC_LIMIT = 50;
+/** What is said after a text cut at its limit. */
+export const CUT_MARK = '… (cut: too long to keep on this device)';
+/** A conversation with nothing in it yet. */
+export const emptyConversation = () => ({
+    items: [],
+    running: false,
+    session: null,
+    asking: null,
+    dropped: 0,
+    diagnostics: [],
+    turnRows: 0,
+});
+const text = (value) => typeof value === 'string' ? value : '';
+const cut = (value, limit) => value.length > limit ? `${value.slice(0, limit)}${CUT_MARK}` : value;
+/** Text appended to what is kept, never past its limit. */
+const appended = (kept, delta, limit) => {
+    if (kept.endsWith(CUT_MARK)) {
+        return kept;
+    }
+    return cut(kept + delta, limit);
+};
+/** A result in words. */
+function said(result) {
+    if (result === undefined || result === null) {
+        return '';
+    }
+    return typeof result === 'string' ? result : JSON.stringify(result);
+}
+/** The question an application asks, as `RUN_FINISHED`'s `result.asking` or a session says it. */
+export function questionOf(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return null;
+    }
+    const asked = raw;
+    const kind = asked.kind;
+    if (kind !== 'text' &&
+        kind !== 'choice' &&
+        kind !== 'form' &&
+        kind !== 'file') {
+        throw new Error(`The application asks something no client knows: ${String(kind)}.`);
+    }
+    const strings = (value) => Array.isArray(value)
+        ? value.filter((item) => typeof item === 'string')
+        : [];
+    const schema = asked.schema;
+    return {
+        kind,
+        prompt: text(asked.prompt),
+        options: strings(asked.options),
+        schema: schema && typeof schema === 'object' && !Array.isArray(schema)
+            ? schema
+            : null,
+        accept: strings(asked.accept),
+    };
+}
+function withItems(state, items, added = 0) {
+    const over = items.length - ITEM_LIMIT;
+    return {
+        ...state,
+        items: over > 0 ? items.slice(over) : items,
+        dropped: state.dropped + Math.max(0, over),
+        turnRows: state.turnRows + added,
+    };
+}
+function changed(state, id, change) {
+    const at = state.items.findIndex(item => item.id === id);
+    if (at < 0) {
+        return null;
+    }
+    const items = state.items.slice();
+    items[at] = change(items[at]);
+    return { ...state, items };
+}
+function noted(state, event) {
+    const entry = {
+        type: event.type,
+        name: text(event.name) || text(event.activityType),
+    };
+    return {
+        ...state,
+        diagnostics: [...state.diagnostics, entry].slice(-DIAGNOSTIC_LIMIT),
+    };
+}
+let rowCount = 0;
+const rowId = (prefix) => `${prefix}-${Date.now().toString(36)}-${(rowCount += 1)}`;
+/** The person's prompt, added before it is sent: its own row. */
+export function withPrompt(state, id, words) {
+    return withItems({ ...state, asking: null }, [
+        ...state.items,
+        { kind: 'message', id, role: 'user', text: words, streaming: false },
+    ]);
+}
+/**
+ * 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 function withTurnEnded(state, end) {
+    const items = state.items.map(item => item.kind === 'message' && item.streaming
+        ? { ...item, streaming: false }
+        : item.kind === 'tool' && item.status === 'running'
+            ? { ...item, status: 'error', error: RUN_END_WORDS[end] }
+            : item.kind === 'step' && item.status === 'running'
+                ? { ...item, status: 'complete' }
+                : item);
+    const ended = { ...state, items, running: false };
+    return withItems(ended, [
+        ...items,
+        { kind: 'end', id: rowId('end'), end, words: RUN_END_WORDS[end] },
+    ]);
+}
+/** A failure said in the conversation (a refusal, a stream cut short): the turn stops with it. */
+export function withError(state, words) {
+    const items = state.items.map(item => item.kind === 'message' && item.streaming
+        ? { ...item, streaming: false }
+        : item.kind === 'tool' && item.status === 'running'
+            ? { ...item, status: 'error' }
+            : item.kind === 'step' && item.status === 'running'
+                ? { ...item, status: 'complete' }
+                : item);
+    return withItems({ ...state, running: false }, [
+        ...items,
+        { kind: 'error', id: rowId('error'), text: words },
+    ]);
+}
+/** A conversation with one more event of its stream. */
+export function reduceConversation(state, event) {
+    switch (event.type) {
+        case 'RUN_STARTED':
+            return { ...state, running: true, asking: null, turnRows: 0 };
+        case 'TEXT_MESSAGE_START': {
+            const id = text(event.messageId) || rowId('message');
+            if (state.items.some(item => item.id === id)) {
+                return state;
+            }
+            const role = event.role === 'user' ? 'user' : 'assistant';
+            return withItems(state, [
+                ...state.items,
+                { kind: 'message', id, role, text: '', streaming: true },
+            ], 1);
+        }
+        case 'TEXT_MESSAGE_CONTENT':
+        case 'TEXT_MESSAGE_CHUNK': {
+            const delta = text(event.delta);
+            const id = text(event.messageId);
+            const grown = changed(state, id, item => item.kind === 'message'
+                ? { ...item, text: appended(item.text, delta, MESSAGE_TEXT_LIMIT) }
+                : item);
+            if (grown) {
+                return grown;
+            }
+            return withItems(state, [
+                ...state.items,
+                {
+                    kind: 'message',
+                    id: id || rowId('message'),
+                    role: event.role === 'user' ? 'user' : 'assistant',
+                    text: cut(delta, MESSAGE_TEXT_LIMIT),
+                    streaming: event.type === 'TEXT_MESSAGE_CONTENT',
+                },
+            ], 1);
+        }
+        case 'TEXT_MESSAGE_END':
+            return (changed(state, text(event.messageId), item => item.kind === 'message' ? { ...item, streaming: false } : item) ?? state);
+        case 'TOOL_CALL_START': {
+            const id = text(event.toolCallId) || rowId('tool');
+            if (state.items.some(item => item.id === id)) {
+                return state;
+            }
+            return withItems(state, [
+                ...state.items,
+                {
+                    kind: 'tool',
+                    id,
+                    name: text(event.toolCallName) || text(event.name),
+                    args: '',
+                    status: 'running',
+                    result: '',
+                    error: '',
+                },
+            ], 1);
+        }
+        case 'TOOL_CALL_ARGS':
+            return (changed(state, text(event.toolCallId), item => item.kind === 'tool'
+                ? {
+                    ...item,
+                    args: appended(item.args, text(event.delta), TOOL_TEXT_LIMIT),
+                }
+                : item) ?? state);
+        case 'TOOL_CALL_END':
+            return state;
+        case 'TOOL_CALL_RESULT': {
+            const result = toolResultOf(event.content);
+            return (changed(state, text(event.toolCallId), item => item.kind === 'tool'
+                ? {
+                    ...item,
+                    status: result.success ? 'complete' : 'error',
+                    result: cut(said(result.result), TOOL_TEXT_LIMIT),
+                    error: result.error ?? '',
+                }
+                : item) ?? noted(state, event));
+        }
+        case 'STEP_STARTED': {
+            const name = text(event.stepName) || text(event.name);
+            return withItems(state, [
+                ...state.items,
+                { kind: 'step', id: rowId('step'), name, status: 'running' },
+            ], 1);
+        }
+        case 'STEP_FINISHED': {
+            const name = text(event.stepName) || text(event.name);
+            const at = state.items
+                .map((item, index) => ({ item, index }))
+                .reverse()
+                .find(({ item }) => item.kind === 'step' &&
+                item.name === name &&
+                item.status === 'running');
+            if (!at) {
+                return noted(state, event);
+            }
+            const items = state.items.slice();
+            items[at.index] = {
+                ...at.item,
+                status: 'complete',
+            };
+            return { ...state, items };
+        }
+        case 'MESSAGES_SNAPSHOT': {
+            const messages = messagesOfThread(event.messages);
+            return withItems({ ...state, dropped: 0 }, messages.map(message => ({
+                kind: 'message',
+                id: message.id,
+                role: message.role === 'user'
+                    ? 'user'
+                    : 'assistant',
+                text: cut(typeof message.content === 'string' ? message.content : '', MESSAGE_TEXT_LIMIT),
+                streaming: false,
+            })), 
+            // The conversation said again is what this turn says (a resume):
+            // never also said as a wordless answer.
+            1);
+        }
+        case 'CUSTOM': {
+            if (event.name === REACTOR_UI_NAME) {
+                return withError(state, UI_ON_RUN);
+            }
+            if (event.name === 'loop.session' &&
+                event.value &&
+                typeof event.value === 'object') {
+                const session = event.value;
+                return {
+                    ...state,
+                    session,
+                    asking: questionOf(session.asking) ?? state.asking,
+                };
+            }
+            return noted(state, event);
+        }
+        case 'ACTIVITY_SNAPSHOT':
+        case 'ACTIVITY_DELTA':
+            if (event.activityType === REACTOR_UI_NAME) {
+                return withError(state, UI_ON_RUN);
+            }
+            return noted(state, event);
+        case 'RUN_FINISHED': {
+            const result = event.result && typeof event.result === 'object'
+                ? event.result
+                : {};
+            const asking = questionOf(result.asking);
+            const items = state.items.map(item => item.kind === 'message' && item.streaming
+                ? { ...item, streaming: false }
+                : item);
+            const finished = { ...state, items, running: false, asking };
+            if (asking || state.turnRows > 0) {
+                return finished;
+            }
+            // Answered without a word: said by how it ended (RUN_END_WORDS).
+            return withItems(finished, [
+                ...items,
+                {
+                    kind: 'end',
+                    id: rowId('end'),
+                    end: 'answered',
+                    words: RUN_END_WORDS.answered,
+                },
+            ]);
+        }
+        case 'RUN_ERROR':
+            return withError(state, text(event.message) || 'Run failed');
+        default:
+            return noted(state, event);
+    }
+}
+/** The question in words with what answers it, for a screen reader or a row. */
+export function questionWords(question) {
+    switch (question.kind) {
+        case 'choice':
+            return `${question.prompt} (${question.options.join(' or ')})`;
+        case 'file':
+            return `${question.prompt} (a file: ${question.accept.join(', ') || 'any file'})`;
+        default:
+            return question.prompt;
+    }
+}
+/** The fields a form question asks, in order, with their titles: what a native form draws. */
+export function formFieldsOf(schema) {
+    const properties = schema?.properties && typeof schema.properties === 'object'
+        ? schema.properties
+        : {};
+    const required = Array.isArray(schema?.required)
+        ? schema?.required
+        : [];
+    return Object.entries(properties).map(([name, field]) => ({
+        name,
+        title: text(field?.title) || name,
+        type: text(field?.type) || 'string',
+        options: Array.isArray(field?.enum) ? field.enum.map(String) : [],
+        required: required.includes(name),
+    }));
+}

package/lib/portable/index.d.ts

@@ -1,11 +1,16 @@
 /**
  * What any JavaScript runtime can import from Agent Runtimes: no React, DOM,
- * Jupyter or Node built-in. Re-exports only; the mobile app reaches Agent
- * Runtimes through this entry alone.
+ * Jupyter, Reactor or Node module. Every module it reaches at run time lives
+ * in this folder (a test holds it to that), so that Datalayer Mobile's Metro
+ * graph takes `lib/portable/*` and nothing else of Agent Runtimes.
  *
  * @module portable
  */
-export { messageOfApproval, normalizeApproval, whyAsked, type ApprovalArgs, type ApprovalRecord, type MessageAsked, } from '../utils/approvals';
-export { AGUIAdapter, type AGUIAdapterConfig } from '../protocols/AGUIAdapter';
-export { createActivityMessage, createAssistantMessage, createUserMessage, generateMessageId, type ChatMessage, type ChatMessageDelta, type ChatMessageInput, type ChatThread, type ContentPart, type MessageRole, type ToolCallStatus, } from '../types/messages';
-export type { ProtocolAdapterConfig, ProtocolConnectionState, ProtocolEvent, ProtocolEventHandler, } from '../types/protocol';
+export { messageOfApproval, normalizeApproval, whyAsked, type ApprovalArgs, type ApprovalRecord, type MessageAsked, } from './approvals';
+export { AgUiFrames, endsRun, eventsOfStream, NOT_STREAMING, REACTOR_UI_NAME, readRunStream, RUN_CUT_SHORT, toolResultOf, UI_ON_RUN, type AgUiEvent, type ToolResultSaid, } from './agui';
+export { AG_UI_NOT_ALLOWED, AG_UI_NOT_ON_RUNTIME, agUiRefusal, refusalBody, refusalDetail, } from './agUiRefusal';
+export { ASKED_FOR_TAG, askedOf, RUN_END_WORDS } from './records';
+export { messagesOfThread, openThread, snapshotOfStream, THREAD_WORDS, } from './thread';
+export { CUT_MARK, DIAGNOSTIC_LIMIT, emptyConversation, formFieldsOf, ITEM_LIMIT, MESSAGE_TEXT_LIMIT, questionOf, questionWords, reduceConversation, TOOL_TEXT_LIMIT, withError, withPrompt, withTurnEnded, type ConversationItem, type ConversationQuestion, type ConversationState, type TurnEnd, } from './conversation';
+export { agentRunClient, agentRuntimesUrlOf, appSessionsClient, RuntimeRefusal, type AgentRunClient, type AgentTurn, type AppSessionsClient, type RuntimeClientOptions, type SessionStart, type StreamOptions, } from './sessions';
+export type { ChatMessage } from '../types/messages';

package/lib/portable/index.js

@@ -2,19 +2,22 @@
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-/*
- * Copyright (c) 2026 Datalayer, Inc.
- * Distributed under the terms of the Modified BSD License.
- */
 /**
  * What any JavaScript runtime can import from Agent Runtimes: no React, DOM,
- * Jupyter or Node built-in. Re-exports only; the mobile app reaches Agent
- * Runtimes through this entry alone.
+ * Jupyter, Reactor or Node module. Every module it reaches at run time lives
+ * in this folder (a test holds it to that), so that Datalayer Mobile's Metro
+ * graph takes `lib/portable/*` and nothing else of Agent Runtimes.
  *
  * @module portable
  */
-export { messageOfApproval, normalizeApproval, whyAsked, } from '../utils/approvals';
-// The AG-UI stream client and the messages it builds; a phone passes a
-// streaming `fetch` in the adapter's config.
-export { AGUIAdapter } from '../protocols/AGUIAdapter';
-export { createActivityMessage, createAssistantMessage, createUserMessage, generateMessageId, } from '../types/messages';
+export { messageOfApproval, normalizeApproval, whyAsked, } from './approvals';
+// A run's stream, read as every client reads it.
+export { AgUiFrames, endsRun, eventsOfStream, NOT_STREAMING, REACTOR_UI_NAME, readRunStream, RUN_CUT_SHORT, toolResultOf, UI_ON_RUN, } from './agui';
+export { AG_UI_NOT_ALLOWED, AG_UI_NOT_ON_RUNTIME, agUiRefusal, refusalBody, refusalDetail, } from './agUiRefusal';
+// The record's words, and a person's conversation read again.
+export { ASKED_FOR_TAG, askedOf, RUN_END_WORDS } from './records';
+export { messagesOfThread, openThread, snapshotOfStream, THREAD_WORDS, } from './thread';
+// A conversation as its stream builds it, for a native client.
+export { CUT_MARK, DIAGNOSTIC_LIMIT, emptyConversation, formFieldsOf, ITEM_LIMIT, MESSAGE_TEXT_LIMIT, questionOf, questionWords, reduceConversation, TOOL_TEXT_LIMIT, withError, withPrompt, withTurnEnded, } from './conversation';
+// The runtime's routes a native client drives.
+export { agentRunClient, agentRuntimesUrlOf, appSessionsClient, RuntimeRefusal, } from './sessions';

package/lib/portable/records.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The words of an application's record that every client shows the same:
+ * how a run ended, and what a person asked without what the runtime told the
+ * application before their words. Read by the web's record feed
+ * (`apps/apps/records`), the chat and Datalayer Mobile.
+ *
+ * @module portable/records
+ */
+/**
+ * How a run ended, in the `output` entry every run ends with, kept whatever
+ * the application's `record.include` says (PAP_DATALAYER R-01): its words
+ * only when it keeps `outputs`.
+ */
+export declare const RUN_END_WORDS: Record<string, string>;
+/**
+ * The mark around what the runtime tells an application of a turn a personal
+ * agent asked over PAP or PACT, before the request (`asked_for_said`,
+ * `ASKED_FOR_TAG` in agent_runtimes.loop.apps.pap_company).
+ */
+export declare const ASKED_FOR_TAG = "asked-for";
+/**
+ * What a person asked, as they are shown it: without what the runtime told
+ * the application before their words (PAP_DATALAYER, decided 2026-10-14).
+ * The record keeps it for the application's builder; the person never wrote
+ * it, so *Your conversations* and a thread opened again leave it out.
+ */
+export declare function askedOf(text: string): string;

package/lib/portable/records.js

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The words of an application's record that every client shows the same:
+ * how a run ended, and what a person asked without what the runtime told the
+ * application before their words. Read by the web's record feed
+ * (`apps/apps/records`), the chat and Datalayer Mobile.
+ *
+ * @module portable/records
+ */
+/**
+ * How a run ended, in the `output` entry every run ends with, kept whatever
+ * the application's `record.include` says (PAP_DATALAYER R-01): its words
+ * only when it keeps `outputs`.
+ */
+export const RUN_END_WORDS = {
+    answered: 'Answered',
+    stopped: 'Stopped',
+    gone: 'Its client went before the answer',
+};
+/**
+ * The mark around what the runtime tells an application of a turn a personal
+ * agent asked over PAP or PACT, before the request (`asked_for_said`,
+ * `ASKED_FOR_TAG` in agent_runtimes.loop.apps.pap_company).
+ */
+export const ASKED_FOR_TAG = 'asked-for';
+/**
+ * What a person asked, as they are shown it: without what the runtime told
+ * the application before their words (PAP_DATALAYER, decided 2026-10-14).
+ * The record keeps it for the application's builder; the person never wrote
+ * it, so *Your conversations* and a thread opened again leave it out.
+ */
+export function askedOf(text) {
+    const open = `<${ASKED_FOR_TAG}>`;
+    const close = `</${ASKED_FOR_TAG}>`;
+    if (!text.startsWith(open)) {
+        return text;
+    }
+    const end = text.indexOf(close);
+    if (end < 0) {
+        throw new Error(`What was asked opens <${ASKED_FOR_TAG}> and never closes it.`);
+    }
+    return text.slice(end + close.length).trimStart();
+}

package/lib/portable/sessions.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The clients a native app talks to a runtime with: an application's
+ * sessions (`/api/v1/apps/sessions`, the Session API) and a standalone agent's
+ * AG-UI mount (`/api/v1/ag-ui/{agent}/`). Each streaming route's events are
+ * handed to `onEvent` as they arrive (`readRunStream`); a refusal is thrown
+ * as a `RuntimeRefusal` with its status and the runtime's own sentence.
+ *
+ * Nothing is read from a page: the runtime's address, the token and a
+ * `fetch` that streams are given (`{ baseUrl, getAccessToken, fetch }`).
+ *
+ * @module portable/sessions
+ */
+import type { ChatMessage } from '../types/messages';
+import { type AgUiEvent } from './agui';
+/** Where a runtime is, and as whom it is asked. */
+export type RuntimeClientOptions = {
+    /** The runtime's agent-runtimes address (`…/agent-runtimes/<runtime>`). */
+    baseUrl: string;
+    getAccessToken: () => string | undefined;
+    /** A `fetch` whose response body streams. */
+    fetch: typeof fetch;
+};
+/** A streaming request's listener and its cancellation. */
+export type StreamOptions = {
+    onEvent: (event: AgUiEvent) => void;
+    signal?: AbortSignal;
+};
+/** A route that refused: its status and the runtime's sentence. */
+export declare class RuntimeRefusal extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/** What starting a session names: the application's agent and what it runs. */
+export type SessionStart = {
+    /** The agent the runtime made for the application. */
+    agent: string;
+    deploymentUid?: string;
+    appUid?: string;
+    version?: number;
+    /** The first message. */
+    opener: string;
+    /** The session's uid, when the client chose it. */
+    session?: string;
+};
+/**
+ * An application's sessions on the runtime that runs it: start, message,
+ * settings, resume (streamed), and stop, end, read (JSON).
+ */
+export declare function appSessionsClient(options: RuntimeClientOptions): {
+    /** Start a session with its first message. */
+    start: (start: SessionStart, streaming: StreamOptions) => Promise<void>;
+    /** The next turn, or the answer to what the application asked (text, a choice). */
+    message: (uid: string, text: string, streaming: StreamOptions) => Promise<void>;
+    /** A settings change: also what answers a form the application asked. */
+    changeSettings: (uid: string, values: Record<string, unknown>, streaming: StreamOptions) => Promise<void>;
+    /** Resume a stopped session — or, with its agent, one the runtime no longer holds, from its record. */
+    resume: (uid: string, agent: string, streaming: StreamOptions) => Promise<void>;
+    /** Stop: what runs is cancelled; the session waits to be resumed. */
+    stop: (uid: string) => Promise<Record<string, unknown>>;
+    /** End the conversation for good; its record stays. */
+    end: (uid: string) => Promise<Record<string, unknown>>;
+    /** What the session is: its state (`open`, `running`, `waiting`, `stopped`) and what it asks. */
+    describe: (uid: string) => Promise<Record<string, unknown>>;
+    /** Its conversation as a person reads it (`messagesOfThread`). */
+    messages: (uid: string) => Promise<ChatMessage[]>;
+};
+export type AppSessionsClient = ReturnType<typeof appSessionsClient>;
+/** One turn of a conversation, as an agent's AG-UI run is sent it. */
+export type AgentTurn = {
+    id: string;
+    role: 'user' | 'assistant';
+    content: string;
+};
+/**
+ * A standalone agent over its AG-UI mount: a run carries the conversation so
+ * far, and stopping it terminates the thread's run on the runtime. A raw
+ * agent has no session, record or question of an application's.
+ */
+export declare function agentRunClient(options: RuntimeClientOptions & {
+    agent: string;
+}): {
+    run: (threadId: string, runId: string, messages: AgentTurn[], streaming: StreamOptions) => Promise<void>;
+    /** Stop the thread's run on the runtime (`POST /api/v1/ag-ui/terminate`). */
+    terminate: (threadId: string) => Promise<void>;
+};
+export type AgentRunClient = ReturnType<typeof agentRunClient>;
+/**
+ * A runtime's agent-runtimes address from its ingress, as the runtimes
+ * service gives it (`…/jupyter/server/<runtime>` → `…/agent-runtimes/<runtime>`,
+ * `build_agent_runtimes_base_url`). Refused when there is none.
+ */
+export declare function agentRuntimesUrlOf(ingress: string): string;