@datalayer/agent-runtimes 1.3.16 → 1.3.18

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

@@ -0,0 +1,24 @@
+import type { ReactorPlugin } from '@datalayer/reactor';
+import type { AppSpec } from '../../types/agentspecs';
+import { type LoopEmbedProps } from '../embed/LoopEmbed';
+/** The id of an agent or a Cog, without its version. */
+export declare const agentIdOf: (app: Pick<AppSpec, "agent" | "team">) => string;
+/**
+ * The plugin that makes a LOOP workspace run an application.
+ *
+ * The agent is created with the application's own document (`app_spec`) in
+ * its payload; a runtime that knows applications configures the agent from
+ * it, and one that does not creates the agent alone — the application is
+ * then shown and not enforced, which is why a hosted application only runs
+ * on a runtime that does.
+ *
+ * An application run by a team is not supported in the workspace yet: a team
+ * is not an agent spec, and is refused here rather than launched as one.
+ */
+export declare function defineAppPlugin(app: AppSpec): ReactorPlugin<Record<string, never>, unknown, unknown>;
+export type AppRendererProps = Omit<LoopEmbedProps, 'agentId'> & {
+    /** The application to render. */
+    app: AppSpec;
+};
+export declare function AppRenderer({ app, plugins, ...embed }: AppRendererProps): React.JSX.Element;
+export default AppRenderer;

package/lib/loop/apps/AppRenderer.js

@@ -0,0 +1,101 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * An application, rendered: the LOOP workspace configured from an Appspec
+ * (LOOP R-01).
+ *
+ * One renderer for every place an application appears — the Studio's
+ * Preview, its hosted page, an embed, the home page — so that what a builder
+ * sees while building is what its users get. It is not a second shell: it is
+ * `LoopEmbed`, given
+ *
+ * - an **application plugin** (`defineAppPlugin`): the agent that answers,
+ *   created with the application in its payload — so the runtime reaches only
+ *   what the application connects to and enforces its rules before every tool
+ *   call — and the application's starters as the openers of the empty chat;
+ * - the **layout of its kind**: a chat is the conversation alone, with the
+ *   A2UI surfaces its answers draw; the other layouts keep the editors.
+ *
+ * @module loop/apps/AppRenderer
+ */
+import { useMemo } from 'react';
+import { defineAgentCapacityPlugin } from '../plugins/agent-capacity';
+import { LoopEmbed } from '../embed/LoopEmbed';
+import { dumpAppspec } from './appspec';
+/** The id of an agent or a Cog, without its version. */
+export const agentIdOf = (app) => {
+    const reference = app.agent || app.team;
+    const at = reference.lastIndexOf(':');
+    return at > 0 && reference.slice(at + 1).includes('.')
+        ? reference.slice(0, at)
+        : reference;
+};
+/**
+ * The plugin that makes a LOOP workspace run an application.
+ *
+ * The agent is created with the application's own document (`app_spec`) in
+ * its payload; a runtime that knows applications configures the agent from
+ * it, and one that does not creates the agent alone — the application is
+ * then shown and not enforced, which is why a hosted application only runs
+ * on a runtime that does.
+ *
+ * An application run by a team is not supported in the workspace yet: a team
+ * is not an agent spec, and is refused here rather than launched as one.
+ */
+export function defineAppPlugin(app) {
+    if (!app.agent) {
+        throw new Error(`“${app.name}” is run by a team, which the workspace does not run as an application yet.`);
+    }
+    return defineAgentCapacityPlugin({
+        key: `app-${app.id}`,
+        displayName: app.name,
+        description: app.description || `The ${app.name} application`,
+        specId: agentIdOf(app),
+        emoji: app.emoji,
+        createPayload: {
+            name: app.id,
+            app_spec: dumpAppspec(app),
+            ...(app.model ? { model: app.model } : {}),
+        },
+        suggestions: app.interface.starters.map(starter => ({
+            text: starter.label,
+            message: starter.message,
+        })),
+    });
+}
+/**
+ * An application in a LOOP workspace: its agent, its starters, its layout.
+ *
+ * Every other prop is `LoopEmbed`'s, and wins over what the application
+ * implies — a host that wants the editors beside a chat still says so.
+ */
+/** No host plugins: one array, so that it never reads as a change. */
+const NO_PLUGINS = [];
+export function AppRenderer({ app, plugins = NO_PLUGINS, ...embed }) {
+    const chatOnly = app.interface.layout === 'chat';
+    /*
+     * The application plugin, made once per application. `LoopEmbed` rebuilds
+     * its whole reactor when its plugins change, so a new plugin on every
+     * render of the host would restart the running workspace. The key is the
+     * application as its file holds it: a change to it is a new application.
+     */
+    const source = JSON.stringify(dumpAppspec(app));
+    const appPlugin = useMemo(() => (app.agent ? defineAppPlugin(app) : null), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [source]);
+    const allPlugins = useMemo(() => (appPlugin ? [appPlugin, ...plugins] : plugins), [appPlugin, plugins]);
+    if (!appPlugin) {
+        return (_jsxs("div", { role: "status", style: { padding: 16 }, children: ["\u201C", app.name, "\u201D is run by a team, which the workspace does not run as an application yet."] }));
+    }
+    return (_jsx(LoopEmbed
+    // The application's own agent: created under its id, so that its
+    // spec is applied to an agent of its own, never to the one it extends.
+    , { 
+        // The application's own agent: created under its id, so that its
+        // spec is applied to an agent of its own, never to the one it extends.
+        agentId: app.id, editors: !chatOnly, showViewSelector: !chatOnly, teamPicker: false, showAgentVariants: false, graph: false, pluginsPanel: false, ...embed, plugins: allPlugins }));
+}
+export default AppRenderer;

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

