@datalayer/agent-runtimes 1.0.28 → 1.3.10

package/lib/examples/components/LexicalEditor.js

@@ -6,24 +6,14 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import '@datalayer/jupyter-react/lib/css/PrismCss';
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { $getRoot, $createParagraphNode } from 'lexical';
-import { LexicalComposer } from '@lexical/react/LexicalComposer';
-import { RichTextPlugin } from '@lexical/react/LexicalRichTextPlugin';
+import { LexicalExtensionComposer } from '@lexical/react/LexicalExtensionComposer';
 import { ContentEditable } from '@lexical/react/LexicalContentEditable';
-import { HistoryPlugin } from '@lexical/react/LexicalHistoryPlugin';
 import { OnChangePlugin } from '@lexical/react/LexicalOnChangePlugin';
 import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext';
-import { LexicalErrorBoundary } from '@lexical/react/LexicalErrorBoundary';
-import { AutoFocusPlugin } from '@lexical/react/LexicalAutoFocusPlugin';
-import { MarkdownShortcutPlugin } from '@lexical/react/LexicalMarkdownShortcutPlugin';
-import { TRANSFORMERS } from '@lexical/markdown';
-import { registerCodeHighlighting } from '@lexical/code';
-import { ListPlugin } from '@lexical/react/LexicalListPlugin';
-import { CheckListPlugin } from '@lexical/react/LexicalCheckListPlugin';
-import { LinkPlugin } from '@lexical/react/LexicalLinkPlugin';
 import { Box } from '@datalayer/primer-addons';
 import { JupyterReactTheme, useJupyter } from '@datalayer/jupyter-react';
-import { ComponentPickerMenuPlugin, JupyterCellPlugin, JupyterInputOutputPlugin, DraggableBlockPlugin, ImagesPlugin, HorizontalRulePlugin, EquationsPlugin, YouTubePlugin, AutoLinkPlugin, AutoEmbedPlugin, LexicalConfigProvider, LexicalStatePlugin, FloatingTextFormatToolbarPlugin, CodeActionMenuPlugin, ListMaxIndentLevelPlugin, } from '@datalayer/jupyter-lexical';
-import { editorConfig } from '../lexical/editorConfig';
+import { ComponentPickerMenuPlugin, JupyterInputOutputPlugin, DraggableBlockPlugin, LexicalConfigProvider, LexicalStatePlugin, FloatingTextFormatToolbarPlugin, CodeActionMenuPlugin, } from '@datalayer/jupyter-lexical';
+import { editorExtension } from '../lexical/editorConfig';
 import '@datalayer/jupyter-lexical/style/index.css';
 import '../lexical/lexical-theme.css';
 const LEXICAL_ID = 'agent-runtime-lexical-editor';
@@ -64,16 +54,6 @@ function LoadContentPlugin({ content }) {
     }, [content, editor]);
     return null;
 }
-/**
- * Lexical plugin for Simple code syntax highlighting.
- */
-function CodeHighlightPlugin() {
-    const [editor] = useLexicalComposerContext();
-    useEffect(() => {
-        return registerCodeHighlighting(editor);
-    }, [editor]);
-    return null;
-}
 /**
  * Wrapper component for kernel-dependent Simple plugins.
  */
