@datalayer/agent-runtimes 1.3.103 → 1.3.104

package/lib/apps/apps/AppBrowserSandbox.d.ts

@@ -0,0 +1,7 @@
+import type { AppSpec } from '../../types/agentspecs';
+export declare const APP_BROWSER_SANDBOX_PLUGIN_NAME = "@datalayer/loop-plugin-app-browser-sandbox";
+/**
+ * The plugin, for one application. Made once per application — a new plugin
+ * rebuilds the workspace.
+ */
+export declare function defineAppBrowserSandboxPlugin(app: Pick<AppSpec, 'id' | 'name' | 'samples'>): import("@datalayer/reactor").ReactorPlugin<Record<string, never>, unknown, unknown>;

package/lib/apps/apps/AppBrowserSandbox.js

@@ -0,0 +1,52 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * An application's code in the page's sandbox (STUDIO E-11): the tool its
+ * agent runs its code with when it turns in the page — `execute_code`,
+ * Python in this browser — and its documents put there before its first run
+ * (`browserSandbox`).
+ *
+ * Handed to the agent only while the sandbox is the browser's: on a runtime
+ * the agent has a sandbox of its own, and a tool of the page would be a
+ * second one beside it. `AppRenderer` adds the plugin for an application
+ * whose agent computes in code (`runsCodeInSandbox`).
+ *
+ * @module apps/apps/AppBrowserSandbox
+ */
+import { definePlugin } from '@datalayer/reactor';
+import { LoopFrontendTool } from '../core';
+import { AGENTS_PLUGIN_NAME, AgentsPlugin, } from '../plugins/agents';
+import { browserCodeTool } from './browserSandbox';
+export const APP_BROWSER_SANDBOX_PLUGIN_NAME = '@datalayer/loop-plugin-app-browser-sandbox';
+/**
+ * The plugin, for one application. Made once per application — a new plugin
+ * rebuilds the workspace.
+ */
+export function defineAppBrowserSandboxPlugin(app) {
+    return definePlugin({
+        name: `${APP_BROWSER_SANDBOX_PLUGIN_NAME}-${app.id}`,
+        displayName: `${app.name}: its code in the browser`,
+        description: `What ${app.name} computes, run in Python in this browser when it turns in the page.`,
+        octicon: 'code',
+        emoji: '\u{1F40D}',
+        // The sandbox is the Agents plugin's: built first, read here.
+        dependencies: [AgentsPlugin],
+        register({ contribute, reactor }) {
+            const sandbox = reactor.getOutput(AGENTS_PLUGIN_NAME)?.sandbox;
+            if (!sandbox) {
+                return;
+            }
+            // One tool for the life of the workspace: its documents are put in the
+            // kernel once, before its first run.
+            const tool = browserCodeTool(app, code => sandbox.execute(code));
+            return contribute(LoopFrontendTool, {
+                id: `app-browser-sandbox-${app.id}`,
+                tools: workspace => workspace.sandbox.target === 'browser' ? [tool] : [],
+                // It changes no editor: kept in the chat view and beside a page.
+                chatView: true,
+            }, { id: `app-browser-sandbox-${app.id}` });
+        },
+    });
+}

package/lib/apps/apps/AppRenderer.js

@@ -74,6 +74,8 @@ import { defineAppRuntimePlugin } from './AppRuntimePlugins';
 import { hasFolderModules } from './customComponents';
 import { appPluginPair } from './pluginPair';
 import { visitorAgentOf } from './visitorToken';
