@adecore/agents-react 0.20.1 → 0.21.1

package/dist/chat/ui/intelligent-ui/renderers/links.js

@@ -0,0 +1,87 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import clsx from 'clsx';
+import { useTranslation } from 'react-i18next';
+import { FileDiff, GitCommitHorizontal, SquareDashed } from 'lucide-react';
+import { FileIcon, Icon, Tooltip } from '@adecore/ui';
+import { CHIP_IN_MESSAGE, MENTION_TONE } from '../../chips.js';
+import { uiReasonText } from '../node-text.js';
+const PLAIN = { state: 'plain' };
+function baseName(path) {
+    const trimmed = path.replace(/\/+$/, '');
+    return trimmed.slice(trimmed.lastIndexOf('/') + 1) || path;
+}
+function plainText(target, link) {
+    switch (target.type) {
+        case 'File':
+            return target.line === undefined ? target.path : `${target.path}:${target.line}`;
+        case 'Diff':
+            return target.path;
+        case 'Commit':
+            return target.sha.slice(0, 7);
+        case 'Node':
+            return link.label ?? target.id;
+    }
+}
+function chipFace(target, link) {
+    switch (target.type) {
+        case 'File':
+            return {
+                face: (_jsxs(_Fragment, { children: [_jsx(FileIcon, { path: target.path, size: 14 }), _jsx("span", { className: "truncate", children: baseName(target.path) }), target.line !== undefined && _jsxs("span", { className: "opacity-70", children: [":", target.line] })] })),
+                hint: target.line === undefined ? target.path : `${target.path}:${target.line}`
+            };
+        case 'Diff':
+            return {
+                face: (_jsxs(_Fragment, { children: [_jsx(Icon, { icon: FileDiff, size: 12 }), _jsx("span", { className: "truncate", children: baseName(target.path) })] })),
+                hint: target.path
+            };
+        case 'Commit':
+            return {
+                face: (_jsxs(_Fragment, { children: [_jsx(Icon, { icon: GitCommitHorizontal, size: 12 }), _jsx("span", { className: "font-mono", children: target.sha.slice(0, 7) })] })),
+                hint: link.label ?? target.sha
+            };
+        case 'Node':
+            return {
+                face: (_jsxs(_Fragment, { children: [_jsx(Icon, { icon: SquareDashed, size: 12 }), _jsx("span", { className: "truncate", children: link.label ?? target.id })] })),
+                hint: null
+            };
+    }
+}
+/*
+ * A resource of the host as a chip, the shape a mention has in a message. The host says whether it
+ * can open the target; one it cannot, outside the project or gone, stays mono text with the reason
+ * in a tooltip. A chip fades in, since a link reads as text until the host checked it.
+ */
+export function UiLinkChip({ target, context }) {
+    const { t } = useTranslation('agent-chat');
+    const link = context.link?.(target) ?? PLAIN;
+    if (link.state === 'plain') {
+        const reason = uiReasonText(t, link.code, link.reason) ?? (context.link === undefined ? null : t('blocks.outsideProject'));
+        // Focusable only with a reason, so a keyboard reaches the tooltip.
+        const text = (_jsx("span", { tabIndex: reason === null ? undefined : 0, className: "font-mono text-code break-all text-text-muted", children: plainText(target, link) }));
+        return reason === null ? text : _jsx(Tooltip, { label: reason, children: text });
+    }
+    const { face, hint } = chipFace(target, link);
+    const { openLink } = context;
+    const chip = openLink === undefined ? (_jsx("span", { className: clsx(CHIP_IN_MESSAGE, MENTION_TONE, 'transition-opacity duration-120 starting:opacity-0'), children: face })) : (_jsx("button", { type: "button", className: clsx(CHIP_IN_MESSAGE, MENTION_TONE, 'transition-opacity duration-120 hover:brightness-95 starting:opacity-0'), onClick: () => openLink(target), children: face }));
+    return hint === null ? chip : _jsx(Tooltip, { label: hint, children: chip });
+}
+/* A link with children is a row: the chip and what the agent says about it. */
+function LinkRow({ target, context, described, children }) {
+    if (!described) {
+        return _jsx(UiLinkChip, { target: target, context: context });
+    }
+    return (_jsxs("div", { className: "flex min-w-0 items-baseline gap-2 px-2 text-sm", children: [_jsx("span", { className: "shrink-0", children: _jsx(UiLinkChip, { target: target, context: context }) }), _jsx("span", { className: "min-w-0 text-text-muted", children: children })] }));
+}
+export function FileRenderer({ node, children, context }) {
+    const { path, line } = node.props;
+    return (_jsx(LinkRow, { target: { type: 'File', path, line }, context: context, described: node.children.length > 0, children: children }));
+}
+export function DiffRenderer({ node, children, context }) {
+    return (_jsx(LinkRow, { target: { type: 'Diff', path: node.props.path }, context: context, described: node.children.length > 0, children: children }));
+}
+export function CommitRenderer({ node, children, context }) {
+    return (_jsx(LinkRow, { target: { type: 'Commit', sha: node.props.sha }, context: context, described: node.children.length > 0, children: children }));
+}
+export function NodeRenderer({ node, children, context }) {
+    return (_jsx(LinkRow, { target: { type: 'Node', id: node.props.id }, context: context, described: node.children.length > 0, children: children }));
+}

