@datalayer/agent-runtimes 1.5.44 → 1.5.46

package/lib/portable/hosts/turnState.js

@@ -0,0 +1,113 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export class TurnState {
+    #answer = '';
+    #asking;
+    #approvals = [];
+    #ended;
+    #error;
+    #files = [];
+    #status = 'Working…';
+    #tools = new Map();
+    /** Whether the turn finished while it streamed: else a `turn.completed` delivery finishes it. */
+    get complete() {
+        return this.#ended === 'completion';
+    }
+    /** Whether the turn ended (answered, stopped, failed) or waits on a question. */
+    get ended() {
+        return this.#ended !== undefined || this.#asking !== undefined;
+    }
+    /** Whether the turn still runs: not ended, and asking nothing. */
+    get running() {
+        return !this.ended;
+    }
+    /** The answer so far, its tables and citations as Markdown. */
+    get answer() {
+        return this.#answer;
+    }
+    /** The question the turn ends on, if any. */
+    get asking() {
+        return this.#asking;
+    }
+    /** The tools whose approval the turn waited on, in order. */
+    get approvals() {
+        return this.#approvals;
+    }
+    /** How the turn ended, if it did. */
+    get ending() {
+        return this.#ended;
+    }
+    /** What the run said when it failed. */
+    get error() {
+        return this.#error;
+    }
+    get files() {
+        return this.#files;
+    }
+    /** The status line: what the turn is doing now. */
+    get status() {
+        return this.#status;
+    }
+    /** Each tool the turn used, by its call, in the order first seen. */
+    get tools() {
+        return this.#tools;
+    }
+    apply(event) {
+        switch (event.kind) {
+            case 'text':
+                this.#answer += event.text;
+                break;
+            case 'progress':
+                this.#status = event.label;
+                break;
+            case 'tool':
+                this.#tools.set(event.id || event.name, {
+                    name: event.name,
+                    status: event.status,
+                });
+                this.#status = `${event.status === 'running' ? 'Using' : event.status === 'failed' ? 'Failed:' : 'Used'} ${event.name}`;
+                break;
+            case 'approval':
+                this.#approvals.push(event.toolName);
+                this.#status = `Waiting for approval to use ${event.toolName}`;
+                break;
+            case 'file':
+                this.#files.push({
+                    mediaType: event.mediaType,
+                    name: event.name,
+                    url: event.url,
+                });
+                break;
+            case 'table':
+                this.#answer += `\n\n| ${event.columns.join(' | ')} |\n|${event.columns.map(() => '---').join('|')}|\n${event.rows.map(row => `| ${row.join(' | ')} |`).join('\n')}\n`;
+                break;
+            case 'citation':
+                this.#answer += `\n[${event.title}](${event.url})`;
+                break;
+            case 'ask':
+                this.#asking = event.question;
+                this.#status = 'Waiting for your answer';
+                break;
+            case 'completion':
+                // The streamed words are the answer: a completion's text only
+                // stands in for none, never repeated after them.
+                if (event.text && !this.#answer) {
+                    this.#answer = event.text;
+                }
+                this.#ended = 'completion';
+                this.#status = 'Complete';
+                break;
+            case 'stop':
+                this.#ended = 'stop';
+                this.#status = 'Stopped';
+                break;
+            case 'error':
+                this.#ended = 'error';
+                this.#error = event.message;
+                this.#status = 'Could not finish';
+                break;
+        }
+    }
+}

package/lib/portable/index.d.ts

@@ -9,6 +9,8 @@
 export { messageOfApproval, normalizeApproval, whyAsked, type ApprovalArgs, type ApprovalRecord, type MessageAsked, } from './approvals';
 export { actionOf, APPROVAL_CARD_WORDS, approvalCardOf, argumentsShown, type ApprovalCard, type ApprovalCardProps, type ApprovalCardSource, } from './approvalCard';
 export { AgUiFrames, endsRun, eventsOfStream, NOT_STREAMING, REACTOR_UI_NAME, readRunStream, RUN_CUT_SHORT, toolResultOf, UI_ON_RUN, type AgUiEvent, type ToolResultSaid, } from './agui';
+export { answerParts, isTerminal, SEMANTIC_EVENTS_VERSION, SEMANTIC_KINDS, type AnswerPart, type AskQuestion, type SemanticEvent, type SemanticKind, } from './semantic';
+export { askQuestionOf, semanticOf, turnOf, type TurnInfo, } from './semanticOfAgUi';
 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';

package/lib/portable/index.js

@@ -15,6 +15,9 @@ export { messageOfApproval, normalizeApproval, whyAsked, } from './approvals';
 export { actionOf, APPROVAL_CARD_WORDS, approvalCardOf, argumentsShown, } from './approvalCard';
 // 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';
+// A run's stream reduced to what a chat host shows (DISCORD DC-005, SLACK S-205).
+export { answerParts, isTerminal, SEMANTIC_EVENTS_VERSION, SEMANTIC_KINDS, } from './semantic';
+export { askQuestionOf, semanticOf, turnOf, } from './semanticOfAgUi';
 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';

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[];