@datalayer/agent-runtimes 1.3.28 → 1.3.30

package/lib/loop/plugins/agents/switchable.js

@@ -197,94 +197,9 @@ export function createSwitchableSandboxService({ serverUrl, initialTarget = 'loc
                 (await detail(restart)));
         }
     }
-    /**
-     * Create the agent whose per-agent Jupyter sandbox backs Local.
-     *
-     * The payload is passed rather than read from the closure: the caller has
-     * already established that it exists, and TypeScript cannot carry that
-     * narrowing across a function boundary.
-     */
-    async function ensureLocalAgent(createPayload) {
-        const id = agentId?.trim();
-        if (!id) {
-            throw new Error('Local needs an agent id before its runtime can start.');
-        }
-        let existing;
-        try {
-            existing = await fetch(`${serverUrl}/api/v1/agents/${encodeURIComponent(id)}`);
-        }
-        catch (reason) {
-            throw new Error(`Local needs an agent-runtimes server at ${serverUrl}, and nothing answered there. ` +
-                `Start one and try again. (${reason instanceof Error ? reason.message : String(reason)})`, { cause: reason });
-        }
-        if (existing.ok) {
-            // The agent is there, which does not mean its sandbox is. Reconfiguring
-            // or restarting the manager stops the per-agent sandboxes, because they
-            // were built under the previous settings — so coming back to Local after
-            // a spell on Jupyter finds the agent alive and nothing behind it. Asking
-            // for the sandbox is idempotent, so it costs a round trip and nothing
-            // else when one is already running.
-            await ensureLocalSandbox(id);
-            return;
-        }
-        if (existing.status !== 404) {
-            throw new Error(`The server could not inspect local agent ${id} (${existing.status} ${existing.statusText}). ` +
-                (await detail(existing)));
-        }
-        const created = await fetch(`${serverUrl}/api/v1/agents`, {
-            method: 'POST',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({
-                // Defaults first, so a blueprint that names its own transport or
-                // sandbox variant — the sandbox capacity plugins do — wins over
-                // them; the name last, because Local's agent id is not negotiable.
-                transport: 'ag-ui',
-                sandbox_variant: 'jupyter-server',
-                ...createPayload,
-                name: id,
-            }),
-        });
-        if (!created.ok && created.status !== 409) {
-            throw new Error(`The server could not launch local agent ${id} (${created.status} ${created.statusText}). ` +
-                (await detail(created)));
-        }
-        // A 409 means somebody else created it between the two calls above, and
-        // that agent is as unlikely to have a sandbox as one found by the GET.
-        if (created.status === 409) {
-            await ensureLocalSandbox(id);
-        }
-    }
-    /**
-     * Make sure the agent has somewhere to run.
-     *
-     * Creating an agent starts its sandbox, so this is only ever needed for one
-     * that already existed. Selecting a target is an operation, not a
-     * preference: when the promise resolves the sandbox is meant to be up, and
-     * without this the kernel indicator sits empty and the notebook binds to
-     * nothing.
-     */
-    async function ensureLocalSandbox(id) {
-        const response = await fetch(`${serverUrl}/api/v1/agents/${encodeURIComponent(id)}/sandbox/ensure`, { method: 'POST' });
-        if (!response.ok) {
-            throw new Error(`The server could not start a sandbox for local agent ${id} ` +
-                `(${response.status} ${response.statusText}). ` +
-                (await detail(response)));
-        }
-    }
-    /**
-     * What the server said went wrong, when it said anything.
-     *
-     * FastAPI puts the reason in `detail`, and a status code on its own sends a
-     * reader to the network tab for something the response already contained.
-     */
-    async function detail(response) {
-        try {
-            const body = (await response.json());
-            return typeof body.detail === 'string' ? body.detail : '';
-        }
-        catch {
-            return '';
-        }
+    /** The agent backing Local, on this workspace's server. */
+    function ensureLocalAgent(createPayload) {
+        return ensureServerAgent(serverUrl, agentId, createPayload);
     }
     function connectActive() {
         disconnect?.();
@@ -403,3 +318,91 @@ export function createSwitchableSandboxService({ serverUrl, initialTarget = 'loc
         },
     };
 }
+/**
+ * Create the agent whose per-agent Jupyter sandbox backs Local, on the
+ * agent-runtimes server at `serverUrl`, unless it is there already — then
+ * only its sandbox is asked for. Exported for a host that addresses the
+ * agent without a workspace: the embed's floating modes (`AppEmbed`).
+ */
+export async function ensureServerAgent(serverUrl, agentId, createPayload) {
+    const id = agentId?.trim();
+    if (!id) {
+        throw new Error('Local needs an agent id before its runtime can start.');
+    }
+    let existing;
+    try {
+        existing = await fetch(`${serverUrl}/api/v1/agents/${encodeURIComponent(id)}`);
+    }
+    catch (reason) {
+        throw new Error(`Local needs an agent-runtimes server at ${serverUrl}, and nothing answered there. ` +
+            `Start one and try again. (${reason instanceof Error ? reason.message : String(reason)})`, { cause: reason });
+    }
+    if (existing.ok) {
+        // The agent is there, which does not mean its sandbox is. Reconfiguring
+        // or restarting the manager stops the per-agent sandboxes, because they
+        // were built under the previous settings — so coming back to Local after
+        // a spell on Jupyter finds the agent alive and nothing behind it. Asking
+        // for the sandbox is idempotent, so it costs a round trip and nothing
+        // else when one is already running.
+        await ensureServerSandbox(serverUrl, id);
+        return;
+    }
+    if (existing.status !== 404) {
+        throw new Error(`The server could not inspect local agent ${id} (${existing.status} ${existing.statusText}). ` +
+            (await detail(existing)));
+    }
+    const created = await fetch(`${serverUrl}/api/v1/agents`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+            // Defaults first, so a blueprint that names its own transport or
+            // sandbox variant — the sandbox capacity plugins do — wins over
+            // them; the name last, because Local's agent id is not negotiable.
+            transport: 'ag-ui',
+            sandbox_variant: 'jupyter-server',
+            ...createPayload,
+            name: id,
+        }),
+    });
+    if (!created.ok && created.status !== 409) {
+        throw new Error(`The server could not launch local agent ${id} (${created.status} ${created.statusText}). ` +
+            (await detail(created)));
+    }
+    // A 409 means somebody else created it between the two calls above, and
+    // that agent is as unlikely to have a sandbox as one found by the GET.
+    if (created.status === 409) {
+        await ensureServerSandbox(serverUrl, id);
+    }
+}
+/**
+ * Make sure the agent has somewhere to run.
+ *
+ * Creating an agent starts its sandbox, so this is only ever needed for one
+ * that already existed. Selecting a target is an operation, not a
+ * preference: when the promise resolves the sandbox is meant to be up, and
+ * without this the kernel indicator sits empty and the notebook binds to
+ * nothing.
+ */
+async function ensureServerSandbox(serverUrl, id) {
+    const response = await fetch(`${serverUrl}/api/v1/agents/${encodeURIComponent(id)}/sandbox/ensure`, { method: 'POST' });
+    if (!response.ok) {
+        throw new Error(`The server could not start a sandbox for local agent ${id} ` +
+            `(${response.status} ${response.statusText}). ` +
+            (await detail(response)));
+    }
+}
+/**
+ * What the server said went wrong, when it said anything.
+ *
+ * FastAPI puts the reason in `detail`, and a status code on its own sends a
+ * reader to the network tab for something the response already contained.
+ */
+async function detail(response) {
+    try {
+        const body = (await response.json());
+        return typeof body.detail === 'string' ? body.detail : '';
+    }
+    catch {
+        return '';
+    }
+}