package/dist/chat/ui/intelligent-ui/renderers/structure.d.ts

@@ -0,0 +1,6 @@
+import type { UiProps } from '@adecore/intelligent-ui';
+import type { UiRendererProps } from '../render-context.js';
+export declare function TabsRenderer({ node, children, context }: UiRendererProps<UiProps<'Tabs'>>): import("react").JSX.Element;
+export declare function TabRenderer({ node, children }: UiRendererProps<UiProps<'Tab'>>): import("react").JSX.Element;
+export declare function SectionsRenderer({ node, children, context }: UiRendererProps<UiProps<'Sections'>>): import("react").JSX.Element;
+export declare function SectionRenderer({ node, children, context }: UiRendererProps<UiProps<'Section'>>): import("react").JSX.Element;

package/dist/chat/ui/intelligent-ui/renderers/structure.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useContext, useId } from 'react';
+import clsx from 'clsx';
+import { ChevronRight } from 'lucide-react';
+import { Icon, Tabs } from '@adecore/ui';
+import { useBlockLocal } from '../block-local.js';
+import { uiChildrenOf } from '../node-text.js';
+const SectionsContext = createContext({ touched: false, touch: () => undefined });
+/* A tab that arrives while the block streams is not picked: the one that was open stays open. */
+export function TabsRenderer({ node, children, context }) {
+    const tabs = uiChildrenOf(node, 'Tab');
+    const [picked, setPicked] = useBlockLocal(context, node.id, () => null);
+    const value = picked !== null && tabs.some((tab) => tab.id === picked) ? picked : (tabs[0]?.id ?? null);
+    return (_jsxs(Tabs.Root, { value: value, onValueChange: (next) => setPicked(String(next)), className: "flex flex-col gap-3", children: [_jsx(Tabs.List, { className: "px-2", children: tabs.map((tab) => (_jsx(Tabs.Tab, { value: tab.id, "data-ui-reveal": tab.id, children: tab.props.title }, tab.id))) }), children] }));
+}
+export function TabRenderer({ node, children }) {
+    return (_jsx(Tabs.Panel, { value: node.id, className: "chat-ui-nodes flex flex-col gap-3", children: children }));
+}
+export function SectionsRenderer({ node, children, context }) {
+    const [touched, setTouched] = useBlockLocal(context, node.id, () => false);
+    return (_jsx(SectionsContext, { value: { touched, touch: () => setTouched(true) }, children: _jsx("div", { className: "chat-ui-nodes flex flex-col divide-y divide-border-soft", children: children }) }));
+}
+/* Arrives open until the person folds a section of the set themselves; the content starts under the title. */
+export function SectionRenderer({ node, children, context }) {
+    const fold = useContext(SectionsContext);
+    const [open, setOpen] = useBlockLocal(context, node.id, () => !fold.touched);
+    const contentId = useId();
+    return (_jsxs("section", { children: [_jsxs("button", { type: "button", "data-ui-reveal": node.id, "aria-expanded": open, "aria-controls": contentId, className: "flex h-8 w-full items-center gap-2 rounded-md px-2 text-left text-sm font-medium text-text hover:bg-surface-hover", onClick: () => {
+                    fold.touch();
+                    setOpen(!open);
+                }, children: [_jsx(Icon, { icon: ChevronRight, size: 14, className: clsx('shrink-0 text-text-faint transition-transform duration-150 motion-reduce:transition-none', open && 'rotate-90') }), _jsx("span", { className: "min-w-0 truncate", children: node.props.title })] }), _jsx("div", { id: contentId, hidden: !open, className: "chat-ui-nodes flex flex-col gap-3 pt-1 pr-2 pb-2 pl-7.5", children: children })] }));
+}

