@datalayer/agent-runtimes 1.3.59 → 1.3.61

package/lib/examples/AgentDecideExample.js

@@ -0,0 +1,73 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * 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 { useMemo } from 'react';
+import { configurePlugin } from '@datalayer/reactor';
+import { Heading, Text } from '@primer/react';
+import { Box, setupPrimerPortals } from '@datalayer/primer-addons';
+import { ThemedProvider } from './utils/themedProvider';
+import { resolveExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
+import { AppRenderer, appDatalayerCreatePayload, } from '../loop/apps/AppRenderer';
+import { AssistantCharactersPlugin } from '../loop/plugins/assistant-characters';
+import { LoopAssistantPlugin } from '../loop/plugins/assistant';
+import { APP_CATALOGUE } from '../specs/apps';
+setupPrimerPortals();
+/** The local server: `?agentRuntimesUrl=` when given, else the examples' own. */
+function serverUrlOf() {
+    const named = typeof window === 'undefined'
+        ? null
+        : new URLSearchParams(window.location.search).get('agentRuntimesUrl');
+    return resolveExampleAgentRuntimesUrl('local', named ?? undefined);
+}
+const AgentDecideExample = () => {
+    const app = APP_CATALOGUE['decide'];
+    const serverUrl = useMemo(serverUrlOf, []);
+    // Made once: a new plugin on a render restarts the workspace.
+    const plugins = useMemo(() => [
+        AssistantCharactersPlugin,
+        configurePlugin(LoopAssistantPlugin, {
+            app: app.interface.assistant ?? undefined,
+            decisions: { serverUrl },
+        }),
+    ], [app, serverUrl]);
+    // The Local agent is the application's: created under its id with its
+    // spec, so that the server runs its instructions, its tool and its rule.
+    const localAgent = useMemo(() => ({ createPayload: appDatalayerCreatePayload(app) }), [app]);
+    return (_jsx(ThemedProvider, { children: _jsxs(Box, { sx: {
+                height: '100vh',
+                minHeight: 0,
+                display: 'flex',
+                bg: 'canvas.default',
+            }, children: [_jsx(Box, { sx: { flex: 1, minWidth: 0, minHeight: 0 }, children: _jsx(AppRenderer, { app: app, serverUrl: serverUrl, target: "local", localAgent: localAgent, plugins: plugins }) }), _jsxs(Box, { as: "aside", sx: {
+                        width: 320,
+                        flexShrink: 0,
+                        p: 3,
+                        borderLeft: '1px solid',
+                        borderColor: 'border.default',
+                        overflowY: 'auto',
+                    }, children: [_jsxs(Heading, { as: "h2", sx: { fontSize: 2, mb: 2 }, children: [app.emoji, " Decide"] }), _jsx(Text, { as: "p", sx: { fontSize: 1, mb: 2 }, children: "Typed decisions asked of Jev, the typed-decision model: yes or no with its probability, one of named options, or a score, each with its confidence." }), _jsxs(Text, { as: "p", sx: { fontSize: 1, mb: 2 }, children: [_jsx("strong", { children: "In the chat" }), ": ask \u201CIs this ticket urgent? \u2018Help! My payouts have been failing for 3 days.\u2019\u201D Its agent calls the ", _jsx("code", { children: "decide" }), " tool, a read it does without asking."] }), _jsxs(Text, { as: "p", sx: { fontSize: 1, mb: 2 }, children: [_jsx("strong", { children: "From the assistant" }), ": hover the character below and choose ", _jsx("em", { children: "Ask a decision" }), " \u2014 the situation, the question, and its type. The answer comes back in its balloon."] }), _jsxs(Text, { as: "p", sx: { fontSize: 0, color: 'fg.muted' }, children: ["Runs on the local agent-runtimes server at ", serverUrl, ", which asks Jev through ai-inference."] })] })] }) }));
+};
+export default AgentDecideExample;

package/lib/examples/AgentNotificationsExample.js

@@ -51,7 +51,7 @@ const AgentNotificationsInner = ({ onLogout, }) => {
             protocol: 'ag-ui',
             agentSpecId: AGENTSPEC_ID,
             enableSkills: true,
-            tools: [],
+            backendTools: [],
         },
     });
     const [notifications, setNotifications] = useState([]);