package/lib/loop/plugins/app-page/AppPage.d.ts

@@ -0,0 +1,16 @@
+/**
+ * An application's page, drawn beside its conversation: its A2UI surface on
+ * the workspace's own renderer (`InlineSurface`), fed by the chat's current
+ * turn, its buttons answered through the chat's controls.
+ *
+ * @module loop/plugins/app-page/AppPage
+ */
+import type { JSX } from 'react';
+import type { AppSpec } from '../../../types/agentspecs';
+import { type LoopWorkspaceContext } from '../../core';
+export type AppPageProps = {
+    app: AppSpec;
+    workspace: LoopWorkspaceContext;
+};
+export declare function AppPage({ app, workspace }: AppPageProps): JSX.Element;
+export default AppPage;

package/lib/loop/plugins/app-page/AppPage.js

@@ -0,0 +1,53 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useMemo, useRef, useState } from 'react';
+import { Box } from '@datalayer/primer-addons';
+import { signal } from '@datalayer/reactor';
+import { useContributions, useSignalValue } from '@datalayer/reactor/react';
+import { LoopChatTurn, } from '../../core';
+import { InlineSurface, SURFACE_CATALOG_ID, } from '../a2ui-surface/InlineSurface';
+import { appPageAction, appPageData, appPageMessages } from './appPage';
+/** No chat in the workspace: the page reads a turn that never starts. */
+const NO_TURN = signal({ id: 0, status: 'idle' });
+export function AppPage({ app, workspace }) {
+    const entries = useContributions(LoopChatTurn);
+    const turn = useSignalValue(entries[0]?.value.turn ?? NO_TURN);
+    const messages = useMemo(() => appPageMessages(app, SURFACE_CATALOG_ID), [app]);
+    const data = useMemo(() => appPageData(app, turn), [app, turn]);
+    const [refusal, setRefusal] = useState(null);
+    // The workspace changes as the chat reports itself; the handler reads the latest.
+    const workspaceRef = useRef(workspace);
+    workspaceRef.current = workspace;
+    // The inputs in words as last sent: a chat's message carries them when they change.
+    const lastInputs = useRef('');
+    const onAction = useCallback((action, surface) => {
+        const outcome = appPageAction(app, { name: action.name, context: action.context ?? {} }, path => surface?.dataModel.get(path), lastInputs.current);
+        const controls = workspaceRef.current.viewControls;
+        if ('refused' in outcome) {
+            setRefusal(outcome.refused);
+            return;
+        }
+        setRefusal(null);
+        if ('stop' in outcome) {
+            controls.stop?.();
+        }
+        else if ('newChat' in outcome) {
+            controls.newChat?.();
+        }
+        else {
+            // The chat's own send, as a surface in the transcript submits; the
+            // prompt channel when the chat has not reported itself yet.
+            if (controls.send) {
+                controls.send(outcome.send);
+            }
+            else {
+                workspaceRef.current.prompts.submit(outcome.send);
+            }
+            lastInputs.current = outcome.inputs;
+            for (const path of outcome.clear) {
+                surface?.dataModel.set(path, '');
+            }
+        }
+    }, [app]);
+    return (_jsx(Box, { "data-testid": "app-page", sx: { height: '100%', minHeight: 0, overflow: 'auto', p: 3 }, children: _jsx(InlineSurface, { messages: messages, data: data, onAction: onAction, validationError: refusal }) }));
+}
+export default AppPage;