+import { defineAppBrowserSandboxPlugin } from './AppBrowserSandbox';
+import { browserSandboxNote, runsCodeInSandbox } from './browserSandbox';
 /** The id of an agent or a Cog, without its version. */
 export const agentIdOf = (app) => {
     const reference = app.agent || app.team;
@@ -127,8 +129,12 @@ export function defineAppPlugin(app, shown = app) {
         suggestions: startersAsOpeners(shown.interface.starters),
         // In the page, the agent is told what a runtime tells it: its own
         // spec's prompt, then the application's instructions; on the
-        // application's model when it names one (`apps/apps/agent`).
-        instructions: app.instructions,
+        // application's model when it names one (`apps/apps/agent`). An agent
+        // that computes in code is told where its code runs there, and where its
+        // documents are (STUDIO E-11, `browserSandbox`).
+        instructions: runsCodeInSandbox(app)
+            ? [app.instructions, browserSandboxNote(app)].filter(Boolean).join('\n\n')
+            : app.instructions,
         model: app.model,
         // Its modes and its profiles (LOOP P-19, P-20), as the session API
         // applies them: the profile's instructions and those of the options
@@ -238,6 +244,9 @@ export function appPreset(app, options = {}) {
             // page side read from it when its components are files of its folder
             // (P-29).
             defineAppRuntimePlugin(app.id, { pageSide: hasFolderModules(app) }),
+            // Its code in the browser's sandbox, when it turns in the page and
+            // computes in code (STUDIO E-11): `execute_code`, its documents there.
+            ...(runsCodeInSandbox(app) ? [defineAppBrowserSandboxPlugin(app)] : []),
             ...(withPage ? [defineAppPagePlugin(shown), ...blocks] : []),
             // The components its developer wrote (LOOP P-17): blocks of its page
             // and renderers of its page, its elements and its answers — its own.

package/lib/apps/apps/appspec.js

@@ -150,6 +150,7 @@ export function emptyAppspec(kind = 'chat') {
         triggers: [],
         memory: '',
         notifications: [],
+        samples: { documents: [], alternatives: [] },
         setup: [],
         enabled: true,
         unavailable_because: '',
@@ -191,6 +192,7 @@ const KNOWN_KEYS = [
     'memory',
     'notifications',
     'decision',
+    'samples',
     'enabled',
     'unavailable_because',
     'tags',
@@ -542,6 +544,21 @@ function parseDecision(data) {
         decisionModel: text(data.decision_model),
     };
 }
+/** What it is tried on before it is anybody's (STUDIO E-06, E-11): read only. */
+function parseSamples(data) {
+    return {
+        documents: records(data.documents).map(document => ({
+            name: text(document.name),
+            file: text(document.file),
+            text: text(document.text),
+        })),
+        alternatives: records(data.alternatives).map(alternative => ({
+            name: text(alternative.name),
+            evidence: text(alternative.evidence),
+            metrics: Object.fromEntries(Object.entries(isData(alternative.metrics) ? alternative.metrics : {}).filter((entry) => typeof entry[1] === 'number')),
+        })),
+    };
+}
 function parseDeployment(data) {
     const deployment = {};
     if (isData(data.hosted)) {
@@ -707,6 +724,7 @@ export function parseAppspec(document) {
         triggers: records(data.triggers).map(parseTrigger),
         memory: text(data.memory),
         notifications: texts(data.notifications),
+        samples: parseSamples(isData(data.samples) ? data.samples : {}),
         enabled: flag(data.enabled, true),
         unavailable_because: text(data.unavailable_because),
         tags: texts(data.tags),
@@ -915,6 +933,18 @@ function dumpDecision(decision) {
         .part('weights', sorted(scenario.weights)).data))
         .text('decision_model', decision.decisionModel).data;
 }
+function dumpSamples(samples) {
+    return new Writer()
+        .list('documents', samples.documents.map(document => new Writer()
+        .text('name', document.name, '\u0000')
+        .text('file', document.file, '\u0000')
+        .text('text', document.text, '\u0000').data))
+        .list('alternatives', samples.alternatives.map(alternative => new Writer()
+        .text('name', alternative.name, '\u0000')
+        .text('evidence', alternative.evidence, '\u0000')
+        // By criterion name, as written: the spec keeps their order.
+        .part('metrics', { ...alternative.metrics }).data)).data;
+}
 /**
  * An application as the document its file holds.
  *
@@ -1037,6 +1067,7 @@ export function dumpAppspec(app) {
         writer.data.decision = dumpDecision(app.decision);
     }
     writer
+        .part('samples', dumpSamples(app.samples))
         .value('enabled', app.enabled, true)
         .text('unavailable_because', app.unavailable_because)
         .list('tags', app.tags)

package/lib/apps/apps/browserSandbox.d.ts

@@ -0,0 +1,69 @@
+/**
+ * An application's code, run in the page (STUDIO E-11).
+ *
+ * On a runtime, an application's agent runs its code in a sandbox of the
+ * runtime's, through `execute_code` — what *Quote Calculator* and *Report
+ * from a File* compute with. Turned in the page, the same agent has the
+ * page's sandbox instead: Python in this browser (Pyodide), the one the
+ * Browser target starts. Nothing of the code runs on Datalayer, and nothing
+ * it writes leaves the browser.
+ *
+ * What it computes from is put there as files, under {@link SANDBOX_INPUTS}:
+ * the documents Datalayer publishes with the application (`samples`, read
+ * only) before its first run, and the files given on its page with the
+ * message that runs on them — which the page used to refuse, having no
+ * session to hand them to.
+ *
+ * Pure: no React, no kernel. The tool that runs it is
+ * `AppBrowserSandboxPlugin`'s.
+ *
+ * @module apps/apps/browserSandbox
+ */
+import type { AppSpec } from '../../types/agentspecs';
+import type { FrontendToolDefinition } from '../../types/tools';
+import type { SandboxExecution } from '../plugins/agents/service';
+/** The tool the agent runs its code with: the name a runtime gives it too. */
+export declare const BROWSER_CODE_TOOL = "execute_code";
+/** Where its files are, in the page's sandbox: in memory, gone with the page. */
+export declare const SANDBOX_INPUTS = "/tmp/inputs";
+/** A file for the sandbox: its name there, and what it holds, in base64. */
+export type SandboxFile = {
+    file: string;
+    base64: string;
+};
+/**
+ * Whether an application's agent runs code: its agent has a sandbox, as every
+ * agent a runtime gives `execute_code` has.
+ */
+export declare function runsCodeInSandbox(app: Pick<AppSpec, 'agent'>): boolean;
+/** Where a file is, in the page's sandbox. */
+export declare const sandboxPath: (file: string) => string;
+/**
+ * A file's name as the sandbox is given it: its own, without a folder, and
+ * only the characters a path says plainly.
+ */
+export declare function sandboxFileName(name: string): string;
+/** UTF-8 text as base64, as the sandbox is given it. */
+export declare function textAsBase64(text: string): string;
+/** The base64 of a `data:` URL, as a page's file is given — or why it has none. */
+export declare function dataUrlBase64(dataUrl: string): string;
+/** The documents Datalayer publishes with the application, as files. */
+export declare function sampleFiles(app: Pick<AppSpec, 'samples'>): SandboxFile[];
+/** The Python that writes files into the sandbox. */
+export declare function writeFilesCode(files: SandboxFile[]): string;
+/**
+ * What the agent is told in the page, after its own prompt and the
+ * application's instructions: where its code runs, and where its documents
+ * are.
+ */
+export declare function browserSandboxNote(app: Pick<AppSpec, 'samples'>): string;
+/** What the message that runs on given files says of them. */
+export declare function givenFilesSentence(files: string[]): string;
+/** What the model reads of an execution: what it printed, what it returned, what failed. */
+export declare function executionForModel(execution: SandboxExecution): Record<string, unknown>;
+/**
+ * The tool an application's agent runs its code with, in the page: Python
+ * in the browser's sandbox, its documents written there before the first
+ * call.
+ */
+export declare function browserCodeTool(app: Pick<AppSpec, 'samples'>, execute: (code: string) => Promise<SandboxExecution>): FrontendToolDefinition;

package/lib/apps/apps/browserSandbox.js

@@ -0,0 +1,159 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { resolveAgentspec } from './agent';
+/** The tool the agent runs its code with: the name a runtime gives it too. */
+export const BROWSER_CODE_TOOL = 'execute_code';
+/** Where its files are, in the page's sandbox: in memory, gone with the page. */
+export const SANDBOX_INPUTS = '/tmp/inputs';
+/**
+ * Whether an application's agent runs code: its agent has a sandbox, as every
+ * agent a runtime gives `execute_code` has.
+ */
+export function runsCodeInSandbox(app) {
+    return Boolean(app.agent && resolveAgentspec(app.agent)?.sandboxVariant);
+}
+/** Where a file is, in the page's sandbox. */
+export const sandboxPath = (file) => `${SANDBOX_INPUTS}/${file}`;
+/**
+ * A file's name as the sandbox is given it: its own, without a folder, and
+ * only the characters a path says plainly.
+ */
+export function sandboxFileName(name) {
+    const base = name.split(/[\\/]/).pop() ?? '';
+    const plain = base.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^[.-]+/, '');
+    return plain || 'file';
+}
+/** UTF-8 text as base64, as the sandbox is given it. */
+export function textAsBase64(text) {
+    const bytes = new TextEncoder().encode(text);
+    let binary = '';
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary);
+}
+/** The base64 of a `data:` URL, as a page's file is given — or why it has none. */
+export function dataUrlBase64(dataUrl) {
+    const at = dataUrl.indexOf(',');
+    if (!dataUrl.startsWith('data:') ||
+        at < 0 ||
+        !/;base64$/.test(dataUrl.slice(0, at))) {
+        throw new Error('A file given on the page is not a base64 data URL.');
+    }
+    return dataUrl.slice(at + 1);
+}
+/** The documents Datalayer publishes with the application, as files. */
+export function sampleFiles(app) {
+    return (app.samples?.documents ?? []).map(document => ({
+        file: document.file,
+        base64: textAsBase64(document.text),
+    }));
+}
+/** The Python that writes files into the sandbox. */
+export function writeFilesCode(files) {
+    const entries = files
+        .map(({ file, base64 }) => `    (${JSON.stringify(file)}, ${JSON.stringify(base64)}),`)
+        .join('\n');
+    return [
+        'import base64 as _b64, pathlib as _pl',
+        `_inputs = _pl.Path(${JSON.stringify(SANDBOX_INPUTS)})`,
+        '_inputs.mkdir(parents=True, exist_ok=True)',
+        'for _name, _data in [',
+        entries,
+        ']:',
+        '    (_inputs / _name).write_bytes(_b64.b64decode(_data))',
+        'del _b64, _pl, _inputs',
+    ].join('\n');
+}
+/**
+ * What the agent is told in the page, after its own prompt and the
+ * application's instructions: where its code runs, and where its documents
+ * are.
+ */
+export function browserSandboxNote(app) {
+    const documents = app.samples?.documents ?? [];
+    return [
+        `Your code runs in Python (Pyodide) in this browser, through \`${BROWSER_CODE_TOOL}\`. ` +
+            'Variables and imports persist between calls. Compute every figure there, ' +
+            'print it, and answer from what it printed.',
+        ...(documents.length > 0
+            ? [
+                'The documents you answer from are files there, read only: ' +
+                    documents
+                        .map(document => `${document.name} at \`${sandboxPath(document.file)}\``)
+                        .join('; ') +
+                    '. Read them in code before you answer.',
+            ]
+            : []),
+        `A file given on the page is put in \`${SANDBOX_INPUTS}\` too: the message that runs on it names it.`,
+    ].join('\n\n');
+}
+/** What the message that runs on given files says of them. */
+export function givenFilesSentence(files) {
+    return `The files given are in the sandbox: ${files.map(file => `\`${sandboxPath(file)}\``).join(', ')}.`;
+}
+/** What the model reads of an execution: what it printed, what it returned, what failed. */
+export function executionForModel(execution) {
+    const results = (execution.outputs ?? []).flatMap(output => {
+        const data = output ??
+            {};
+        if (data.output_type !== 'execute_result' &&
+            data.output_type !== 'display_data') {
+            return [];
+        }
+        const plain = data.data?.['text/plain'];
+        return typeof plain === 'string' ? [plain] : [];
+    });
+    return {
+        success: execution.success,
+        ...(execution.stdout ? { stdout: execution.stdout } : {}),
+        ...(results.length > 0 ? { results } : {}),
+        ...(execution.error ? { error: execution.error } : {}),
+    };
+}
+/**
+ * The tool an application's agent runs its code with, in the page: Python
+ * in the browser's sandbox, its documents written there before the first
+ * call.
+ */
+export function browserCodeTool(app, execute) {
+    let seeded = null;
+    const seed = () => {
+        const files = sampleFiles(app);
+        seeded =
+            seeded ??
+                (files.length === 0
+                    ? Promise.resolve()
+                    : execute(writeFilesCode(files)).then(written => {
+                        if (!written.success) {
+                            seeded = null;
+                            throw new Error(`The application's documents could not be put in the sandbox: ${written.error ?? 'it failed'}.`);
+                        }
+                    }));
+        return seeded;
+    };
+    return {
+        name: BROWSER_CODE_TOOL,
+        description: 'Run Python in the sandbox, in this browser (Pyodide). Variables and imports ' +
+            `persist between calls. The application's documents and the files given on ` +
+            `its page are under ${SANDBOX_INPUTS}. Returns what it printed, what it ` +
+            'returned and any error.',
+        parameters: {
+            type: 'object',
+            properties: {
+                code: { type: 'string', description: 'The Python to run.' },
+            },
+            required: ['code'],
+        },
+        handler: async (args) => {
+            const code = typeof args?.code === 'string' ? args.code : '';
+            if (!code.trim()) {
+                return { success: false, error: 'No code was given to run.' };
+            }
+            await seed();
+            return executionForModel(await execute(code));
+        },
+    };
+}