package/dist/chat/ui/intelligent-ui/renderers/text.d.ts

@@ -0,0 +1,8 @@
+import type { UiProps } from '@adecore/intelligent-ui';
+import { type UiRendererProps } from '../render-context.js';
+export declare function SummaryRenderer({ node, children }: UiRendererProps<UiProps<'Summary'>>): import("react").JSX.Element;
+export declare function CalloutRenderer({ node, children }: UiRendererProps<UiProps<'Callout'>>): import("react").JSX.Element;
+export declare function TagRenderer({ node, children }: UiRendererProps<UiProps<'Tag'>>): import("react").JSX.Element;
+export declare function ProgressRenderer({ node, children, context }: UiRendererProps<UiProps<'Progress'>>): import("react").JSX.Element;
+export declare function StepsRenderer({ children }: UiRendererProps<UiProps<'Steps'>>): import("react").JSX.Element;
+export declare function StepRenderer({ node, children, context }: UiRendererProps<UiProps<'Step'>>): import("react").JSX.Element;

package/dist/chat/ui/intelligent-ui/renderers/text.js

@@ -0,0 +1,61 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useContext } from 'react';
+import clsx from 'clsx';
+import { useTranslation } from 'react-i18next';
+import { Circle, CircleCheck, CircleDot, CircleMinus, CircleX } from 'lucide-react';
+import { Icon, Meter, Pill, Spinner } from '@adecore/ui';
+import { formatNumber, formatPercent } from '@adecore/ui/format';
+import { UiHeadContext } from '../render-context.js';
+import { uiNodeLabel } from '../node-text.js';
+import { UI_TONE_ICONS, UI_TONE_PILL, UI_TONE_SURFACE, UI_TONE_TEXT } from '../tones.js';
+const STEP_ICONS = {
+    done: CircleCheck,
+    pending: Circle,
+    failed: CircleX,
+    skipped: CircleMinus
+};
+const STEP_TONES = {
+    done: 'text-status-idle',
+    running: 'text-accent',
+    pending: 'text-text-faint',
+    failed: 'text-status-error',
+    skipped: 'text-text-faint'
+};
+/* Whether the block still changes: while it streams, or while it reads live data. Only then does anything spin. */
+function isLive(context) {
+    return context.phase === 'streaming' || (context.live !== undefined && context.live !== null && context.live.state !== 'refused');
+}
+/* The head of the block when it is the first node, a subheading without an icon further down. */
+export function SummaryRenderer({ node, children }) {
+    const headId = useContext(UiHeadContext);
+    const head = headId === undefined || headId === node.id;
+    const { tone, badge } = node.props;
+    return (_jsxs("div", { className: "flex items-start gap-2 px-2", children: [head && tone !== undefined && _jsx(Icon, { icon: UI_TONE_ICONS[tone], size: 16, className: clsx('mt-0.75 shrink-0', UI_TONE_TEXT[tone]) }), _jsx("div", { className: "min-w-0 grow text-sm font-semibold text-balance text-text", children: children }), badge !== undefined && badge !== '' && (_jsx(Pill, { shape: "tag", tone: tone === undefined ? 'muted' : UI_TONE_PILL[tone], className: "shrink-0", children: badge }))] }));
+}
+export function CalloutRenderer({ node, children }) {
+    const { tone, title } = node.props;
+    return (_jsxs("div", { className: clsx('flex gap-2 rounded-md p-2 text-sm', UI_TONE_SURFACE[tone]), children: [_jsx(Icon, { icon: UI_TONE_ICONS[tone], size: 16, className: clsx('mt-0.75 shrink-0', UI_TONE_TEXT[tone]) }), _jsxs("div", { className: "min-w-0 grow", children: [title !== undefined && title !== '' && _jsx("div", { className: "font-medium text-text", children: title }), _jsx("div", { className: "text-text-muted", children: children })] })] }));
+}
+export function TagRenderer({ node, children }) {
+    const { tone } = node.props;
+    return (_jsx(Pill, { shape: "tag", size: "sm", tone: tone === undefined ? 'muted' : UI_TONE_PILL[tone], children: children }));
+}
+/* Without a value the progress is indeterminate; without a max the value is a percentage. */
+export function ProgressRenderer({ node, children, context }) {
+    const { t } = useTranslation('agent-chat');
+    const { value, max } = node.props;
+    const limit = max ?? 100;
+    const reading = value === undefined ? null : limit === 100 ? formatPercent(value) : t('blocks.progress.of', { value: formatNumber(value), max: formatNumber(limit) });
+    const label = uiNodeLabel(node);
+    return (_jsxs("div", { className: "flex flex-col gap-1 px-2", children: [_jsxs("div", { className: "flex items-baseline justify-between gap-3 text-xs", children: [_jsx("span", { className: "min-w-0 text-text", children: children }), reading !== null ? (_jsx("span", { className: "shrink-0 text-text-muted tabular-nums", children: reading })) : (isLive(context) && _jsx(Spinner, { size: 12, className: "shrink-0 self-center text-text-faint" }))] }), _jsx(Meter, { value: value ?? null, max: limit, label: label === '' ? t('blocks.progress.label') : label, valueText: reading ?? undefined })] }));
+}
+export function StepsRenderer({ children }) {
+    return _jsx("ol", { className: "chat-ui-nodes flex flex-col px-2", children: children });
+}
+/* A running step spins only while the block is live; in a quiet block it is a still dot. */
+export function StepRenderer({ node, children, context }) {
+    const { t } = useTranslation('agent-chat');
+    const { state, detail } = node.props;
+    const quiet = state === 'pending' || state === 'skipped';
+    return (_jsxs("li", { className: "flex min-h-7 items-center gap-2 text-sm", children: [_jsx("span", { className: clsx('grid size-4 shrink-0 place-items-center', STEP_TONES[state]), children: state === 'running' ? (isLive(context) ? (_jsx(Spinner, { size: 14 })) : (_jsx(Icon, { icon: CircleDot, size: 14 }))) : (_jsx(Icon, { icon: STEP_ICONS[state], size: 14 })) }), _jsx("span", { className: "sr-only", children: t(`blocks.step.${state}`) }), _jsx("span", { className: clsx('min-w-0 grow', quiet ? 'text-text-faint' : 'text-text'), children: children }), detail !== undefined && detail !== '' && _jsx("span", { className: "shrink-0 text-xs text-text-faint tabular-nums", children: detail })] }));
+}