package/lib/loop/plugins/app-page/appPage.d.ts

@@ -0,0 +1,180 @@
+/**
+ * An application's page, as data: what it publishes to its surface by path,
+ * what it takes from it, and what a button on it does (LOOP R-01, R-01b,
+ * C-04).
+ *
+ * A chat, a widget or a worker runs as its conversation. Its page is its
+ * A2UI surface (`interface.surface`) drawn beside that conversation, fed from
+ * it: the question last asked, the answer as it streams, where the turn
+ * stands. What a block writes — an input's `value` — stays in the surface's
+ * data model at a path the application takes, and what a button does reaches
+ * the application through the chat's own channels: a message sent, the
+ * answer stopped, the conversation started over. Nothing here is a server
+ * API; a setting reaches the application in the words of the message it is
+ * sent with, until the session API carries a settings change (R-04).
+ *
+ * A decision is not here: its page is drawn by the Studio's run page, with
+ * its own paths (`INTERFACE_PATHS`), until it moves onto the workspace (R-02).
+ *
+ * Pure: the plugin (`./index`) and its view (`./AppPage`) do the drawing.
+ *
+ * @module loop/plugins/app-page/appPage
+ */
+import type { AppSettingSpec, AppSpec } from '../../../types/agentspecs';
+import type { ChatTurnSnapshot } from '../../core';
+/** The id of the editor surface an application's page is drawn in. */
+export declare const APP_PAGE_SURFACE = "app-page";
+/** The id of the A2UI surface itself, inside it. */
+export declare const APP_PAGE_SURFACE_ID = "app";
+/** The kinds that run as their conversation and may have a page drawn by it. */
+export type AppPageKind = 'chat' | 'widget' | 'worker';
+/**
+ * One thing an application publishes to its page, or takes from it, by
+ * path. The shape of the Studio's `InterfacePath`, so that the Canvas reads
+ * this list as it reads a decision's.
+ */
+export type AppPagePath = {
+    path: string;
+    /** What it is, for a composer. */
+    meaning: string;
+    /** What it is, for a person choosing it on the Canvas. */
+    words: string;
+    list?: boolean;
+};
+/** What a Button on the page may do: the Studio's `InterfaceAction`. */
+export type AppPageAction = {
+    name: string;
+    meaning: string;
+    words: string;
+    /** The keys its context may carry. */
+    context: string[];
+    /** Each key, in words. */
+    asks: Record<string, string>;
+};
+/** What one kind gives its page and takes from it. */
+export type AppKindPaths = {
+    /** What a block may show. */
+    publishes: AppPagePath[];
+    /** Where what a block writes is read. */
+    accepts: AppPagePath[];
+    /** What a Button may do. */
+    actions: AppPageAction[];
+    /**
+     * Whether each of the application's settings (`interface.settings`) is
+     * also published and taken, at `/inputs/<id>` — see {@link appKindPaths}.
+     */
+    inputs: boolean;
+};
+/**
+ * What each kind publishes to its page and takes from it, by path — the
+ * least that is real today, read from the conversation it runs as.
+ */
+export declare const APP_KIND_PATHS: Record<AppPageKind, AppKindPaths>;
+/** Whether a kind runs as its conversation and has its paths here. */
+export declare const isAppPageKind: (kind: string) => kind is AppPageKind;
+/** The path a setting, an input of the page, is kept at. */
+export declare const inputPath: (id: string) => string;
+/**
+ * What an application publishes and takes, with its own settings: the kind's
+ * list, and for a kind that has inputs each setting at `/inputs/<id>`, both
+ * shown and written. Empty lists for a decision, or a kind not known.
+ */
+export declare function appKindPaths(app: Pick<AppSpec, 'kind' | 'interface'>): AppKindPaths;
+/**
+ * Whether the workspace draws the application's page: a chat, a widget or a
+ * worker whose layout has one (`page`, `split`). A `chat` layout is the
+ * conversation alone: a surface composed for it is not drawn, which
+ * `surfaceUnshown` says in a sentence.
+ */
+export declare function hasAppPage(app: Pick<AppSpec, 'kind' | 'interface' | 'agent'>): boolean;
+/**
+ * Why a composed surface is not drawn, or `null` when it is (or there is
+ * none): the application's layout is `chat`, the conversation alone.
+ */
+export declare function surfaceUnshown(app: Pick<AppSpec, 'kind' | 'interface' | 'agent'>): string | null;
+/** A setting's first value, as its input holds it. */
+export declare function initialInput(setting: AppSettingSpec): unknown;
+/** What the conversation publishes to the page, by path, now. */
+export declare function appPageData(app: Pick<AppSpec, 'kind' | 'name' | 'goal'>, turn: ChatTurnSnapshot): Record<string, unknown>;
+/** The page's data model when it is drawn: what is published, the inputs, the draft. */
+export declare function appPageInitialData(app: Pick<AppSpec, 'kind' | 'name' | 'goal' | 'interface'>): Record<string, unknown>;
+/**
+ * The inputs written on the page, in words, one per line: each setting by
+ * its label, then any other value a block wrote under `/inputs` by its id.
+ */
+export declare function inputsInWords(app: Pick<AppSpec, 'interface'>, inputs: unknown): string;
+/** What a button asked, as the surface hands it over. */
+export type AppPageEvent = {
+    name: string;
+    context?: Record<string, unknown>;
+};
+/** What the page does about a button: at most one of these. */
+export type AppPageOutcome = {
+    /** A message for the application, sent as the person's next turn. */
+    send: string;
+    /** The inputs in words as sent, to tell a change next time. */
+    inputs: string;
+    /** Paths to empty once it is sent. */
+    clear: string[];
+} | {
+    stop: true;
+} | {
+    newChat: true;
+} | {
+    refused: string;
+};
+/**
+ * What a button pressed on the page does.
+ *
+ * `read` gives what is in the surface's data model at a path; `lastInputs`
+ * is the inputs in words as last sent, so that a chat's message carries its
+ * settings only when they changed.
+ */
+export declare function appPageAction(app: Pick<AppSpec, 'kind' | 'name' | 'interface'>, event: AppPageEvent, read: (path: string) => unknown, lastInputs?: string): AppPageOutcome;
+/** A Text, a Button and its label: the parts the default pages are made of. */
+type Component = {
+    id: string;
+    component: string;
+    [key: string]: unknown;
+};
+/**
+ * The page drawn when the application has a page layout and no surface
+ * composed: what its kind publishes, its settings as inputs, and the
+ * buttons its kind handles that the conversation does not already give.
+ */
+export declare function defaultAppSurface(app: Pick<AppSpec, 'kind' | 'interface'>): Component[];
+/**
+ * The A2UI messages that draw the application's page: its surface composed,
+ * or the default page of its kind, fed its first data.
+ */
+export declare function appPageMessages(app: Pick<AppSpec, 'kind' | 'name' | 'goal' | 'interface'>, catalogId: string): ({
+    version: "v0.9";
+    createSurface: {
+        surfaceId: string;
+        catalogId: string;
+    };
+    updateComponents?: undefined;
+    updateDataModel?: undefined;
+} | {
+    version: "v0.9";
+    updateComponents: {
+        surfaceId: string;
+        components: {
+            [property: string]: unknown;
+            id: string;
+            component: string;
+        }[];
+    };
+    createSurface?: undefined;
+    updateDataModel?: undefined;
+} | {
+    version: "v0.9";
+    updateDataModel: {
+        surfaceId: string;
+        path: string;
+        value: Record<string, unknown>;
+    };
+    createSurface?: undefined;
+    updateComponents?: undefined;
+})[];
+export {};