package/lib/apps/apps/index.d.ts

@@ -4,11 +4,13 @@
  * @module apps/apps
  */
 export * from './agent';
+export * from './AppBrowserSandbox';
 export * from './AppComposer';
 export * from './AppFeedback';
 export * from './AppKept';
 export * from './AppRenderer';
 export * from './appspec';
+export * from './browserSandbox';
 export * from './checks';
 export * from './composer';
 export * from './computer';

package/lib/apps/apps/index.js

@@ -8,11 +8,13 @@
  * @module apps/apps
  */
 export * from './agent';
+export * from './AppBrowserSandbox';
 export * from './AppComposer';
 export * from './AppFeedback';
 export * from './AppKept';
 export * from './AppRenderer';
 export * from './appspec';
+export * from './browserSandbox';
 export * from './checks';
 export * from './composer';
 export * from './computer';

package/lib/apps/plugins/chat/ChatView.js

@@ -37,7 +37,8 @@ import { INPUT_PROMPT_PLUGIN_NAME, } from '../input-prompt';
 import { agentRuntimeStore, useAgentRuntimeContextSnapshot, } from '../../../stores';
 import { useIAMStore } from '../../../state';
 import { useVisitorToken } from '../../apps/visitorToken';
-import { AGENTS_PLUGIN_NAME } from '../agents/plugin';
+import { AGENTS_PLUGIN_NAME, } from '../agents/plugin';
+import { BROWSER_CODE_TOOL, dataUrlBase64, givenFilesSentence, sandboxFileName, writeFilesCode, } from '../../apps/browserSandbox';
 import { useConfig } from '../../../hooks/useConfig';
 import { useSkills, useSkillActions } from '../../../hooks/useSkills';
 import { AI_MODEL_CATALOGUE, isChatModel } from '../../../specs/models';
