@datalayer/agent-runtimes 1.3.94 → 1.3.96

package/lib/apps/plugins/agents/switchable.d.ts

@@ -55,6 +55,18 @@ export type SandboxTargetSpec = {
 };
 /** The four, in the order the control shows them: nearest first. */
 export declare const SANDBOX_TARGETS: readonly SandboxTarget[];
+/**
+ * Why a target is shown but not offered here — said on it — or nothing when
+ * it is offered.
+ *
+ * *Local* is a local agent with the Jupyter server it starts beside itself,
+ * and a web page has no machine of the reader's to start them on. Decided
+ * 2026-10-10 (Eric): not offered on the web for now, and left in the switch,
+ * held, so that a reader sees what exists and why it is not here. Inside
+ * JupyterLab it is offered as before — the same line the code-sandbox picker
+ * draws for a Jupyter Server's kernels (`codeSandboxProviders`).
+ */
+export declare function heldTargetReason(target: SandboxTarget): string | undefined;
 export declare const TARGET_SPECS: Record<SandboxTarget, SandboxTargetSpec>;
 /** Whether an agent runs on this target — the question the chat asks. */
 export declare function targetHasAgent(target: SandboxTarget): boolean;

package/lib/apps/plugins/agents/switchable.js

@@ -22,6 +22,7 @@
  * @module apps/plugins/agents/switchable
  */
 import { computed, signal, } from '@datalayer/reactor';
