@datalayer/agent-runtimes 1.0.28 → 1.3.10

package/lib/chat/tools/A2AAgentDialog.js

@@ -0,0 +1,265 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The overlay behind "card" on an A2A run.
+ *
+ * Everything the run's events said about the agent — where it was launched,
+ * its endpoint, its task and state — and the agent card fetched live from the
+ * agent itself, laid out field by field with the raw JSON underneath, and a
+ * link out to the card's URL for whoever wants the tab after all.
+ *
+ * @module chat/tools/A2AAgentDialog
+ */
+import React, { useEffect, useState } from 'react';
+import { Heading, Label, Link, Spinner, Text } from '@primer/react';
+import { Dialog } from '@primer/react/experimental';
+import { LinkExternalIcon } from '@primer/octicons-react';
+import { Box } from '@datalayer/primer-addons';
+/**
+ * The agent behind a delegated run, or `null` when the run is not over A2A.
+ * Later events win, except the name, which is the first one's.
+ */
+export function a2aAgentDetails(events, fallbackName) {
+    if (!events.some(event => event.transport === 'a2a')) {
+        return null;
+    }
+    const details = {
+        name: events[0]?.subagentName ?? fallbackName ?? 'agent',
+    };
+    for (const event of events) {
+        if (event.url)
+            details.url = event.url;
+        if (event.launch && event.launch !== 'auto')
+            details.launch = event.launch;
+        if (event.phase === 'status' && event.state)
+            details.state = event.state;
+        if (event.taskId)
+            details.taskId = event.taskId;
+        if (event.runtimeUid)
+            details.runtimeUid = event.runtimeUid;
+        if (event.agentCard)
+            details.card = event.agentCard;
+    }
+    return details;
+}
+/** Where an A2A agent publishes its card. */
+export function agentCardUrl(url) {
+    return `${url.replace(/\/+$/, '')}/.well-known/agent-card.json`;
+}
+/** The agent card at `url`, fetched when the URL is known and refetched when it changes. */
+export function useAgentCard(url) {
+    const [state, setState] = useState({
+        status: url ? 'loading' : 'idle',
+    });
+    useEffect(() => {
+        if (!url) {
+            setState({ status: 'idle' });
+            return;
+        }
+        const controller = new AbortController();
+        setState({ status: 'loading' });
+        fetch(agentCardUrl(url), {
+            signal: controller.signal,
+            headers: { Accept: 'application/json' },
+        })
+            .then(async (response) => {
+            if (!response.ok) {
+                throw new Error(`${response.status} ${response.statusText}`.trim());
+            }
+            const body = await response.json();
+            if (!body || typeof body !== 'object' || Array.isArray(body)) {
+                throw new Error('The agent card is not a JSON object');
+            }
+            setState({ status: 'loaded', card: body });
+        })
+            .catch((reason) => {
+            if (controller.signal.aborted)
+                return;
+            setState({
+                status: 'error',
+                error: reason instanceof Error ? reason.message : String(reason),
+            });
+        });
+        return () => controller.abort();
+    }, [url]);
+    return state;
+}
+// ---------------------------------------------------------------------------
+// Reading a card without trusting its shape
+// ---------------------------------------------------------------------------
+const record = (value) => value && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : undefined;
+const items = (value) => Array.isArray(value)
+    ? value.map(record).filter((v) => !!v)
+    : [];
+const text = (value) => typeof value === 'string' && value ? value : undefined;
+const strings = (value) => Array.isArray(value)
+    ? value.filter((v) => typeof v === 'string')
+    : [];
+// ---------------------------------------------------------------------------
+// Pieces
+// ---------------------------------------------------------------------------
+function Section({ title, children, }) {
+    return (_jsxs(Box, { sx: { display: 'flex', flexDirection: 'column', gap: 2 }, children: [_jsx(Heading, { as: "h4", sx: { fontSize: 1, m: 0 }, children: title }), children] }));
+}
+function Row({ label, children, }) {
+    return (_jsxs(Box, { sx: {
+            display: 'grid',
+            gridTemplateColumns: '112px 1fr',
+            gap: 2,
+            alignItems: 'baseline',
+            fontSize: 0,
+        }, children: [_jsx(Text, { sx: { color: 'fg.muted', fontSize: 0 }, children: label }), _jsx(Box, { sx: { minWidth: 0, wordBreak: 'break-all' }, children: children })] }));
+}
+function External({ href, children, }) {
+    return (_jsxs(Link, { href: href, target: "_blank", rel: "noreferrer", sx: {
+            fontSize: 0,
+            fontFamily: 'mono',
+            display: 'inline-flex',
+            alignItems: 'center',
+            gap: 1,
+        }, children: [children ?? href, _jsx(LinkExternalIcon, { size: 12 })] }));
+}
+function Mono({ children }) {
+    return _jsx(Text, { sx: { fontSize: 0, fontFamily: 'mono' }, children: children });
+}
+/** camelCase or snake_case, as words, for a key the card renderer never heard of. */
+function humanize(key) {
+    const spaced = key
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/[_-]+/g, ' ')
+        .toLowerCase();
+    return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+const isUrl = (value) => /^https?:\/\//.test(value);
+const None = ({ word = 'none' }) => (_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: word }));
+/**
+ * Any JSON value, laid out: scalars as text (URLs as links, booleans as
+ * yes/no), arrays as lists, objects as key/value rows — three levels deep,
+ * compact JSON below that. A key the card renderer never heard of still
+ * reads as information rather than as a blob to open the raw JSON for.
+ */
+function ValueView({ value, depth = 0, }) {
+    if (value === null || value === undefined) {
+        return _jsx(None, { word: "\u2014" });
+    }
+    if (typeof value === 'boolean') {
+        return (_jsx(Label, { size: "small", variant: value ? 'success' : 'secondary', children: value ? 'yes' : 'no' }));
+    }
+    if (typeof value === 'number') {
+        return _jsx(Mono, { children: String(value) });
+    }
+    if (typeof value === 'string') {
+        return isUrl(value) ? (_jsx(External, { href: value })) : (_jsx(Text, { sx: { fontSize: 0 }, children: value }));
+    }
+    if (depth >= 3) {
+        return _jsx(Mono, { children: JSON.stringify(value) });
+    }
+    if (Array.isArray(value)) {
+        if (value.length === 0) {
+            return _jsx(None, {});
+        }
+        if (value.every(item => typeof item !== 'object' || item === null)) {
+            return (_jsx(Box, { sx: { display: 'flex', gap: 2, flexWrap: 'wrap' }, children: value.map((item, index) => (_jsx(ValueView, { value: item, depth: depth + 1 }, index))) }));
+        }
+        return (_jsx(Box, { sx: { display: 'flex', flexDirection: 'column', gap: 2 }, children: value.map((item, index) => (_jsx(Box, { sx: { pl: 2, borderLeft: '2px solid', borderColor: 'border.muted' }, children: _jsx(ValueView, { value: item, depth: depth + 1 }) }, index))) }));
+    }
+    const entries = Object.entries(value);
+    if (entries.length === 0) {
+        return _jsx(None, { word: "empty" });
+    }
+    return (_jsx(Box, { sx: {
+            display: 'grid',
+            gridTemplateColumns: 'max-content 1fr',
+            columnGap: 2,
+            rowGap: 1,
+            alignItems: 'baseline',
+        }, children: entries.map(([key, entry]) => (_jsxs(React.Fragment, { children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: humanize(key) }), _jsx(Box, { sx: { minWidth: 0, wordBreak: 'break-all' }, children: _jsx(ValueView, { value: entry, depth: depth + 1 }) })] }, key))) }));
+}
+/** The keys laid out by hand below; every other top-level key gets a row of its own. */
+const HANDLED_KEYS = new Set([
+    'name',
+    'description',
+    'version',
+    'protocolVersion',
+    'url',
+    'documentationUrl',
+    'iconUrl',
+    'provider',
+    'supportedInterfaces',
+    'capabilities',
+    'skills',
+    'defaultInputModes',
+    'defaultOutputModes',
+]);
+/**
+ * The card, field by field: the fields the A2A card schema names, laid out
+ * the way a reader wants them, then every other top-level key the agent
+ * chose to publish — nothing is left to the raw JSON alone.
+ */
+function CardFields({ card, }) {
+    const provider = record(card.provider);
+    const capabilities = record(card.capabilities);
+    const capabilityEntries = Object.entries(capabilities ?? {});
+    const extensions = items(capabilities?.extensions);
+    const interfaces = items(card.supportedInterfaces);
+    const skills = items(card.skills);
+    const inputs = strings(card.defaultInputModes);
+    const outputs = strings(card.defaultOutputModes);
+    const others = Object.entries(card).filter(([key]) => !HANDLED_KEYS.has(key));
+    return (_jsxs(Box, { sx: { display: 'flex', flexDirection: 'column', gap: 2 }, children: [_jsxs(Box, { children: [_jsx(Text, { sx: { fontSize: 1, fontWeight: 'bold' }, children: text(card.name) ?? 'Unnamed agent' }), text(card.version) ? (_jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted', ml: 2 }, children: ["v", text(card.version)] })) : null, text(card.protocolVersion) ? (_jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted', ml: 2 }, children: ["A2A ", text(card.protocolVersion)] })) : null, text(card.description) ? (_jsx(Text, { as: "p", sx: { fontSize: 0, color: 'fg.muted', mt: 1, mb: 0 }, children: text(card.description) })) : null] }), text(card.url) ? (_jsx(Row, { label: "Endpoint", children: _jsx(External, { href: text(card.url) }) })) : null, text(card.documentationUrl) ? (_jsx(Row, { label: "Documentation", children: _jsx(External, { href: text(card.documentationUrl) }) })) : null, text(card.iconUrl) ? (_jsx(Row, { label: "Icon", children: _jsx(External, { href: text(card.iconUrl) }) })) : null, provider ? (_jsx(Row, { label: "Provider", children: _jsx(ValueView, { value: provider, depth: 1 }) })) : null, card.supportedInterfaces !== undefined ? (_jsx(Row, { label: "Interfaces", children: interfaces.length === 0 ? (_jsx(None, {})) : (_jsx(Box, { sx: { display: 'flex', flexDirection: 'column', gap: 1 }, children: interfaces.map((entry, index) => (_jsxs(Box, { sx: {
+                            display: 'flex',
+                            gap: 2,
+                            alignItems: 'center',
+                            flexWrap: 'wrap',
+                        }, children: [_jsx(Label, { size: "small", children: text(entry.protocolBinding) ?? 'binding' }), text(entry.url) ? _jsx(Mono, { children: text(entry.url) }) : null, text(entry.protocolVersion) ? (_jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: ["v", text(entry.protocolVersion)] })) : null] }, index))) })) })) : null, capabilities !== undefined ? (_jsx(Row, { label: "Capabilities", children: capabilityEntries.length === 0 ? (_jsx(None, {})) : (_jsxs(Box, { sx: { display: 'flex', flexDirection: 'column', gap: 1 }, children: [_jsx(Box, { sx: { display: 'flex', gap: 1, flexWrap: 'wrap' }, children: capabilityEntries
+                                .filter(([, flag]) => typeof flag === 'boolean')
+                                .map(([key, flag]) => (_jsxs(Label, { size: "small", variant: flag ? 'success' : 'secondary', children: [key, ": ", flag ? 'yes' : 'no'] }, key))) }), extensions.map((extension, index) => (_jsxs(Box, { sx: {
+                                display: 'flex',
+                                gap: 2,
+                                alignItems: 'baseline',
+                                flexWrap: 'wrap',
+                            }, children: [_jsx(Mono, { children: text(extension.uri) ?? 'extension' }), extension.required === true ? (_jsx(Label, { size: "small", variant: "attention", children: "required" })) : null, text(extension.description) ? (_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: text(extension.description) })) : null] }, index))), capabilityEntries
+                            .filter(([key, entry]) => typeof entry !== 'boolean' && key !== 'extensions')
+                            .map(([key, entry]) => (_jsxs(Box, { sx: { display: 'flex', gap: 2 }, children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: humanize(key) }), _jsx(ValueView, { value: entry, depth: 1 })] }, key)))] })) })) : null, card.skills !== undefined ? (_jsx(Row, { label: "Skills", children: skills.length === 0 ? (_jsx(None, {})) : (_jsx(Box, { sx: { display: 'flex', flexDirection: 'column', gap: 1 }, children: skills.map((skill, index) => (_jsxs(Box, { children: [_jsx(Text, { sx: { fontSize: 0, fontWeight: 'bold' }, children: text(skill.name) ?? text(skill.id) ?? 'skill' }), text(skill.description) ? (_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted', ml: 2 }, children: text(skill.description) })) : null, strings(skill.tags).length > 0 ? (_jsx(Box, { sx: { display: 'inline-flex', gap: 1, ml: 2 }, children: strings(skill.tags).map(tag => (_jsx(Label, { size: "small", children: tag }, tag))) })) : null] }, index))) })) })) : null, card.defaultInputModes !== undefined ? (_jsx(Row, { label: "Input modes", children: inputs.length ? _jsx(Mono, { children: inputs.join(', ') }) : _jsx(None, {}) })) : null, card.defaultOutputModes !== undefined ? (_jsx(Row, { label: "Output modes", children: outputs.length ? _jsx(Mono, { children: outputs.join(', ') }) : _jsx(None, {}) })) : null, others.map(([key, value]) => (_jsx(Row, { label: humanize(key), children: _jsx(ValueView, { value: value }) }, key)))] }));
+}
+const LAUNCH_LABEL = {
+    local: 'launched on the local agent-runtimes server',
+    cloud: 'launched on a Datalayer runtime',
+    remote: 'reached at a URL the spec named',
+    auto: 'launch not decided yet',
+};
+/**
+ * Everything about the agent behind an A2A run: the run's own facts, the
+ * card fetched from the agent, the raw JSON, and the way out to the URL.
+ */
+export function A2AAgentDialog({ details, onClose, }) {
+    const fetched = useAgentCard(details.url);
+    const cardUrl = details.url ? agentCardUrl(details.url) : undefined;
+    const openCard = () => {
+        if (cardUrl)
+            window.open(cardUrl, '_blank', 'noopener,noreferrer');
+    };
+    return (_jsx(Dialog, { onClose: onClose, title: `A2A agent · ${details.name}`, subtitle: "A separate agent, reached over the A2A protocol", width: "large", footerButtons: [
+            ...(cardUrl
+                ? [{ content: 'Open agent card', onClick: openCard }]
+                : []),
+            { content: 'Close', onClick: onClose, buttonType: 'primary' },
+        ], children: _jsxs(Box, { "data-a2a-agent-dialog": details.name, "data-a2a-card-status": fetched.status, sx: { display: 'flex', flexDirection: 'column', gap: 3 }, children: [_jsxs(Section, { title: "This run", children: [details.description ? (_jsx(Text, { as: "p", sx: { fontSize: 0, color: 'fg.muted', m: 0 }, children: details.description })) : null, _jsx(Row, { label: "Launch", children: _jsxs(Text, { sx: { fontSize: 0 }, children: [details.launch ?? 'auto', _jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: [' ', "\u2014 ", LAUNCH_LABEL[details.launch ?? 'auto'] ?? ''] })] }) }), details.ref ? (_jsx(Row, { label: "Agentspec", children: _jsx(Mono, { children: details.ref }) })) : null, _jsx(Row, { label: "State", children: _jsx(Text, { sx: { fontSize: 0 }, children: details.state ?? 'unknown' }) }), details.taskId ? (_jsx(Row, { label: "Task", children: _jsx(Mono, { children: details.taskId }) })) : null, details.runtimeUid ? (_jsx(Row, { label: "Runtime", children: _jsx(Mono, { children: details.runtimeUid }) })) : null, details.url ? (_jsx(Row, { label: "Endpoint", children: _jsx(External, { href: details.url }) })) : null, cardUrl ? (_jsx(Row, { label: "Agent card", children: _jsx(External, { href: cardUrl }) })) : null] }), _jsxs(Section, { title: "Agent card", children: [fetched.status === 'idle' ? (_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "No endpoint known yet: the card can be fetched once the agent is launched." })) : null, fetched.status === 'loading' ? (_jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, children: [_jsx(Spinner, { size: "small" }), _jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: ["Fetching ", cardUrl, "\u2026"] })] })) : null, fetched.status === 'error' ? (_jsxs(Text, { sx: { fontSize: 0, color: 'danger.fg' }, children: ["The card could not be fetched from here (", fetched.error, "). It may still open in a tab through the link above."] })) : null, fetched.status === 'loaded' ? (_jsxs(_Fragment, { children: [_jsx(CardFields, { card: fetched.card }), _jsxs(Box, { as: "details", sx: { fontSize: 0 }, children: [_jsx(Box, { as: "summary", sx: { cursor: 'pointer', color: 'fg.muted' }, children: "Raw JSON" }), _jsx(Box, { as: "pre", "data-a2a-card-json": true, sx: {
+                                                mt: 2,
+                                                p: 2,
+                                                bg: 'canvas.subtle',
+                                                border: '1px solid',
+                                                borderColor: 'border.default',
+                                                borderRadius: 2,
+                                                overflow: 'auto',
+                                                maxHeight: 280,
+                                                fontSize: 0,
+                                                m: 0,
+                                            }, children: JSON.stringify(fetched.card, null, 2) })] })] })) : null] }), details.card && fetched.status !== 'loaded' ? (_jsxs(Section, { title: "Card, as the server saw it at launch", children: [_jsx(Row, { label: "Name", children: _jsxs(Text, { sx: { fontSize: 0 }, children: [details.card.name ?? '—', details.card.version ? ` v${details.card.version}` : ''] }) }), details.card.description ? (_jsx(Row, { label: "Description", children: _jsx(Text, { sx: { fontSize: 0 }, children: details.card.description }) })) : null, details.card.skills && details.card.skills.length > 0 ? (_jsx(Row, { label: "Skills", children: _jsx(Text, { sx: { fontSize: 0 }, children: details.card.skills.join(', ') }) })) : null] })) : null] }) }));
+}
+export default A2AAgentDialog;

package/lib/chat/tools/ToolApprovalBanner.d.ts

@@ -27,5 +27,5 @@ export interface ToolApprovalBannerProps {
 /**
  * Persistent banner for tool approval notifications.
  */
-export declare function ToolApprovalBanner({ pendingApprovals, onReview, onApproveAll, onDismiss, collapsible, }: ToolApprovalBannerProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function ToolApprovalBanner({ pendingApprovals, onReview, onApproveAll, onDismiss, collapsible, }: ToolApprovalBannerProps): import("react").JSX.Element | null;
 export default ToolApprovalBanner;

package/lib/chat/tools/ToolApprovalDialog.d.ts

@@ -22,7 +22,7 @@ export interface ToolApprovalDialogProps {
 /**
  * Tool Approval Dialog component
  */
-export declare function ToolApprovalDialog({ isOpen, toolName, toolDescription, args, onApprove, onDeny, onClose, showRememberChoice, }: ToolApprovalDialogProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function ToolApprovalDialog({ isOpen, toolName, toolDescription, args, onApprove, onDeny, onClose, showRememberChoice, }: ToolApprovalDialogProps): import("react").JSX.Element | null;
 /**
  * Hook to manage tool approval dialog state
  */

package/lib/chat/tools/ToolCallDisplay.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Default tool call display component.
+ * Shows tool execution with collapsible details.
+ *
+ * @module chat/tools/ToolCallDisplay
+ */
+import React from 'react';
 import type { CodeError, ExecutionResult, DisplayToolCallStatus } from '../../types';
 /**
  * Error type classification for display purposes
@@ -47,5 +54,5 @@ export interface ToolCallDisplayProps {
  * - Color-coded status indicators
  * - Rich error display distinguishing execution errors from code errors
  */
-export declare function ToolCallDisplay({ toolCallId, toolName, args, result, status, error, executionResult, codeError, exitCode, executionError, approvalRequired, approvalState, approvalDecisionSource, onApprove, onDeny, approvalLoading, }: ToolCallDisplayProps): import("react/jsx-runtime").JSX.Element;
+export declare function ToolCallDisplay({ toolCallId, toolName, args, result, status, error, executionResult, codeError, exitCode, executionError, approvalRequired, approvalState, approvalDecisionSource, onApprove, onDeny, approvalLoading, }: ToolCallDisplayProps): React.JSX.Element;
 export default ToolCallDisplay;

package/lib/chat/tools/index.d.ts

@@ -5,5 +5,6 @@
  */
 export { ToolCallDisplay, type ToolCallDisplayProps, type ErrorType, } from './ToolCallDisplay';
 export { SubagentActivity, type SubagentActivityProps, } from './SubagentActivity';
+export { A2AAgentDialog, a2aAgentDetails, agentCardUrl, useAgentCard, type A2AAgentDetails, type A2AAgentDialogProps, type AgentCardFetch, } from './A2AAgentDialog';
 export { ToolApprovalBanner, type ToolApprovalBannerProps, type PendingApproval, } from './ToolApprovalBanner';
 export { ToolApprovalDialog, useToolApprovalDialog, type ToolApprovalDialogProps, } from './ToolApprovalDialog';

package/lib/chat/tools/index.js

@@ -9,5 +9,6 @@
  */
 export { ToolCallDisplay, } from './ToolCallDisplay';
 export { SubagentActivity, } from './SubagentActivity';
+export { A2AAgentDialog, a2aAgentDetails, agentCardUrl, useAgentCard, } from './A2AAgentDialog';
 export { ToolApprovalBanner, } from './ToolApprovalBanner';
 export { ToolApprovalDialog, useToolApprovalDialog, } from './ToolApprovalDialog';

package/lib/chat/usage/ContextPie.d.ts

@@ -0,0 +1,17 @@
+import type { ContextSnapshotData } from '../../types/context';
+export interface ContextPieProps {
+    /** Agent usage data from the context-snapshot API */
+    agentUsage: ContextSnapshotData;
+    /** Horizontal padding to match the chat layout */
+    padding: number;
+    /**
+     * Whether to draw the context ring.
+     *
+     * False by default. It is a small pie of how the window is spent, and it
+     * earns its place only where a person is likely to fill one — an agent
+     * working through a notebook — rather than in every chat that happens to
+     * report usage. The numbers beside it are shown either way.
+     */
+    showContextRing?: boolean;
+}
+export declare function ContextPie({ agentUsage, padding, showContextRing, }: ContextPieProps): import("react").JSX.Element;

package/lib/chat/usage/{TokenUsageBar.js → ContextPie.js}

@@ -4,11 +4,13 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * TokenUsageBar — Compact bar showing context-window usage with a
- * tiny pie chart, session totals, and a hover overlay with category
- * breakdown.
+ * What the context window is holding.
  *
- * @module chat/elements/TokenUsageBar
+ * A row under the prompt: a ring of how the window is spent, the totals for
+ * the session and the last turn, and a hover overlay breaking the ring down
+ * by category.
+ *
+ * @module chat/usage/ContextPie
  */
 import { useRef, useState } from 'react';
 import { Text } from '@primer/react';
@@ -18,17 +20,21 @@ import { formatTokenCount } from '../../utils';
 // ---------------------------------------------------------------------------
 // Component
 // ---------------------------------------------------------------------------
-export function TokenUsageBar({ agentUsage, padding }) {
+export function ContextPie({ agentUsage, padding, showContextRing = false, }) {
     // State for context pie chart overlay
     const [contextOverlayOpen, setContextOverlayOpen] = useState(false);
     const contextAnchorRef = useRef(null);
     const hoverTimeoutRef = useRef(null);
-    const hasTurn = agentUsage.turnUsage &&
-        (agentUsage.turnUsage.inputTokens > 0 ||
-            agentUsage.turnUsage.outputTokens > 0);
-    const hasSession = agentUsage.sessionUsage &&
-        (agentUsage.sessionUsage.inputTokens > 0 ||
-            agentUsage.sessionUsage.outputTokens > 0);
+    /*
+     * Shown whenever the agent reports them, zero included.
+     *
+     * They were hidden until one of the two counts went above zero, which meant
+     * the bar changed shape after the first answer — and, worse, that a reader
+     * could not tell "nothing sent yet" from "this agent does not report it".
+     * A zero is an answer; a missing row is not.
+     */
+    const hasTurn = !!agentUsage.turnUsage;
+    const hasSession = !!agentUsage.sessionUsage;
     const hasCostUsage = !!agentUsage.costUsage &&
         (agentUsage.costUsage.cumulativeCostUsd > 0 ||
             agentUsage.costUsage.lastTurnCostUsd > 0);
@@ -156,7 +162,7 @@ export function TokenUsageBar({ agentUsage, padding }) {
             overflow: 'visible',
             whiteSpace: 'nowrap',
             minWidth: 0,
-        }, children: [_jsxs(Box, { sx: { position: 'relative', flexShrink: 0 }, onMouseEnter: () => {
+        }, children: [showContextRing && (_jsxs(Box, { sx: { position: 'relative', flexShrink: 0 }, onMouseEnter: () => {
                     if (hoverTimeoutRef.current)
                         clearTimeout(hoverTimeoutRef.current);
                     hoverTimeoutRef.current = setTimeout(() => setContextOverlayOpen(true), 150);
@@ -193,7 +199,7 @@ export function TokenUsageBar({ agentUsage, padding }) {
                                     color: 'fg.default',
                                     display: 'block',
                                     mb: 2,
-                                }, children: "Context Window" }), _jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted', display: 'block', mb: 1 }, children: [_jsx(Text, { as: "span", sx: { fontWeight: 'semibold', color: 'fg.default' }, children: formatTokenCount(usedTokens) }), ' / ', formatTokenCount(windowTokens), ' tokens'] }), agentUsage.costUsage && (_jsxs(Text, { sx: {
+                                }, children: "Context" }), _jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted', display: 'block', mb: 1 }, children: [_jsx(Text, { as: "span", sx: { fontWeight: 'semibold', color: 'fg.default' }, children: formatTokenCount(usedTokens) }), ' / ', formatTokenCount(windowTokens), ' tokens'] }), agentUsage.costUsage && (_jsxs(Text, { sx: {
                                     fontSize: 0,
                                     color: 'fg.muted',
                                     display: 'block',
@@ -227,5 +233,5 @@ export function TokenUsageBar({ agentUsage, padding }) {
                                     display: 'block',
                                     mt: 2,
                                     fontStyle: 'italic',
-                                }, children: "Quality may decline as limit nears." }))] }))] }), _jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted', flexShrink: 0 }, children: [_jsx(Text, { as: "span", sx: { fontWeight: 'semibold', color: 'fg.default', fontSize: 0 }, children: formatTokenCount(agentUsage.totalTokens) }), ' / ', formatTokenCount(agentUsage.contextWindow), ' ctx'] }), hasCostUsage && (_jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted', flexShrink: 0 }, children: ['· cost ', _jsx(Text, { as: "span", sx: { fontWeight: 'semibold', color: 'fg.default', fontSize: 0 }, children: formatUsd(costUsage?.lastTurnCostUsd ?? 0) }), ' turn / ', _jsx(Text, { as: "span", sx: { fontWeight: 'semibold', color: 'fg.default', fontSize: 0 }, children: formatUsd(costUsage?.cumulativeCostUsd ?? 0) })] })), hasSession && (_jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted', flexShrink: 0 }, children: ['· ', formatTokenCount(sessionUsage?.inputTokens ?? 0), _jsx(Text, { as: "span", sx: { color: 'success.fg', fontSize: 0 }, children: '▲' }), ' ', formatTokenCount(sessionUsage?.outputTokens ?? 0), _jsx(Text, { as: "span", sx: { color: 'attention.fg', fontSize: 0 }, children: '▼' })] })), hasTurn && (_jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted', flexShrink: 0 }, children: ['· turn ', formatTokenCount(turnUsage?.inputTokens ?? 0), _jsx(Text, { as: "span", sx: { color: 'success.fg', fontSize: 0 }, children: '▲' }), ' ', formatTokenCount(turnUsage?.outputTokens ?? 0), _jsx(Text, { as: "span", sx: { color: 'attention.fg', fontSize: 0 }, children: '▼' })] }))] }));
+                                }, children: "Quality may decline as limit nears." }))] }))] })), _jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted', flexShrink: 0 }, children: [_jsx(Text, { as: "span", sx: { fontWeight: 'semibold', color: 'fg.default', fontSize: 0 }, children: formatTokenCount(agentUsage.totalTokens) }), ' / ', formatTokenCount(agentUsage.contextWindow), ' ctx'] }), hasCostUsage && (_jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted', flexShrink: 0 }, children: ['· cost ', _jsx(Text, { as: "span", sx: { fontWeight: 'semibold', color: 'fg.default', fontSize: 0 }, children: formatUsd(costUsage?.lastTurnCostUsd ?? 0) }), ' turn / ', _jsx(Text, { as: "span", sx: { fontWeight: 'semibold', color: 'fg.default', fontSize: 0 }, children: formatUsd(costUsage?.cumulativeCostUsd ?? 0) })] })), hasSession && (_jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted', flexShrink: 0 }, children: ['· session ', formatTokenCount(sessionUsage?.inputTokens ?? 0), _jsx(Text, { as: "span", sx: { color: 'success.fg', fontSize: 0 }, children: '▲' }), ' ', formatTokenCount(sessionUsage?.outputTokens ?? 0), _jsx(Text, { as: "span", sx: { color: 'attention.fg', fontSize: 0 }, children: '▼' })] })), hasTurn && (_jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted', flexShrink: 0 }, children: ['· turn ', formatTokenCount(turnUsage?.inputTokens ?? 0), _jsx(Text, { as: "span", sx: { color: 'success.fg', fontSize: 0 }, children: '▲' }), ' ', formatTokenCount(turnUsage?.outputTokens ?? 0), _jsx(Text, { as: "span", sx: { color: 'attention.fg', fontSize: 0 }, children: '▼' })] }))] }));
 }