package/dist/chat/ui/intelligent-ui/reply-parts.d.ts

@@ -0,0 +1,9 @@
+import type { UiBlock } from '@adecore/intelligent-ui';
+export type UiReplyPart = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'ui';
+    block: UiBlock;
+};
+export declare function uiReplyParts(text: string, blocks: readonly UiBlock[], streaming?: boolean): UiReplyPart[];

package/dist/chat/ui/intelligent-ui/reply-parts.js

@@ -0,0 +1,18 @@
+export function uiReplyParts(text, blocks, streaming = false) {
+    const parts = [];
+    let position = 0;
+    for (const block of [...blocks].sort((left, right) => left.start - right.start)) {
+        if (!Number.isInteger(block.start) || !Number.isInteger(block.end) || block.start < position || block.end < block.start || block.end > text.length) {
+            continue;
+        }
+        if (block.start > position) {
+            parts.push({ kind: 'text', text: text.slice(position, block.start) });
+        }
+        parts.push({ kind: 'ui', block });
+        position = streaming && !block.complete ? text.length : block.end;
+    }
+    if (position < text.length) {
+        parts.push({ kind: 'text', text: text.slice(position) });
+    }
+    return parts;
+}

package/dist/chat/ui/intelligent-ui/table-data.d.ts

@@ -0,0 +1,31 @@
+import type { UiProps, UiViewNode } from '@adecore/intelligent-ui';
+export type UiColumnKind = NonNullable<UiProps<'Column'>['as']>;
+export interface UiTableColumn {
+    key: string;
+    title: string;
+    unit?: string;
+    as: UiColumnKind;
+}
+export type UiTableCell = {
+    kind: 'empty';
+} | {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'number';
+    as: 'number' | 'bytes' | 'duration';
+    value: number;
+} | {
+    kind: 'date';
+    at: number;
+} | {
+    kind: 'file';
+    path: string;
+} | {
+    kind: 'tag';
+    text: string;
+};
+export declare const UI_TABLE_ROWS = 50;
+export declare function isNumericColumn(column: UiTableColumn): boolean;
+export declare function uiTableColumns(node: UiViewNode<UiProps<'Table'>>): UiTableColumn[];
+export declare function uiTableCell(value: unknown, column: UiTableColumn): UiTableCell;