+import { insideJupyterLab } from './host';
 import { browserSource, createBrowserSandboxService, } from './browserService';
 import { createServerSandboxService, } from './service';
 /**
@@ -40,6 +41,23 @@ export const SANDBOX_TARGETS = [
     'jupyter',
     'datalayer',
 ];
+/**
+ * Why a target is shown but not offered here — said on it — or nothing when
+ * it is offered.
+ *
+ * *Local* is a local agent with the Jupyter server it starts beside itself,
+ * and a web page has no machine of the reader's to start them on. Decided
+ * 2026-10-10 (Eric): not offered on the web for now, and left in the switch,
+ * held, so that a reader sees what exists and why it is not here. Inside
+ * JupyterLab it is offered as before — the same line the code-sandbox picker
+ * draws for a Jupyter Server's kernels (`codeSandboxProviders`).
+ */
+export function heldTargetReason(target) {
+    if (target === 'local' && !insideJupyterLab()) {
+        return 'Not offered on the web for now: a local agent and the Jupyter server it starts run beside JupyterLab, not in a page.';
+    }
+    return undefined;
+}
 export const TARGET_SPECS = {
     browser: {
         label: 'Browser',
@@ -298,6 +316,11 @@ export function createSwitchableSandboxService({ serverUrl, initialTarget = 'loc
             if (next === previous) {
                 return;
             }
+            // Held here: refused whoever asks, not only by the switch's button.
+            const held = heldTargetReason(next);
+            if (held) {
+                throw new Error(held);
+            }
             // Disconnect first: two live sandboxes would race to report status, and
             // the reader would watch the header flicker between them.
             disconnect?.();

package/lib/apps/plugins/app-computer/AppComputer.js

@@ -126,11 +126,27 @@ export function AppComputer({ app, workspace, }) {
         ? noRuntimeSaid(workspace?.sandbox ?? IDLE_SANDBOX_SNAPSHOT, chatText)
         : undefined;
     const agentId = workspace?.agentId || app.id;
+    const [state, setState] = useState();
+    /*
+     * Where its files come from (STUDIO D-22).
+     *
+     * The runtime says it when the plane keeps a host for what applications
+     * serve (`servedFrom`, `DATALAYER_USER_APPS_URL`): a file is then fetched
+     * from that origin rather than from the runtimes' host, which is every
+     * runtime's and so same-origin with all of them. Read from the computer's
+     * own answer rather than configured here, because it is the runtime that
+     * knows which names it answers to; unsaid, nothing changes.
+     */
+    const servedFrom = state?.servedFrom ?? '';
     const context = useMemo(() => serverUrl === undefined
         ? undefined
-        : { serverUrl, agentId, token: token || undefined }, [serverUrl, agentId, token]);
+        : {
+            serverUrl,
+            agentId,
+            token: token || undefined,
+            userAppsUrl: servedFrom || undefined,
+        }, [serverUrl, agentId, token, servedFrom]);
     const parts = computerParts(app);
-    const [state, setState] = useState();
     const [error, setError] = useState('');
     const [busy, setBusy] = useState(false);
     // Nothing is set once it is gone: an answer may come back after.

package/lib/apps/plugins/canvas-parts/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The agent's toolbox, contributed (LOOP C-20): one plugin per source of
+ * parts — the servers of the catalogue a connection reaches, its skills, its
+ * models, and the rules, tests and events an agent answers to — each
+ * contributing to `loop.canvas.part`. The toolbox is what the enabled
+ * plugins contribute, as the palette is (`canvas-blocks`, C-12).
+ *
+ * @module apps/plugins/canvas-parts
+ */
+import { type ReactorPlatform, type ReactorPlugin } from '@datalayer/reactor';
+import { LoopCanvasPart, type CanvasPartContribution } from '../../core/canvasParts';
+type PartsReader = {
+    getContributions: (point: typeof LoopCanvasPart) => ReadonlyArray<{
+        value: CanvasPartContribution;
+    }>;
+};
+/** The short ids an organization turns off, and the plugin each names. */
+export declare const CANVAS_PART_SOURCES: readonly ["connections", "skills", "models", "rules", "tests", "events"];
+export type CanvasPartSource = (typeof CANVAS_PART_SOURCES)[number];
+export declare const canvasPartsPluginName: (source: CanvasPartSource) => string;
+/** A connection to each server of the catalogue: read-only, as its owner, every tool. */
+export declare const CONNECTION_PARTS: CanvasPartContribution[];
+/** Each skill of the catalogue. */
+export declare const SKILL_PARTS: CanvasPartContribution[];
+/** Each chat model of the catalogue. */
+export declare const MODEL_PARTS: CanvasPartContribution[];
+/** The rules a person most often sets, each one of the four behaviours. */
+export declare const RULE_PARTS: CanvasPartContribution[];
+/** A test: a question, and what a good answer does. */
+export declare const TEST_PARTS: CanvasPartContribution[];
+/** The events an application answers (C-21): on a schedule, on an event, once. */
+export declare const EVENT_PARTS: CanvasPartContribution[];
+export declare const CANVAS_PART_PLUGINS: ReactorPlugin<Record<string, never>, unknown, unknown>[];
+/** The toolbox's reactor, its named plugins disabled; a name no plugin has is refused. */
+export declare function canvasPartsReactor(disabled?: readonly string[], plugins?: ReactorPlugin<any, any, any>[]): ReactorPlatform;
+/**
+ * The toolbox for an organization's plugins off: the ids it turns off that
+ * name a source of parts (`skills`, …) take those parts off; the rest are the
+ * palette's.
+ */
+export declare function canvasPartsReactorOf(pluginsOff: readonly string[]): ReactorPlatform;
+/** What the toolbox offers: the parts the enabled plugins contribute, in their order. */
+export declare function canvasPartsOf(reactor: PartsReader): CanvasPartContribution[];
+export {};

package/lib/apps/plugins/canvas-parts/index.js

@@ -0,0 +1,209 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The agent's toolbox, contributed (LOOP C-20): one plugin per source of
+ * parts — the servers of the catalogue a connection reaches, its skills, its
+ * models, and the rules, tests and events an agent answers to — each
+ * contributing to `loop.canvas.part`. The toolbox is what the enabled
+ * plugins contribute, as the palette is (`canvas-blocks`, C-12).
+ *
+ * @module apps/plugins/canvas-parts
+ */
+import { buildReactorFromPlugins, contribution, definePlugin, } from '@datalayer/reactor';
+import { MCP_SERVER_LIBRARY } from '../../../specs/mcpServers';
+import { listChatModels } from '../../../specs/models';
+import { getSkillSpecs } from '../../../specs/skills';
+import { LoopCanvasPart, } from '../../core/canvasParts';
+/** The short ids an organization turns off, and the plugin each names. */
+export const CANVAS_PART_SOURCES = [
+    'connections',
+    'skills',
+    'models',
+    'rules',
+    'tests',
+    'events',
+];
+export const canvasPartsPluginName = (source) => `@datalayer/loop-plugin-parts-${source}`;
+const partsPlugin = (source, displayName, parts) => definePlugin({
+    name: canvasPartsPluginName(source),
+    displayName,
+    description: `${displayName} in the agent's toolbox on the Canvas.`,
+    octicon: 'package',
+    contributes: parts.map(part => contribution(LoopCanvasPart, part, { id: part.id })),
+});
+/** A connection to each server of the catalogue: read-only, as its owner, every tool. */
+export const CONNECTION_PARTS = Object.values(MCP_SERVER_LIBRARY).map(server => ({
+    id: `connection:${server.id}`,
+    kind: 'connection',
+    label: server.name,
+    says: server.description ?? '',
+    emoji: server.emoji,
+    example: { server: server.id, access: 'read', as: 'owner', only: [] },
+    enabled: server.enabled,
+}));
+/** Each skill of the catalogue. */
+export const SKILL_PARTS = getSkillSpecs().map(skill => ({
+    id: `skill:${skill.id}`,
+    kind: 'skill',
+    label: skill.name,
+    says: skill.description,
+    emoji: skill.emoji,
+    example: skill.id,
+    enabled: skill.enabled,
+}));
+/** Each chat model of the catalogue. */
+export const MODEL_PARTS = listChatModels().map(model => ({
+    id: `model:${model.id}`,
+    kind: 'model',
+    label: model.name,
+    says: model.description,
+    example: model.id,
+    // A model's `available` says whether its key is set where the catalogue
+    // was read, not whether it may be chosen: every chat model may.
+    enabled: true,
+}));
+/** The rules a person most often sets, each one of the four behaviours. */
+export const RULE_PARTS = [
+    {
+        id: 'rule:ask-before-sending',
+        kind: 'rule',
+        label: 'Ask before sending',
+        says: 'It asks you before it sends anything on your behalf.',
+        example: {
+            action: 'Send on my behalf',
+            applies_to: ['send'],
+            behaviour: 'ask_first',
+        },
+        enabled: true,
+    },
+    {
+        id: 'rule:read-freely',
+        kind: 'rule',
+        label: 'Read freely',
+        says: 'It reads what its connections reach without asking.',
+        example: { action: 'Read', applies_to: ['read'], behaviour: 'do_it' },
+        enabled: true,
+    },
+    {
+        id: 'rule:never-delete',
+        kind: 'rule',
+        label: 'Leave deleting to me',
+        says: 'It never deletes: it tells you what it would.',
+        example: {
+            action: 'Delete',
+            applies_to: ['delete'],
+            behaviour: 'leave_to_me',
+        },
+        enabled: true,
+    },
+    {
+        id: 'rule:buy-if-asked',
+        kind: 'rule',
+        label: 'Buy only when asked',
+        says: 'It buys only when you ask it to, in so many words.',
+        example: { action: 'Buy', applies_to: ['buy'], behaviour: 'if_asked' },
+        enabled: true,
+    },
+];
+/** A test: a question, and what a good answer does. */
+export const TEST_PARTS = [
+    {
+        id: 'test:answers-from-sources',
+        kind: 'test',
+        label: 'Answers from its sources',
+        says: 'A question, and what a good answer does.',
+        example: {
+            ask: 'What is due this week?',
+            expect: 'It lists what is due this week, read from its sources, and says where.',
+        },
+        enabled: true,
+    },
+    {
+        id: 'test:says-when-it-cannot',
+        kind: 'test',
+        label: 'Says when it cannot',
+        says: 'A question it cannot answer, and it says so.',
+        example: {
+            ask: 'What will the price be next year?',
+            expect: 'It says it cannot know, and does not guess.',
+        },
+        enabled: true,
+    },
+];
+/** The events an application answers (C-21): on a schedule, on an event, once. */
+export const EVENT_PARTS = [
+    {
+        id: 'event:schedule',
+        kind: 'event',
+        label: 'On a schedule',
+        says: 'Every weekday at 9:00, or any time a schedule says.',
+        example: {
+            type: 'schedule',
+            cron: '0 9 * * 1-5',
+            description: 'Every weekday at 9:00',
+            prompt: 'Summarise what came in since yesterday.',
+        },
+        enabled: true,
+    },
+    {
+        id: 'event:email-received',
+        kind: 'event',
+        label: 'When an email arrives',
+        says: 'A message arriving in the inbox it reads.',
+        example: {
+            type: 'event',
+            event: 'email_received',
+            prompt: 'Read the email, and draft a reply for me to approve.',
+        },
+        enabled: true,
+    },
+    {
+        id: 'event:once',
+        kind: 'event',
+        label: 'Once, at a moment',
+        says: 'One run, at a date and a time.',
+        example: {
+            type: 'once',
+            at: '2026-12-31T09:00:00',
+            prompt: 'Close the year: list what is still open.',
+        },
+        enabled: true,
+    },
+];
+export const CANVAS_PART_PLUGINS = [
+    partsPlugin('connections', 'Connections', CONNECTION_PARTS),
+    partsPlugin('skills', 'Skills', SKILL_PARTS),
+    partsPlugin('models', 'Models', MODEL_PARTS),
+    partsPlugin('rules', 'Rules', RULE_PARTS),
+    partsPlugin('tests', 'Tests', TEST_PARTS),
+    partsPlugin('events', 'Events', EVENT_PARTS),
+];
+/** The toolbox's reactor, its named plugins disabled; a name no plugin has is refused. */
+export function canvasPartsReactor(disabled = [], plugins = CANVAS_PART_PLUGINS) {
+    const reactor = buildReactorFromPlugins(plugins);
+    reactor.start();
+    for (const name of disabled) {
+        if (!reactor.hasPlugin(name)) {
+            throw new Error(`No plugin of the toolbox is named "${name}"; they are ${plugins.map(plugin => plugin.name).join(', ') || 'none'}.`);
+        }
+        reactor.disable(name);
+    }
+    return reactor;
+}
+/**
+ * The toolbox for an organization's plugins off: the ids it turns off that
+ * name a source of parts (`skills`, …) take those parts off; the rest are the
+ * palette's.
+ */
+export function canvasPartsReactorOf(pluginsOff) {
+    const sources = new Set(CANVAS_PART_SOURCES);
+    return canvasPartsReactor(pluginsOff
+        .filter(id => sources.has(id))
+        .map(id => canvasPartsPluginName(id)));
+}
+/** What the toolbox offers: the parts the enabled plugins contribute, in their order. */
+export function canvasPartsOf(reactor) {
+    return reactor.getContributions(LoopCanvasPart).map(entry => entry.value);
+}

package/lib/components/teams/useA2ATeam.js

@@ -14,7 +14,7 @@
  * assessment and Change detection), one `ask_<peer>` tool per peer, with
  * {@link a2aPeerTool}. A team of two names its peer as `peerApp`; a team of
  * N names them as `peers` (LOOP A-08). An entry that runs on a runtime
- * itself (a scene of one member: Month-end close, Crop monitoring) is asked
+ * itself (a scene of one member: Month-end Close, Crop Monitoring) is asked
  * over A2A from the page, with no agent in the browser: `entryPeer`.
  *
  * What each of them does is kept as a persona — the state its character

package/lib/examples/HomeExample.js

@@ -4,7 +4,7 @@ import { Heading, Text, TextInput, Label } from '@primer/react';
 import { SearchIcon } from '@primer/octicons-react';
 const HomeExample = ({ examples = [], searchQuery = '', onSearchChange, onSelectExample, }) => {
     const sortedExamples = [...examples].sort((a, b) => a.title.localeCompare(b.title));
-    return (_jsx(Box, { width: "100%", height: "100%", overflow: "auto", bg: "canvas.default", children: _jsxs(Box, { maxWidth: "1600px", margin: "0 auto", p: 4, display: "flex", flexDirection: "column", gap: 3, children: [_jsxs(Box, { display: "flex", justifyContent: "space-between", alignItems: "center", gap: 3, flexWrap: "wrap", children: [_jsxs(Box, { children: [_jsx(Heading, { as: "h2", sx: { fontSize: 4, mb: 1 }, children: "Agent Runtimes Examples" }), _jsx(Text, { sx: { color: 'fg.muted', fontSize: 1 }, children: "Browse all examples as cards and open any flow in one click." })] }), _jsx(TextInput, { autoFocus: true, value: searchQuery, onChange: event => onSearchChange?.(event.target.value), placeholder: "Search examples", leadingVisual: SearchIcon, sx: { minWidth: ['100%', '320px'] } })] }), sortedExamples.length === 0 ? (_jsx(Box, { border: "1px dashed", borderColor: "border.default", borderRadius: 3, p: 4, textAlign: "center", color: "fg.muted", children: "No examples match your search." })) : (_jsx(Box, { display: "grid", gridTemplateColumns: [
+    return (_jsx(Box, { width: "100%", height: "100%", overflow: "auto", bg: "canvas.default", children: _jsxs(Box, { maxWidth: "1600px", margin: "0 auto", p: 4, display: "flex", flexDirection: "column", gap: 3, children: [_jsxs(Box, { display: "flex", justifyContent: "space-between", alignItems: "center", gap: 3, flexWrap: "wrap", children: [_jsxs(Box, { children: [_jsx(Heading, { as: "h2", sx: { fontSize: 4, mb: 1 }, children: "Agent Runtimes Examples" }), _jsx(Text, { sx: { color: 'fg.muted', fontSize: 1 }, children: "Browse all examples as cards and open any flow in one click." })] }), _jsx(TextInput, { autoFocus: true, value: searchQuery, onChange: event => onSearchChange?.(event.target.value), placeholder: "Search examples", leadingVisual: SearchIcon, sx: { minWidth: ['100%', '320px'] } })] }), sortedExamples.length === 0 ? (_jsx(Box, { border: "1px dashed", borderColor: "border.default", borderRadius: "card", p: 4, textAlign: "center", color: "fg.muted", children: "No examples match your search." })) : (_jsx(Box, { display: "grid", gridTemplateColumns: [
                         '1fr',
                         'repeat(2, minmax(0, 1fr))',
                         'repeat(4, minmax(0, 1fr))',

package/lib/examples/ScenesExample.d.ts

@@ -12,7 +12,7 @@
  * are served over A2A by `examples/sales-accounting-a2a/serve_scenes.py`,
  * Accounting on :8767 as before and each other member on a runtime of its
  * own from :8768 (`sceneRuntimePorts`), or wherever `VITE_A2A_<MEMBER>_URL`
- * says. A scene whose entry runs on a runtime itself (Month-end close, Crop
+ * says. A scene whose entry runs on a runtime itself (Month-end Close, Crop
  * monitoring) is asked over A2A from the page, as the person
  * (`useA2ATeam`'s `entryPeer`). A member that is not reached is drawn all
  * the same, and the box says what its application needs (`setup`) and how

package/lib/examples/example-selector.js

@@ -112,7 +112,7 @@ export const EXAMPLE_ENTRIES = [
     // for one sandbox — and a second one that would not agree with the first.
     ['example', 'loop', 'workspace', 'sandbox', 'owns-sandbox-control']),
     makeEntry('LoopAppComputerExample', () => import('./LoopAppComputerExample'), 'An application beside its computer: what its agent ran on its sandbox, its files, and Take over and Hand back (LOOP R-23).', ['example', 'loop', 'app', 'computer', 'sandbox', 'owns-sandbox-control']),
-    makeEntry('ScenesExample', () => import('./ScenesExample'), 'The scenes of the catalogue in tabs — Sales & Accounting, Month-end close, Crop monitoring, Disaster assessment — each its graph and transcript, its cues as suggestions, played against the local servers (LOOP A-15).', ['example', 'loop', 'scenes', 'a2a', 'agentspecs', 'team']),
+    makeEntry('ScenesExample', () => import('./ScenesExample'), 'The scenes of the catalogue in tabs — Sales & Accounting, Month-end Close, Crop Monitoring, Disaster Assessment — each its graph and transcript, its cues as suggestions, played against the local servers (LOOP A-15).', ['example', 'loop', 'scenes', 'a2a', 'agentspecs', 'team']),
     makeEntry('LoopShellExample', () => import('./LoopShellExample'), 'The Loop shell at its most naked: a blank canvas, a floating draggable prompt, and an editor selector in the corner — none, notebook or document.', 
     // `owns-sandbox-control`: the shell is pinned to the browser sandbox, so
     // the page's selector would offer three targets it cannot move to.

package/lib/hooks/useAgUi.js

@@ -3,6 +3,7 @@
  * Distributed under the terms of the Modified BSD License.
  */
 import { useCallback, useEffect, useState } from 'react';
+import { agUiRefusal, refusalBody } from '../protocols/agUiRefusal';
 /**
  * Hook to manage chat state with AG-UI protocol.
  *
@@ -94,7 +95,9 @@ export function useAgUi(options = {}) {
                 body: JSON.stringify(requestBody),
             });
             if (!response.ok) {
-                throw new Error(`AG-UI request failed: ${response.status} ${response.statusText}`);
+                // Why, in the page's own words (F-15): a 404 at an agent's AG-UI
+                // address means the agent is not on this runtime.
+                throw new Error(agUiRefusal(response.status, response.statusText, await refusalBody(response)));
             }
             // Handle streaming response
             const reader = response.body?.getReader();

package/lib/protocols/AGUIAdapter.js

@@ -3,6 +3,7 @@
  * Distributed under the terms of the Modified BSD License.
  */
 import { generateMessageId, createAssistantMessage } from '../types/messages';
+import { agUiRefusal, refusalBody } from './agUiRefusal';
 import { BaseProtocolAdapter } from './BaseProtocolAdapter';
 /**
  * AG-UI protocol adapter
@@ -214,7 +215,10 @@ export class AGUIAdapter extends BaseProtocolAdapter {
                 signal: controller.signal,
             });
             if (!response.ok) {
-                throw new Error(`AG-UI request failed: ${response.status} ${response.statusText}`);
+                // Why, in the page's own words (F-15): a 404 at an agent's AG-UI
+                // address means the agent is not on this runtime, which the status
+                // alone never said.
+                throw new Error(agUiRefusal(response.status, response.statusText, await refusalBody(response)));
             }
             // Parse SSE stream
             await this.parseSSEStream(response);

package/lib/protocols/agUiRefusal.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Why an AG-UI run was not answered, in the page's own words (LOOP F-15).
+ *
+ * What a person met before was `AG-UI request failed: 404` — the status and
+ * nothing else. A 404 at an agent's AG-UI address has one meaning: the agent
+ * is not on the runtime the page is addressing. The commonest way to get
+ * there is to open an application whose agent runs its code in the browser:
+ * the runtime refuses to start it (`browser_sandbox_refusal`, 422), the page
+ * addresses it anyway, and the address answers nothing. So the page says
+ * that, and says what to do about it.
+ *
+ * When the server said why — a refusal of the platform's own, carried as
+ * `detail` — that sentence is the better one and is used instead: it is
+ * about this agent, where ours is about any.
+ *
+ * Pure, so the hook, the adapter and the tests read a refusal the same way
+ * (the repo's jest/vitest rule: rules live outside components).
+ *
+ * @module protocols/agUiRefusal
+ */
+/** What the page says when an agent's AG-UI address answers nothing. */
+export declare const AG_UI_NOT_ON_RUNTIME: string;
+/** What the page says when the address refused the caller. */
+export declare const AG_UI_NOT_ALLOWED: string;
+/**
+ * The `detail` a platform refusal carries, or `''`.
+ *
+ * A body that is not JSON — an HTML 404 from the page's own origin, which is
+ * what a page addressing a runtime it never got answers — carries none.
+ */
+export declare function refusalDetail(body: string | undefined): string;
+/**
+ * Why the run was not answered, as the page says it.
+ *
+ * @param status - The status the address answered with.
+ * @param statusText - Its text, for a status we have nothing better for.
+ * @param body - What came back, when it was read; a refusal's `detail` wins.
+ */
+export declare function agUiRefusal(status: number, statusText: string, body?: string): string;
+/**
+ * Read a refusal's body without letting the reading itself throw: a body
+ * already consumed, or a connection that went away, leaves us with the
+ * status alone, which is still better than nothing.
+ */
+export declare function refusalBody(response: {
+    text: () => Promise<string>;
+}): Promise<string | undefined>;

package/lib/protocols/agUiRefusal.js

@@ -0,0 +1,87 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Why an AG-UI run was not answered, in the page's own words (LOOP F-15).
+ *
+ * What a person met before was `AG-UI request failed: 404` — the status and
+ * nothing else. A 404 at an agent's AG-UI address has one meaning: the agent
+ * is not on the runtime the page is addressing. The commonest way to get
+ * there is to open an application whose agent runs its code in the browser:
+ * the runtime refuses to start it (`browser_sandbox_refusal`, 422), the page
+ * addresses it anyway, and the address answers nothing. So the page says
+ * that, and says what to do about it.
+ *
+ * When the server said why — a refusal of the platform's own, carried as
+ * `detail` — that sentence is the better one and is used instead: it is
+ * about this agent, where ours is about any.
+ *
+ * Pure, so the hook, the adapter and the tests read a refusal the same way
+ * (the repo's jest/vitest rule: rules live outside components).
+ *
+ * @module protocols/agUiRefusal
+ */
+/** What the page says when an agent's AG-UI address answers nothing. */
+export const AG_UI_NOT_ON_RUNTIME = 'This agent is not on the runtime the page is addressing: its AG-UI address answered nothing. ' +
+    'An agent that runs its code in the browser is never started on a runtime — run it in the page, ' +
+    'or give it a sandbox a runtime has (eval, jupyter-server).';
+/** What the page says when the address refused the caller. */
+export const AG_UI_NOT_ALLOWED = 'This agent did not answer the page: the run was refused. ' +
+    'Sign in again, or open the application from its own address.';
+/**
+ * The `detail` a platform refusal carries, or `''`.
+ *
+ * A body that is not JSON — an HTML 404 from the page's own origin, which is
+ * what a page addressing a runtime it never got answers — carries none.
+ */
+export function refusalDetail(body) {
+    if (!body) {
+        return '';
+    }
+    let said;
+    try {
+        said = JSON.parse(body);
+    }
+    catch {
+        return '';
+    }
+    if (!said || typeof said !== 'object') {
+        return '';
+    }
+    const detail = said.detail;
+    return typeof detail === 'string' ? detail.trim() : '';
+}
+/**
+ * Why the run was not answered, as the page says it.
+ *
+ * @param status - The status the address answered with.
+ * @param statusText - Its text, for a status we have nothing better for.
+ * @param body - What came back, when it was read; a refusal's `detail` wins.
+ */
+export function agUiRefusal(status, statusText, body) {
+    const detail = refusalDetail(body);
+    if (detail) {
+        return detail;
+    }
+    if (status === 404) {
+        return AG_UI_NOT_ON_RUNTIME;
+    }
+    if (status === 401 || status === 403) {
+        return AG_UI_NOT_ALLOWED;
+    }
+    return `AG-UI request failed: ${status} ${statusText}`.trim();
+}
+/**
+ * Read a refusal's body without letting the reading itself throw: a body
+ * already consumed, or a connection that went away, leaves us with the
+ * status alone, which is still better than nothing.
+ */
+export async function refusalBody(response) {
+    try {
+        return await response.text();
+    }
+    catch {
+        return undefined;
+    }
+}