@@ -0,0 +1,69 @@
+/**
+ * The Appspec as a file, and as the application an editor holds.
+ *
+ * An application is kept as a YAML or JSON document in the spec's own words —
+ * `applies_to`, `ready_at`, `keep_for` — with nothing written that is at its
+ * default. An editor works on the whole of it: an {@link AppSpec} with every
+ * field present, in TypeScript's spelling.
+ *
+ * {@link parseAppspec} reads the first into the second, and
+ * {@link dumpAppspec} writes it back: the same application always writes the
+ * same document, keys in one fixed order — the spec's own where it declares
+ * them, alphabetical where it does not (a scenario's weights, a component of
+ * a surface) — so that a difference between two versions shows what changed
+ * and nothing else. Reading what was written
+ * gives the application back, and writing what was read gives the document
+ * back — which is what lets three editors work on one file.
+ *
+ * Reading is tolerant, because a draft is not yet an application: what is
+ * missing takes its default, and what is wrong is reported beside the result
+ * rather than thrown. Whether the application can be used is decided by the
+ * spec's own validation, not here.
+ *
+ * Pure: nothing here calls a service or renders.
+ *
+ * @module loop/apps/appspec
+ */
+import type { AppAccent, AppKind, AppLayout, AppSpec } from '../../types/agentspecs';
+/** The version of the spec itself. */
+export declare const APP_SCHEMA = "loop.app/v1";
+/** The face of an application that has not chosen one. */
+export declare const DEFAULT_EMOJI = "\uD83D\uDC40";
+export declare const APP_KINDS: AppKind[];
+export declare const APP_ACCENTS: AppAccent[];
+/** The layout a kind starts with. */
+export declare const DEFAULT_LAYOUTS: Record<AppKind, AppLayout>;
+/** What an application keeps of what it did, when it does not say. */
+export declare const DEFAULT_RECORD_INCLUDE: string[];
+type Data = Record<string, unknown>;
+/** A retention as days: `90_days`, `18_months`, `1_years`; 0 when it cannot be read. */
+export declare function retentionDays(keepFor: string): number;
+/** An application with nothing said: what *Start blank* opens. */
+export declare function emptyAppspec(kind?: AppKind): AppSpec;
+/** What reading a document gives: the application, and what the document got wrong. */
+export interface ParsedAppspec {
+    app: AppSpec;
+    /** In sentences; empty when the document reads as it was written. */
+    problems: string[];
+}
+/**
+ * An application from a document in the spec's own words.
+ *
+ * Tolerant: what is missing takes its default, and what cannot be read is
+ * reported in `problems` — a key the spec does not know, a version of the
+ * spec this does not read, a kind that is not one. The application returned
+ * is always whole, so an editor can open it and show what is wrong.
+ */
+export declare function parseAppspec(document: unknown): ParsedAppspec;
+/**
+ * An application as the document its file holds.
+ *
+ * The spec's own words, keys in one fixed order, nothing written that is at
+ * its default: the same application always writes the same document. What an
+ * application carries that is not the spec's — what it needs set up — is left
+ * out.
+ */
+export declare function dumpAppspec(app: AppSpec): Data;
+/** The keys of a document in the order they are written. */
+export declare const APPSPEC_KEY_ORDER: readonly string[];
+export {};