package/dist/chat/ui/intelligent-ui/table-data.js

@@ -0,0 +1,79 @@
+import { uiChildrenOf } from './node-text.js';
+/* Rows shown before a person asks for all of them. */
+export const UI_TABLE_ROWS = 50;
+/* Columns a table without Column children takes from its rows. */
+const DERIVED_COLUMNS = 8;
+const NUMERIC_KINDS = new Set(['number', 'bytes', 'duration']);
+export function isNumericColumn(column) {
+    return NUMERIC_KINDS.has(column.as);
+}
+/*
+ * The columns a table can draw: its Column children whose key some row has, each key once. A table
+ * without columns takes the keys of its rows, as numbers when every value there is one. Empty when
+ * nothing is usable, which draws the fallback.
+ */
+export function uiTableColumns(node) {
+    const rows = node.props.rows;
+    const present = (key) => rows.some((row) => Object.hasOwn(row, key));
+    const declared = uiChildrenOf(node, 'Column');
+    if (declared.length > 0) {
+        const seen = new Set();
+        return declared.flatMap(({ props }) => {
+            if (seen.has(props.key) || (rows.length > 0 && !present(props.key))) {
+                return [];
+            }
+            seen.add(props.key);
+            return [{ key: props.key, title: props.title ?? props.key, unit: props.unit, as: props.as ?? 'text' }];
+        });
+    }
+    const keys = [];
+    for (const row of rows) {
+        for (const key of Object.keys(row)) {
+            if (!keys.includes(key) && keys.length < DERIVED_COLUMNS) {
+                keys.push(key);
+            }
+        }
+    }
+    return keys.map((key) => {
+        const values = rows.map((row) => row[key]).filter((value) => value !== undefined && value !== null);
+        const numeric = values.length > 0 && values.every((value) => typeof value === 'number' && Number.isFinite(value));
+        return { key, title: key, as: numeric ? 'number' : 'text' };
+    });
+}
+function textOf(value) {
+    return typeof value === 'object' ? JSON.stringify(value) : String(value);
+}
+function numberOf(value) {
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? value : null;
+    }
+    if (typeof value === 'string' && value.trim() !== '') {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+}
+/* A duration is in milliseconds and a date is milliseconds since the epoch or an ISO string; anything else reads as text. */
+export function uiTableCell(value, column) {
+    if (value === undefined || value === null || value === '') {
+        return { kind: 'empty' };
+    }
+    switch (column.as) {
+        case 'number':
+        case 'bytes':
+        case 'duration': {
+            const number = numberOf(value);
+            return number === null ? { kind: 'text', text: textOf(value) } : { kind: 'number', as: column.as, value: number };
+        }
+        case 'date': {
+            const at = typeof value === 'number' ? value : typeof value === 'string' ? Date.parse(value) : Number.NaN;
+            return Number.isFinite(at) ? { kind: 'date', at } : { kind: 'text', text: textOf(value) };
+        }
+        case 'file':
+            return typeof value === 'string' ? { kind: 'file', path: value } : { kind: 'text', text: textOf(value) };
+        case 'tag':
+            return { kind: 'tag', text: textOf(value) };
+        case 'text':
+            return { kind: 'text', text: textOf(value) };
+    }
+}