@@ -104,5 +84,5 @@ export const LexicalEditor = ({ content = INITIAL_CONTENT, serviceManager, extra
             padding: 3,
             backgroundColor: 'canvas.default',
             minHeight: '600px',
-        }, children: _jsx(LexicalConfigProvider, { lexicalId: LEXICAL_ID, serviceManager: serviceManager, children: _jsx(LexicalComposer, { initialConfig: editorConfig, children: _jsxs("div", { className: "lexical-editor-inner", ref: onRef, children: [_jsx(LexicalStatePlugin, {}), _jsx(RichTextPlugin, { contentEditable: _jsx(ContentEditable, { className: "lexical-editor-content", "aria-label": "Lexical Editor" }), ErrorBoundary: LexicalErrorBoundary }), _jsx(OnChangePlugin, { onChange: handleChange }), _jsx(HistoryPlugin, {}), _jsx(AutoFocusPlugin, {}), _jsx(ListPlugin, {}), _jsx(CheckListPlugin, {}), _jsx(LinkPlugin, {}), _jsx(AutoLinkPlugin, {}), _jsx(ListMaxIndentLevelPlugin, { maxDepth: 7 }), _jsx(MarkdownShortcutPlugin, { transformers: TRANSFORMERS }), _jsx(LoadContentPlugin, { content: content }), _jsx(CodeHighlightPlugin, {}), _jsx(ImagesPlugin, { captionsEnabled: false }), _jsx(HorizontalRulePlugin, {}), _jsx(EquationsPlugin, {}), _jsx(YouTubePlugin, {}), _jsx(AutoEmbedPlugin, {}), _jsx(JupyterCellPlugin, {}), _jsx(JupyterReactTheme, { useBaseStyles: false, children: _jsx(SimpleKernelPluginsInner, {}) }), floatingAnchorElem && (_jsxs(_Fragment, { children: [_jsx(DraggableBlockPlugin, { anchorElem: floatingAnchorElem }), _jsx(FloatingTextFormatToolbarPlugin, { anchorElem: floatingAnchorElem, setIsLinkEditMode: setIsLinkEditMode, extraItems: extraItems }), _jsx(CodeActionMenuPlugin, { anchorElem: floatingAnchorElem })] })), children] }) }) }) }));
+        }, children: _jsx(LexicalConfigProvider, { lexicalId: LEXICAL_ID, serviceManager: serviceManager, children: _jsx(LexicalExtensionComposer, { extension: editorExtension, contentEditable: null, children: _jsxs("div", { className: "lexical-editor-inner", ref: onRef, children: [_jsx(LexicalStatePlugin, {}), _jsx(ContentEditable, { className: "lexical-editor-content", "aria-label": "Lexical Editor" }), _jsx(OnChangePlugin, { onChange: handleChange }), _jsx(LoadContentPlugin, { content: content }), _jsx(JupyterReactTheme, { useBaseStyles: false, children: _jsx(SimpleKernelPluginsInner, {}) }), floatingAnchorElem && (_jsxs(_Fragment, { children: [_jsx(DraggableBlockPlugin, { anchorElem: floatingAnchorElem }), _jsx(FloatingTextFormatToolbarPlugin, { anchorElem: floatingAnchorElem, setIsLinkEditMode: setIsLinkEditMode, extraItems: extraItems }), _jsx(CodeActionMenuPlugin, { anchorElem: floatingAnchorElem })] })), children] }) }) }) }));
 };

package/lib/examples/components/haiku/HaikuDisplay.d.ts