package/lib/examples/AgentSkillsExample.js

@@ -74,7 +74,7 @@ const AgentSkillsInner = ({ onLogout }) => {
             protocol: 'ag-ui',
             agentSpecId: AGENTSPEC_ID,
             enableSkills: true,
-            tools: [],
+            backendTools: [],
         },
     });
     const chatAuthToken = token === null ? undefined : token;

package/lib/examples/AgentspecsExample.js

@@ -602,7 +602,7 @@ githubClientId, kaggleToken, }) => {
         setGoal(spec.goal || '');
         setSystemPrompt(spec.systemPrompt || spec.goal || DEFAULT_SYSTEM_PROMPT);
         setSystemPromptCodemodeAddons(spec.systemPromptCodemodeAddons || '');
-        setTools(spec.tools || []);
+        setTools(spec.backendTools || []);
         setSandboxVariant(spec.sandboxVariant || '');
         if (spec.model) {
             setModel(spec.model);
@@ -650,7 +650,7 @@ githubClientId, kaggleToken, }) => {
             protocol: normalizedProtocol,
             systemPrompt: systemPrompt || undefined,
             systemPromptCodemodeAddons: systemPromptCodemodeAddons || undefined,
-            tools,
+            backendTools: tools,
             sandboxVariant: sandboxVariant || undefined,
             skills: selectedSkills,
             mcpServers: selectedMcpServers.map(server => ({
@@ -786,7 +786,7 @@ githubClientId, kaggleToken, }) => {
                 model: model,
                 system_prompt: systemPrompt || DEFAULT_SYSTEM_PROMPT,
                 system_prompt_codemode_addons: systemPromptCodemodeAddons || undefined,
-                tools: tools,
+                backend_tools: tools,
                 sandbox_variant: sandboxVariant || undefined,
                 enable_skills: enableSkills,
                 enable_codemode: enableCodemode,

package/lib/examples/ChatAssistantExample.js

@@ -21,6 +21,15 @@ import { ChatFloating } from '../chat';
 import { AssistantCharactersPlugin, assistantCharacterNamed, assistantCharactersOf, } from '../loop/plugins/assistant-characters';
 import { OwlCharacterPlugin } from './utils/owlCharacterPlugin';
 import { readAcsCharacter, readClippyCharacter, } from '../chat/assistant/formats';
+/**
+ * The agent-runtimes server the assistant talks to: `?agentRuntimesUrl=`
+ * when given, else this machine's on port 8765. It serves the `assistant`
+ * agent, and asks Jev the decisions asked from the balloon.
+ */
+const SERVER = ((typeof window === 'undefined'
+    ? null
+    : new URLSearchParams(window.location.search).get('agentRuntimesUrl')) ||
+    'http://127.0.0.1:8765').replace(/\/+$/, '');
 /** The plugins this page enables: Datalayer's characters and the owl's. */
 const reactor = buildReactorFromPlugins([
     AssistantCharactersPlugin,
@@ -75,6 +84,8 @@ const ChatAssistantExample = () => {
                                         catch (error) {
                                             setLoadError(error instanceof Error ? error.message : String(error));
                                         }
-                                    } }), loadError && (_jsx(Text, { as: "p", role: "alert", sx: { color: 'danger.fg', mt: 2 }, children: loadError })), typeof character !== 'string' && (_jsxs(Text, { as: "p", sx: { mt: 2 }, children: ["Playing ", character.name, "."] }))] })] }), _jsx(ChatFloating, { defaultViewMode: "assistant", assistantCharacter: drawn, protocol: "vercel-ai", endpoint: "http://127.0.0.1:8765/api/v1/vercel-ai/assistant", title: "Assistant", description: "Hello! Ask me anything about this page.", position: "bottom-right", useStore: false }, typeof character === 'string' ? character : character.sprite)] }) }));
+                                    } }), loadError && (_jsx(Text, { as: "p", role: "alert", sx: { color: 'danger.fg', mt: 2 }, children: loadError })), typeof character !== 'string' && (_jsxs(Text, { as: "p", sx: { mt: 2 }, children: ["Playing ", character.name, "."] }))] })] }), _jsx(ChatFloating, { defaultViewMode: "assistant", assistantCharacter: drawn, protocol: "vercel-ai", endpoint: `${SERVER}/api/v1/vercel-ai/assistant`, title: "Assistant", description: "Hello! Ask me anything about this page.", position: "bottom-right", useStore: false, 
+                    // Ask a decision beside the composer: Jev, through this server.
+                    decisions: { serverUrl: SERVER } }, typeof character === 'string' ? character : character.sprite)] }) }));
 };
 export default ChatAssistantExample;