package/dist/chat/ui/intelligent-ui/tones.d.ts

@@ -0,0 +1,7 @@
+import { type LucideIcon } from 'lucide-react';
+import type { UiTone } from '@adecore/intelligent-ui';
+import type { PillProps } from '@adecore/ui';
+export declare const UI_TONE_ICONS: Readonly<Record<UiTone, LucideIcon>>;
+export declare const UI_TONE_TEXT: Readonly<Record<UiTone, string>>;
+export declare const UI_TONE_SURFACE: Readonly<Record<UiTone, string>>;
+export declare const UI_TONE_PILL: Readonly<Record<UiTone, NonNullable<PillProps['tone']>>>;

package/dist/chat/ui/intelligent-ui/tones.js

@@ -0,0 +1,31 @@
+import { CircleCheck, Info, MessageCircle, OctagonAlert, TriangleAlert } from 'lucide-react';
+/* Every tone has an icon of its own, so color is never the only thing that tells two apart. */
+export const UI_TONE_ICONS = {
+    neutral: MessageCircle,
+    info: Info,
+    success: CircleCheck,
+    warning: TriangleAlert,
+    danger: OctagonAlert
+};
+export const UI_TONE_TEXT = {
+    neutral: 'text-text-muted',
+    info: 'text-status-running',
+    success: 'text-positive',
+    warning: 'text-status-needs-you',
+    danger: 'text-status-error'
+};
+/* The tone mixed over the ground, for a surface such as a callout. */
+export const UI_TONE_SURFACE = {
+    neutral: 'bg-text/7',
+    info: 'bg-status-running/10',
+    success: 'bg-positive/10',
+    warning: 'bg-status-needs-you/12',
+    danger: 'bg-status-error/10'
+};
+export const UI_TONE_PILL = {
+    neutral: 'muted',
+    info: 'accent',
+    success: 'idle',
+    warning: 'needsYou',
+    danger: 'error'
+};

package/dist/chat/ui/intelligent-ui/use-later.d.ts

@@ -0,0 +1 @@
+export declare function useLater(on: boolean, ms: number): boolean;

package/dist/chat/ui/intelligent-ui/use-later.js

@@ -0,0 +1,16 @@
+import { useEffect, useState } from 'react';
+/* True once `on` has held for `ms`, for a spinner that only shows when waiting takes long. */
+export function useLater(on, ms) {
+    const [late, setLate] = useState(false);
+    useEffect(() => {
+        if (!on) {
+            return;
+        }
+        const timer = setTimeout(() => setLate(true), ms);
+        return () => {
+            clearTimeout(timer);
+            setLate(false);
+        };
+    }, [on, ms]);
+    return on && late;
+}