@@ -357,6 +358,18 @@ export default function ChatView({ workspace }) {
     const heldForAdapter = useRef([]);
     /** Whether the agent is turned in this page: read by `sendNow`, set below. */
     const inPageRef = useRef(false);
+    /**
+     * The page's sandbox, when the agent turned in the page runs its code
+     * there (`execute_code`, STUDIO E-11): what a file given on the page is
+     * put in. Read by `sendNow`, set below.
+     */
+    const pageSandboxRef = useRef(undefined);
+    /**
+     * Why its host closed the conversation (`ChatAvailabilityProvider`), or
+     * nothing: a page's own send is refused with it as the composer is — a
+     * stopped deployment, a visitor's turns all taken. Set below.
+     */
+    const hostClosedRef = useRef(undefined);
     /** What goes with every run (an application's modes, LOOP P-19), read when it is sent. */
     const runProps = useContributions(LoopRunProps);
     const runPropsRef = useRef(runProps);
@@ -369,18 +382,49 @@ export default function ChatView({ workspace }) {
      *
      * What the page did besides the message goes with it as AG-UI's
      * `forwardedProps` (`loop`, LOOP R-04): the application's session takes a
-     * file there. An agent turned in this page has no session, and no file is
-     * handed to it: said, rather than dropped. What the workspace's plugins
-     * send with every run (`LoopRunProps`: the modes the person is in, LOOP
-     * P-19) goes under it — and an agent turned in this page applies the modes
-     * itself (`modeEffect`, `BrowserAgentAdapter`).
+     * file there. An agent turned in this page has no session: one that runs
+     * its code in the page's sandbox has the files put there, and the message
+     * names them (STUDIO E-11); to any other no file is handed — said, rather
+     * than dropped. What the workspace's plugins send with every run
+     * (`LoopRunProps`: the modes the person is in, LOOP P-19) goes under it —
+     * and an agent turned in this page applies the modes itself (`modeEffect`,
+     * `BrowserAgentAdapter`).
      */
     const sendNow = useCallback((message, given) => {
+        if (hostClosedRef.current) {
+            return hostClosedRef.current;
+        }
         const forwardedProps = runForwardedProps(runPropsRef.current.map(entry => entry.value), given);
         // The page's files, or those attached in the composer (LOOP P-21).
         const loop = forwardedProps?.loop;
         if (inPageRef.current && loop?.files && loop.files.length > 0) {
-            return 'A file is given to an application running on a runtime: run it on Datalayer or on your machine to give it one.';
+            const sandbox = pageSandboxRef.current;
+            if (!sandbox) {
+                return 'A file is given to an application running on a runtime: run it on Datalayer or on your machine to give it one.';
+            }
+            let files;
+            try {
+                files = loop.files.map(file => ({
+                    file: sandboxFileName(String(file.name ?? '')),
+                    base64: dataUrlBase64(String(file.data_url ?? '')),
+                }));
+            }
+            catch (error) {
+                return error instanceof Error ? error.message : String(error);
+            }
+            // Put in the sandbox first, then sent: the message names where.
+            void sandbox.execute(writeFilesCode(files)).then(written => {
+                if (!written.success) {
+                    setTransient(`The files could not be put in the sandbox: ${written.error ?? 'it failed'}.`);
+                    return;
+                }
+                // Sent as any message is, its files now in the sandbox.
+                sendNow(`${message}\n\n${givenFilesSentence(files.map(file => file.file))}`, {
+                    ...forwardedProps,
+                    loop: Object.fromEntries(Object.entries(loop).filter(([key]) => key !== 'files')),
+                });
+            });
+            return;
         }
         // A new turn: whatever the panel showed is gone, this message is it.
         turnFeedRef.current?.begin(message, controlsRef.current?.thread());
@@ -938,6 +982,11 @@ export default function ChatView({ workspace }) {
             ...commandTools.filter(tool => !taken.has(tool.name)),
         ];
     }, [notebookTools, commandTools]);
+    // The page's sandbox, while the agent turned here runs its code in it.
+    pageSandboxRef.current =
+        inPage && agentTools.some(tool => tool.name === BROWSER_CODE_TOOL)
+            ? reactor.getOutput(AGENTS_PLUGIN_NAME)?.sandbox
+            : undefined;
     /*
      * Where this workspace's agent actually lives.
      *
@@ -1045,6 +1094,9 @@ export default function ChatView({ workspace }) {
      * Studio's Preview and the hosted page, rather than left unanswered.
      */
     const ambient = useChatAvailability();
+    hostClosedRef.current = ambient.disabled
+        ? ambient.disableReason || 'This conversation is closed here.'
+        : undefined;
     /*
      * No agent to talk to: a Datalayer runtime not assigned (STUDIO P-24,
      * round 9). Said in a sentence — why, when its launch was refused — and

package/lib/components/inspector/a2aSpans.js

@@ -199,7 +199,11 @@ class ResponseRecorder {
                 'a2a.artifact.media_type': typeof media === 'string' ? media : undefined,
             },
         };
-        chunk.text += text;
+        // An `append` chunk adds to what came; one that is not says the artifact
+        // whole — the runtime's last chunk carries the whole answer again. Added
+        // to it, an answer said in one chunk (a visitor's refusal) was written
+        // twice in the transcript (STUDIO H-03, 2026-10-10).
+        chunk.text = update.append ? chunk.text + text : text;
         chunk.events.push(message);
         if (update.append && !update.lastChunk) {
             // A chunk of an artifact being streamed: one event once it is whole.