@datalayer/agent-runtimes 1.3.59 → 1.3.61

package/lib/chat/assistant/DecisionAsk.js

@@ -0,0 +1,96 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { Button, FormControl, Select, Text, Textarea, TextInput, } from '@primer/react';
+import { Box } from '@datalayer/primer-addons';
+import { DEFAULT_SCORE_RANGE, decisionAskProblem, decisionRequest, decisionResponseWords, } from './decisions';
+/** The balloon's words for a decision. */
+export const DECISION_WORDS = {
+    ask: 'Ask a decision',
+    asking: 'Asking…',
+    submit: 'Ask',
+    cancel: 'Cancel',
+    again: 'Ask another',
+    types: {
+        noul: 'Yes or no',
+        choice: 'A choice',
+        score: 'A score',
+    },
+};
+const LINK_SX = {
+    mt: 1,
+    p: 0,
+    border: 0,
+    bg: 'transparent',
+    color: 'accent.fg',
+    textDecoration: 'underline',
+    cursor: 'pointer',
+    fontSize: 1,
+};
+export function DecisionAsk({ ask, onActiveChange, }) {
+    const [open, setOpen] = useState(false);
+    const [situation, setSituation] = useState('');
+    const [question, setQuestion] = useState('');
+    const [name, setName] = useState('');
+    const [type, setType] = useState('noul');
+    const [options, setOptions] = useState('');
+    const [from, setFrom] = useState(String(DEFAULT_SCORE_RANGE.from));
+    const [to, setTo] = useState(String(DEFAULT_SCORE_RANGE.to));
+    const [problem, setProblem] = useState();
+    const [asking, setAsking] = useState(false);
+    const [answer, setAnswer] = useState();
+    // Gone from the screen — the conversation opened, the balloon closed — it
+    // no longer holds the balloon up.
+    const activeChange = useRef(onActiveChange);
+    activeChange.current = onActiveChange;
+    useEffect(() => () => activeChange.current?.(false), []);
+    const show = (active) => {
+        setOpen(active);
+        onActiveChange?.(active);
+    };
+    const close = () => {
+        setAnswer(undefined);
+        setProblem(undefined);
+        show(false);
+    };
+    if (!open) {
+        return (_jsx(Box, { as: "button", type: "button", "data-balloon-ask-decision": "", onClick: () => show(true), sx: { ...LINK_SX, display: 'block' }, children: DECISION_WORDS.ask }));
+    }
+    if (answer !== undefined) {
+        return (_jsxs(Box, { "data-balloon-decision": "answered", sx: { mt: 2 }, children: [_jsx(Text, { as: "p", "data-decision-answer": "", sx: { m: 0, fontWeight: 'semibold' }, children: answer }), _jsxs(Box, { sx: { display: 'flex', gap: 2, mt: 2 }, children: [_jsx(Button, { size: "small", onClick: () => setAnswer(undefined), children: DECISION_WORDS.again }), _jsx(Button, { size: "small", variant: "invisible", onClick: close, children: DECISION_WORDS.cancel })] })] }));
+    }
+    const submit = async () => {
+        const asked = {
+            situation,
+            question,
+            type,
+            name,
+            options: options.split('\n'),
+            range: { from: Number(from), to: Number(to) },
+        };
+        const refused = decisionAskProblem(asked);
+        setProblem(refused);
+        if (refused) {
+            return;
+        }
+        const request = decisionRequest(asked);
+        setAsking(true);
+        try {
+            setAnswer(decisionResponseWords(request, await ask(request)));
+        }
+        catch (error) {
+            setAnswer(`Nothing was decided: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        finally {
+            setAsking(false);
+        }
+    };
+    return (_jsxs(Box, { as: "form", "data-balloon-decision": "asking", "aria-label": DECISION_WORDS.ask, onSubmit: (event) => {
+            event.preventDefault();
+            void submit();
+        }, onKeyDown: (event) => {
+            if (event.key === 'Escape') {
+                close();
+            }
+        }, sx: { mt: 2, display: 'flex', flexDirection: 'column', gap: 2 }, children: [_jsxs(FormControl, { children: [_jsx(FormControl.Label, { children: "Situation" }), _jsx(Textarea, { block: true, rows: 3, resize: "vertical", name: "situation", placeholder: "Help! My payouts have been failing for 3 days.", value: situation, onChange: event => setSituation(event.target.value) })] }), _jsxs(FormControl, { children: [_jsx(FormControl.Label, { children: "Question" }), _jsx(TextInput, { block: true, size: "small", name: "question", placeholder: "Is it urgent?", value: question, onChange: event => setQuestion(event.target.value) })] }), _jsxs(Box, { sx: { display: 'flex', gap: 2 }, children: [_jsxs(FormControl, { sx: { flex: 1 }, children: [_jsx(FormControl.Label, { children: "Type" }), _jsx(Select, { block: true, size: "small", name: "type", value: type, onChange: event => setType(event.target.value), children: Object.keys(DECISION_WORDS.types).map(option => (_jsx(Select.Option, { value: option, children: DECISION_WORDS.types[option] }, option))) })] }), _jsxs(FormControl, { sx: { flex: 1 }, children: [_jsx(FormControl.Label, { children: "Name" }), _jsx(TextInput, { block: true, size: "small", name: "name", placeholder: "Answer", value: name, onChange: event => setName(event.target.value) })] })] }), type === 'choice' && (_jsxs(FormControl, { children: [_jsx(FormControl.Label, { children: "Options, one per line" }), _jsx(Textarea, { block: true, rows: 3, resize: "vertical", name: "options", placeholder: 'Billing\nTech\nSales', value: options, onChange: event => setOptions(event.target.value) })] })), type === 'score' && (_jsxs(Box, { sx: { display: 'flex', gap: 2 }, children: [_jsxs(FormControl, { sx: { flex: 1 }, children: [_jsx(FormControl.Label, { children: "From" }), _jsx(TextInput, { block: true, size: "small", type: "number", name: "from", value: from, onChange: event => setFrom(event.target.value) })] }), _jsxs(FormControl, { sx: { flex: 1 }, children: [_jsx(FormControl.Label, { children: "To" }), _jsx(TextInput, { block: true, size: "small", type: "number", name: "to", value: to, onChange: event => setTo(event.target.value) })] })] })), problem ? (_jsx(Text, { as: "p", role: "alert", sx: { m: 0, color: 'danger.fg', fontSize: 0 }, children: problem })) : null, _jsxs(Box, { sx: { display: 'flex', gap: 2 }, children: [_jsx(Button, { size: "small", variant: "primary", type: "submit", disabled: asking, children: asking ? DECISION_WORDS.asking : DECISION_WORDS.submit }), _jsx(Button, { size: "small", type: "button", onClick: close, disabled: asking, children: DECISION_WORDS.cancel })] })] }));
+}
+export default DecisionAsk;

package/lib/chat/assistant/SpeechBalloon.d.ts

@@ -1,14 +1,19 @@
 /**
  * A speech balloon over something that stands for the agent — the floating
  * assistant's character, or the floating popup's button while the chat is
- * closed: the agent's newest words, as the Office Assistant said them
- * (LOOP T-23), with *Open the conversation* when there is more — and an
- * approval it waits on, answered there with *Approve* or *Deny*.
+ * closed: a peek, one short line — the agent's newest words, as the Office
+ * Assistant said them (LOOP T-23), cut to their first words, or a
+ * notification — that opens the conversation when clicked, and can be
+ * dismissed; an approval it waits on, answered there with *Approve* or
+ * *Deny*, and how many more wait; and, where the runtime can be asked and
+ * the conversation is elsewhere (the LOOP workspace), *Ask a decision*: a
+ * typed decision asked of Jev, its answer said back in the balloon.
  *
  * @module chat/assistant/SpeechBalloon
  */
 import type { JSX } from 'react';
 import { type BalloonApproval } from './state';
+import type { DecisionAsker } from './decisions';
 export interface SpeechBalloonProps {
     text: string;
     /** There is more than the balloon holds. */
@@ -25,6 +30,14 @@ export interface SpeechBalloonProps {
     tailAt: number;
     /** An approval it waits on: what is asked, and the two answers. */
     approval?: BalloonApproval;
+    /** Asks a typed decision of the runtime: offers *Ask a decision*. */
+    decide?: DecisionAsker;
+    /** The decision's form or answer is on screen: it stays, and is wider. */
+    onDecisionActive?: (active: boolean) => void;
+    /** Wider, for the decision's form. */
+    wide?: boolean;
+    /** Puts the peek away: a × beside its line. Never for an approval. */
+    onDismissPeek?: () => void;
 }
-export declare function SpeechBalloon({ text, more, onOpen, above, side, align, tailAt, approval, }: SpeechBalloonProps): JSX.Element;
+export declare function SpeechBalloon({ text, more, onOpen, above, side, align, tailAt, approval, decide, onDecisionActive, wide, onDismissPeek, }: SpeechBalloonProps): JSX.Element;
 export default SpeechBalloon;

package/lib/chat/assistant/SpeechBalloon.js

@@ -1,8 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Button, Text } from '@primer/react';
+import { Button, IconButton, Text } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
+import { XIcon } from '@primer/octicons-react';
 import { ASSISTANT_WORDS } from './state';
-export function SpeechBalloon({ text, more = false, onOpen, above, side = 'above', align, tailAt, approval, }) {
+import { moreWaiting } from './ConversationBalloon';
+import { DecisionAsk } from './DecisionAsk';
+export function SpeechBalloon({ text, more = false, onOpen, above, side = 'above', align, tailAt, approval, decide, onDecisionActive, wide = false, onDismissPeek, }) {
     return (_jsxs(Box, { role: "status", "aria-live": "polite", "data-speech-balloon": "", sx: {
             position: 'absolute',
             // Pixels, as strings: a number here is read as the theme's space
@@ -11,8 +14,8 @@ export function SpeechBalloon({ text, more = false, onOpen, above, side = 'above
                 ? { bottom: `${above}px` }
                 : { top: `${above}px` }),
             [align]: 0,
-            maxWidth: 280,
-            width: 'max-content',
+            maxWidth: wide ? 300 : 280,
+            width: wide ? 300 : 'max-content',
             px: 3,
             py: 2,
             bg: 'canvas.default',
@@ -37,15 +40,18 @@ export function SpeechBalloon({ text, more = false, onOpen, above, side = 'above
                 borderColor: 'border.default',
                 transform: side === 'above' ? 'rotate(45deg)' : 'rotate(225deg)',
             },
-        }, children: [_jsx(Text, { as: "p", sx: { m: 0 }, children: text }), approval && (_jsxs(Box, { "data-balloon-approval": approval.id, sx: { mt: 1 }, children: [_jsx(Text, { as: "p", sx: { m: 0, fontWeight: 'semibold' }, children: approval.asks }), approval.why ? (_jsx(Text, { as: "p", sx: { m: 0, color: 'fg.muted', fontSize: 0 }, children: approval.why })) : null, _jsxs(Box, { sx: { display: 'flex', gap: 2, mt: 2 }, children: [_jsx(Button, { size: "small", variant: "primary", disabled: approval.deciding, onClick: approval.onApprove, children: ASSISTANT_WORDS.approve }), _jsx(Button, { size: "small", disabled: approval.deciding, onClick: approval.onDeny, children: ASSISTANT_WORDS.deny })] }), approval.others > 0 ? (_jsx(Text, { as: "p", sx: { m: 0, mt: 1, color: 'fg.muted', fontSize: 0 }, children: `${approval.others} more waiting.` })) : null] })), more && (_jsx(Box, { as: "button", type: "button", onClick: onOpen, sx: {
-                    mt: 1,
-                    p: 0,
-                    border: 0,
-                    bg: 'transparent',
-                    color: 'accent.fg',
-                    textDecoration: 'underline',
-                    cursor: 'pointer',
-                    fontSize: 1,
-                }, children: "Open the conversation" }))] }));
+        }, children: [_jsxs(Box, { sx: { display: 'flex', alignItems: 'flex-start', gap: 1 }, children: [_jsx(Box, { as: "button", type: "button", "data-balloon-peek": "", "data-balloon-more": more ? '' : undefined, onClick: onOpen, sx: {
+                            flex: 1,
+                            minWidth: 0,
+                            m: 0,
+                            p: 0,
+                            border: 0,
+                            bg: 'transparent',
+                            color: 'inherit',
+                            font: 'inherit',
+                            textAlign: 'left',
+                            cursor: 'pointer',
+                            '&:hover': { textDecoration: 'underline' },
+                        }, children: text }), onDismissPeek && !approval ? (_jsx(IconButton, { icon: XIcon, size: "small", variant: "invisible", "aria-label": "Dismiss", "data-balloon-dismiss": "", onClick: onDismissPeek, sx: { mt: '-4px', mr: '-8px', flexShrink: 0 } })) : null] }), approval && (_jsxs(Box, { "data-balloon-approval": approval.id, sx: { mt: 1 }, children: [_jsx(Text, { as: "p", sx: { m: 0, fontWeight: 'semibold' }, children: approval.asks }), approval.why ? (_jsx(Text, { as: "p", sx: { m: 0, color: 'fg.muted', fontSize: 0 }, children: approval.why })) : null, _jsxs(Box, { sx: { display: 'flex', gap: 2, mt: 2 }, children: [_jsx(Button, { size: "small", variant: "primary", disabled: approval.deciding, onClick: approval.onApprove, children: ASSISTANT_WORDS.approve }), _jsx(Button, { size: "small", disabled: approval.deciding, onClick: approval.onDeny, children: ASSISTANT_WORDS.deny })] }), approval.others > 0 ? (_jsx(Text, { as: "p", sx: { m: 0, mt: 1, color: 'fg.muted', fontSize: 0 }, children: moreWaiting(approval.others) })) : null] })), decide && _jsx(DecisionAsk, { ask: decide, onActiveChange: onDecisionActive })] }));
 }
 export default SpeechBalloon;

package/lib/chat/assistant/decisions.d.ts

@@ -0,0 +1,104 @@
+/**
+ * A decision asked from the floating assistant's balloon: a situation, a
+ * question about it and its type — yes or no, a choice among options, a score
+ * on a range — asked of Jev, the typed-decision model, through the runtime's
+ * `POST /api/v1/configure/inference/decisions`: the route that asks as the
+ * `decide` tool does, with the token the runtime calls its models with.
+ *
+ * The answer comes back in plain words with its confidence: "Urgent: yes
+ * (0.87)", "Team: Billing (0.94)", "Score: 4 of 5 (0.5)".
+ *
+ * @module chat/assistant/decisions
+ */
+/** The three types of a question, as ai-inference names them. */
+export type DecisionType = 'noul' | 'choice' | 'score';
+/** What the balloon's form asks. */
+export interface DecisionAsk {
+    /** The text the question is about: a ticket, a message, a review. */
+    situation: string;
+    /** The question: a statement (yes or no) or a question (choice, score). */
+    question: string;
+    /** Its type. */
+    type: DecisionType;
+    /** A short name the answer is said under ("Urgent", "Team"). */
+    name?: string;
+    /** A choice's options, at least two. */
+    options?: string[];
+    /** A score's range, lowest first: from 1 to 5 by default. */
+    range?: {
+        from: number;
+        to: number;
+    };
+}
+/** One question as the runtime's route takes it (`DecisionQuestion`). */
+export interface DecisionQuestionBody {
+    name: string;
+    type: DecisionType;
+    instructions: string;
+    options: string[];
+}
+/** The body of `POST /configure/inference/decisions`. */
+export interface DecisionsRequestBody {
+    state: string;
+    questions: DecisionQuestionBody[];
+}
+/** One typed answer, as ai-inference gives it. */
+export interface DecisionAnswer {
+    type?: DecisionType;
+    /** noul: the probability that the statement holds. */
+    probability?: number;
+    /** choice: the option chosen. */
+    choice?: string;
+    /** score: the step, from 0. */
+    score?: number;
+    confidence?: number;
+    probabilities?: Record<string, number>;
+    /** score: each step's label, by its index. */
+    legend?: Record<string, string>;
+}
+/** What the route answers: the answers by name, or why nothing was decided. */
+export interface DecisionsResponseBody {
+    model?: string;
+    answers?: Record<string, DecisionAnswer>;
+    refusal?: string;
+}
+/** The balloon's asker: a request in, the route's answer out. */
+export type DecisionAsker = (body: DecisionsRequestBody) => Promise<DecisionsResponseBody>;
+/** The name an answer is said under when the form gave none. */
+export declare const DEFAULT_DECISION_NAME = "Answer";
+/** The default range of a score. */
+export declare const DEFAULT_SCORE_RANGE: {
+    readonly from: 1;
+    readonly to: 5;
+};
+/** The steps of a score's range, lowest first: `1..5` is `["1", …, "5"]`. */
+export declare function scoreSteps(range: {
+    from: number;
+    to: number;
+}): string[];
+/**
+ * Why the form cannot be asked as it is, in a sentence, or `undefined`.
+ */
+export declare function decisionAskProblem(ask: DecisionAsk): string | undefined;
+/** The form's ask as the runtime's route takes it: one named question. */
+export declare function decisionRequest(ask: DecisionAsk): DecisionsRequestBody;
+/** A probability or a confidence as said: two places at most, `0.5`, `0.87`. */
+export declare function confidenceWords(value: number): string;
+/**
+ * One answer in plain words with its confidence: "Urgent: yes (0.87)" — a
+ * no is said with the probability that it does not hold — "Team: Billing
+ * (0.94)", "Score: 4 of 5 (0.5)" — a rubric of words by its step,
+ * "Severity: blocking (0.7)".
+ */
+export declare function decisionAnswerWords(name: string, answer: DecisionAnswer, options?: readonly string[]): string;
+/**
+ * What the route answered, in the balloon's words: the one answer, or the
+ * sentence saying why nothing was decided.
+ */
+export declare function decisionResponseWords(request: DecisionsRequestBody, response: DecisionsResponseBody): string;
+/**
+ * Ask at a runtime: `POST {serverUrl}/api/v1/configure/inference/decisions`,
+ * with the person's token when there is one. A refusal of the route itself
+ * comes back as a sentence, never a throw.
+ */
+export declare function decisionsAskerAt(serverUrl: string, token?: string): DecisionAsker;

package/lib/chat/assistant/decisions.js

@@ -0,0 +1,161 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** The name an answer is said under when the form gave none. */
+export const DEFAULT_DECISION_NAME = 'Answer';
+/** The default range of a score. */
+export const DEFAULT_SCORE_RANGE = { from: 1, to: 5 };
+/** The longest range a score may have, in steps. */
+const MAX_SCORE_STEPS = 11;
+/** The steps of a score's range, lowest first: `1..5` is `["1", …, "5"]`. */
+export function scoreSteps(range) {
+    const steps = [];
+    for (let step = range.from; step <= range.to; step += 1) {
+        steps.push(String(step));
+    }
+    return steps;
+}
+/**
+ * Why the form cannot be asked as it is, in a sentence, or `undefined`.
+ */
+export function decisionAskProblem(ask) {
+    if (!ask.situation.trim()) {
+        return 'Say the situation the question is about.';
+    }
+    if (!ask.question.trim()) {
+        return 'Ask a question.';
+    }
+    if (ask.type === 'choice') {
+        const options = (ask.options ?? []).filter(option => option.trim());
+        if (options.length < 2) {
+            return 'A choice needs at least two options.';
+        }
+        if (new Set(options.map(option => option.trim())).size !== options.length) {
+            return 'Two options are the same.';
+        }
+    }
+    if (ask.type === 'score') {
+        const range = ask.range ?? DEFAULT_SCORE_RANGE;
+        if (!Number.isInteger(range.from) || !Number.isInteger(range.to)) {
+            return 'A score goes from a whole number to another.';
+        }
+        if (range.to <= range.from) {
+            return 'A score goes from a lower number to a higher one.';
+        }
+        if (range.to - range.from + 1 > MAX_SCORE_STEPS) {
+            return `A score has at most ${MAX_SCORE_STEPS} steps.`;
+        }
+    }
+    return undefined;
+}
+/** The form's ask as the runtime's route takes it: one named question. */
+export function decisionRequest(ask) {
+    const options = ask.type === 'choice'
+        ? (ask.options ?? []).map(option => option.trim()).filter(Boolean)
+        : ask.type === 'score'
+            ? scoreSteps(ask.range ?? DEFAULT_SCORE_RANGE)
+            : [];
+    return {
+        state: ask.situation.trim(),
+        questions: [
+            {
+                name: ask.name?.trim() || DEFAULT_DECISION_NAME,
+                type: ask.type,
+                instructions: ask.question.trim(),
+                options,
+            },
+        ],
+    };
+}
+/** A probability or a confidence as said: two places at most, `0.5`, `0.87`. */
+export function confidenceWords(value) {
+    return String(Number(value.toFixed(2)));
+}
+/**
+ * One answer in plain words with its confidence: "Urgent: yes (0.87)" — a
+ * no is said with the probability that it does not hold — "Team: Billing
+ * (0.94)", "Score: 4 of 5 (0.5)" — a rubric of words by its step,
+ * "Severity: blocking (0.7)".
+ */
+export function decisionAnswerWords(name, answer, options = []) {
+    if (typeof answer.probability === 'number' && answer.choice === undefined) {
+        const holds = answer.probability >= 0.5;
+        return `${name}: ${holds ? 'yes' : 'no'} (${confidenceWords(holds ? answer.probability : 1 - answer.probability)})`;
+    }
+    const confidence = typeof answer.confidence === 'number'
+        ? ` (${confidenceWords(answer.confidence)})`
+        : '';
+    if (typeof answer.score === 'number') {
+        const steps = options.length
+            ? options
+            : Object.keys(answer.legend ?? {})
+                .sort((a, b) => Number(a) - Number(b))
+                .map(key => answer.legend?.[key] ?? key);
+        const said = answer.legend?.[String(answer.score)] ?? steps[answer.score];
+        const last = steps[steps.length - 1];
+        // A range of numbers says where on it ("4 of 5"); a rubric of words says
+        // its step ("blocking").
+        const numeric = steps.length > 0 && steps.every(step => /^-?\d+$/.test(step.trim()));
+        return `${name}: ${said ?? answer.score + 1}${numeric && last !== undefined ? ` of ${last}` : ''}${confidence}`;
+    }
+    if (typeof answer.choice === 'string') {
+        return `${name}: ${answer.choice}${confidence}`;
+    }
+    return `${name}: no answer`;
+}
+/**
+ * What the route answered, in the balloon's words: the one answer, or the
+ * sentence saying why nothing was decided.
+ */
+export function decisionResponseWords(request, response) {
+    if (response.refusal) {
+        return response.refusal;
+    }
+    const [question] = request.questions;
+    const answer = response.answers?.[question.name];
+    if (!answer) {
+        return 'Nothing was decided: the answer did not come back.';
+    }
+    return decisionAnswerWords(question.name, answer, question.options);
+}
+/**
+ * Ask at a runtime: `POST {serverUrl}/api/v1/configure/inference/decisions`,
+ * with the person's token when there is one. A refusal of the route itself
+ * comes back as a sentence, never a throw.
+ */
+export function decisionsAskerAt(serverUrl, token) {
+    const base = serverUrl.replace(/\/+$/, '');
+    return async (body) => {
+        let response;
+        try {
+            response = await fetch(`${base}/api/v1/configure/inference/decisions`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...(token ? { Authorization: `Bearer ${token}` } : {}),
+                },
+                body: JSON.stringify(body),
+            });
+        }
+        catch {
+            return {
+                refusal: 'Nothing was decided: the runtime could not be reached.',
+            };
+        }
+        if (!response.ok) {
+            let detail = '';
+            try {
+                const said = (await response.json());
+                detail = typeof said.detail === 'string' ? said.detail : '';
+            }
+            catch {
+                // No body worth saying.
+            }
+            return {
+                refusal: `Nothing was decided: the runtime refused it (${response.status})${detail ? `: ${detail}` : '.'}`,
+            };
+        }
+        return (await response.json());
+    };
+}

package/lib/chat/assistant/state.d.ts

@@ -71,7 +71,7 @@ export interface AssistantSaying {
     /** Whether there was more than the balloon holds. */
     more: boolean;
 }
-/** How much of a message the balloon says before *Open the conversation*. */
+/** How much of a message is kept as the agent's saying before it is cut. */
 export declare const SAYING_LIMIT = 220;
 /**
  * The newest thing the agent said, as the Office Assistant said it: in the

package/lib/chat/assistant/state.js

@@ -49,7 +49,7 @@ export const ASSISTANT_WORDS = {
     /** Its deployment is paused (R-17). */
     paused: 'Paused — it answers again once it is resumed.',
 };
-/** How much of a message the balloon says before *Open the conversation*. */
+/** How much of a message is kept as the agent's saying before it is cut. */
 export const SAYING_LIMIT = 220;
 /**
  * The newest thing the agent said, as the Office Assistant said it: in the

package/lib/chat/base/ChatBase.js

@@ -463,6 +463,8 @@ function parseApprovedMcpToolsByServer(mcpStatusData) {
 // ---------------------------------------------------------------------------
 // ChatBase (outer wrapper — ensures QueryClient is available)
 // ---------------------------------------------------------------------------
+/** When the welcome is said: it has no time of its own. */
+const WELCOME_AT = new Date(0);
 /**
  * ChatBase component — Universal chat panel supporting store, protocol, and custom modes.
  */
@@ -507,7 +509,7 @@ function ChatBaseInner({ title, subtitle, showHeader = false, showTokenUsage = t
 // Mode selection
 useStore: useStoreMode = true, protocol: protocolRaw, onSendMessage, onSendReady, onLoadingChange, onContextSnapshot, enableStreaming = false, 
 // Extended props
-brandIcon, avatarConfig, headerButtons, showPoweredBy = false, poweredByProps, emptyState, renderToolResult, renderHeader, showTurnFooter = true, notebookToolSurfacesId, footerContent, showInformation = false, onInformationClick, headerContent, children, borderRadius, backgroundColor, border, boxShadow, compact = false, placeholder, description = 'Start a conversation with the AI agent.', onStateUpdate, onNewChat, onClear, onMessagesChange, onItemsChange, onDisplayItemsChange, autoFocus = false, suggestions, submitOnSuggestionClick = true, hideMessagesAfterToolUI = false, focusTrigger, frontendTools: frontendToolsProp, enableEphemeralNotebook = false, initialEphemeralNotebookOpen = true, onEphemeralNotebookOpenChange, enableEphemeralDocument = false, initialEphemeralSurfaceMode, onEphemeralSurfaceModeChange, collapsed = false, onExpandFromCollapsed, ephemeralNotebookToolbar, ephemeralNotebookToolbarExtraItems, ephemeralDocumentToolbarExtraItems, ephemeralNotebookCollaborationProvider, ephemeralNotebookCollaborationDocumentId, ephemeralDocumentCollaboration, ephemeralRuntimeOverride, 
+brandIcon, avatarConfig, headerButtons, showPoweredBy = false, poweredByProps, emptyState, renderToolResult, renderHeader, showTurnFooter = true, notebookToolSurfacesId, footerContent, welcome, trailingContent, showInformation = false, onInformationClick, headerContent, children, borderRadius, backgroundColor, border, boxShadow, compact = false, placeholder, description = 'Start a conversation with the AI agent.', onStateUpdate, onNewChat, onClear, onMessagesChange, onItemsChange, onDisplayItemsChange, autoFocus = false, suggestions, submitOnSuggestionClick = true, hideMessagesAfterToolUI = false, focusTrigger, frontendTools: frontendToolsProp, enableEphemeralNotebook = false, initialEphemeralNotebookOpen = true, onEphemeralNotebookOpenChange, enableEphemeralDocument = false, initialEphemeralSurfaceMode, onEphemeralSurfaceModeChange, collapsed = false, onExpandFromCollapsed, ephemeralNotebookToolbar, ephemeralNotebookToolbarExtraItems, ephemeralDocumentToolbarExtraItems, ephemeralNotebookCollaborationProvider, ephemeralNotebookCollaborationDocumentId, ephemeralDocumentCollaboration, ephemeralRuntimeOverride, 
 // Tool invocation hooks
 onToolCallStart, onToolCallComplete, 
 // Identity/Authorization props
@@ -3478,7 +3480,23 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
             })
                 .filter(item => item.message)
             : undefined;
-    const messagesContent = children ? (children) : (_jsx(Box, { sx: {
+    /*
+     * The welcome, as the first message: drawn as the agent's own words are,
+     * never sent nor kept. With it, the history is never empty, so the empty
+     * state gives way to it.
+     */
+    const welcomedItems = welcome
+        ? [
+            {
+                id: '__welcome__',
+                role: 'assistant',
+                content: welcome,
+                createdAt: WELCOME_AT,
+            },
+            ...displayItems,
+        ]
+        : displayItems;
+    const messagesContent = children ? (children) : (_jsxs(Box, { sx: {
             display: 'flex',
             flexDirection: 'column',
             minHeight: 0,
@@ -3494,7 +3512,7 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
             maxWidth: 920,
             mx: 'auto',
             bg: 'canvas.default',
-        }, children: _jsx(ChatMessageList, { displayItems: displayItems, isLoading: isLoading, isStreaming: isStreaming, showLoadingIndicator: showLoadingIndicator, hideMessagesAfterToolUI: hideMessagesAfterToolUI, avatarConfig: defaultAvatarConfig, padding: padding, renderToolResult: effectiveRenderToolResult, approvalConfig: approvalConfig, messagesEndRef: messagesEndRef, onRespond: handleRespond, showTurnFooters: showTurnFooter, agentUsage: agentUsage, onRemoveItems: handleRemoveItems, mcpServers: filteredMcpServers, emptyContent: launching ? null : (_jsx(ChatEmptyState, { emptyState: emptyState, brandIcon: brandIcon, description: resolvedDescription, suggestions: resolvedSuggestions, submitOnSuggestionClick: submitOnSuggestionClick, onSuggestionSubmit: handleSuggestionSubmit, onSuggestionFill: handleSuggestionFill })) }) }));
+        }, children: [_jsx(ChatMessageList, { displayItems: welcomedItems, isLoading: isLoading, isStreaming: isStreaming, showLoadingIndicator: showLoadingIndicator, hideMessagesAfterToolUI: hideMessagesAfterToolUI, avatarConfig: defaultAvatarConfig, padding: padding, renderToolResult: effectiveRenderToolResult, approvalConfig: approvalConfig, messagesEndRef: messagesEndRef, onRespond: handleRespond, showTurnFooters: showTurnFooter, agentUsage: agentUsage, onRemoveItems: handleRemoveItems, mcpServers: filteredMcpServers, emptyContent: launching ? null : (_jsx(ChatEmptyState, { emptyState: emptyState, brandIcon: brandIcon, description: resolvedDescription, suggestions: resolvedSuggestions, submitOnSuggestionClick: submitOnSuggestionClick, onSuggestionSubmit: handleSuggestionSubmit, onSuggestionFill: handleSuggestionFill })) }), trailingContent] }));
     const inputToolbar = showInput ? (_jsx(InputPrompt, { input: input, setInput: setInput, isLoading: isLoading, kernelStatus: liveKernelStatus, connectionConfirmed: connectionConfirmed, placeholder: placeholder, 
         /*
           The same openers the empty state offers, typed into the box they would
@@ -3695,7 +3713,7 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
                                 top: 8,
                                 right: 8,
                                 zIndex: 6,
-                            }, children: _jsx(IconButton, { icon: SidebarExpandIcon, "aria-label": "Open chat", onClick: onExpandFromCollapsed, variant: "default", size: "small" }) })) : (_jsx(FloatingBrandButton, { isOpen: false, onToggle: onExpandFromCollapsed, position: "bottom-right", tooltip: "Open chat" })))] })) : (_jsxs(_Fragment, { children: [_jsx(Box, { ref: messagesContainerRef, sx: {
+                            }, children: _jsx(IconButton, { icon: SidebarExpandIcon, "aria-label": "Open chat", onClick: onExpandFromCollapsed, variant: "default", size: "small" }) })) : (_jsx(FloatingBrandButton, { isOpen: false, onToggle: onExpandFromCollapsed, position: "bottom-right", tooltip: "Open chat" })))] })) : (_jsxs(_Fragment, { children: [_jsx(Box, { ref: messagesContainerRef, "data-chat-history": "", sx: {
                             flex: 1,
                             flexGrow: 1,
                             minHeight: 0,

package/lib/chat/marks/toolMarks.js

@@ -16,7 +16,7 @@
 import { MCP_SERVER_LIBRARY } from '../../specs/mcpServers';
 import { SKILLS_CATALOG } from '../../specs/skills';
 import { FRONTEND_TOOL_CATALOG } from '../../specs/frontendTools';
-import { TOOL_CATALOG } from '../../specs/tools';
+import { BACKEND_TOOL_CATALOG } from '../../specs/backendTools';
 /** The tools the skills area runs a skill through. */
 export const SKILL_TOOLS = new Set([
     'run_skill_script',
@@ -57,7 +57,7 @@ function frontendTools() {
 function runtimeTools() {
     if (!runtimeIndex) {
         runtimeIndex = new Map();
-        for (const spec of Object.values(TOOL_CATALOG)) {
+        for (const spec of Object.values(BACKEND_TOOL_CATALOG)) {
             const method = spec.runtime?.method;
             if (method && !runtimeIndex.has(method)) {
                 runtimeIndex.set(method, { id: spec.id, ...marksOf(spec) });

package/lib/config/AgentConfiguration.d.ts

@@ -19,7 +19,8 @@ export interface LibraryAgentspec {
     icon?: string | null;
     color?: string | null;
     skills: string[];
-    tools?: string[];
+    /** Backend tools (agentspecs/backend-tools), as the runtime serves them. */
+    backendTools?: string[];
     systemPrompt?: string | null;
     systemPromptCodemodeAddons?: string | null;
     suggestions: string[];

package/lib/config/AgentConfiguration.js

@@ -477,10 +477,10 @@ export const AgentConfiguration = ({ agentLibrary, protocol: transport, extensio
             .map(selection => normalizeMcpServerId(selection.id));
     }, [selectedMcpServers, catalogServerIdSet]);
     const resolvedSpecTools = useMemo(() => {
-        if (!activeSpec || !Array.isArray(activeSpec.tools)) {
+        if (!activeSpec || !Array.isArray(activeSpec.backendTools)) {
             return [];
         }
-        return activeSpec.tools
+        return activeSpec.backendTools
             .map(tool => normalizeToolLabel(tool))
             .filter((tool) => !!tool);
     }, [activeSpec]);

package/lib/examples/AgentDecideExample.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Decide: typed decisions asked of Jev (`cloudflare:wrk/typesafe/jev`), the
+ * typed-decision model, from the chat and from the floating assistant.
+ *
+ * The *Decide* application of the catalogue (agentspecs `apps/decide.yaml`)
+ * in the LOOP workspace, on the Local target: its agent — `example-simple`
+ * with the `decide` tool — runs on the local agent-runtimes server, and
+ * answers a question about a text by asking a typed decision. The floating
+ * assistant beside it offers *Ask a decision* in its balloon: the situation,
+ * the question and its type, asked through the same server's
+ * `/api/v1/configure/inference/decisions`, the route that asks as `decide`
+ * does, with the same token.
+ *
+ * The server needs ai-inference: start it with
+ * `AGENT_RUNTIMES_INFERENCE_PROVIDER_OVERRIDE=datalayer`,
+ * `DATALAYER_AI_INFERENCE_URL=https://r1.datalayer.run` and
+ * `DATALAYER_AI_INFERENCE_API_KEY` set from `DATALAYER_API_KEY`. Another
+ * server than `http://localhost:8765` is named with `?agentRuntimesUrl=`.
+ *
+ * @module examples/AgentDecideExample
+ */
+import React from 'react';
+declare const AgentDecideExample: React.FC;
+export default AgentDecideExample;