package/dist/chat/ui/intelligent-ui/use-ui-links.d.ts

@@ -0,0 +1,9 @@
+import type { ChatUiLinkReading, ChatUiQueryState } from '@adecore/agent-contracts';
+import { type UiLinkTarget } from '@adecore/intelligent-ui/links';
+import { type UiBlock, UiState } from '@adecore/intelligent-ui';
+import type { UiRenderContext } from './render-context.js';
+export declare function useUiLinks(block: UiBlock, state: UiState, context: Pick<UiRenderContext, 'scopeId' | 'chatId' | 'itemId' | 'phase'>, reads: Readonly<Record<string, string>>, frozen?: ChatUiQueryState['blocks'][string]): {
+    link: ((target: UiLinkTarget) => ChatUiLinkReading) | undefined;
+    openLink: ((target: UiLinkTarget) => void) | undefined;
+    openUrl: ((url: string) => void | undefined) | undefined;
+};

package/dist/chat/ui/intelligent-ui/use-ui-links.js

@@ -0,0 +1,126 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { uiLinkTargets } from '@adecore/intelligent-ui/links';
+import { uiInputValues, UI_HOST_LIMITS, UiState } from '@adecore/intelligent-ui';
+import { chatHost } from '../../../host.js';
+// Inputs that change in a run, such as a dragged slider, check their links once the run rested.
+const LINK_SETTLE_MS = 300;
+export function useUiLinks(block, state, context, reads, frozen) {
+    const [checked, setChecked] = useState({});
+    // What each node was last checked as, so a change of input checks only the targets it moved.
+    const asked = useRef(new Map());
+    const host = chatHost().intelligentUi;
+    const values = uiInputValues(block, state);
+    const scope = state.scope();
+    const queryValues = Object.fromEntries(Object.keys(block.queries)
+        .filter((name) => Object.hasOwn(scope, name))
+        .map((name) => [name, scope[name]]));
+    let targets = {};
+    try {
+        if (block.complete) {
+            targets = uiLinkTargets(block, values, queryValues);
+        }
+    }
+    catch { }
+    const signature = JSON.stringify(targets);
+    const input = JSON.stringify(values);
+    const tickets = JSON.stringify(reads);
+    const defaultInput = useMemo(() => JSON.stringify(uiInputValues(block, new UiState(block))), [block]);
+    const link = host?.link;
+    useEffect(() => {
+        asked.current.clear();
+    }, [block.id, block.revision, context.scopeId, context.chatId, context.itemId, link]);
+    useEffect(() => {
+        if (!link || !block.revision || context.phase !== 'final') {
+            return;
+        }
+        let stopped = false;
+        const validate = async () => {
+            const moved = Object.entries(JSON.parse(signature))
+                .slice(0, UI_HOST_LIMITS.links)
+                .filter(([nodeId, target]) => asked.current.get(nodeId) !== JSON.stringify(target));
+            for (const [nodeId, target] of moved) {
+                const record = (reading) => {
+                    asked.current.set(nodeId, JSON.stringify(target));
+                    setChecked((previous) => ({ ...previous, [nodeId]: { target: JSON.stringify(target), reading } }));
+                };
+                try {
+                    const reading = await link(context.scopeId, {
+                        chatId: context.chatId,
+                        itemId: context.itemId,
+                        blockId: block.id,
+                        revision: block.revision,
+                        nodeId,
+                        values: JSON.parse(input),
+                        reads: JSON.parse(tickets)
+                    });
+                    if (stopped) {
+                        return;
+                    }
+                    record(reading);
+                }
+                catch {
+                    if (stopped) {
+                        return;
+                    }
+                    record({ state: 'plain' });
+                }
+            }
+        };
+        // The first check runs at once; a later one waits until the inputs rested.
+        const timer = setTimeout(() => void validate(), asked.current.size === 0 ? 0 : LINK_SETTLE_MS);
+        return () => {
+            stopped = true;
+            clearTimeout(timer);
+        };
+    }, [block.id, block.revision, context.scopeId, context.chatId, context.itemId, context.phase, signature, input, tickets, link]);
+    const idOf = (target) => Object.entries(targets).find(([, entry]) => JSON.stringify(entry) === JSON.stringify(target))?.[0];
+    const resolution = (target) => {
+        const id = idOf(target);
+        if (id === undefined) {
+            return { state: 'plain' };
+        }
+        if (checked[id]?.target === JSON.stringify(target)) {
+            return checked[id].reading;
+        }
+        if (input === defaultInput && frozen && frozen.revision === block.revision) {
+            const firstQueries = Object.fromEntries(Object.entries(frozen.readings)
+                .filter(([, reading]) => reading.state === 'fresh')
+                .map(([name, reading]) => [name, reading.value]));
+            if (JSON.stringify(queryValues) === JSON.stringify(firstQueries)) {
+                return frozen.links?.[id] ?? { state: 'plain' };
+            }
+        }
+        return { state: 'plain' };
+    };
+    const open = (target) => {
+        const nodeId = idOf(target);
+        if (!nodeId || !link || !block.revision) {
+            return;
+        }
+        void link(context.scopeId, {
+            chatId: context.chatId,
+            itemId: context.itemId,
+            blockId: block.id,
+            revision: block.revision,
+            nodeId,
+            values,
+            reads: { ...reads }
+        })
+            .then((reading) => {
+            setChecked((previous) => ({ ...previous, [nodeId]: { target: JSON.stringify(target), reading } }));
+            if (reading.state === 'chip' && reading.target) {
+                host?.openLink?.(context.scopeId, reading);
+            }
+        })
+            .catch(() => {
+            setChecked((previous) => ({ ...previous, [nodeId]: { target: JSON.stringify(target), reading: { state: 'plain' } } }));
+        });
+    };
+    const hostOpenUrl = host?.openUrl;
+    const openUrl = useCallback((url) => hostOpenUrl?.(context.scopeId, url), [hostOpenUrl, context.scopeId]);
+    return {
+        link: link ? resolution : undefined,
+        openLink: link && host?.openLink ? open : undefined,
+        openUrl: hostOpenUrl ? openUrl : undefined
+    };
+}

