@datalayer/agent-runtimes 1.5.45 → 1.5.47

package/lib/portable/semantic-events.json

@@ -0,0 +1,480 @@
+{
+  "version": 1,
+  "about": "The semantic agent events a chat host renders (Slack, Discord: plans/DISCORD.md DC-005, plans/SLACK.md S-004, S-205), and the AG-UI events of agent-runtimes' session API (agent_runtimes/routes/apps.py, agent_runtimes/loop/apps/sessions.py, agent_runtimes/loop/apps/external_turns.py) each reduces to. src/portable/semanticOfAgUi.ts reduces every case (src/portable/__tests__/semantic.unit.test.ts); agent_runtimes/tests/test_semantic_events_contract.py holds the cases to what the runtime emits.",
+  "kinds": [
+    "text",
+    "progress",
+    "tool",
+    "approval",
+    "table",
+    "file",
+    "citation",
+    "ask",
+    "completion",
+    "stop",
+    "error"
+  ],
+  "producers": {
+    "text": "AG-UI TEXT_MESSAGE_CONTENT / TEXT_MESSAGE_CHUNK delta",
+    "progress": "AG-UI STEP_STARTED stepName",
+    "tool": "AG-UI TOOL_CALL_START (running), TOOL_CALL_RESULT (complete, or failed when success is false)",
+    "approval": "AG-UI TOOL_CALL_RESULT whose result says pending_approval; the decision itself arrives as an approval.requested delivery",
+    "table": "a Markdown table in the answer (src/portable/semantic.ts answerParts); no AG-UI event carries one",
+    "file": "none in agent-runtimes 1.5.45: reserved, rendered as a safe HTTPS link when produced",
+    "citation": "an HTTPS Markdown link in the answer (answerParts); no AG-UI event carries one",
+    "ask": "AG-UI RUN_FINISHED with result.asking (agent_runtimes/loop/apps/sessions.py question_of); the run stream carries no loop.ask event",
+    "completion": "AG-UI RUN_FINISHED without asking",
+    "stop": "the host itself, after its own Stop: a stopped session's stream ends without RUN_FINISHED or RUN_ERROR (agent_runtimes/loop/apps/sessions.py stop, _close); no AG-UI event carries it",
+    "error": "AG-UI RUN_ERROR message"
+  },
+  "cases": [
+    {
+      "agui": [
+        {
+          "type": "TEXT_MESSAGE_CONTENT",
+          "messageId": "m1",
+          "delta": "Option B "
+        }
+      ],
+      "semantic": [
+        {
+          "kind": "text",
+          "text": "Option B "
+        }
+      ]
+    },
+    {
+      "agui": [
+        {
+          "type": "TEXT_MESSAGE_CHUNK",
+          "messageId": "m1",
+          "delta": "is safer."
+        }
+      ],
+      "semantic": [
+        {
+          "kind": "text",
+          "text": "is safer."
+        }
+      ]
+    },
+    {
+      "agui": [
+        {
+          "type": "TEXT_MESSAGE_CONTENT",
+          "messageId": "m1",
+          "delta": ""
+        }
+      ],
+      "semantic": []
+    },
+    {
+      "agui": [
+        {
+          "type": "STEP_STARTED",
+          "stepName": "Reading the launch notes"
+        }
+      ],
+      "semantic": [
+        {
+          "kind": "progress",
+          "label": "Reading the launch notes"
+        }
+      ]
+    },
+    {
+      "agui": [
+        {
+          "type": "TOOL_CALL_START",
+          "toolCallId": "c1",
+          "toolCallName": "search"
+        },
+        {
+          "type": "TOOL_CALL_ARGS",
+          "toolCallId": "c1",
+          "delta": "{\"q\":\"launch\"}"
+        },
+        {
+          "type": "TOOL_CALL_END",
+          "toolCallId": "c1"
+        },
+        {
+          "type": "TOOL_CALL_RESULT",
+          "toolCallId": "c1",
+          "messageId": "r1",
+          "content": "{\"success\": true}"
+        }
+      ],
+      "semantic": [
+        {
+          "kind": "tool",
+          "id": "c1",
+          "name": "search",
+          "status": "running"
+        },
+        {
+          "kind": "tool",
+          "id": "c1",
+          "name": "search",
+          "status": "complete"
+        }
+      ]
+    },
+    {
+      "agui": [
+        {
+          "type": "TOOL_CALL_START",
+          "toolCallId": "c2",
+          "toolCallName": "run_code"
+        },
+        {
+          "type": "TOOL_CALL_RESULT",
+          "toolCallId": "c2",
+          "messageId": "r2",
+          "content": "{\"success\": false, \"execution_error\": \"boom\"}"
+        }
+      ],
+      "semantic": [
+        {
+          "kind": "tool",
+          "id": "c2",
+          "name": "run_code",
+          "status": "running"
+        },
+        {
+          "kind": "tool",
+          "id": "c2",
+          "name": "run_code",
+          "status": "failed"
+        }
+      ]
+    },
+    {
+      "agui": [
+        {
+          "type": "TOOL_CALL_START",
+          "toolCallId": "c3",
+          "toolCallName": "send_email"
+        },
+        {
+          "type": "TOOL_CALL_RESULT",
+          "toolCallId": "c3",
+          "messageId": "r3",
+          "content": "{\"pending_approval\": true}"
+        }
+      ],
+      "semantic": [
+        {
+          "kind": "tool",
+          "id": "c3",
+          "name": "send_email",
+          "status": "running"
+        },
+        {
+          "kind": "approval",
+          "toolCallId": "c3",
+          "toolName": "send_email"
+        }
+      ]
+    },
+    {
+      "agui": [
+        {
+          "type": "RUN_FINISHED",
+          "threadId": "S1",
+          "runId": "t1"
+        }
+      ],
+      "semantic": [
+        {
+          "kind": "completion"
+        }
+      ]
+    },
+    {
+      "agui": [
+        {
+          "type": "RUN_FINISHED",
+          "threadId": "S1",
+          "runId": "t1",
+          "result": {
+            "asking": {
+              "kind": "choice",
+              "prompt": "Which option?",
+              "options": ["A", "B"]
+            }
+          }
+        }
+      ],
+      "semantic": [
+        {
+          "kind": "ask",
+          "question": {
+            "kind": "choice",
+            "prompt": "Which option?",
+            "options": ["A", "B"]
+          }
+        }
+      ]
+    },
+    {
+      "agui": [
+        {
+          "type": "RUN_FINISHED",
+          "threadId": "S1",
+          "runId": "t1",
+          "result": {
+            "asking": {
+              "kind": "text",
+              "prompt": "Which quarter?"
+            }
+          }
+        }
+      ],
+      "semantic": [
+        {
+          "kind": "ask",
+          "question": {
+            "kind": "text",
+            "prompt": "Which quarter?"
+          }
+        }
+      ]
+    },
+    {
+      "agui": [
+        {
+          "type": "RUN_FINISHED",
+          "threadId": "S1",
+          "runId": "t1",
+          "result": {
+            "asking": {
+              "kind": "signature",
+              "prompt": "Sign here"
+            }
+          }
+        }
+      ],
+      "semantic": [
+        {
+          "kind": "ask",
+          "question": {
+            "kind": "form",
+            "prompt": "Sign here"
+          }
+        }
+      ]
+    },
+    {
+      "agui": [
+        {
+          "type": "RUN_FINISHED",
+          "threadId": "S1",
+          "runId": "t1",
+          "result": {
+            "asking": {
+              "kind": "form",
+              "prompt": "Your details",
+              "schema": {}
+            }
+          }
+        }
+      ],
+      "semantic": [
+        {
+          "kind": "ask",
+          "question": {
+            "kind": "form",
+            "prompt": "Your details"
+          }
+        }
+      ]
+    },
+    {
+      "agui": [
+        {
+          "type": "RUN_FINISHED",
+          "threadId": "S1",
+          "runId": "t1",
+          "result": {
+            "asking": {
+              "kind": "file",
+              "prompt": "Your receipt",
+              "accept": ["application/pdf"],
+              "max_bytes": 1000000
+            }
+          }
+        }
+      ],
+      "semantic": [
+        {
+          "kind": "ask",
+          "question": {
+            "kind": "file",
+            "prompt": "Your receipt"
+          }
+        }
+      ]
+    },
+    {
+      "agui": [
+        {
+          "type": "CUSTOM",
+          "name": "loop.turn",
+          "value": {
+            "turn": "t1",
+            "external_event_id": "Ev1",
+            "replayed": false,
+            "state": "running"
+          }
+        }
+      ],
+      "semantic": []
+    },
+    {
+      "agui": [
+        {
+          "type": "RUN_ERROR",
+          "message": "The model is unavailable."
+        }
+      ],
+      "semantic": [
+        {
+          "kind": "error",
+          "message": "The model is unavailable."
+        }
+      ]
+    },
+    {
+      "agui": [
+        {
+          "type": "CUSTOM",
+          "name": "loop.session",
+          "value": {
+            "uid": "S1"
+          }
+        },
+        {
+          "type": "CUSTOM",
+          "name": "reactor.ui",
+          "value": {}
+        },
+        {
+          "type": "RUN_STARTED",
+          "threadId": "S1",
+          "runId": "t1"
+        },
+        {
+          "type": "MESSAGES_SNAPSHOT",
+          "messages": []
+        }
+      ],
+      "semantic": []
+    },
+    {
+      "agui": [
+        {
+          "type": "CUSTOM",
+          "name": "loop.turn",
+          "value": {
+            "session": "S1",
+            "turn": "t1",
+            "external_event_id": "Ev1",
+            "replayed": true,
+            "state": "finished"
+          }
+        }
+      ],
+      "semantic": []
+    },
+    {
+      "agui": [
+        {
+          "type": "CUSTOM",
+          "name": "loop.turn",
+          "value": {
+            "session": "S1",
+            "turn": "t1",
+            "external_event_id": "Ev1",
+            "replayed": true,
+            "state": "failed"
+          }
+        }
+      ],
+      "semantic": []
+    },
+    {
+      "agui": [
+        {
+          "type": "CUSTOM",
+          "name": "loop.page",
+          "value": {
+            "inputs": {},
+            "outputs": {}
+          }
+        },
+        {
+          "type": "CUSTOM",
+          "name": "voice.say",
+          "value": {
+            "text": "Hello",
+            "voice": "",
+            "language": "en"
+          }
+        },
+        {
+          "type": "CUSTOM",
+          "name": "voice.interrupted",
+          "value": {}
+        }
+      ],
+      "semantic": []
+    },
+    {
+      "agui": [
+        {
+          "type": "TEXT_MESSAGE_START",
+          "messageId": "m2",
+          "role": "assistant"
+        },
+        {
+          "type": "TEXT_MESSAGE_END",
+          "messageId": "m2"
+        },
+        {
+          "type": "STEP_FINISHED",
+          "stepName": "Reading the launch notes"
+        }
+      ],
+      "semantic": []
+    }
+  ],
+  "answers": [
+    {
+      "answer": "Two options.\n\n| Option | Risk |\n|---|---|\n| A | High |\n| B | Low |\n\nSee [the launch notes](https://datalayer.ai/notes) and [an unsafe link](javascript:alert(1)).",
+      "parts": [
+        {
+          "kind": "text",
+          "text": "Two options."
+        },
+        {
+          "kind": "table",
+          "columns": ["Option", "Risk"],
+          "rows": [
+            ["A", "High"],
+            ["B", "Low"]
+          ]
+        },
+        {
+          "kind": "text",
+          "text": "See [the launch notes](https://datalayer.ai/notes) and [an unsafe link](javascript:alert(1))."
+        },
+        {
+          "kind": "citation",
+          "title": "the launch notes",
+          "url": "https://datalayer.ai/notes"
+        }
+      ]
+    }
+  ]
+}

