@datalayer/agent-runtimes 1.5.88 → 1.5.89

package/lib/apps/plugins/agent-outputs/sheets.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The outputs agent's spreadsheets, drawn with Datalayer Cells — in the
+ * chat message itself, and wherever else the page shows them.
+ *
+ * A ```csv block in an answer (its first line `# filename: <name>.csv`) is
+ * a workbook: one model per block, read once and kept here, so the grid in
+ * the message and the one in a side panel are the same workbook. The message
+ * draws it read-only (a mirror that follows it), 240 px high, with a download
+ * button. {@link AgentOutputsSheetsPlugin} contributes that renderer to the
+ * chat's `ChatCodeBlock` point; {@link AgentOutputsSheetToolsPlugin} hands
+ * the Cells plugin's agent tools (the `cells` bundle) the last spreadsheet
+ * answered, so an agent asked to chart it inserts the chart into that
+ * workbook — and it appears on both grids.
+ *
+ * Kept out of the plugin's index, which the apps barrel re-exports: only a
+ * page that wants spreadsheets loads Cells.
+ *
+ * @module apps/plugins/agent-outputs/sheets
+ */
+import { type JSX } from 'react';
+import { type CellsModel } from '@datalayer/cells';
+import { type ChatCodeBlockProps } from '../../../chat/messages/codeBlocks';
+/** The fence languages a spreadsheet is written in. */
+export declare const SHEET_LANGUAGES: string[];
+/** A spreadsheet block: its file name, extension, and the rows' text. */
+export type SheetBlock = {
+    name: string;
+    extension: 'csv' | 'tsv';
+    /** The CSV or TSV itself, without the `# filename:` line. */
+    source: string;
+};
+/**
+ * The spreadsheet a fenced block holds, by its language or by a
+ * `# filename:` first line ending in .csv or .tsv; `null` for another block.
+ */
+export declare function parseSheetBlock(language: string, code: string): SheetBlock | null;
+/**
+ * The workbook of a spreadsheet block, read once: every grid showing the
+ * same block shows the same model. The block met last for the first time is
+ * the latest, which is the one the agent tools act on.
+ */
+export declare function sheetModel(block: SheetBlock): Promise<CellsModel>;
+/** The workbook of the last spreadsheet answered, once read. */
+export declare function latestSheetModel(): CellsModel | undefined;
+/** Forget every workbook (tests). */
+export declare function resetSheets(): void;
+/** A block's workbook, or the sentence why it could not be read. */
+export declare function useSheetModel(block: SheetBlock | null): {
+    model: CellsModel | null;
+    error: string;
+};
+/**
+ * A read-only copy of a workbook that follows it: the message's grid can
+ * neither be typed into nor lose the agent's chart.
+ */
+export declare function useReadOnlyMirror(model: CellsModel | null): CellsModel | null;
+/**
+ * The height that shows a workbook's active sheet whole — its data and its
+ * charts — between `min` and `max`, followed as the workbook changes: a chart
+ * the agent inserts below the data comes into view instead of sitting under
+ * a frame of fixed height (28 October 2026).
+ */
+export declare function useFitHeight(model: CellsModel | null, min?: number, max?: number): number;
+/** Save a block as its file. */
+export declare function downloadSheet(block: SheetBlock): void;
+/** A spreadsheet in a chat message: its grid, read-only, and a download button. */
+export declare function SheetCodeBlock({ language, code, }: ChatCodeBlockProps): JSX.Element;
+export declare const AGENT_OUTPUTS_SHEETS_PLUGIN_NAME = "@datalayer/loop-plugin-agent-outputs-sheets";
+/** A ```csv (or ```tsv) block of an answer, drawn as a Cells grid in the message. */
+export declare const AgentOutputsSheetsPlugin: import("@datalayer/reactor").ReactorPlugin<Record<string, never>, unknown, unknown>;
+/**
+ * The Cells agent tools (`cells_read_range`, `cells_insert_chart`, …) on the
+ * last spreadsheet answered. Its bundle id is `cells`, the frontend toolset
+ * the `example-output` spec names.
+ */
+export declare const AgentOutputsSheetToolsPlugin: import("@datalayer/reactor").ReactorPlugin<Record<string, never>, unknown, unknown>;

package/lib/apps/plugins/agent-outputs/sheets.js