package/lib/chat/useViewportDrag.d.ts

@@ -0,0 +1,11 @@
+/** Where the box sits once somebody has moved it, in viewport pixels. */
+export type DragPosition = {
+    left: number;
+    top: number;
+} | null;
+export declare function useViewportDrag(boxRef: React.RefObject<HTMLElement | null>): {
+    position: DragPosition;
+    onHandlePointerDown: (event: React.PointerEvent<HTMLElement>) => void;
+    reset: () => void;
+};
+export default useViewportDrag;

package/lib/chat/useViewportDrag.js

@@ -0,0 +1,61 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Moving a fixed-position box about the viewport by a handle.
+ *
+ * The mechanics behind the chat's "Floating draggable" mode. The same idea
+ * as `FloatingCard`'s, which moves a prompt about its host; this one moves
+ * the whole chat window about the viewport, because that is what a fixed
+ * box is positioned against. The box stays reachable: however far it is
+ * dragged, a margin of it stays on screen, so its handle can always be
+ * picked up again.
+ *
+ * @module chat/useViewportDrag
+ */
+import { useCallback, useRef, useState } from 'react';
+/** How much of the box must stay inside the viewport. */
+const MARGIN = 24;
+export function useViewportDrag(boxRef) {
+    const [position, setPosition] = useState(null);
+    /* Where the pointer took hold, so the box moves by the pointer's delta
+       rather than snapping its corner to the cursor. */
+    const grip = useRef(null);
+    const onHandlePointerDown = useCallback((event) => {
+        const box = boxRef.current;
+        if (!box) {
+            return;
+        }
+        const rect = box.getBoundingClientRect();
+        grip.current = {
+            dx: event.clientX - rect.left,
+            dy: event.clientY - rect.top,
+        };
+        const handle = event.currentTarget;
+        // Absent in test DOMs; the move listeners below still work there.
+        handle.setPointerCapture?.(event.pointerId);
+        const move = (moved) => {
+            if (!grip.current) {
+                return;
+            }
+            const left = Math.min(Math.max(moved.clientX - grip.current.dx, MARGIN - rect.width), window.innerWidth - MARGIN);
+            const top = Math.min(Math.max(moved.clientY - grip.current.dy, 0), window.innerHeight - MARGIN);
+            setPosition({ left, top });
+        };
+        const up = () => {
+            grip.current = null;
+            handle.removeEventListener('pointermove', move);
+            handle.removeEventListener('pointerup', up);
+            handle.removeEventListener('pointercancel', up);
+        };
+        handle.addEventListener('pointermove', move);
+        handle.addEventListener('pointerup', up);
+        handle.addEventListener('pointercancel', up);
+        event.preventDefault();
+    }, [boxRef]);
+    /** Back to wherever the box starts: called when the mode changes. */
+    const reset = useCallback(() => setPosition(null), []);
+    return { position, onHandlePointerDown, reset };
+}
+export default useViewportDrag;

