@datalayer/agent-runtimes 1.3.48 → 1.3.50

package/lib/examples/LoopAppComputerExample.d.ts

@@ -0,0 +1,14 @@
+/**
+ * An application's computer, beside its page (LOOP R-23).
+ *
+ * An application whose files and shell are on, drawn as the Studio's Preview
+ * draws it — `AppRenderer` with its `sidebar` — on the Local target: its
+ * agent runs on the local agent-runtimes server, and the computer view beside
+ * it shows what ran on its sandbox, its files, and *Take over* and *Hand
+ * back*.
+ *
+ * @module examples/LoopAppComputerExample
+ */
+import React from 'react';
+declare const LoopAppComputerExample: React.FC;
+export default LoopAppComputerExample;

package/lib/examples/LoopAppComputerExample.js

@@ -0,0 +1,58 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * An application's computer, beside its page (LOOP R-23).
+ *
+ * An application whose files and shell are on, drawn as the Studio's Preview
+ * draws it — `AppRenderer` with its `sidebar` — on the Local target: its
+ * agent runs on the local agent-runtimes server, and the computer view beside
+ * it shows what ran on its sandbox, its files, and *Take over* and *Hand
+ * back*.
+ *
+ * @module examples/LoopAppComputerExample
+ */
+import { useMemo } from 'react';
+import { Box, setupPrimerPortals } from '@datalayer/primer-addons';
+import { ThemedProvider } from './utils/themedProvider';
+import { resolveExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
+import { AppRenderer } from '../loop/apps/AppRenderer';
+import { APP_CATALOGUE } from '../specs/apps';
+setupPrimerPortals();
+/** Web Research, given a computer with its files and its shell on. */
+function computerDesk() {
+    const base = APP_CATALOGUE['web-research'];
+    return {
+        ...base,
+        id: 'computer-desk',
+        name: 'Computer Desk',
+        emoji: '🖥️',
+        description: 'Works on its own computer: runs code, reads and writes files.',
+        connections: [],
+        rules: [],
+        instructions: 'You have a computer: run Python on it with your tools, and keep what you make in files there.',
+        interface: {
+            ...base.interface,
+            welcome: 'I work on my own computer. Ask me to compute something.',
+            starters: [
+                {
+                    label: 'Write a file',
+                    message: 'Run Python that writes the squares of 1 to 5 in squares.txt, then print the file.',
+                },
+            ],
+        },
+        permissions: {
+            ...base.permissions,
+            computer: { browse: false, files: true, shell: true },
+        },
+    };
+}
+const LoopAppComputerExample = () => {
+    const app = useMemo(computerDesk, []);
+    return (_jsx(ThemedProvider, { children: _jsx(Box, { sx: { height: '100vh', minHeight: 0 }, children: _jsx(AppRenderer, { app: app, 
+                // The examples Vite server has no /api proxy.
+                serverUrl: resolveExampleAgentRuntimesUrl('local'), target: "local", sidebar: true }) }) }));
+};
+export default LoopAppComputerExample;

package/lib/examples/example-selector.js

@@ -106,6 +106,7 @@ export const EXAMPLE_ENTRIES = [
     // the shell hides the one in its header rather than showing two controls
     // for one sandbox — and a second one that would not agree with the first.
     ['example', 'loop', 'workspace', 'sandbox', 'owns-sandbox-control']),
+    makeEntry('LoopAppComputerExample', () => import('./LoopAppComputerExample'), 'An application beside its computer: what its agent ran on its sandbox, its files, and Take over and Hand back (LOOP R-23).', ['example', 'loop', 'app', 'computer', 'sandbox', 'owns-sandbox-control']),
     makeEntry('LoopShellExample', () => import('./LoopShellExample'), 'The Loop shell at its most naked: a blank canvas, a floating draggable prompt, and an editor selector in the corner — none, notebook or document.', 
     // `owns-sandbox-control`: the shell is pinned to the browser sandbox, so
     // the page's selector would offer three targets it cannot move to.

package/lib/examples/main.js

@@ -67,6 +67,9 @@ const EXAMPLE_GROUP_ORDER = [
  */
 const ANONYMOUS_EXAMPLES = new Set([
     'LoopWorkspaceExample',
+    // An application beside its computer, on the local agent-runtimes server:
+    // nothing allocated on Datalayer, and the machine itself needs no token.
+    'LoopAppComputerExample',
     // Runs on the browser sandbox: nothing to allocate, nothing to sign into.
     'LoopShellExample',
     // Temporarily anonymous so the Jupyter output surface can be driven and

package/lib/loop/apps/AppRenderer.d.ts

@@ -29,9 +29,9 @@
  * - its **frame**, when the host asks (`frame`): the `window-frame` plugin's
  *   window, its title the application's face and name;
  * - its **sidebar**, when the host asks (`sidebar`, R-01b): its rules and
- *   the approvals waiting for the person (`app-rules`), and what it did
- *   (`app-activity`), beside its page — what its builder reads in the
- *   Studio's Preview.
+ *   the approvals waiting for the person (`app-rules`), what it did
+ *   (`app-activity`), and its computer, live (`app-computer`, R-23), beside
+ *   its page — what its builder reads in the Studio's Preview.
  *
  * Which plugins a kind needs, and how its workspace is laid out, is one
  * function: `appPreset`, the preset per kind, as `loopPlugins` is for the
@@ -153,7 +153,8 @@ export type AppPreset = {
  *   but those of the UI plugins its organization turned off (`pluginsOff`),
  *   whose contributions are the blocks it may draw (R-01b); a thumb and a
  *   comment on each answer when its record keeps feedback (V-18); with
- *   `sidebar`, its rules and approvals card and its activity feed (R-01b);
+ *   `sidebar`, its rules and approvals card, its activity feed and its
+ *   computer (R-01b, R-23);
  *   laid out as `interface.layout` says;
  * - a **decision**: the page its host draws (`page`), as the one view of a
  *   workspace without a conversation (R-02).
@@ -164,7 +165,7 @@ export type AppPreset = {
 export declare function appPreset(app: AppSpec, options?: {
     page?: ComponentType<AppHostPageProps>;
     pluginsOff?: readonly string[];
-    /** Its rules and approvals, and its activity, beside its page. */
+    /** Its rules and approvals, its activity and its computer, beside its page. */
     sidebar?: boolean;
     /** What its record is kept under: its activity's. */
     appUid?: string;

package/lib/loop/apps/AppRenderer.js

@@ -34,9 +34,9 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * - its **frame**, when the host asks (`frame`): the `window-frame` plugin's
  *   window, its title the application's face and name;
  * - its **sidebar**, when the host asks (`sidebar`, R-01b): its rules and
- *   the approvals waiting for the person (`app-rules`), and what it did
- *   (`app-activity`), beside its page — what its builder reads in the
- *   Studio's Preview.
+ *   the approvals waiting for the person (`app-rules`), what it did
+ *   (`app-activity`), and its computer, live (`app-computer`, R-23), beside
+ *   its page — what its builder reads in the Studio's Preview.
  *
  * Which plugins a kind needs, and how its workspace is laid out, is one
  * function: `appPreset`, the preset per kind, as `loopPlugins` is for the
@@ -52,6 +52,7 @@ import { CANVAS_BLOCK_PLUGINS, canvasBlocksPluginName, } from '../plugins/canvas
 import { LoopEmbed } from '../embed/LoopEmbed';
 import { dumpAppspec } from './appspec';
 import { defineAppActivityPlugin } from '../plugins/app-activity';
+import { defineAppComputerPlugin } from '../plugins/app-computer';
 import { defineAppRulesPlugin } from '../plugins/app-rules';
 import { defineAppFeedbackPlugin } from './AppFeedback';
 import { keepsFeedback } from './feedback';
@@ -88,6 +89,9 @@ export function defineAppPlugin(app) {
         createPayload: {
             name: app.id,
             app_spec: dumpAppspec(app),
+            // Its shell is its code: Codemode's `execute_code`, only when it is on
+            // (LOOP R-23), as on Datalayer (`appDatalayerCreatePayload`).
+            enable_codemode: Boolean(app.permissions?.computer?.shell),
             ...(app.model ? { model: app.model } : {}),
         },
         suggestions: app.interface.starters.map(starter => ({
@@ -141,7 +145,8 @@ export function appLayoutOptions(app) {
  *   but those of the UI plugins its organization turned off (`pluginsOff`),
  *   whose contributions are the blocks it may draw (R-01b); a thumb and a
  *   comment on each answer when its record keeps feedback (V-18); with
- *   `sidebar`, its rules and approvals card and its activity feed (R-01b);
+ *   `sidebar`, its rules and approvals card, its activity feed and its
+ *   computer (R-01b, R-23);
  *   laid out as `interface.layout` says;
  * - a **decision**: the page its host draws (`page`), as the one view of a
  *   workspace without a conversation (R-02).
@@ -180,6 +185,8 @@ export function appPreset(app, options = {}) {
                 ? [
                     defineAppRulesPlugin(app),
                     defineAppActivityPlugin(app, options.appUid),
+                    // Its computer, live (R-23).
+                    defineAppComputerPlugin(app),
                 ]
                 : []),
         ],

package/lib/loop/apps/computer.d.ts

@@ -0,0 +1,134 @@
+/**
+ * An application's computer (LOOP R-23, I-01): the sandbox its agent runs on,
+ * as the computer view shows it — its three parts, each off until it is
+ * turned on; what its agent ran on it, from the conversation's tool calls;
+ * its files, read-only; and *Take over* and *Hand back*, through the
+ * runtime's `/api/v1/apps/agents/{agent}/computer` routes.
+ *
+ * Pure but for `fetch`: no React.
+ *
+ * @module loop/apps/computer
+ */
+import type { AppSpec } from '../../types/agentspecs';
+import type { ConversationEntry } from '../core';
+/** The parts of a computer, in the order a person reads them. */
+export declare const COMPUTER_PARTS: readonly ["browse", "files", "shell"];
+export type ComputerPart = (typeof COMPUTER_PARTS)[number];
+export type ComputerParts = Record<ComputerPart, boolean>;
+/** The tools of each part, as the runtime gives them (`loop/apps/computer.py`). */
+export declare const COMPUTER_PART_TOOLS: Record<ComputerPart, readonly string[]>;
+/** What the computer view says. */
+export declare const COMPUTER_WORDS: {
+    readonly title: "Computer";
+    readonly part: Record<ComputerPart, string>;
+    readonly on: "on";
+    readonly off: "off";
+    readonly none: "It has no computer: browse, files and shell are all off. Turn one on in its permissions to give it one.";
+    readonly offSaid: (parts: string[]) => string;
+    readonly noBrowser: "Browser: no browser runs on its computer yet, so there is nothing to show.";
+    readonly agentHas: "Its agent has the computer.";
+    readonly youHave: "You have the computer: its agent waits for it until you hand it back.";
+    readonly someoneHas: "Somebody else has taken this computer over.";
+    readonly takeOver: "Take over";
+    readonly handBack: "Hand back";
+    readonly run: "Run";
+    readonly yourCode: "Python to run on its computer";
+    readonly terminal: "What ran on it";
+    readonly nothingRan: "Nothing has run on it yet in this conversation.";
+    readonly files: "Files";
+    readonly notStarted: "Its computer starts when its agent first uses it: no file yet.";
+    readonly emptyDirectory: "Empty.";
+    readonly up: "Up";
+    readonly download: "Download";
+    readonly signedOut: "Its computer is shown once you are signed in to Datalayer.";
+};
+/** Each part of an application's computer, on or off, as its Appspec says. */
+export declare function computerParts(app: AppSpec): ComputerParts;
+/** Whether its agent uses a computer at all. */
+export declare const hasComputer: (parts: ComputerParts) => boolean;
+/** The parts turned off, in words. */
+export declare const partsOff: (parts: ComputerParts) => string[];
+/** The part of the computer a tool uses, or undefined. */
+export declare function partOf(toolName: string): ComputerPart | undefined;
+/** One thing its agent did on its computer: the command, and what it said. */
+export type TerminalEntry = {
+    tool: string;
+    part: ComputerPart;
+    /** The code run, or the file's path. */
+    command: string;
+    /** What came back; undefined while it runs. */
+    output?: string;
+};
+/** The most of an output the view shows. */
+export declare const OUTPUT_LIMIT = 4000;
+/**
+ * What a tool of its computer returned, as a terminal shows it: the printed
+ * output and the error of code run (Codemode answers with an object, or its
+ * JSON), anything else as it came.
+ */
+export declare function outputOf(value: unknown): string;
+/**
+ * What its agent ran on its computer, in order: the conversation's calls to
+ * the tools of its shell and of its files, each with what it returned —
+ * streamed, as the conversation is.
+ */
+export declare function terminalEntries(conversation: readonly ConversationEntry[]): TerminalEntry[];
+/** Who has its computer, as the runtime says. */
+export type ComputerHolder = {
+    kind: string;
+    uid: string;
+    since: number;
+};
+/** Its computer, as the runtime describes it. */
+export type ComputerState = {
+    agent: string;
+    app: string;
+    parts: ComputerParts;
+    browser: boolean;
+    started: boolean;
+    held: ComputerHolder | null;
+    /** Whether the person asking is who has it. */
+    yours: boolean;
+};
+/** One entry of a directory of its computer. */
+export type ComputerFile = {
+    name: string;
+    path: string;
+    type: 'file' | 'directory';
+    size: number;
+    modified: number;
+};
+/** What a person's code said on its computer. */
+export type RunOutput = {
+    stdout: string;
+    stderr: string;
+    error: string;
+};
+/** Where its computer is reached, and as whom. */
+export type ComputerContext = {
+    /** The agent-runtimes server its agent runs on. */
+    serverUrl: string;
+    /** Its agent, as the runtime names it. */
+    agentId: string;
+    /** The person's token; none on the machine itself. */
+    token?: string;
+};
+/** The computer's routes, for an agent. */
+export declare const computerUrl: (context: ComputerContext, tail?: string) => string;
+/** Its parts, whether it started, who has it. */
+export declare const readComputer: (context: ComputerContext) => Promise<ComputerState>;
+/** A directory of its working directory. */
+export declare const listComputerFiles: (context: ComputerContext, path?: string) => Promise<ComputerFile[]>;
+/** One of its files, to save. */
+export declare const downloadComputerFile: (context: ComputerContext, path: string) => Promise<Blob>;
+/** Take it over: what runs is interrupted, its agent's calls wait. */
+export declare const takeOverComputer: (context: ComputerContext) => Promise<{
+    held: ComputerHolder;
+    interrupted: boolean;
+}>;
+/** Hand it back to its agent. */
+export declare const handBackComputer: (context: ComputerContext) => Promise<void>;
+/** Run code on it, as the person who took it over. */
+export declare const runOnComputer: (context: ComputerContext, code: string) => Promise<RunOutput>;
+/** The directory above a path of its working directory. */
+export declare function parentOf(path: string): string;

package/lib/loop/apps/computer.js

@@ -0,0 +1,190 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** The parts of a computer, in the order a person reads them. */
+export const COMPUTER_PARTS = ['browse', 'files', 'shell'];
+/** The tools of each part, as the runtime gives them (`loop/apps/computer.py`). */
+export const COMPUTER_PART_TOOLS = {
+    // No sandbox Datalayer runs has a browser yet.
+    browse: [],
+    files: ['list_computer_files', 'read_computer_file', 'write_computer_file'],
+    shell: ['execute_code', 'run_skill_script'],
+};
+/** What the computer view says. */
+export const COMPUTER_WORDS = {
+    title: 'Computer',
+    part: {
+        browse: 'Browse',
+        files: 'Files',
+        shell: 'Shell',
+    },
+    on: 'on',
+    off: 'off',
+    none: 'It has no computer: browse, files and shell are all off. Turn one on in its permissions to give it one.',
+    offSaid: (parts) => `Off, so its agent is given no tool for it: ${parts.join(', ')}.`,
+    noBrowser: 'Browser: no browser runs on its computer yet, so there is nothing to show.',
+    agentHas: 'Its agent has the computer.',
+    youHave: 'You have the computer: its agent waits for it until you hand it back.',
+    someoneHas: 'Somebody else has taken this computer over.',
+    takeOver: 'Take over',
+    handBack: 'Hand back',
+    run: 'Run',
+    yourCode: 'Python to run on its computer',
+    terminal: 'What ran on it',
+    nothingRan: 'Nothing has run on it yet in this conversation.',
+    files: 'Files',
+    notStarted: 'Its computer starts when its agent first uses it: no file yet.',
+    emptyDirectory: 'Empty.',
+    up: 'Up',
+    download: 'Download',
+    signedOut: 'Its computer is shown once you are signed in to Datalayer.',
+};
+/** Each part of an application's computer, on or off, as its Appspec says. */
+export function computerParts(app) {
+    const computer = app.permissions?.computer;
+    return {
+        browse: Boolean(computer?.browse),
+        files: Boolean(computer?.files),
+        shell: Boolean(computer?.shell),
+    };
+}
+/** Whether its agent uses a computer at all. */
+export const hasComputer = (parts) => COMPUTER_PARTS.some(part => parts[part]);
+/** The parts turned off, in words. */
+export const partsOff = (parts) => COMPUTER_PARTS.filter(part => !parts[part]).map(part => COMPUTER_WORDS.part[part].toLowerCase());
+/** The part of the computer a tool uses, or undefined. */
+export function partOf(toolName) {
+    return COMPUTER_PARTS.find(part => COMPUTER_PART_TOOLS[part].includes(toolName));
+}
+/** The most of an output the view shows. */
+export const OUTPUT_LIMIT = 4000;
+/**
+ * What a tool of its computer returned, as a terminal shows it: the printed
+ * output and the error of code run (Codemode answers with an object, or its
+ * JSON), anything else as it came.
+ */
+export function outputOf(value) {
+    let found = value;
+    if (typeof found === 'string') {
+        try {
+            const parsed = JSON.parse(found);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                found = parsed;
+            }
+        }
+        catch {
+            // Text, as it came.
+        }
+    }
+    let text;
+    if (found && typeof found === 'object' && !Array.isArray(found)) {
+        const ran = found;
+        const printed = [
+            typeof ran.stdout === 'string' ? ran.stdout : ran.output,
+            ran.stderr,
+            ran.error ?? ran.execution_error ?? ran.code_error,
+        ].filter((part) => typeof part === 'string' && part.trim() !== '');
+        text =
+            printed.length > 0
+                ? printed.join('\n')
+                : 'stdout' in ran || 'output' in ran
+                    ? ''
+                    : JSON.stringify(found, null, 2);
+    }
+    else {
+        text =
+            typeof found === 'string'
+                ? found
+                : found === null || found === undefined
+                    ? ''
+                    : JSON.stringify(found, null, 2);
+    }
+    return text.length > OUTPUT_LIMIT
+        ? `${text.slice(0, OUTPUT_LIMIT)}\n… (${(text.length - OUTPUT_LIMIT).toLocaleString('en')} characters more)`
+        : text;
+}
+function commandOf(args) {
+    for (const key of ['code', 'path', 'script_name']) {
+        const value = args[key];
+        if (typeof value === 'string' && value.trim()) {
+            return value;
+        }
+    }
+    // A call read back from history may come without its arguments.
+    return Object.keys(args).length ? JSON.stringify(args) : '';
+}
+/**
+ * What its agent ran on its computer, in order: the conversation's calls to
+ * the tools of its shell and of its files, each with what it returned —
+ * streamed, as the conversation is.
+ */
+export function terminalEntries(conversation) {
+    const entries = [];
+    for (const entry of conversation) {
+        if (entry.role !== 'tool') {
+            continue;
+        }
+        const part = partOf(entry.name);
+        if (!part) {
+            continue;
+        }
+        entries.push({
+            tool: entry.name,
+            part,
+            command: commandOf(entry.args ?? {}),
+            output: entry.result === undefined ? undefined : outputOf(entry.result),
+        });
+    }
+    return entries;
+}
+/** The computer's routes, for an agent. */
+export const computerUrl = (context, tail = '') => `${context.serverUrl.replace(/\/+$/, '')}/api/v1/apps/agents/${encodeURIComponent(context.agentId)}/computer${tail}`;
+async function asked(context, tail, init = {}) {
+    const response = await fetch(computerUrl(context, tail), {
+        ...init,
+        headers: {
+            ...(init.body ? { 'Content-Type': 'application/json' } : {}),
+            ...(context.token ? { Authorization: `Bearer ${context.token}` } : {}),
+        },
+    });
+    if (!response.ok) {
+        let detail = `${response.status}`;
+        try {
+            const body = (await response.json());
+            detail = typeof body.detail === 'string' ? body.detail : detail;
+        }
+        catch {
+            // A refusal without a sentence: its status says it.
+        }
+        throw new Error(detail);
+    }
+    return response;
+}
+/** Its parts, whether it started, who has it. */
+export const readComputer = async (context) => (await asked(context, '')).json();
+/** A directory of its working directory. */
+export const listComputerFiles = async (context, path = '.') => {
+    const response = await asked(context, `/files?path=${encodeURIComponent(path)}`);
+    const body = (await response.json());
+    return body.entries;
+};
+/** One of its files, to save. */
+export const downloadComputerFile = async (context, path) => (await asked(context, `/file?path=${encodeURIComponent(path)}`)).blob();
+/** Take it over: what runs is interrupted, its agent's calls wait. */
+export const takeOverComputer = async (context) => (await asked(context, '/take-over', { method: 'POST' })).json();
+/** Hand it back to its agent. */
+export const handBackComputer = async (context) => {
+    await asked(context, '/hand-back', { method: 'POST' });
+};
+/** Run code on it, as the person who took it over. */
+export const runOnComputer = async (context, code) => (await asked(context, '/run', {
+    method: 'POST',
+    body: JSON.stringify({ code }),
+})).json();
+/** The directory above a path of its working directory. */
+export function parentOf(path) {
+    const parts = path.split('/').filter(part => part && part !== '.');
+    parts.pop();
+    return parts.length ? parts.join('/') : '.';
+}

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

@@ -8,6 +8,7 @@ export * from './AppFeedback';
 export * from './AppRenderer';
 export * from './appspec';
 export * from './checks';
+export * from './computer';
 export * from './feedback';
 export * from './records';
 export * from './rules';

package/lib/loop/apps/index.js

@@ -12,6 +12,7 @@ export * from './AppFeedback';
 export * from './AppRenderer';
 export * from './appspec';
 export * from './checks';
+export * from './computer';
 export * from './feedback';
 export * from './records';
 export * from './rules';

package/lib/loop/index.d.ts

@@ -53,6 +53,7 @@ export { defineA2uiScenePlugin, type A2uiSceneOptions, } from './plugins/a2ui-sc
 export { APP_KIND_PATHS, APP_PAGE_PLUGIN_NAME, APP_PAGE_SURFACE, AppPage, appKindPaths, appPageAction, appPageData, defineAppPagePlugin, hasAppPage, surfaceUnshown, type AppKindPaths, type AppPageAction, type AppPageKind, type AppPagePath, } from './plugins/app-page';
 export { APP_RULES_PLUGIN_NAME, APP_RULES_WORDS, AppRulesCard, defineAppRulesPlugin, } from './plugins/app-rules';
 export { APP_ACTIVITY_PLUGIN_NAME, APP_ACTIVITY_WORDS, AppActivity, defineAppActivityPlugin, } from './plugins/app-activity';
+export { APP_COMPUTER_PLUGIN_NAME, AppComputer, defineAppComputerPlugin, } from './plugins/app-computer';
 export { GraphViewPlugin, GRAPH_PLUGIN_NAME, GRAPH_VIEW_TYPE, } from './plugins/graph';
 export { PluginsPanelPlugin, PLUGINS_PANEL_PLUGIN_NAME, PluginsPanel, } from './plugins/plugins-panel';
 export { AGENTS_PLUGIN_NAME, AgentsPlugin, SandboxSelector, browserSource, createBrowserSandboxService, createServerSandboxService, createSwitchableSandboxService, suppliedSource, useOptionalSandboxService, useSandboxService, type AgentsConfig, type AgentsOutput, type SandboxExecution, type SandboxService, type SandboxTarget, type ServiceManagerSource, type SwitchableSandboxService, } from './plugins/agents';

package/lib/loop/index.js

@@ -66,6 +66,7 @@ export { defineA2uiScenePlugin, } from './plugins/a2ui-scene';
 export { APP_KIND_PATHS, APP_PAGE_PLUGIN_NAME, APP_PAGE_SURFACE, AppPage, appKindPaths, appPageAction, appPageData, defineAppPagePlugin, hasAppPage, surfaceUnshown, } from './plugins/app-page';
 export { APP_RULES_PLUGIN_NAME, APP_RULES_WORDS, AppRulesCard, defineAppRulesPlugin, } from './plugins/app-rules';
 export { APP_ACTIVITY_PLUGIN_NAME, APP_ACTIVITY_WORDS, AppActivity, defineAppActivityPlugin, } from './plugins/app-activity';
+export { APP_COMPUTER_PLUGIN_NAME, AppComputer, defineAppComputerPlugin, } from './plugins/app-computer';
 export { GraphViewPlugin, GRAPH_PLUGIN_NAME, GRAPH_VIEW_TYPE, } from './plugins/graph';
 export { PluginsPanelPlugin, PLUGINS_PANEL_PLUGIN_NAME, PluginsPanel, } from './plugins/plugins-panel';
 export { AGENTS_PLUGIN_NAME, AgentsPlugin, SandboxSelector, browserSource, createBrowserSandboxService, createServerSandboxService, createSwitchableSandboxService, suppliedSource, useOptionalSandboxService, useSandboxService, } from './plugins/agents';

package/lib/loop/plugins/app-computer/AppComputer.d.ts

@@ -0,0 +1,25 @@
+/**
+ * An application's computer, beside its page (LOOP R-23, R-01b): the sandbox
+ * its agent runs on, live.
+ *
+ * - its **parts** — browse, files, shell — on or off, as its permissions say;
+ *   a part off gives its agent no tool, and is said to be off;
+ * - **what ran on it**: the code its agent ran and the files it read and
+ *   wrote, each with what came back, streamed from the conversation's tool
+ *   calls;
+ * - its **files**, read-only, each to download, read again as each turn ends;
+ * - its **browser**: none runs on any sandbox yet, and it says so;
+ * - **Take over**: what runs on it is interrupted and its agent's calls to it
+ *   wait while the person runs code on it themselves; **Hand back** lets its
+ *   agent go on.
+ *
+ * @module loop/plugins/app-computer/AppComputer
+ */
+import type { JSX } from 'react';
+import type { AppSpec } from '../../../types/agentspecs';
+import { type LoopWorkspaceContext } from '../../core';
+export declare function AppComputer({ app, workspace, }: {
+    app: AppSpec;
+    workspace?: LoopWorkspaceContext;
+}): JSX.Element;
+export default AppComputer;

package/lib/loop/plugins/app-computer/AppComputer.js

@@ -0,0 +1,179 @@
+import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { Button, Heading, Label, Spinner, Text, Textarea } from '@primer/react';
+import { Box } from '@datalayer/primer-addons';
+import { signal } from '@datalayer/reactor';
+import { useContributions, useSignalValue } from '@datalayer/reactor/react';
+import { useIAMStore } from '@datalayer/core/lib/state/substates/IAMState';
+import { LoopChatTurn, } from '../../core';
+import { COMPUTER_PARTS, COMPUTER_WORDS, computerParts, downloadComputerFile, handBackComputer, hasComputer, listComputerFiles, parentOf, partsOff, readComputer, runOnComputer, takeOverComputer, terminalEntries, } from '../../apps/computer';
+const NO_TURN = signal({ id: 0, status: 'idle' });
+const NO_CONVERSATION = signal([]);
+const MONO_FACE = 'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace';
+const MONO = {
+    fontFamily: MONO_FACE,
+    fontSize: 0,
+    whiteSpace: 'pre-wrap',
+    wordBreak: 'break-word',
+    m: 0,
+};
+function Parts({ app }) {
+    const parts = computerParts(app);
+    const off = partsOff(parts);
+    return (_jsxs(Box, { "data-testid": "computer-parts", children: [_jsx(Box, { sx: { display: 'flex', gap: 1, flexWrap: 'wrap', mb: 1 }, children: COMPUTER_PARTS.map(part => (_jsxs(Label, { variant: parts[part] ? 'success' : 'secondary', "data-part": part, "data-on": parts[part] ? 'true' : 'false', children: [COMPUTER_WORDS.part[part], ":", ' ', parts[part] ? COMPUTER_WORDS.on : COMPUTER_WORDS.off] }, part))) }), off.length > 0 && off.length < COMPUTER_PARTS.length ? (_jsx(Text, { as: "p", sx: { fontSize: 0, color: 'fg.muted', m: 0 }, children: COMPUTER_WORDS.offSaid(off) })) : null] }));
+}
+function Terminal({ conversation, }) {
+    const entries = terminalEntries(conversation);
+    return (_jsxs(Box, { "data-testid": "computer-terminal", children: [_jsx(Heading, { as: "h4", sx: { fontSize: 1, mt: 3, mb: 1 }, children: COMPUTER_WORDS.terminal }), entries.length === 0 ? (_jsx(Text, { as: "p", sx: { fontSize: 1, color: 'fg.muted', m: 0 }, children: COMPUTER_WORDS.nothingRan })) : (_jsx(Box, { sx: {
+                    bg: 'canvas.inset',
+                    border: '1px solid',
+                    borderColor: 'border.muted',
+                    borderRadius: 2,
+                    p: 2,
+                    maxHeight: 320,
+                    overflow: 'auto',
+                }, children: entries.map((entry, index) => (_jsxs(Box, { sx: { mb: 2 }, children: [_jsx(Text, { as: "p", sx: { ...MONO, fontWeight: 'semibold' }, children: `$ ${entry.tool}${entry.command ? `: ${entry.command}` : ''}` }), entry.output === undefined ? (_jsx(Spinner, { size: "small" })) : (_jsx(Text, { as: "pre", sx: { ...MONO, color: 'fg.muted' }, children: entry.output }))] }, index))) }))] }));
+}
+function save(blob, name) {
+    const url = URL.createObjectURL(blob);
+    const anchor = document.createElement('a');
+    anchor.href = url;
+    anchor.download = name;
+    anchor.click();
+    URL.revokeObjectURL(url);
+}
+function Files({ context, state, ended, }) {
+    const [path, setPath] = useState('.');
+    const [entries, setEntries] = useState();
+    const [error, setError] = useState('');
+    useEffect(() => {
+        if (!state.started) {
+            return undefined;
+        }
+        let cancelled = false;
+        listComputerFiles(context, path).then(found => {
+            if (!cancelled) {
+                setEntries(found);
+                setError('');
+            }
+        }, (failed) => !cancelled &&
+            setError(failed instanceof Error ? failed.message : String(failed)));
+        return () => {
+            cancelled = true;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [
+        context.serverUrl,
+        context.agentId,
+        context.token,
+        path,
+        state.started,
+        ended,
+    ]);
+    return (_jsxs(Box, { "data-testid": "computer-files", children: [_jsxs(Heading, { as: "h4", sx: { fontSize: 1, mt: 3, mb: 1 }, children: [COMPUTER_WORDS.files, path !== '.' ? (_jsx(Text, { sx: { fontWeight: 'normal', color: 'fg.muted' }, children: ` · ${path}` })) : null] }), !state.started ? (_jsx(Text, { as: "p", sx: { fontSize: 1, color: 'fg.muted', m: 0 }, children: COMPUTER_WORDS.notStarted })) : error ? (_jsx(Text, { as: "p", sx: { fontSize: 1, color: 'danger.fg', m: 0 }, children: error })) : !entries ? (_jsx(Spinner, { size: "small" })) : (_jsxs(Box, { as: "ul", sx: { listStyle: 'none', p: 0, m: 0 }, children: [path !== '.' ? (_jsx(Box, { as: "li", children: _jsx(Button, { size: "small", variant: "invisible", onClick: () => setPath(parentOf(path)), children: COMPUTER_WORDS.up }) })) : null, entries.length === 0 ? (_jsx(Text, { as: "p", sx: { fontSize: 1, color: 'fg.muted', m: 0 }, children: COMPUTER_WORDS.emptyDirectory })) : null, entries.map(entry => (_jsx(Box, { as: "li", "data-path": entry.path, sx: {
+                            display: 'flex',
+                            alignItems: 'center',
+                            gap: 2,
+                            fontSize: 1,
+                            py: 1,
+                            borderTop: '1px solid',
+                            borderColor: 'border.muted',
+                        }, children: entry.type === 'directory' ? (_jsx(Button, { size: "small", variant: "invisible", onClick: () => setPath(entry.path), children: `${entry.name}/` })) : (_jsxs(_Fragment, { children: [_jsx(Text, { sx: { flex: 1, fontFamily: MONO_FACE, fontSize: 0 }, children: entry.name }), _jsx(Text, { sx: { color: 'fg.muted', fontSize: 0 }, children: `${entry.size.toLocaleString('en')} bytes` }), _jsx(Button, { size: "small", "aria-label": `${COMPUTER_WORDS.download} ${entry.name}`, onClick: () => {
+                                        downloadComputerFile(context, entry.path).then(blob => save(blob, entry.name), (failed) => setError(failed instanceof Error
+                                            ? failed.message
+                                            : String(failed)));
+                                    }, children: COMPUTER_WORDS.download })] })) }, entry.path)))] }))] }));
+}
+function YourTerminal({ context }) {
+    const [code, setCode] = useState('');
+    const [running, setRunning] = useState(false);
+    const [outputs, setOutputs] = useState([]);
+    const run = () => {
+        setRunning(true);
+        runOnComputer(context, code).then(output => {
+            setOutputs(previous => [...previous, { code, output }]);
+            setCode('');
+            setRunning(false);
+        }, (failed) => {
+            setOutputs(previous => [
+                ...previous,
+                {
+                    code,
+                    output: {
+                        stdout: '',
+                        stderr: '',
+                        error: failed instanceof Error ? failed.message : String(failed),
+                    },
+                },
+            ]);
+            setRunning(false);
+        });
+    };
+    return (_jsxs(Box, { "data-testid": "computer-your-terminal", sx: { mt: 2 }, children: [outputs.map((each, index) => (_jsxs(Box, { sx: { mb: 2 }, children: [_jsx(Text, { as: "p", sx: { ...MONO, fontWeight: 'semibold' }, children: `>>> ${each.code}` }), _jsx(Text, { as: "pre", sx: { ...MONO, color: 'fg.muted' }, children: [each.output.stdout, each.output.stderr, each.output.error]
+                            .filter(Boolean)
+                            .join('\n') })] }, index))), _jsx(Textarea, { "aria-label": COMPUTER_WORDS.yourCode, placeholder: COMPUTER_WORDS.yourCode, value: code, onChange: event => setCode(event.target.value), sx: { width: '100%', fontFamily: MONO_FACE }, rows: 3 }), _jsx(Button, { size: "small", sx: { mt: 1 }, disabled: running || !code.trim(), onClick: run, children: COMPUTER_WORDS.run })] }));
+}
+export function AppComputer({ app, workspace, }) {
+    const token = useIAMStore(state => state.token) ?? '';
+    const turnEntries = useContributions(LoopChatTurn);
+    const turn = useSignalValue(turnEntries[0]?.value.turn ?? NO_TURN);
+    const conversation = useSignalValue(turnEntries[0]?.value.conversation ?? NO_CONVERSATION);
+    const settled = turn.status !== 'thinking' && turn.status !== 'streaming';
+    const [ended, setEnded] = useState(0);
+    useEffect(() => {
+        if (settled) {
+            setEnded(turn.id);
+        }
+    }, [settled, turn.id]);
+    const serverUrl = workspace?.sandbox.agentBaseUrl || workspace?.serverUrl || '';
+    const agentId = workspace?.agentId || app.id;
+    const context = useMemo(() => ({ serverUrl, agentId, token: token || undefined }), [serverUrl, agentId, token]);
+    const parts = computerParts(app);
+    const [state, setState] = useState();
+    const [error, setError] = useState('');
+    const [busy, setBusy] = useState(false);
+    // Nothing is set once it is gone: an answer may come back after.
+    const alive = useRef(true);
+    useEffect(() => {
+        alive.current = true;
+        return () => {
+            alive.current = false;
+        };
+    }, []);
+    const read = useCallback(() => {
+        readComputer(context).then(found => {
+            if (alive.current) {
+                setState(found);
+                setError('');
+            }
+        }, (failed) => alive.current &&
+            setError(failed instanceof Error ? failed.message : String(failed)));
+    }, [context]);
+    const used = hasComputer(parts);
+    useEffect(() => {
+        if (used && serverUrl) {
+            read();
+        }
+    }, [used, serverUrl, read, ended]);
+    const act = (step) => {
+        setBusy(true);
+        step(context).then(() => {
+            if (alive.current) {
+                setBusy(false);
+                read();
+            }
+        }, (failed) => {
+            if (alive.current) {
+                setBusy(false);
+                setError(failed instanceof Error ? failed.message : String(failed));
+            }
+        });
+    };
+    const me = Boolean(state?.yours);
+    return (_jsxs(Box, { "data-testid": "app-computer", children: [_jsx(Heading, { as: "h3", sx: { fontSize: 2, mb: 2 }, children: COMPUTER_WORDS.title }), _jsx(Parts, { app: app }), !used ? (_jsx(Text, { as: "p", sx: { fontSize: 1, color: 'fg.muted', m: 0, mt: 1 }, children: COMPUTER_WORDS.none })) : (_jsxs(_Fragment, { children: [_jsx(Text, { as: "p", sx: { fontSize: 0, color: 'fg.muted', m: 0, mt: 1 }, children: COMPUTER_WORDS.noBrowser }), error ? (_jsx(Text, { as: "p", sx: { fontSize: 1, color: 'danger.fg', m: 0, mt: 2 }, children: error })) : null, state ? (_jsxs(Box, { sx: { mt: 2 }, "data-testid": "computer-holder", children: [_jsx(Text, { as: "p", sx: { fontSize: 1, m: 0, mb: 1 }, children: !state.held
+                                    ? COMPUTER_WORDS.agentHas
+                                    : me
+                                        ? COMPUTER_WORDS.youHave
+                                        : COMPUTER_WORDS.someoneHas }), !state.held ? (_jsx(Button, { size: "small", disabled: busy, onClick: () => act(takeOverComputer), children: COMPUTER_WORDS.takeOver })) : me ? (_jsxs(_Fragment, { children: [_jsx(Button, { size: "small", variant: "primary", disabled: busy, onClick: () => act(handBackComputer), children: COMPUTER_WORDS.handBack }), _jsx(YourTerminal, { context: context })] })) : null] })) : null, _jsx(Terminal, { conversation: conversation }), state ? (_jsx(Files, { context: context, state: state, ended: ended })) : null] }))] }));
+}
+export default AppComputer;

package/lib/loop/plugins/app-computer/index.d.ts

@@ -0,0 +1,8 @@
+import { type ReactorPlugin } from '@datalayer/reactor';
+import type { AppSpec } from '../../../types/agentspecs';
+export declare const APP_COMPUTER_PLUGIN_NAME = "@datalayer/loop-plugin-app-computer";
+/** The plugin that shows an application's computer beside its page. */
+export declare function defineAppComputerPlugin(app: AppSpec): ReactorPlugin<Record<string, never>, unknown, unknown>;
+export { AppComputer } from './AppComputer';
+export { COMPUTER_WORDS } from '../../apps/computer';
+export default defineAppComputerPlugin;

package/lib/loop/plugins/app-computer/index.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { definePlugin } from '@datalayer/reactor';
+import { LoopSlots } from '../../core';
+import { AppComputer } from './AppComputer';
+export const APP_COMPUTER_PLUGIN_NAME = '@datalayer/loop-plugin-app-computer';
+/** The plugin that shows an application's computer beside its page. */
+export function defineAppComputerPlugin(app) {
+    // One component per plugin: the slot keeps it, and the application with it.
+    function Computer({ workspace, }) {
+        return _jsx(AppComputer, { app: app, workspace: workspace });
+    }
+    const plugin = definePlugin({
+        name: `${APP_COMPUTER_PLUGIN_NAME}-${app.id}`,
+        displayName: `${app.name}: computer`,
+        description: `The computer ${app.name} runs on: what ran on it, its files, and taking it over.`,
+        octicon: 'device-desktop',
+        build: () => ({
+            components: [
+                {
+                    id: 'app-computer',
+                    slot: LoopSlots.sidebar,
+                    order: 30,
+                    Component: Computer,
+                },
+            ],
+        }),
+    });
+    return plugin;
+}
+export { AppComputer } from './AppComputer';
+export { COMPUTER_WORDS } from '../../apps/computer';
+export default defineAppComputerPlugin;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datalayer/agent-runtimes",
-    "version": "1.3.48",
+    "version": "1.3.50",
     "type": "module",
     "workspaces": [
         ".",