@@ -14,5 +14,5 @@ export interface HaikuDisplayProps {
  * Displays a carousel of haiku cards with navigation controls.
  * Shows the most recent haiku first with ability to browse older ones.
  */
-export declare function HaikuDisplay({ haikus, title, }: HaikuDisplayProps): import("react/jsx-runtime").JSX.Element;
+export declare function HaikuDisplay({ haikus, title, }: HaikuDisplayProps): import("react").JSX.Element;
 export default HaikuDisplay;

package/lib/examples/components/haiku/InlineHaikuCard.d.ts

@@ -35,5 +35,5 @@ export interface InlineHaikuCardProps {
  * - English translation (below)
  * - Decorative corner accents
  */
-export declare function InlineHaikuCard({ haiku, status, error, size, }: InlineHaikuCardProps): import("react/jsx-runtime").JSX.Element;
+export declare function InlineHaikuCard({ haiku, status, error, size, }: InlineHaikuCardProps): import("react").JSX.Element;
 export default InlineHaikuCard;

package/lib/examples/components/weather/InlineWeatherCard.d.ts

@@ -39,5 +39,5 @@ export interface InlineWeatherCardProps {
  * - Temperature in both Celsius and Fahrenheit
  * - Humidity, wind speed, and feels like temperature
  */
-export declare function InlineWeatherCard({ location, result, status, error, }: InlineWeatherCardProps): import("react/jsx-runtime").JSX.Element;
+export declare function InlineWeatherCard({ location, result, status, error, }: InlineWeatherCardProps): import("react").JSX.Element;
 export default InlineWeatherCard;

package/lib/examples/example-selector.js

@@ -6,11 +6,15 @@
 const DISPLAY_NAME_EXCEPTIONS = [
     [/\bAg Ui\b/g, 'AG-UI'],
     [/\bA2 Ui\b/g, 'A2UI'],
+    [/\bA2 A\b/g, 'A2A'],
     [/\bCopilot Kit\b/g, 'CopilotKit'],
     [/\bGen Ui\b/g, 'Gen UI'],
     [/\bM C P\b/g, 'MCP'],
     [/\bOtel\b/g, 'OTEL'],
-    [/\bAgent Specs\b/g, 'Agent Specifications'],
+    [/\bAgentspecs\b/g, 'Agent Specifications'],
+    // The document editor is Lexical underneath; the examples are about the
+    // document.
+    [/\bLexical\b/g, 'Document'],
 ];
 function humanizeExampleName(name) {
     let result = name
@@ -31,10 +35,12 @@ function inferTags(id) {
         tags.add('ag-ui');
     if (id.startsWith('A2Ui'))
         tags.add('a2ui');
+    if (id.startsWith('AgentA2A'))
+        tags.add('a2a');
     if (id.includes('Notebook'))
         tags.add('notebook');
-    if (id.includes('Lexical'))
-        tags.add('lexical');
+    if (id.includes('Lexical') || id.includes('Document'))
+        tags.add('document');
     if (id.includes('Chat'))
         tags.add('chat');
     if (id.includes('Sandbox'))
@@ -68,6 +74,7 @@ export const EXAMPLE_ENTRIES = [
     makeEntry('A2UiContactCardExample', () => import('./A2UiContactCardExample'), 'A2UI example rendering contact card interactions.'),
     makeEntry('A2UiRestaurantExample', () => import('./A2UiRestaurantExample'), 'A2UI restaurant flow example.'),
     makeEntry('A2UiViewerExample', () => import('./A2UiViewerExample'), 'A2UI viewer integration example.'),
+    makeEntry('A2UiJupyterOutputExample', () => import('./A2UiJupyterOutputExample'), 'One Jupyter execution shown twice: raw kernel outputs, and the A2UI surface the server converter makes of them.'),
     makeEntry('A2UiAgentExample', () => import('./A2UiAgentExample'), 'A2UI Agent with built-in chat component and Python A2UI extension surface.'),
     makeEntry('AgUiAgenticExample', () => import('./AgUiAgenticExample'), 'AG-UI agentic workflow example.'),
     makeEntry('AgUiBackendToolRenderingExample', () => import('./AgUiBackendToolRenderingExample'), 'AG-UI backend tool rendering example.'),
@@ -76,11 +83,14 @@ export const EXAMPLE_ENTRIES = [
     makeEntry('AgUiSharedStateExample', () => import('./AgUiSharedStateExample'), 'AG-UI shared state synchronization example.'),
     makeEntry('AgUiToolsBasedGenUiExample', () => import('./AgUiToolsBasedGenUiExample'), 'AG-UI tool-based generative UI example.'),
     makeEntry('AgentspecsExample', () => import('./AgentspecsExample'), 'Configure and run agents from specs and transports.'),
+    makeEntry('NotebookPageAgent', () => import('./NotebookPageAgent'), 'A notebook as a page: floating prompt on top, a team of agents working in it.'),
+    makeEntry('DocumentPageAgent', () => import('./DocumentPageAgent'), 'A document as a page: floating prompt on top, an agent writing in it.'),
+    makeEntry('DecksAgent', () => import('./DecksAgent'), 'A deck beside the chat: the decks plugin in a Loop, and an agent that writes presentations as data.'),
     makeEntry('CellExample', () => import('./CellExample'), 'Simple cell example.'),
     makeEntry('ChatCustomExample', () => import('./ChatCustomExample'), 'Custom chat experience composition example.'),
     makeEntry('ChatExample', () => import('./ChatExample'), 'Baseline chat integration example.'),
     makeEntry('ChatStandaloneExample', () => import('./ChatStandaloneExample'), 'Standalone chat component usage example.'),
-    makeEntry('CopilotKitLexicalExample', () => import('./CopilotKitLexicalExample'), 'CopilotKit integration with Lexical editor.'),
+    makeEntry('CopilotKitLexicalExample', () => import('./CopilotKitLexicalExample'), 'CopilotKit integration with the document editor.'),
     makeEntry('CopilotKitNotebookExample', () => import('./CopilotKitNotebookExample'), 'CopilotKit integration with notebook workflows.'),
     makeEntry('AgentCheckpointsExample', () => import('./AgentCheckpointsExample'), 'Checkpoint and resume lifecycle for agents.'),
     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']),
@@ -90,6 +100,15 @@ export const EXAMPLE_ENTRIES = [
     makeEntry('AgentGuardrailsExample', () => import('./AgentGuardrailsExample'), 'Guardrails and safety checks for agent runs.'),
     makeEntry('AgentHooksExample', () => import('./AgentHooksExample'), 'Pre-hooks and post-hooks lifecycle execution example.'),
     makeEntry('AgentInferenceProviderExample', () => import('./AgentInferenceProviderExample'), 'Switch local and datalayer inference providers with live low-level provider events.', ['example', 'agent', 'inference', 'provider', 'runtime']),
+    makeEntry('LoopWorkspaceExample', () => import('./LoopWorkspaceExample'), 'The LOOP workspace: a blank shell, with the chat, the editors and the plugin list all contributed as plugins.', 
+    // `owns-sandbox-control`: this example brings its own sandbox switch, so
+    // the shell hides the one in its header rather than showing two controls
+    // for one sandbox — and a second one that would not agree with the first.
+    ['example', 'loop', 'workspace', 'sandbox', 'owns-sandbox-control']),
+    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.
+    ['example', 'loop', 'shell', 'prompt', 'editors', 'owns-sandbox-control']),
     makeEntry('AgentLoopExample', () => import('./AgentLoopExample'), 'Define and launch an agent execution loop (observe/think/act/evaluate) over a live notebook, driven by generic loop specs.', ['example', 'agent', 'loop', 'notebook', 'agentspecs']),
     makeEntry('AgentToolApprovalsExample', () => import('./AgentToolApprovalsExample'), 'Tool approval workflows and manual decisions.'),
     makeEntry('AgentMemoryExample', () => import('./AgentMemoryExample'), 'Memory-aware conversation and retrieval example.'),
@@ -99,12 +118,13 @@ export const EXAMPLE_ENTRIES = [
     makeEntry('AgentCodeSandboxExample', () => import('./AgentCodeSandboxExample'), 'Sandbox execution variants and context controls.'),
     makeEntry('AgentMonitoringExample', () => import('./AgentMonitoringExample'), 'Runtime monitoring and live metrics example.'),
     makeEntry('AgentSubagentsExample', () => import('./AgentSubagentsExample'), 'Multi-agent delegation with the in-repo subagents capability.'),
+    makeEntry('AgentA2AExample', () => import('./AgentA2AExample'), 'Delegation to separate agents over the A2A protocol, launched locally or on Datalayer runtimes.'),
     makeEntry('AgentNotificationsExample', () => import('./AgentNotificationsExample'), 'Notifications and event routing example.'),
     makeEntry('AgentOutputsExample', () => import('./AgentOutputsExample'), 'Structured outputs and rendering patterns.'),
     makeEntry('AgentParametersExample', () => import('./AgentParametersExample'), 'Launch-time parameterized agent creation with JSON schema.'),
     makeEntry('AgentTriggersExample', () => import('./AgentTriggersExample'), 'Scheduled and one-shot trigger flows.'),
-    makeEntry('LexicalAgentExample', () => import('./LexicalAgentExample'), 'Lexical document integration example.'),
-    makeEntry('LexicalAgentSidebarExample', () => import('./LexicalAgentSidebarExample'), 'Lexical with sidebar orchestration example.'),
+    makeEntry('LexicalAgentExample', () => import('./LexicalAgentExample'), 'Document agent integration example.'),
+    makeEntry('LexicalAgentSidebarExample', () => import('./LexicalAgentSidebarExample'), 'Document agent with sidebar orchestration example.'),
     makeEntry('NotebookAgentExample', () => import('./NotebookAgentExample'), 'Notebook orchestration and runtime example.'),
     makeEntry('NotebookAgentSidebarExample', () => import('./NotebookAgentSidebarExample'), 'Notebook plus sidebar controls example.'),
     makeEntry('NotebookExample', () => import('./NotebookExample'), 'Minimal notebook integration example.'),

package/lib/examples/hooks/useCreateAgentOnce.d.ts

@@ -0,0 +1,41 @@
+import type { AgentConfig } from '../../types/config';
+export interface UseCreateAgentOnceOptions {
+    /** Whether there is anything to attempt. */
+    enabled: boolean;
+    /**
+     * Whether *this* agent already exists, which makes the attempt moot.
+     *
+     * A boolean rather than an id, because the caller is the only one who can
+     * answer it. The runtime state is a shared singleton that the shell writes
+     * to as well: on the cloud target it launches a runtime and registers an
+     * agent of its own before an example mounts. Skipping on "some agent id is
+     * set" therefore skipped creating the example's agent because somebody
+     * else's was already there — and every message then came back "No agent
+     * registered for this ID".
+     */
+    alreadyCreated?: boolean;
+    createAgent: (config: AgentConfig) => Promise<AgentCreated>;
+    config: AgentConfig;
+}
+/** What creating an agent gives back. */
+export type AgentCreated = {
+    agentId?: string;
+    endpoint?: string;
+    isReady?: boolean;
+};
+export interface UseCreateAgentOnceResult {
+    /** Whether the single attempt has been made. */
+    attempted: boolean;
+    /**
+     * The agent this hook created, once the call has returned.
+     *
+     * The trustworthy signal that the agent exists: it is the answer to our own
+     * request, rather than a read of state anything else can overwrite.
+     */
+    created?: AgentCreated;
+    /** Why it failed, when it did. Reported, never retried. */
+    error?: string;
+}
+/** Create an agent at most once. */
+export declare function useCreateAgentOnce(options: UseCreateAgentOnceOptions): UseCreateAgentOnceResult;
+export default useCreateAgentOnce;

package/lib/examples/hooks/useCreateAgentOnce.js

@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Ask for something once, and stop.
+ *
+ * Its own module because "attempt exactly once, and if it fails say why rather
+ * than try again" is a policy, and it was the missing one. Five examples each
+ * ended their creation attempt with `.catch(() => setCreateRequested(false))`
+ * while the effect making the attempt listed `createRequested` among its
+ * dependencies — so a failure re-armed the effect. With an unreachable sandbox
+ * the examples app posted `/api/v1/agents` as fast as the server could return
+ * 503, and the page looked like it was reloading without end.
+ *
+ * A `useState` guard cleared in a `.catch` is not a guard; it is a retry loop
+ * with extra steps.
+ *
+ * @module examples/hooks/useCreateAgentOnce
+ */
+import { useEffect, useRef, useState } from 'react';
+/** Create an agent at most once. */
+export function useCreateAgentOnce(options) {
+    const { enabled, alreadyCreated, createAgent, config } = options;
+    const [attempted, setAttempted] = useState(false);
+    const [created, setCreated] = useState();
+    const [error, setError] = useState();
+    // A ref, not state: the effect must not depend on a value its own failure
+    // path writes, or the failure re-arms it.
+    const attemptedRef = useRef(false);
+    // Read at attempt time rather than depended upon, so a caller that rebuilds
+    // its config object on every render cannot provoke a second attempt.
+    const configRef = useRef(config);
+    configRef.current = config;
+    useEffect(() => {
+        if (attemptedRef.current || alreadyCreated || !enabled) {
+            return;
+        }
+        attemptedRef.current = true;
+        setAttempted(true);
+        void createAgent(configRef.current)
+            .then(setCreated)
+            .catch((reason) => {
+            // Recorded, never retried: `attemptedRef` is not cleared here, which
+            // is the whole of the fix.
+            setError(reason instanceof Error ? reason.message : String(reason));
+        });
+    }, [alreadyCreated, createAgent, enabled]);
+    return { attempted, created, error };
+}
+export default useCreateAgentOnce;

package/lib/examples/hooks/useExampleAgentProtocol.d.ts

@@ -0,0 +1,35 @@
+import type { ProtocolConfig } from '../../types/protocol';
+import type { FrontendToolDefinition } from '../../types/tools';
+/** Why a browser agent is unusable when it is. */
+export declare const BROWSER_SIGN_IN_REASON: string;
+export interface UseExampleAgentProtocolOptions {
+    /** Whether the loop turns in this page. */
+    inBrowser: boolean;
+    /** The agent's name, which is also its id on a runtime. */
+    agentName: string;
+    /** The agent's instructions, for the in-page harness to run with. */
+    systemPrompt?: string;
+    /** The model id, as a spec spells it. */
+    model?: string;
+    /** The tools the agent may call in this page, if any. */
+    frontendTools?: FrontendToolDefinition[];
+    /** Base URL of the agent's runtime, for the remote case. */
+    remoteBaseUrl?: string;
+}
+export interface UseExampleAgentProtocolResult {
+    protocol: ProtocolConfig;
+    /**
+     * The tools to pass the chat component — which is not always the tools.
+     *
+     * Against a runtime the chat runs frontend tools itself: a `tool-call`
+     * arrives over the wire and it answers with the result. In the browser the
+     * SDK owns the loop and calls the handlers directly, so handing them to the
+     * chat as well would run every tool twice.
+     */
+    chatFrontendTools?: FrontendToolDefinition[];
+    /** Whether the in-page agent is unusable for want of a sign-in. */
+    needsSignIn: boolean;
+}
+/** The protocol config for this example, and who should run its tools. */
+export declare function useExampleAgentProtocol(options: UseExampleAgentProtocolOptions): UseExampleAgentProtocolResult;
+export default useExampleAgentProtocol;

package/lib/examples/hooks/useExampleAgentProtocol.js

@@ -0,0 +1,63 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * What to give a chat, chosen by where the loop turns.
+ *
+ * Extracted from `useExampleJupyterAgent` when it turned out that the choice
+ * has nothing to do with notebooks. `ChatExample` has no sandbox, no tools and
+ * no surface — it is a conversation and nothing else — and it still has to
+ * make the same decision the moment someone selects Browser in the runtime
+ * control.
+ *
+ * Remotely the chat speaks the Vercel AI wire protocol to an agent's endpoint.
+ * In the browser it speaks to the in-page harness, and carries the prompt and
+ * the tools rather than a URL.
+ *
+ * @module examples/hooks/useExampleAgentProtocol
+ */
+import { useMemo } from 'react';
+import { browserProtocolConfig } from '../../runtimes/browser';
+import { useBrowserInference } from '../../hooks/useBrowserInference';
+/** Why a browser agent is unusable when it is. */
+export const BROWSER_SIGN_IN_REASON = 'Sign in to use this agent. The loop runs in your browser and needs no ' +
+    'runtime, but the model it asks is reached through the Datalayer inference ' +
+    'service, which answers to signed-in members only.';
+/** The protocol config for this example, and who should run its tools. */
+export function useExampleAgentProtocol(options) {
+    const { inBrowser, agentName, systemPrompt, model, frontendTools, remoteBaseUrl, } = options;
+    /* Only an in-page agent spends the visitor's trial key. A server-backed one
+       authenticates itself, and starting a clock against a conversation that
+       will never use it is a countdown on nothing. */
+    const { inference, needsSignIn } = useBrowserInference(inBrowser);
+    const protocol = useMemo(() => inBrowser
+        ? browserProtocolConfig({
+            agentId: agentName,
+            instructions: systemPrompt,
+            model,
+            frontendTools,
+            inference,
+        })
+        : {
+            type: 'vercel-ai',
+            endpoint: `${remoteBaseUrl}/api/v1/vercel-ai/${agentName}`,
+            agentId: agentName,
+            enableConfigQuery: true,
+            configEndpoint: `${remoteBaseUrl}/api/v1/configure`,
+        }, [
+        agentName,
+        frontendTools,
+        inBrowser,
+        inference,
+        model,
+        remoteBaseUrl,
+        systemPrompt,
+    ]);
+    return {
+        protocol,
+        chatFrontendTools: inBrowser ? undefined : frontendTools,
+        needsSignIn: inBrowser && needsSignIn,
+    };
+}
+export default useExampleAgentProtocol;

package/lib/examples/hooks/useExampleAgentRuntime.d.ts

@@ -1,35 +1,35 @@
+import type { UseAgentReturn } from '../../hooks/useAgentRuntimes';
 import type { AgentConfig } from '../../types/config';
-interface UseExampleAgentRuntimeOptions {
+import { type ExampleRuntimeTarget } from '../utils/runtimeTargetStore';
+export interface UseExampleAgentRuntimeOptions {
     exampleId: string;
     agentName: string;
     specId?: string;
-    environmentName?: string;
     autoStart?: boolean;
     autoCreateAgent?: boolean;
     agentConfig?: AgentConfig;
 }
-interface UseExampleAgentRuntimeResult {
-    location: 'local' | 'cloud';
+export interface UseExampleAgentRuntimeResult extends UseAgentReturn {
+    location: ExampleRuntimeTarget;
     baseUrl: string;
     agentId?: string;
     agentBaseUrl?: string;
-    status: string;
-    isReady: boolean;
-    error: string | null;
-    createAgent: (config?: AgentConfig) => Promise<{
-        agentId?: string;
-        endpoint?: string;
-        isReady?: boolean;
-    }>;
+    /** Whether an agent runs on the current target at all. */
+    hasAgent: boolean;
     /**
-     * Tear down the agent launched by this hook: delete it on the server and
-     * wipe in-process agent state so a fresh runtime can be launched.
+     * What to spread onto a `ChatBase` so it shows itself switched off, with the
+     * reason, wherever there is no agent to talk to.
+     *
+     * Computed here so no example has to know which targets have agents — the
+     * question is about the target, and the target is the shell's business.
      */
-    teardown: () => Promise<void>;
+    chatGate: {
+        disabled: boolean;
+        disableReason?: string;
+    };
 }
 /**
  * Connects examples to agent runtimes through shared hooks and supports
  * both local and cloud execution modes.
  */
 export declare function useExampleAgentRuntime(options: UseExampleAgentRuntimeOptions): UseExampleAgentRuntimeResult;
-export {};

package/lib/examples/hooks/useExampleAgentRuntime.js

@@ -3,44 +3,38 @@
  * Distributed under the terms of the Modified BSD License.
  */
 import { useEffect, useMemo } from 'react';
-import { useAgentRuntimes } from '../../hooks/useAgentRuntimes';
-import { useExampleAgentRuntimesUrl } from '../utils/useExampleAgentRuntimesUrl';
-import { useRuntimeTargetStore } from '../utils/runtimeTargetStore';
+import { runtimeTargetCapabilities, useRuntimeTargetStore, } from '../utils/runtimeTargetStore';
 import { agentSummaryStore } from '../utils/agentSummaryStore';
+import { useExampleAgentRuntimes } from './useExampleAgentRuntimes';
+import { harnessOf, SPEC_HARNESS_BY_HARNESS } from '../../runtimes/variants';
 /**
  * Connects examples to agent runtimes through shared hooks and supports
  * both local and cloud execution modes.
  */
 export function useExampleAgentRuntime(options) {
-    const { exampleId, agentName, specId, environmentName = 'local-agent-runtimes', autoStart = true, autoCreateAgent = true, agentConfig, } = options;
+    const { exampleId, agentName, specId, autoStart = true, autoCreateAgent = true, agentConfig, } = options;
     const location = useRuntimeTargetStore(state => state.target);
-    const baseUrl = useExampleAgentRuntimesUrl();
-    const isCloud = location === 'cloud';
+    const capabilities = runtimeTargetCapabilities(location);
+    const isCloud = location === 'datalayer';
     const combinedConfig = useMemo(() => ({
         name: agentName,
         agentSpecId: specId,
         ...agentConfig,
     }), [agentName, specId, agentConfig]);
-    const { runtime, status, isReady, error, connectToRuntime, createAgent, teardown, } = useAgentRuntimes({
-        agentSpecId: isCloud ? specId : undefined,
+    const result = useExampleAgentRuntimes({
+        agentSpecId: specId,
         autoCreateAgent,
-        autoStart: isCloud ? autoStart : false,
-        runtimeCreationTarget: isCloud
-            ? 'backend-services'
-            : 'local-agent-runtimes',
-        runtimeCreationBaseUrl: isCloud ? undefined : baseUrl,
+        autoStart,
         agentConfig: combinedConfig,
     });
-    useEffect(() => {
-        if (isCloud) {
-            return;
-        }
-        connectToRuntime({
-            podName: agentName,
-            environmentName,
-            jupyterBaseUrl: baseUrl,
-        });
-    }, [isCloud, connectToRuntime, agentName, environmentName, baseUrl]);
+    const { runtime, status, isReady, error, variant } = result;
+    // The harness reported is the one actually turning the loop, read off the
+    // variant rather than off the spec: a spec states what it needs, and this
+    // says what it got.
+    const harness = SPEC_HARNESS_BY_HARNESS[harnessOf(variant)];
+    const baseUrl = isCloud
+        ? runtime?.agentBaseUrl || result.runtimeCreationBaseUrl
+        : result.runtimeCreationBaseUrl;
     useEffect(() => {
         // Agent status and code sandbox status are both reported by the
         // agent-runtimes API server. For local runs that server is `baseUrl`
@@ -55,6 +49,8 @@ export function useExampleAgentRuntime(options) {
             agentName,
             agentId: runtime?.agentId,
             specId,
+            harness,
+            variant,
             location,
             baseUrl: agentApiBaseUrl,
             sandboxBaseUrl: runtime?.agentBaseUrl,
@@ -71,6 +67,8 @@ export function useExampleAgentRuntime(options) {
         runtime?.agentId,
         runtime?.agentBaseUrl,
         specId,
+        harness,
+        variant,
         location,
         baseUrl,
         isCloud,
@@ -79,14 +77,17 @@ export function useExampleAgentRuntime(options) {
         error,
     ]);
     return {
+        ...result,
         location,
         baseUrl,
         agentId: runtime?.agentId,
         agentBaseUrl: runtime?.agentBaseUrl,
+        hasAgent: capabilities.hasAgent,
+        chatGate: capabilities.hasAgent
+            ? { disabled: false }
+            : { disabled: true, disableReason: capabilities.noAgentReason },
         status,
         isReady,
         error,
-        createAgent,
-        teardown,
     };
 }

package/lib/examples/hooks/useExampleAgentRuntimes.js

@@ -3,80 +3,64 @@
  * Distributed under the terms of the Modified BSD License.
  */
 import { useAgentRuntimes, } from '../../hooks/useAgentRuntimes';
-import { useEffect, useMemo, useRef } from 'react';
-import { useRuntimeTargetStore } from '../utils/runtimeTargetStore';
+import { useMemo } from 'react';
+import { runtimeTargetCapabilities, useRuntimeTargetStore, } from '../utils/runtimeTargetStore';
 import { useExampleAgentRuntimesUrl } from '../utils/useExampleAgentRuntimesUrl';
+import { locationOf, toAgentRuntimeVariant, variantForLocation, } from '../../runtimes/variants';
 /**
  * High-level examples hook that applies the shared Local/Cloud runtime target
  * defaults while preserving explicit overrides from individual examples.
  */
 export function useExampleAgentRuntimes(options) {
     const runtimeTarget = useRuntimeTargetStore(state => state.target);
+    const capabilities = runtimeTargetCapabilities(runtimeTarget);
     const localRuntimeBaseUrl = useExampleAgentRuntimesUrl();
-    const runtimeCreationTarget = options.runtimeCreationTarget ??
-        (runtimeTarget === 'cloud' ? 'backend-services' : 'local-agent-runtimes');
+    // The examples' four targets collapse to two runtimes: only `datalayer` is
+    // the cloud one. `variant` is what the hook speaks now, so the summary and
+    // the chat can name what is actually running rather than infer it.
+    const variant = toAgentRuntimeVariant(options.variant ??
+        options.runtimeCreationTarget ??
+        (runtimeTarget === 'browser'
+            ? // The browser turns its own loop, whatever a spec's `harness` says:
+                // there is no server here to run anything else.
+                variantForLocation('browser')
+            : runtimeTarget === 'datalayer'
+                ? 'backend-services'
+                : 'local-agent-runtimes'));
+    const isLocal = locationOf(variant) === 'local';
     const runtimeCreationBaseUrl = options.runtimeCreationBaseUrl ??
-        (runtimeCreationTarget === 'local-agent-runtimes'
-            ? localRuntimeBaseUrl
-            : undefined);
-    const autoStart = options.autoStart ?? runtimeCreationTarget === 'backend-services';
-    const result = useAgentRuntimes({
-        ...options,
-        runtimeCreationTarget,
-        runtimeCreationBaseUrl,
-        autoStart,
-    });
-    const bootstrapAttemptKeyRef = useRef(null);
-    const fallbackPodName = useMemo(() => {
-        const configuredName = typeof options.agentConfig?.name === 'string'
-            ? options.agentConfig.name.trim()
-            : '';
-        if (configuredName) {
-            return configuredName;
-        }
-        const configuredSpecId = typeof options.agentSpecId === 'string' ? options.agentSpecId.trim() : '';
-        if (configuredSpecId) {
-            return configuredSpecId;
-        }
-        return 'example-agent-runtime';
+        (isLocal ? localRuntimeBaseUrl : undefined);
+    // Two of the four targets are a sandbox and nothing else. Launching an agent
+    // there would call a service that is not running, so the hook simply does
+    // not — and `useExampleAgentRuntime` reports why, for the chat to show.
+    const autoStart = capabilities.hasAgent
+        ? (options.autoStart ?? !isLocal)
+        : false;
+    const fallbackRuntimeName = useMemo(() => {
+        const configuredName = options.agentConfig?.name?.trim();
+        return (configuredName || options.agentSpecId?.trim() || 'example-agent-runtime');
     }, [options.agentConfig?.name, options.agentSpecId]);
-    useEffect(() => {
-        if (result.runtime || result.isLaunching) {
-            return;
-        }
-        const bootstrapKey = `${runtimeTarget}:${runtimeCreationTarget}:${fallbackPodName}`;
-        if (bootstrapAttemptKeyRef.current === bootstrapKey) {
-            return;
-        }
-        if (runtimeCreationTarget === 'local-agent-runtimes') {
-            bootstrapAttemptKeyRef.current = bootstrapKey;
-            result.connectToRuntime({
-                podName: fallbackPodName,
-                environmentName: 'local-agent-runtimes',
-                jupyterBaseUrl: runtimeCreationBaseUrl,
-            });
-            return;
+    const runtimeConnection = useMemo(() => isLocal
+        ? {
+            runtimeName: fallbackRuntimeName,
+            environmentName: 'local-agent-runtimes',
+            jupyterBaseUrl: runtimeCreationBaseUrl,
         }
-        if (runtimeCreationTarget === 'backend-services' &&
-            !autoStart &&
-            options.agentSpecId) {
-            bootstrapAttemptKeyRef.current = bootstrapKey;
-            void result.launchRuntime().catch(() => {
-                bootstrapAttemptKeyRef.current = null;
-            });
+        : undefined, [fallbackRuntimeName, runtimeCreationBaseUrl, isLocal]);
+    const agentConfig = useMemo(() => isLocal && options.agentSpecId
+        ? {
+            ...options.agentConfig,
+            agentSpecId: options.agentConfig?.agentSpecId ?? options.agentSpecId,
         }
-    }, [
-        runtimeTarget,
-        runtimeCreationTarget,
+        : options.agentConfig, [options.agentConfig, options.agentSpecId, isLocal]);
+    return useAgentRuntimes({
+        ...options,
+        agentConfig,
+        variant,
         runtimeCreationBaseUrl,
-        fallbackPodName,
         autoStart,
-        options.agentSpecId,
-        result.runtime,
-        result.isLaunching,
-        result.connectToRuntime,
-        result.launchRuntime,
-    ]);
-    return result;
+        autoCreateAgent: capabilities.hasAgent ? options.autoCreateAgent : false,
+        runtimeConnection: options.runtimeConnection ?? runtimeConnection,
+    });
 }
 export default useExampleAgentRuntimes;