package/dist/chat/ui/intelligent-ui/use-ui-queries.d.ts

@@ -0,0 +1,21 @@
+import type { ChatUiQueryReading, ChatUiQueryState } from '@adecore/agent-contracts';
+import { UiState, type UiBlock, type UiViewNode } from '@adecore/intelligent-ui';
+import type { UiLiveValue, UiLiveStatus, UiRenderContext } from './render-context.js';
+export declare function useUiQueries(block: UiBlock, state: UiState, context: Pick<UiRenderContext, 'scopeId' | 'chatId' | 'itemId' | 'phase'>, element: HTMLDivElement | null, frozen?: ChatUiQueryState['blocks'][string]): {
+    live: UiLiveStatus | undefined;
+    reads: Record<string, string>;
+    reading: boolean;
+    ready: boolean;
+    readsFor: (values: Readonly<Record<string, unknown>>) => Record<string, string> | null;
+    currentReadings: {
+        [k: string]: {
+            state: "failed" | "fresh" | "refused";
+            value?: unknown;
+            readId?: string | undefined;
+            readAt: number;
+            code?: string | undefined;
+            reason?: string | undefined;
+        };
+    };
+};
+export declare function useUiLiveValues(block: UiBlock, nodes: readonly UiViewNode[], readings: Readonly<Record<string, ChatUiQueryReading>>): ((id: string, prop: string, path?: readonly [number, string]) => UiLiveValue | undefined) | undefined;