package/lib/portable/semantic.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The semantic agent events a chat host renders (Slack, Discord), version 1:
+ * a session's AG-UI stream reduced to what a host shows (`semanticOfAgUi.ts`),
+ * never a notebook widget or a web component. The contract and its fixture
+ * cases are `semantic-events.json`, beside this file, tested here
+ * (`__tests__/semantic.unit.test.ts`) and by the runtime that emits the
+ * events (`agent_runtimes/tests/test_semantic_events_contract.py`).
+ *
+ * Moved from the Slack service (plans/DISCORD.md DC-005, SLACK S-004, S-205).
+ *
+ * @module portable/semantic
+ */
+export declare const SEMANTIC_EVENTS_VERSION = 1;
+export declare const SEMANTIC_KINDS: readonly ["text", "progress", "tool", "approval", "table", "file", "citation", "ask", "completion", "stop", "error"];
+export type SemanticKind = (typeof SEMANTIC_KINDS)[number];
+export type AskQuestion = Readonly<{
+    /** `text` and `choice` are answered in the host; `file` and `form` hand off to Datalayer. */
+    kind: 'text' | 'choice' | 'file' | 'form';
+    prompt: string;
+    options?: readonly string[];
+}>;
+export type SemanticEvent = Readonly<{
+    kind: 'text';
+    text: string;
+}> | Readonly<{
+    kind: 'progress';
+    label: string;
+}> | Readonly<{
+    kind: 'tool';
+    id: string;
+    name: string;
+    status: 'running' | 'complete' | 'failed';
+}> | Readonly<{
+    kind: 'approval';
+    toolCallId: string;
+    toolName: string;
+}> | Readonly<{
+    kind: 'table';
+    columns: readonly string[];
+    rows: readonly (readonly string[])[];
+}> | Readonly<{
+    kind: 'file';
+    name: string;
+    url: string;
+    mediaType?: string;
+}> | Readonly<{
+    kind: 'citation';
+    title: string;
+    url: string;
+}> | Readonly<{
+    kind: 'ask';
+    question: AskQuestion;
+}> | Readonly<{
+    kind: 'completion';
+    text?: string;
+}> | Readonly<{
+    kind: 'stop';
+}> | Readonly<{
+    kind: 'error';
+    message: string;
+}>;
+/** Whether an event ends the turn's presentation. */
+export declare function isTerminal(event: SemanticEvent): boolean;
+/** One part of a finished answer: words, a table, or a citation. */
+export type AnswerPart = Readonly<{
+    kind: 'text';
+    text: string;
+}> | Extract<SemanticEvent, {
+    kind: 'table';
+} | {
+    kind: 'citation';
+}>;
+/**
+ * The parts of an answer as a host shows them: its Markdown tables as tables,
+ * its HTTPS links as citations (once each, in order), the rest as words. Only
+ * `https:` links are citations: any other scheme stays words.
+ */
+export declare function answerParts(answer: string): AnswerPart[];