package/lib/examples/example-selector.js

@@ -98,6 +98,7 @@ export const EXAMPLE_ENTRIES = [
     makeEntry('AgentCompactionExample', () => import('./AgentCompactionExample'), 'Set a context token budget and watch history compaction summarize older messages, with live from/to token and timing details.', ['example', 'agent', 'compaction', 'context', 'tokens']),
     makeEntry('AgentCodemodeExample', () => import('./AgentCodemodeExample'), 'Code mode execution and tool orchestration example.'),
     makeEntry('AgentCodeSandboxesExample', () => import('./AgentCodeSandboxesExample'), 'Launch sandbox-variant agent specs and compare code execution across backends.', ['example', 'agent', 'sandbox', 'codemode']),
+    makeEntry('AgentDecideExample', () => import('./AgentDecideExample'), 'Decide: typed decisions asked of Jev — yes or no, a choice, a score — from the chat, where the agent calls decide, and from the floating assistant’s Ask a decision.', ['example', 'agent', 'loop', 'app', 'decisions', 'jev', 'assistant']),
     makeEntry('AgentEvalsExample', () => import('./AgentEvalsExample'), 'Evaluation workflows for agent outputs.'),
     makeEntry('AgentGuardrailsExample', () => import('./AgentGuardrailsExample'), 'Guardrails and safety checks for agent runs.'),
     makeEntry('AgentHooksExample', () => import('./AgentHooksExample'), 'Pre-hooks and post-hooks lifecycle execution example.'),

package/lib/examples/index.d.ts

@@ -25,6 +25,7 @@ export { default as AgentCheckpointsExample } from './AgentCheckpointsExample';
 export { default as AgentCompactionExample } from './AgentCompactionExample';
 export { default as AgentCodemodeExample } from './AgentCodemodeExample';
 export { default as AgentCodeSandboxesExample } from './AgentCodeSandboxesExample';
+export { default as AgentDecideExample } from './AgentDecideExample';
 export { default as AgentEvalsExample } from './AgentEvalsExample';
 export { default as AgentGuardrailsExample } from './AgentGuardrailsExample';
 export { default as AgentHooksExample } from './AgentHooksExample';

package/lib/examples/index.js

@@ -31,6 +31,7 @@ export { default as AgentCheckpointsExample } from './AgentCheckpointsExample';
 export { default as AgentCompactionExample } from './AgentCompactionExample';
 export { default as AgentCodemodeExample } from './AgentCodemodeExample';
 export { default as AgentCodeSandboxesExample } from './AgentCodeSandboxesExample';
+export { default as AgentDecideExample } from './AgentDecideExample';
 export { default as AgentEvalsExample } from './AgentEvalsExample';
 export { default as AgentGuardrailsExample } from './AgentGuardrailsExample';
 export { default as AgentHooksExample } from './AgentHooksExample';

package/lib/examples/main.js

@@ -70,6 +70,9 @@ const ANONYMOUS_EXAMPLES = new Set([
     // An application beside its computer, on the local agent-runtimes server:
     // nothing allocated on Datalayer, and the machine itself needs no token.
     'LoopAppComputerExample',
+    // Decide, on the local agent-runtimes server as above: Jev is asked
+    // through the server's ai-inference, with the server's own key.
+    'AgentDecideExample',
     // Runs on the browser sandbox: nothing to allocate, nothing to sign into.
     'LoopShellExample',
     // Temporarily anonymous so the Jupyter output surface can be driven and

package/lib/loop/apps/appspec.js

@@ -89,7 +89,7 @@ export function emptyAppspec(kind = 'chat') {
         instructions: '',
         model: '',
         skills: [],
-        tools: [],
+        backendTools: [],
         context: [],
         contents: [],
         connections: [],
@@ -147,7 +147,7 @@ const KNOWN_KEYS = [
     'instructions',
     'model',
     'skills',
-    'tools',
+    'backend_tools',
     'context',
     'contents',
     'connections',
@@ -341,7 +341,7 @@ export function parseAppspec(document) {
         instructions: text(data.instructions),
         model: text(data.model),
         skills: texts(data.skills),
-        tools: texts(data.tools),
+        backendTools: texts(data.backend_tools),
         context: texts(data.context),
         contents: texts(data.contents),
         connections: records(data.connections).map(parseConnection),
@@ -541,7 +541,7 @@ export function dumpAppspec(app) {
         .text('instructions', app.instructions)
         .text('model', app.model)
         .list('skills', app.skills)
-        .list('tools', app.tools)
+        .list('backend_tools', app.backendTools)
         .list('context', app.context)
         .list('contents', app.contents)
         .list('connections', app.connections.map(connection => new Writer()

package/lib/loop/apps/checks.js

@@ -36,7 +36,7 @@ import { getModel } from '../../specs/models';
 import { getNotificationSpec } from '../../specs/notifications';
 import { getSkillSpec } from '../../specs/skills';
 import { getTeamSpec } from '../../specs/teams';
-import { getToolSpec } from '../../specs/tools';
+import { getBackendToolSpec } from '../../specs/backendTools';
 import { getTrack } from '../../specs/tracks';
 import { pluginsOffSetupNotes } from '../plugins/canvas-blocks';
 import { isAssistantCharacterId, parseAppspec } from './appspec';
@@ -173,8 +173,8 @@ function referenceProblems(app, organizationFrames) {
         if (!getSkillSpec(idOf(ref)))
             missing('skill', ref);
     }
-    for (const ref of app.tools) {
-        if (!getToolSpec(idOf(ref)))
+    for (const ref of app.backendTools) {
+        if (!getBackendToolSpec(idOf(ref)))
             missing('tool', ref);
     }
     for (const ref of app.checks.guards) {
@@ -241,7 +241,7 @@ function referenceProblems(app, organizationFrames) {
                 continue;
             const [server, name] = splitRef(target);
             if (server === undefined) {
-                if (!getToolSpec(name)) {
+                if (!getBackendToolSpec(name)) {
                     problems.push(`The rule “${rule.action}” names the tool “${target}”, which the catalogue does not have.`);
                 }
                 continue;
@@ -339,8 +339,8 @@ function setupNotes(app) {
     }
     for (const ref of app.skills)
         note('skill', ref, getSkillSpec(idOf(ref)));
-    for (const ref of app.tools)
-        note('tool', ref, getToolSpec(idOf(ref)));
+    for (const ref of app.backendTools)
+        note('tool', ref, getBackendToolSpec(idOf(ref)));
     for (const ref of app.checks.guards)
         note('Guard', ref, own(GUARD_CATALOGUE, idOf(ref)));
     for (const ref of app.checks.gates)

package/lib/loop/apps/rules.js

@@ -34,7 +34,7 @@
  *
  * @module loop/apps/rules
  */
-import { SERVER_ACTIONS, TOOL_ACTIONS } from '../../specs/actions';
+import { SERVER_ACTIONS, BACKEND_TOOL_ACTIONS } from '../../specs/actions';
 /** The four behaviours, from the freest to the most restricted. */
 export const BEHAVIOURS = [
     'do_it',
@@ -138,7 +138,7 @@ function entryOf(server, name) {
 export function classesOf(ref, args) {
     const [server, name] = splitRef(ref);
     if (server === undefined) {
-        return [...(own(TOOL_ACTIONS, name) ?? [])];
+        return [...(own(BACKEND_TOOL_ACTIONS, name) ?? [])];
     }
     const [classes, conditions] = entryOf(server, name);
     for (const condition of conditions) {

package/lib/loop/plugins/assistant/index.d.ts

@@ -9,7 +9,9 @@
  * while the conversation is out of sight, holds there the approval it waits
  * on, answered with *Approve* or *Deny* on the path every approval of it is
  * answered on (T-23, U-19), opens the conversation when clicked, and is
- * dragged about and sent away as the chat's own assistant is (T-27).
+ * dragged about and sent away as the chat's own assistant is (T-27). Given
+ * the runtime to ask (`decisions`), its balloon offers *Ask a decision*: a
+ * typed decision asked of Jev through the runtime, answered there.
  *
  * The workspace's chat is the conversation: on a page layout, its side panel
  * is opened and closed; where the conversation is always on screen, a click
@@ -33,6 +35,16 @@ export type LoopAssistantConfig = {
      * the balloon says an approval waits and the conversation answers it.
      */
     appId?: string;
+    /**
+     * The runtime decisions are asked at — its
+     * `/api/v1/configure/inference/decisions`, as the `decide` tool asks — and
+     * the token to ask with, if it needs one: the balloon offers *Ask a
+     * decision*. Without it, it does not.
+     */
+    decisions?: {
+        serverUrl: string;
+        token?: string;
+    };
 };
 /**
  * What the character acts out (T-22), from what the application is doing as
@@ -43,6 +55,6 @@ export declare function assistantStateOfTurn(turn: ChatTurnSnapshot, presence: P
     arriving?: boolean;
     leaving?: boolean;
 }): AssistantState;
-export declare function LoopAssistant({ app, person, appId, }: LoopAssistantConfig): JSX.Element | null;
+export declare function LoopAssistant({ app, person, appId, decisions, }: LoopAssistantConfig): JSX.Element | null;
 export declare const LoopAssistantPlugin: import("@datalayer/reactor").ReactorPlugin<LoopAssistantConfig, unknown, unknown>;
 export default LoopAssistantPlugin;

package/lib/loop/plugins/assistant/index.js

@@ -7,6 +7,8 @@ import { Box } from '@datalayer/primer-addons';
 import { useIAMStore } from '@datalayer/core/lib/state/substates/IAMState';
 import { pageLayoutPanelOpen, togglePagePanel, } from '@datalayer/primer-addons/lib/reactor';
 import { AssistantStage } from '../../../chat/assistant/AssistantStage';
+import { decisionsAskerAt } from '../../../chat/assistant/decisions';
+import { peekLine } from '../../../chat/assistant/ConversationBalloon';
 import { ASSISTANT_WORDS, assistantStateOf, keepAway, keptAway, latestSaying, } from '../../../chat/assistant/state';
 import { useApproveToolRequest, useRejectToolRequest, useToolApprovalsQuery, } from '../../../hooks/useToolApprovals';
 import { approvalsOfApp, ruleOfApproval } from '../app-rules/AppRulesCard';
@@ -67,7 +69,7 @@ function focusComposer() {
     const composer = document.querySelector('[data-chat-composer] textarea, [data-chat-composer] [contenteditable="true"]');
     composer?.focus();
 }
-export function LoopAssistant({ app, person, appId, }) {
+export function LoopAssistant({ app, person, appId, decisions, }) {
     const contributed = useContributions(LoopAssistantCharacter).map(entry => entry.value);
     const chosen = assistantCharacterFor(contributed, { app, person });
     const turnEntries = useContributions(LoopChatTurn);
@@ -110,6 +112,9 @@ export function LoopAssistant({ app, person, appId, }) {
     }, [open, saying?.id]);
     const stageRef = useRef(null);
     const drag = useViewportDrag(stageRef, { whole: true });
+    const decide = useMemo(() => decisions?.serverUrl
+        ? decisionsAskerAt(decisions.serverUrl, decisions.token)
+        : undefined, [decisions?.serverUrl, decisions?.token]);
     if (away !== 'none') {
         return null;
     }
@@ -138,7 +143,14 @@ export function LoopAssistant({ app, person, appId, }) {
             : presence === 'waiting'
                 ? { text: ASSISTANT_WORDS.waiting }
                 : unheard && saying
-                    ? { text: saying.text, more: saying.more }
+                    ? {
+                        // A peek: the first words; the rest is in the conversation.
+                        ...peekLine(saying.text),
+                        onDismiss: () => {
+                            setHeardId(saying.id);
+                            setFresh(false);
+                        },
+                    }
                     : { text: 'Click me to open the conversation.' };
     const insist = state === 'greeting' ||
         presence === 'waiting' ||
@@ -162,16 +174,21 @@ export function LoopAssistant({ app, person, appId, }) {
     };
     return (_jsxs(_Fragment, { children: [appId && signedIn ? (_jsx(WaitingApprovals, { appId: appId, onWaiting: setApproval })) : null, _jsx(AssistantStage, { character: chosen.character, state: state, size: SIZE, place: drag.position
                     ? { left: `${drag.position.left}px`, top: `${drag.position.top}px` }
-                    : { right: '24px', bottom: '24px' }, stageRef: stageRef, onDragStart: drag.onHandlePointerDown, open: open, onToggle: onToggle, balloon: balloon, insist: insist, onDismiss: onDismiss })] }));
+                    : { right: '24px', bottom: '24px' }, stageRef: stageRef, onDragStart: drag.onHandlePointerDown, open: open, onToggle: onToggle, balloon: balloon, insist: insist, onDismiss: onDismiss, decide: decide })] }));
 }
 export const LoopAssistantPlugin = definePlugin({
     name: LOOP_ASSISTANT_PLUGIN_NAME,
-    config: { app: undefined, person: undefined, appId: undefined },
+    config: {
+        app: undefined,
+        person: undefined,
+        appId: undefined,
+        decisions: undefined,
+    },
     displayName: 'Floating assistant',
     description: 'The chat as a character on the page: the application’s own, or the one the person chose, from the characters the enabled plugins contribute.',
     octicon: 'paperclip',
     build: ({ config }) => {
-        const Configured = () => (_jsx(LoopAssistant, { app: config.app, person: config.person, appId: config.appId }));
+        const Configured = () => (_jsx(LoopAssistant, { app: config.app, person: config.person, appId: config.appId, decisions: config.decisions }));
         return {
             components: [
                 { id: 'loop-assistant', slot: LoopSlots.root, Component: Configured },

package/lib/specs/actions.d.ts

@@ -11,7 +11,7 @@ import type { ActionClass, AppBehaviour, AppEscalation, ServerActionsSpec } from
 /** The classes of action, from the one that changes nothing. */
 export declare const ACTION_CLASSES: ActionClass[];
 /** What each tool of the tools catalogue does, by id. */
-export declare const TOOL_ACTIONS: Record<string, ActionClass[]>;
+export declare const BACKEND_TOOL_ACTIONS: Record<string, ActionClass[]>;
 /**
  * What each MCP server's tools do, by server id. `checked` is the day the
  * names were read off the running server; absent when nobody looked.

package/lib/specs/actions.js

@@ -12,7 +12,7 @@ export const ACTION_CLASSES = [
     'publish',
 ];
 /** What each tool of the tools catalogue does, by id. */
-export const TOOL_ACTIONS = {
+export const BACKEND_TOOL_ACTIONS = {
     'create-plan': ['read'],
     'current-time': ['read'],
     decide: ['read'],