package/lib/chat/viewModes.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The ways a chat can be shown, and which of them a host can offer.
+ *
+ * The header draws these as a segmented toggle. The list lives here, apart
+ * from the header, so the rules about it — the order, the words, and which
+ * modes are greyed out — can be read and tested without rendering anything.
+ *
+ * "Sidebar panel" is the one with a condition. The other three float over
+ * the page and need nothing from it; a sidebar has to dock *somewhere*, and
+ * where is the host's to say. A host says it by passing a mount point — the
+ * element the panel goes into — and without one the option is shown but
+ * disabled, so the person can see the mode exists and that this page has no
+ * place for it, rather than clicking it and watching nothing happen.
+ *
+ * @module chat/viewModes
+ */
+import type { ChatViewMode } from '../types/chat';
+/** One entry of the header's toggle. */
+export type ChatViewModeOption = {
+    mode: ChatViewMode;
+    /** The tooltip, and the button's accessible name. */
+    label: string;
+};
+/** The modes, in the order the toggle shows them: floating first, docked last. */
+export declare const CHAT_VIEW_MODES: readonly ChatViewModeOption[];
+/** Why the sidebar option is greyed out, for its tooltip. */
+export declare const SIDEBAR_NEEDS_MOUNT_POINT = "No mount point for a sidebar on this page";
+/** Whether a mode floats over the page rather than docking into it. */
+export declare function isFloatingChatViewMode(mode: ChatViewMode | undefined): boolean;
+/**
+ * Where a host said the sidebar goes.
+ *
+ * An element, or a selector for one — a host that renders the sidebar itself
+ * marks the container with an attribute and passes the selector, which is
+ * easier than threading a ref through a layout. Resolved when asked, since a
+ * container may mount after the chat does; nothing is cached.
+ */
+export declare function resolveMountPoint(mountPoint: HTMLElement | string | null | undefined): HTMLElement | null;
+/**
+ * The modes the toggle shows but does not let anyone pick.
+ *
+ * Only the sidebar can be one, and only for want of a mount point. A chat
+ * already docked keeps its option live whatever the host passed: it is
+ * there, and greying out the mode it is in would read as a bug.
+ */
+export declare function disabledChatViewModes({ sidebarMountPoint, viewMode, }: {
+    /** The resolved element, or nothing. */
+    sidebarMountPoint?: HTMLElement | null;
+    /** The mode the chat is in now. */
+    viewMode?: ChatViewMode;
+}): ChatViewMode[];