@@ -0,0 +1,230 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The outputs agent's spreadsheets, drawn with Datalayer Cells — in the
+ * chat message itself, and wherever else the page shows them.
+ *
+ * A ```csv block in an answer (its first line `# filename: <name>.csv`) is
+ * a workbook: one model per block, read once and kept here, so the grid in
+ * the message and the one in a side panel are the same workbook. The message
+ * draws it read-only (a mirror that follows it), 240 px high, with a download
+ * button. {@link AgentOutputsSheetsPlugin} contributes that renderer to the
+ * chat's `ChatCodeBlock` point; {@link AgentOutputsSheetToolsPlugin} hands
+ * the Cells plugin's agent tools (the `cells` bundle) the last spreadsheet
+ * answered, so an agent asked to chart it inserts the chart into that
+ * workbook — and it appears on both grids.
+ *
+ * Kept out of the plugin's index, which the apps barrel re-exports: only a
+ * page that wants spreadsheets loads Cells.
+ *
+ * @module apps/plugins/agent-outputs/sheets
+ */
+import { useEffect, useState } from 'react';
+import { Button, Text } from '@primer/react';
+import { DownloadIcon } from '@primer/octicons-react';
+import { Box } from '@datalayer/primer-addons';
+import { contribution, definePlugin } from '@datalayer/reactor';
+import { CellsProvider, createCellsModel, Spreadsheet, } from '@datalayer/cells';
+import { CellsChartsPlugin } from '@datalayer/cells/charts';
+import { chartRect } from '@datalayer/cells/core';
+import { importCsv, usedZone } from '@datalayer/cells/csv';
+import { cellsAgentToolsPlugin } from '@datalayer/cells/plugin';
+import { ChatCodeBlock, } from '../../../chat/messages/codeBlocks.js';
+/** The fence languages a spreadsheet is written in. */
+export const SHEET_LANGUAGES = ['csv', 'tsv', 'spreadsheet', 'cells'];
+const FILENAME = /^#\s*filename:\s*([\w.-]+)\s*(?:\n|$)/i;
+/**
+ * The spreadsheet a fenced block holds, by its language or by a
+ * `# filename:` first line ending in .csv or .tsv; `null` for another block.
+ */
+export function parseSheetBlock(language, code) {
+    const text = code.replace(/^\s*\n/, '');
+    const named = FILENAME.exec(text)?.[1];
+    const byName = /\.(csv|tsv)$/i.exec(named ?? '')?.[1]?.toLowerCase();
+    if (!SHEET_LANGUAGES.includes(language) && byName === undefined) {
+        return null;
+    }
+    const extension = byName === 'tsv' || (byName === undefined && language === 'tsv')
+        ? 'tsv'
+        : 'csv';
+    const source = (named ? text.replace(FILENAME, '') : text).replace(/\s+$/, '');
+    if (source === '') {
+        return null;
+    }
+    return { name: named ?? `output.${extension}`, extension, source };
+}
+const MAX_SHEETS = 40;
+const sheets = new Map();
+const ready = new Map();
+let latestKey;
+const keyOf = (block) => `${block.name}\n${block.source}`;
+/**
+ * The workbook of a spreadsheet block, read once: every grid showing the
+ * same block shows the same model. The block met last for the first time is
+ * the latest, which is the one the agent tools act on.
+ */
+export function sheetModel(block) {
+    const key = keyOf(block);
+    const known = sheets.get(key);
+    if (known) {
+        return known;
+    }
+    latestKey = key;
+    const model = createCellsModel({ plugins: [CellsChartsPlugin] });
+    const read = importCsv(model, block.source, { worker: false }).then(() => {
+        ready.set(key, model);
+        return model;
+    });
+    sheets.set(key, read);
+    read.catch(() => sheets.delete(key));
+    // Streaming makes a block per chunk: the oldest go, never the latest.
+    for (const old of sheets.keys()) {
+        if (sheets.size <= MAX_SHEETS) {
+            break;
+        }
+        if (old !== latestKey) {
+            sheets.delete(old);
+            ready.delete(old);
+        }
+    }
+    return read;
+}
+/** The workbook of the last spreadsheet answered, once read. */
+export function latestSheetModel() {
+    return latestKey === undefined ? undefined : ready.get(latestKey);
+}
+/** Forget every workbook (tests). */
+export function resetSheets() {
+    sheets.clear();
+    ready.clear();
+    latestKey = undefined;
+}
+/** A block's workbook, or the sentence why it could not be read. */
+export function useSheetModel(block) {
+    const [state, setState] = useState({ model: null, error: '' });
+    const key = block ? keyOf(block) : '';
+    useEffect(() => {
+        if (!block) {
+            return;
+        }
+        let cancelled = false;
+        sheetModel(block)
+            .then(model => !cancelled && setState({ model, error: '' }))
+            .catch((e) => !cancelled &&
+            setState({
+                model: null,
+                error: e instanceof Error ? e.message : String(e),
+            }));
+        return () => {
+            cancelled = true;
+        };
+        // The block is its key.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [key]);
+    return state;
+}
+/**
+ * A read-only copy of a workbook that follows it: the message's grid can
+ * neither be typed into nor lose the agent's chart.
+ */
+export function useReadOnlyMirror(model) {
+    const [mirror, setMirror] = useState(null);
+    useEffect(() => {
+        if (!model) {
+            setMirror(null);
+            return;
+        }
+        const copy = createCellsModel({
+            readOnly: true,
+            plugins: [CellsChartsPlugin],
+        });
+        copy.replaceData(model.toJSON(), 'remote');
+        setMirror(copy);
+        return model.subscribe(() => copy.replaceData(model.toJSON(), 'remote'));
+    }, [model]);
+    return mirror;
+}
+/** The column header's height and a scrollbar's, in px, around the content. */
+const GRID_CHROME = 24 + 16;
+/**
+ * The height that shows a workbook's active sheet whole — its data and its
+ * charts — between `min` and `max`, followed as the workbook changes: a chart
+ * the agent inserts below the data comes into view instead of sitting under
+ * a frame of fixed height (28 October 2026).
+ */
+export function useFitHeight(model, min = 160, max = 560) {
+    const [height, setHeight] = useState(min);
+    useEffect(() => {
+        if (!model) {
+            return;
+        }
+        const measure = () => {
+            const sheet = model.sheet(model.selection.sheet);
+            let bottom = sheet.rows.offsetOf(usedZone(model, sheet.id).bottom + 1);
+            for (const spec of sheet.charts.values()) {
+                const rect = chartRect(sheet, spec);
+                bottom = Math.max(bottom, rect.y + rect.height);
+            }
+            setHeight(Math.min(max, Math.max(min, Math.ceil(bottom) + GRID_CHROME)));
+        };
+        measure();
+        return model.subscribe(measure);
+    }, [model, min, max]);
+    return height;
+}
+/** Save a block as its file. */
+export function downloadSheet(block) {
+    const type = block.extension === 'tsv' ? 'text/tab-separated-values' : 'text/csv';
+    const url = URL.createObjectURL(new Blob([block.source + '\n'], { type: `${type};charset=utf-8` }));
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = block.name;
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+    URL.revokeObjectURL(url);
+}
+/** A spreadsheet in a chat message: its grid, read-only, and a download button. */
+export function SheetCodeBlock({ language, code, }) {
+    const block = parseSheetBlock(language, code);
+    const { model, error } = useSheetModel(block);
+    const mirror = useReadOnlyMirror(model);
+    const height = useFitHeight(mirror);
+    if (!block) {
+        return _jsx(_Fragment, {});
+    }
+    return (
+    // The whole measure of the message (the chat gives it to what declares
+    // `width: 100%`), and wide enough for a few columns even in a bubble that
+    // hugs its text: a grid has no width of its own, and showed one column.
+    _jsxs(Box, { "data-sheet-block": block.name, my: 2, width: "100%", minWidth: "min(560px, 90vw)", children: [error ? (_jsxs(Text, { sx: { color: 'danger.fg', fontSize: 0 }, children: ["Could not read the spreadsheet: ", error] })) : mirror ? (_jsx(CellsProvider, { model: mirror, children: _jsx(Box, { height: height, border: "1px solid", borderColor: "border.muted", borderRadius: 2, overflow: "hidden", children: _jsx(Spreadsheet, { model: mirror, "aria-label": block.name }) }) })) : (_jsx(Text, { sx: { color: 'fg.muted', fontSize: 0 }, children: "Reading\u2026" })), _jsx(Box, { mt: 1, children: _jsxs(Button, { size: "small", variant: "invisible", leadingVisual: DownloadIcon, onClick: () => downloadSheet(block), children: ["Download ", block.name] }) })] }));
+}
+export const AGENT_OUTPUTS_SHEETS_PLUGIN_NAME = '@datalayer/loop-plugin-agent-outputs-sheets';
+/** A ```csv (or ```tsv) block of an answer, drawn as a Cells grid in the message. */
+export const AgentOutputsSheetsPlugin = definePlugin({
+    name: AGENT_OUTPUTS_SHEETS_PLUGIN_NAME,
+    displayName: 'Agent Outputs: spreadsheets',
+    description: 'A CSV the agent writes, drawn as a Datalayer Cells grid in the chat.',
+    octicon: 'table',
+    emoji: '🧮',
+    contributes: [
+        contribution(ChatCodeBlock, {
+            id: 'cells-sheet',
+            languages: SHEET_LANGUAGES,
+            match: block => parseSheetBlock(block.language, block.code) !== null,
+            Component: SheetCodeBlock,
+        }, { id: 'cells-sheet' }),
+    ],
+});
+/**
+ * The Cells agent tools (`cells_read_range`, `cells_insert_chart`, …) on the
+ * last spreadsheet answered. Its bundle id is `cells`, the frontend toolset
+ * the `example-output` spec names.
+ */
+export const AgentOutputsSheetToolsPlugin = cellsAgentToolsPlugin({
+    model: latestSheetModel,
+    name: '@datalayer/loop-plugin-agent-outputs-sheet-tools',
+});

package/lib/chat/messages/ChatMarkdown.d.ts

@@ -2,7 +2,9 @@
  * An agent's words, as markdown: what the chat's messages draw them with
  * (`ChatMessageList`), and what the floating assistant's balloon draws its
  * current line with — one renderer, so a code block, a table or a list
- * looks the same wherever the words are read.
+ * looks the same wherever the words are read. A fenced block whose language
+ * a plugin contributed a renderer for (`ChatCodeBlock`, a ```csv block drawn
+ * as a spreadsheet) is drawn by that renderer, in the message.
  *
  * @module chat/messages/ChatMarkdown
  */

package/lib/chat/messages/ChatMarkdown.js

@@ -4,6 +4,9 @@ import { Streamdown } from 'streamdown';
 import { REHYPE_PLUGINS_WITHOUT_HTML } from './markdownWithoutHtml.js';
 import { streamdownMarkdownStyles } from '../styles/streamdownStyles.js';
 import { normalizeAssistantMarkdown } from './assistantMarkdown.js';
+import { ChatCodePre } from './codeBlocks.js';
+/** The markdown elements the chat draws itself: a `pre` that hands its block to a contributed renderer. */
+const COMPONENTS = { pre: ChatCodePre };
 export function ChatMarkdown({ text, density = 'comfortable', }) {
     return (_jsx(Box, { "data-chat-markdown": "", sx: {
             ...streamdownMarkdownStyles,
@@ -14,6 +17,6 @@ export function ChatMarkdown({ text, density = 'comfortable', }) {
                     '& p:last-child': { marginBottom: 0 },
                 }
                 : {}),
-        }, children: _jsx(Streamdown, { rehypePlugins: REHYPE_PLUGINS_WITHOUT_HTML, children: normalizeAssistantMarkdown(text) }) }));
+        }, children: _jsx(Streamdown, { rehypePlugins: REHYPE_PLUGINS_WITHOUT_HTML, components: COMPONENTS, children: normalizeAssistantMarkdown(text) }) }));
 }
 export default ChatMarkdown;

package/lib/chat/messages/codeBlocks.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Fenced code blocks drawn by a plugin, in the agent's words.
+ *
+ * The chat draws an agent's answer as markdown (`ChatMarkdown`), and a
+ * fenced block as code. A plugin that knows better what a block of some
+ * language is — a ```csv block is a spreadsheet — contributes a renderer to
+ * {@link ChatCodeBlock}, and the block is drawn by it, in the message itself.
+ * Read from the Reactor platform the chat is mounted in, like the renderers
+ * of a tool call's display: a chat with no platform, or no renderer for the
+ * language, draws the block as code, as before.
+ *
+ * @module chat/messages/codeBlocks
+ */
+import { type ComponentType, type JSX, type ReactNode } from 'react';
+import { type Contribution } from '@datalayer/reactor';
+/** One fenced block of an answer: its info string's language, and its text. */
+export type ChatCodeBlockProps = {
+    /** The fence's language, lower-cased: `csv` for ```csv. Empty for a bare fence. */
+    language: string;
+    /** The block's text, as written between the fences. */
+    code: string;
+};
+/** A renderer of fenced blocks, contributed to {@link ChatCodeBlock}. */
+export type ChatCodeBlockContribution = {
+    /** Stable id, for the registry and the graph. */
+    id: string;
+    /** The fence languages it draws, lower-case: `['csv', 'tsv']`. */
+    languages: string[];
+    /** A finer test, on the block itself; the block is drawn as code when it says no. */
+    match?: (block: ChatCodeBlockProps) => boolean;
+    /** What draws the block, in place of the code. */
+    Component: ComponentType<ChatCodeBlockProps>;
+};
+/** Where plugins put their fenced-block renderers. The first that takes a block draws it. */
+export declare const ChatCodeBlock: import("@datalayer/reactor").ContributionPoint<ChatCodeBlockContribution>;
+/**
+ * The fenced block a `<pre>` holds, as markdown renders one: a `<code>`
+ * element whose class names the language. `null` for anything else.
+ */
+export declare function codeBlockOf(children: ReactNode): ChatCodeBlockProps | null;
+/** The renderer that takes a block, among the contributions, in their order. */
+export declare function codeBlockRenderer(contributions: readonly Contribution<ChatCodeBlockContribution>[], block: ChatCodeBlockProps): ChatCodeBlockContribution | undefined;
+/**
+ * The markdown `pre` the chat hands its renderer: a block a contribution
+ * takes is drawn by it, every other one exactly as the default `pre` draws
+ * it (its code element, unwrapped).
+ */
+export declare function ChatCodePre({ children, }: {
+    children?: ReactNode;
+}): JSX.Element;

package/lib/chat/messages/codeBlocks.js

@@ -0,0 +1,81 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Fenced code blocks drawn by a plugin, in the agent's words.
+ *
+ * The chat draws an agent's answer as markdown (`ChatMarkdown`), and a
+ * fenced block as code. A plugin that knows better what a block of some
+ * language is — a ```csv block is a spreadsheet — contributes a renderer to
+ * {@link ChatCodeBlock}, and the block is drawn by it, in the message itself.
+ * Read from the Reactor platform the chat is mounted in, like the renderers
+ * of a tool call's display: a chat with no platform, or no renderer for the
+ * language, draws the block as code, as before.
+ *
+ * @module chat/messages/codeBlocks
+ */
+import { isValidElement, useSyncExternalStore, } from 'react';
+import { defineContributionPoint } from '@datalayer/reactor';
+import { useOptionalReactorPlatform } from '@datalayer/reactor/react';
+/** Where plugins put their fenced-block renderers. The first that takes a block draws it. */
+export const ChatCodeBlock = defineContributionPoint('chat.codeBlock');
+const LANGUAGE = /(?:^|\s)language-([^\s]+)/;
+/** The text of a React node: strings and numbers, joined, through elements' children. */
+function textOf(node) {
+    if (typeof node === 'string' || typeof node === 'number') {
+        return String(node);
+    }
+    if (Array.isArray(node)) {
+        return node.map(textOf).join('');
+    }
+    if (isValidElement(node)) {
+        return textOf(node.props.children);
+    }
+    return '';
+}
+/**
+ * The fenced block a `<pre>` holds, as markdown renders one: a `<code>`
+ * element whose class names the language. `null` for anything else.
+ */
+export function codeBlockOf(children) {
+    const only = Array.isArray(children)
+        ? children.filter(child => child !== null && child !== '\n')
+        : [children];
+    if (only.length !== 1 || !isValidElement(only[0])) {
+        return null;
+    }
+    const props = only[0].props;
+    const language = LANGUAGE.exec(props.className ?? '')?.[1]?.toLowerCase();
+    if (language === undefined) {
+        return null;
+    }
+    return { language, code: textOf(props.children) };
+}
+/** The renderer that takes a block, among the contributions, in their order. */
+export function codeBlockRenderer(contributions, block) {
+    return contributions
+        .map(entry => entry.value)
+        .find(value => value.languages.includes(block.language) &&
+        (value.match ? value.match(block) : true));
+}
+const NO_SUBSCRIPTION = () => () => { };
+/**
+ * The markdown `pre` the chat hands its renderer: a block a contribution
+ * takes is drawn by it, every other one exactly as the default `pre` draws
+ * it (its code element, unwrapped).
+ */
+export function ChatCodePre({ children, }) {
+    const platform = useOptionalReactorPlatform();
+    useSyncExternalStore(platform?.subscribe ?? NO_SUBSCRIPTION, () => platform?.getRevision() ?? 0);
+    const block = platform ? codeBlockOf(children) : null;
+    const renderer = block
+        ? codeBlockRenderer(platform.getContributions(ChatCodeBlock), block)
+        : undefined;
+    if (block && renderer) {
+        const { Component } = renderer;
+        return (_jsx("div", { "data-chat-code-block": renderer.id, children: _jsx(Component, { language: block.language, code: block.code }) }));
+    }
+    return _jsx(_Fragment, { children: children });
+}

package/lib/examples/AgentOutputsExample.d.ts

@@ -14,6 +14,13 @@
  * We subscribe to the chat store, detect the output type of the latest
  * assistant message, auto-switch the sidebar tab, and render the payload
  * inline in the sidebar.
+ *
+ * A spreadsheet (a ```csv block) is also drawn in the chat message itself, by
+ * the `AgentOutputsSheetsPlugin` renderer the chat reads from its
+ * `ChatCodeBlock` point; the message's grid and the Sheet tab's are one
+ * workbook. The Cells agent tools (`AgentOutputsSheetToolsPlugin`, the
+ * `cells` bundle the spec's `frontend_tools` names) act on the last one, so
+ * "Chart the spreadsheet" inserts a chart that appears on both grids.
  */
 import React from 'react';
 declare const AgentOutputsExample: React.FC;

package/lib/examples/AgentOutputsExample.js

@@ -19,6 +19,13 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  * We subscribe to the chat store, detect the output type of the latest
  * assistant message, auto-switch the sidebar tab, and render the payload
  * inline in the sidebar.
+ *
+ * A spreadsheet (a ```csv block) is also drawn in the chat message itself, by
+ * the `AgentOutputsSheetsPlugin` renderer the chat reads from its
+ * `ChatCodeBlock` point; the message's grid and the Sheet tab's are one
+ * workbook. The Cells agent tools (`AgentOutputsSheetToolsPlugin`, the
+ * `cells` bundle the spec's `frontend_tools` names) act on the last one, so
+ * "Chart the spreadsheet" inserts a chart that appears on both grids.
  */
 /// <reference types="vite/client" />
 import { useEffect, useState, useRef, useMemo } from 'react';
@@ -26,15 +33,16 @@ import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 import { Text, Button, Heading, Label } from '@primer/react';
 import { TableIcon, FileIcon, CodeIcon, GraphIcon, DownloadIcon, } from '@primer/octicons-react';
 import { Box } from '@datalayer/primer-addons';
+import { CellsProvider, Spreadsheet } from '@datalayer/cells';
 import { AuthRequiredView } from './components/index.js';
 import { useSimpleAuthStore } from '@datalayer/core/lib/views/otel/index.js';
 import { ThemedProvider } from './utils/themedProvider.js';
 import { uniqueAgentId } from './utils/agentId.js';
 import { LoopEmbed } from '../apps/index.js';
-import { AgentOutputsPlugin } from '../apps/plugins/agent-outputs/index.js';
+import { downloadSheet, parseSheetBlock, useFitHeight, useSheetModel, } from '../apps/plugins/agent-outputs/sheets.js';
+import { AGENT_OUTPUTS_LOOP_PLUGINS } from './utils/agentOutputsPlugins.js';
 import { useChatStore } from '../stores/chatStore.js';
 import { useExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl.js';
-const LOOP_PLUGINS_AGENTOUT = [AgentOutputsPlugin];
 const queryClient = new QueryClient();
 // ─── Constants ─────────────────────────────────────────────────────────────
 const AGENT_NAME = 'outputs-example-agent';
@@ -57,8 +65,6 @@ const expandCompactMarkdownTable = (text) => {
     return text.replace(/\|\|/g, '|\n|');
 };
 const EXT_LIKE_INFOS = new Set([
-    'csv',
-    'tsv',
     'txt',
     'md',
     'markdown',
@@ -119,6 +125,20 @@ const detectOutput = (m) => {
         }
         // File: info string is a known extension OR first line declares a filename.
         const filenameMatch = firstLine.match(/^#\s*filename:\s*([\w.-]+)/i);
+        // Spreadsheet: a CSV or TSV, by its fence (`csv`, `tsv`, `spreadsheet`,
+        // `cells`) or a `# filename:` ending in .csv or .tsv — read as the chat's
+        // renderer reads it, so both grids show the same workbook.
+        const sheet = parseSheetBlock(info, rawBody);
+        if (sheet) {
+            return {
+                tab: 'sheet',
+                payload: sheet.source,
+                filename: sheet.name,
+                extension: sheet.extension,
+                sheet,
+                messageId: m.id,
+            };
+        }
         if (filenameMatch || EXT_LIKE_INFOS.has(info)) {
             const filename = filenameMatch?.[1] ?? (info ? `output.${info}` : 'output.txt');
             return {
@@ -257,6 +277,24 @@ const ChartView = ({ source }) => {
     }
     return (_jsx(ReactECharts, { option: option, style: { height: 280, width: '100%' } }));
 };
+// ─── Spreadsheet renderer (Datalayer Cells) ───────────────────────────────
+/**
+ * A CSV or TSV the agent wrote, in a Datalayer Cells grid: the workbook the
+ * chat message shows too (read once, on this thread), editable here, and
+ * where the agent's chart goes.
+ */
+const SheetView = ({ block }) => {
+    const { model, error } = useSheetModel(block);
+    // As tall as its data and charts (up to 640 px), so a chart the agent adds shows.
+    const height = useFitHeight(model, 200, 640);
+    if (error) {
+        return (_jsxs(Text, { sx: { color: 'danger.fg', fontSize: 0 }, children: ["Could not read the spreadsheet: ", error] }));
+    }
+    if (!model) {
+        return _jsx(Text, { sx: { color: 'fg.muted', fontSize: 0 }, children: "Reading\u2026" });
+    }
+    return (_jsx(CellsProvider, { model: model, children: _jsx(Box, { height: height, border: "1px solid", borderColor: "border.muted", children: _jsx(Spreadsheet, { model: model, "aria-label": block.name }) }) }));
+};
 // ─── Inner component (rendered after auth) ─────────────────────────────────
 const AgentOutputsInner = () => {
     // The Loop creates the agent from the plugin's blueprint when it connects;
@@ -312,10 +350,11 @@ const AgentOutputsInner = () => {
         document.body.removeChild(a);
         URL.revokeObjectURL(url);
     };
-    return (_jsxs(Box, { height: "100%", display: "flex", flexDirection: "column", children: [_jsxs(Box, { display: "flex", alignItems: "center", gap: 2, px: 3, py: 2, borderBottom: "1px solid", borderColor: "border.default", flexShrink: 0, children: [_jsx(TableIcon, { size: 16 }), _jsx(Heading, { as: "h3", sx: { fontSize: 2, flex: 1 }, children: "Agent Outputs \u2014 Local Runtime" })] }), _jsxs(Box, { flex: 1, minHeight: 0, display: "flex", children: [_jsx(Box, { flex: 1, minWidth: 0, children: _jsx(LoopEmbed, { serverUrl: agentBaseUrl, target: "local", showAgentVariants: true, agentId: agentName, editors: false, showHeader: true, plugins: LOOP_PLUGINS_AGENTOUT }) }), _jsxs(Box, { width: 420, borderLeft: "1px solid", borderColor: "border.default", display: "flex", flexDirection: "column", overflow: "hidden", children: [_jsx(Box, { display: "flex", borderBottom: "1px solid", borderColor: "border.default", flexShrink: 0, children: [
+    return (_jsxs(Box, { height: "100%", display: "flex", flexDirection: "column", children: [_jsxs(Box, { display: "flex", alignItems: "center", gap: 2, px: 3, py: 2, borderBottom: "1px solid", borderColor: "border.default", flexShrink: 0, children: [_jsx(TableIcon, { size: 16 }), _jsx(Heading, { as: "h3", sx: { fontSize: 2, flex: 1 }, children: "Agent Outputs \u2014 Local Runtime" })] }), _jsxs(Box, { flex: 1, minHeight: 0, display: "flex", children: [_jsx(Box, { flex: 1, minWidth: 0, children: _jsx(LoopEmbed, { serverUrl: agentBaseUrl, target: "local", showAgentVariants: true, agentId: agentName, editors: false, showHeader: true, plugins: AGENT_OUTPUTS_LOOP_PLUGINS }) }), _jsxs(Box, { width: 420, borderLeft: "1px solid", borderColor: "border.default", display: "flex", flexDirection: "column", overflow: "hidden", children: [_jsx(Box, { display: "flex", borderBottom: "1px solid", borderColor: "border.default", flexShrink: 0, children: [
                                     { key: 'table', icon: TableIcon, label: 'Table' },
                                     { key: 'json', icon: CodeIcon, label: 'JSON' },
                                     { key: 'chart', icon: GraphIcon, label: 'Chart' },
+                                    { key: 'sheet', icon: TableIcon, label: 'Sheet' },
                                     { key: 'files', icon: FileIcon, label: 'Files' },
                                 ].map(t => {
                                     const n = countByTab(t.key);
@@ -328,14 +367,15 @@ const AgentOutputsInner = () => {
                                             borderColor: activeTab === t.key ? 'accent.fg' : 'transparent',
                                             fontWeight: activeTab === t.key ? 'bold' : 'normal',
                                         }, children: [t.label, n > 0 ? ` (${n})` : ''] }, t.key));
-                                }) }), _jsxs(Box, { p: 3, flex: 1, overflow: "auto", children: [_jsxs(Heading, { as: "h4", sx: { fontSize: 1, mb: 2 }, children: [activeTab.charAt(0).toUpperCase() + activeTab.slice(1), " outputs"] }), filtered.length === 0 ? (_jsxs(Text, { sx: { color: 'fg.muted', fontSize: 0 }, children: ["No ", activeTab, " outputs yet. Use one of the openers in the chat to produce one \u2014 the side panel will switch to the matching tab automatically."] })) : (filtered.map((d, idx) => (_jsxs(Box, { p: 2, mb: 2, border: "1px solid", borderColor: "border.default", borderRadius: 2, children: [_jsxs(Box, { display: "flex", justifyContent: "space-between", alignItems: "center", mb: 2, gap: 2, children: [_jsx(Text, { sx: { fontSize: 1, fontWeight: 'bold' }, children: d.filename ?? `${d.tab} output` }), _jsx(Label, { size: "small", variant: "secondary", children: d.tab })] }), d.tab === 'table' && _jsx(MarkdownTable, { source: d.payload }), d.tab === 'json' && (_jsx(Box, { as: "pre", bg: "canvas.default", p: 2, borderRadius: 2, fontFamily: "mono", fontSize: 0, maxHeight: 320, overflow: "auto", whiteSpace: "pre-wrap", m: 0, children: (() => {
+                                }) }), _jsxs(Box, { p: 3, flex: 1, overflow: "auto", children: [_jsxs(Heading, { as: "h4", sx: { fontSize: 1, mb: 2 }, children: [activeTab.charAt(0).toUpperCase() + activeTab.slice(1), " outputs"] }), filtered.length === 0 ? (_jsxs(Text, { sx: { color: 'fg.muted', fontSize: 0 }, children: ["No ", activeTab, " outputs yet. Use one of the openers in the chat to produce one \u2014 the side panel will switch to the matching tab automatically.", activeTab === 'sheet' &&
+                                                ' For a spreadsheet, ask for the data as CSV, for example: "Give me twelve months of sales by region as a CSV".'] })) : (filtered.map((d, idx) => (_jsxs(Box, { p: 2, mb: 2, border: "1px solid", borderColor: "border.default", borderRadius: 2, children: [_jsxs(Box, { display: "flex", justifyContent: "space-between", alignItems: "center", mb: 2, gap: 2, children: [_jsx(Text, { sx: { fontSize: 1, fontWeight: 'bold' }, children: d.filename ?? `${d.tab} output` }), _jsx(Label, { size: "small", variant: "secondary", children: d.tab })] }), d.tab === 'table' && _jsx(MarkdownTable, { source: d.payload }), d.tab === 'json' && (_jsx(Box, { as: "pre", bg: "canvas.default", p: 2, borderRadius: 2, fontFamily: "mono", fontSize: 0, maxHeight: 320, overflow: "auto", whiteSpace: "pre-wrap", m: 0, children: (() => {
                                                     try {
                                                         return JSON.stringify(JSON.parse(d.payload), null, 2);
                                                     }
                                                     catch {
                                                         return d.payload;
                                                     }
-                                                })() })), d.tab === 'chart' && _jsx(ChartView, { source: d.payload }), d.tab === 'files' && (_jsxs(_Fragment, { children: [_jsx(Box, { as: "pre", bg: "canvas.default", p: 2, borderRadius: 2, fontFamily: "mono", fontSize: 0, maxHeight: 200, overflow: "auto", whiteSpace: "pre-wrap", m: 0, mb: 2, children: d.payload }), _jsxs(Button, { size: "small", leadingVisual: DownloadIcon, onClick: () => download(d), children: ["Download ", d.filename ?? 'file'] })] }))] }, d.messageId + ':' + idx))))] })] })] })] }));
+                                                })() })), d.tab === 'chart' && _jsx(ChartView, { source: d.payload }), d.tab === 'sheet' && d.sheet && (_jsxs(_Fragment, { children: [_jsx(SheetView, { block: d.sheet }), _jsx(Box, { mt: 2, children: _jsxs(Button, { size: "small", leadingVisual: DownloadIcon, onClick: () => downloadSheet(d.sheet), children: ["Download ", d.filename ?? 'spreadsheet'] }) })] })), d.tab === 'files' && (_jsxs(_Fragment, { children: [_jsx(Box, { as: "pre", bg: "canvas.default", p: 2, borderRadius: 2, fontFamily: "mono", fontSize: 0, maxHeight: 200, overflow: "auto", whiteSpace: "pre-wrap", m: 0, mb: 2, children: d.payload }), _jsxs(Button, { size: "small", leadingVisual: DownloadIcon, onClick: () => download(d), children: ["Download ", d.filename ?? 'file'] })] }))] }, d.messageId + ':' + idx))))] })] })] })] }));
 };
 // ─── Sync token to core IAM store ──────────────────────────────────────────
 const syncTokenToIamStore = (token) => {

package/lib/examples/utils/agentOutputsPlugins.d.ts

@@ -0,0 +1,2 @@
+/** The Loop's plugins on the outputs page: the agent, the chat's grids, the grid's tools. */
+export declare const AGENT_OUTPUTS_LOOP_PLUGINS: import("@datalayer/reactor").ReactorPlugin<Record<string, never>, unknown, unknown>[];

package/lib/examples/utils/agentOutputsPlugins.js

@@ -0,0 +1,27 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The Loop plugins of the outputs example (`AgentOutputsExample`): the
+ * `example-output` agent, the chat's spreadsheet renderer, and the Cells
+ * agent tools on the last spreadsheet answered. The agent runs on a server,
+ * so the page names the bundle whose tools it hands it — `cells`, the grid's
+ * tools, run on this page's reactor — through the chat extras.
+ *
+ * Apart from the page, so a test reads the list without mounting the Loop.
+ *
+ * @module examples/utils/agentOutputsPlugins
+ */
+import { AgentOutputsPlugin } from '../../apps/plugins/agent-outputs/index.js';
+import { AgentOutputsSheetsPlugin, AgentOutputsSheetToolsPlugin, } from '../../apps/plugins/agent-outputs/sheets.js';
+import { createChatExtrasPlugin } from '../../apps/plugins/chat-extras/index.js';
+const SHEET_EXTRAS = createChatExtrasPlugin();
+SHEET_EXTRAS.setExtras({ agentToolBundles: ['cells'] });
+/** The Loop's plugins on the outputs page: the agent, the chat's grids, the grid's tools. */
+export const AGENT_OUTPUTS_LOOP_PLUGINS = [
+    AgentOutputsPlugin,
+    AgentOutputsSheetsPlugin,
+    AgentOutputsSheetToolsPlugin,
+    SHEET_EXTRAS.plugin,
+];