package/lib/portable/semantic.js

@@ -0,0 +1,100 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The semantic agent events a chat host renders (Slack, Discord), version 1:
+ * a session's AG-UI stream reduced to what a host shows (`semanticOfAgUi.ts`),
+ * never a notebook widget or a web component. The contract and its fixture
+ * cases are `semantic-events.json`, beside this file, tested here
+ * (`__tests__/semantic.unit.test.ts`) and by the runtime that emits the
+ * events (`agent_runtimes/tests/test_semantic_events_contract.py`).
+ *
+ * Moved from the Slack service (plans/DISCORD.md DC-005, SLACK S-004, S-205).
+ *
+ * @module portable/semantic
+ */
+export const SEMANTIC_EVENTS_VERSION = 1;
+export const SEMANTIC_KINDS = [
+    'text',
+    'progress',
+    'tool',
+    'approval',
+    'table',
+    'file',
+    'citation',
+    'ask',
+    'completion',
+    'stop',
+    'error',
+];
+/** Whether an event ends the turn's presentation. */
+export function isTerminal(event) {
+    return (event.kind === 'completion' ||
+        event.kind === 'stop' ||
+        event.kind === 'error' ||
+        event.kind === 'ask');
+}
+const TABLE_ROW = /^\s*\|.*\|\s*$/;
+const TABLE_RULE = /^\s*\|(\s*:?-{3,}:?\s*\|)+\s*$/;
+const LINK = /\[([^\]\n]{1,300})\]\((https:\/\/[^\s)]{1,2000})\)/g;
+function cells(line) {
+    return line
+        .trim()
+        .replace(/^\|/, '')
+        .replace(/\|$/, '')
+        .split('|')
+        .map(cell => cell.trim());
+}
+/**
+ * The parts of an answer as a host shows them: its Markdown tables as tables,
+ * its HTTPS links as citations (once each, in order), the rest as words. Only
+ * `https:` links are citations: any other scheme stays words.
+ */
+export function answerParts(answer) {
+    const parts = [];
+    const lines = answer.split('\n');
+    let words = [];
+    const flush = () => {
+        const text = words.join('\n').trim();
+        if (text) {
+            parts.push({ kind: 'text', text });
+        }
+        words = [];
+    };
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? '';
+        const rule = lines[index + 1] ?? '';
+        if (TABLE_ROW.test(line) && TABLE_RULE.test(rule)) {
+            flush();
+            const columns = cells(line);
+            const rows = [];
+            index += 2;
+            while (index < lines.length && TABLE_ROW.test(lines[index] ?? '')) {
+                const row = cells(lines[index] ?? '');
+                rows.push(columns.map((_, column) => row[column] ?? ''));
+                index += 1;
+            }
+            index -= 1;
+            parts.push({ kind: 'table', columns, rows });
+            continue;
+        }
+        words.push(line);
+    }
+    flush();
+    const seen = new Set();
+    for (const part of [...parts]) {
+        if (part.kind !== 'text') {
+            continue;
+        }
+        for (const match of part.text.matchAll(LINK)) {
+            const [, title, url] = match;
+            if (!title || !url || seen.has(url)) {
+                continue;
+            }
+            seen.add(url);
+            parts.push({ kind: 'citation', title, url });
+        }
+    }
+    return parts;
+}