package/lib/chat/viewModes.js

@@ -0,0 +1,57 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** The modes, in the order the toggle shows them: floating first, docked last. */
+export const CHAT_VIEW_MODES = [
+    { mode: 'floating', label: 'Full-height popup' },
+    { mode: 'floating-small', label: 'Floating popup' },
+    { mode: 'floating-draggable', label: 'Floating draggable' },
+    { mode: 'sidebar', label: 'Sidebar panel' },
+];
+/** Why the sidebar option is greyed out, for its tooltip. */
+export const SIDEBAR_NEEDS_MOUNT_POINT = 'No mount point for a sidebar on this page';
+/** Whether a mode floats over the page rather than docking into it. */
+export function isFloatingChatViewMode(mode) {
+    return (mode === 'floating' ||
+        mode === 'floating-small' ||
+        mode === 'floating-draggable');
+}
+/**
+ * Where a host said the sidebar goes.
+ *
+ * An element, or a selector for one — a host that renders the sidebar itself
+ * marks the container with an attribute and passes the selector, which is
+ * easier than threading a ref through a layout. Resolved when asked, since a
+ * container may mount after the chat does; nothing is cached.
+ */
+export function resolveMountPoint(mountPoint) {
+    if (!mountPoint) {
+        return null;
+    }
+    if (typeof mountPoint !== 'string') {
+        return mountPoint.isConnected ? mountPoint : null;
+    }
+    if (typeof document === 'undefined') {
+        return null;
+    }
+    try {
+        return document.querySelector(mountPoint);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The modes the toggle shows but does not let anyone pick.
+ *
+ * Only the sidebar can be one, and only for want of a mount point. A chat
+ * already docked keeps its option live whatever the host passed: it is
+ * there, and greying out the mode it is in would read as a bug.
+ */
+export function disabledChatViewModes({ sidebarMountPoint, viewMode, }) {
+    if (sidebarMountPoint || viewMode === 'sidebar') {
+        return [];
+    }
+    return ['sidebar'];
+}