package/lib/portable/semanticOfAgUi.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A session's AG-UI events reduced to the semantic events a chat host
+ * renders (`semantic.ts`, version 1). A stream is read with `AgUiFrames` or
+ * `readRunStream` (`agui.ts`); this says what each event means to a host.
+ *
+ * The runtime's `loop.turn` event says which turn a stream is and where it
+ * stands (`running`, `finished`, `failed`: agent_runtimes/loop/apps/
+ * external_turns.py); a stopped session's stream ends without a run end,
+ * so `stop` is never read from an event: the host that pressed Stop says it.
+ * A question is read from `RUN_FINISHED.result.asking` only: the run stream
+ * carries no `loop.ask` event (that is the record's word, `record.py`).
+ *
+ * Moved from the Slack service (plans/DISCORD.md DC-005, SLACK S-205).
+ *
+ * @module portable/semanticOfAgUi
+ */
+import type { AgUiEvent } from './agui';
+import type { AskQuestion, SemanticEvent } from './semantic';
+/** What one turn says of itself: its id, and whether it is a replay. */
+export type TurnInfo = Readonly<{
+    replayed: boolean;
+    session: string;
+    state: string;
+    turn: string;
+}>;
+/** The turn a `loop.turn` event names, or `undefined` for any other event. */
+export declare function turnOf(event: AgUiEvent): TurnInfo | undefined;
+/**
+ * The question a turn ends on (`RUN_FINISHED.result.asking`), as
+ * a host asks it, or `undefined` when the value is not a question. A kind a
+ * host does not know is answered in Datalayer, as a form (SLACK S-307):
+ * never guessed to be text. (`conversation.ts`'s `questionOf`, for a native
+ * client, throws on such a kind instead.)
+ */
+export declare function askQuestionOf(value: unknown): AskQuestion | undefined;
+/**
+ * The semantic events (version 1) one AG-UI event means: none for an event a
+ * host does not show. `tools` keeps each running call's name by its id, for
+ * its result.
+ */
+export declare function semanticOf(event: AgUiEvent, tools: Map<string, string>): SemanticEvent[];