@datalayer/agent-runtimes 1.3.18 → 1.3.20

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

@@ -20,5 +20,14 @@ export type AppRendererProps = Omit<LoopEmbedProps, 'agentId'> & {
     /** The application to render. */
     app: AppSpec;
 };
+/**
+ * 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. */
+/** The agentspec a runtime is allocated with before an application's agent is created on it. */
+export declare const DATALAYER_BOOTSTRAP_AGENTSPEC = "example-simple";
 export declare function AppRenderer({ app, plugins, ...embed }: AppRendererProps): React.JSX.Element;
 export default AppRenderer;

package/lib/loop/apps/AppRenderer.js

@@ -73,6 +73,8 @@ export function defineAppPlugin(app) {
  * 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. */
+/** The agentspec a runtime is allocated with before an application's agent is created on it. */
+export const DATALAYER_BOOTSTRAP_AGENTSPEC = 'example-simple';
 const NO_PLUGINS = [];
 export function AppRenderer({ app, plugins = NO_PLUGINS, ...embed }) {
     const chatOnly = app.interface.layout === 'chat';
@@ -87,6 +89,28 @@ export function AppRenderer({ app, plugins = NO_PLUGINS, ...embed }) {
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [source]);
     const allPlugins = useMemo(() => (appPlugin ? [appPlugin, ...plugins] : plugins), [appPlugin, plugins]);
+    /*
+     * On Datalayer, the application runs on a runtime: allocated with a plain
+     * agentspec, its agent created there with the application's spec — so that
+     * the runtime registers it and decides every tool call by its rules (LOOP
+     * R-03, R-05), as `loop apps run --cloud` does.
+     */
+    const datalayerCreatePayload = useMemo(() => app.agent
+        ? {
+            // Under the application's id, over AG-UI: what the workspace's
+            // chat addresses (`agentId` below).
+            name: app.id,
+            transport: 'ag-ui',
+            agent_spec_id: agentIdOf(app),
+            app_spec: dumpAppspec(app),
+            // Code Mode calls every tool through `execute_code`, which an
+            // application without a shell is refused: its tools are called
+            // one by one instead, each decided by its rules.
+            enable_codemode: Boolean(app.permissions?.computer?.shell),
+        }
+        : undefined, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [source]);
     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."] }));
     }
@@ -96,6 +120,9 @@ export function AppRenderer({ app, plugins = NO_PLUGINS, ...embed }) {
     , { 
         // 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 }));
+        agentId: app.id, editors: !chatOnly, showViewSelector: !chatOnly, teamPicker: false, showAgentVariants: false, graph: false, pluginsPanel: false, datalayerAgentSpecId: DATALAYER_BOOTSTRAP_AGENTSPEC, 
+        // Where an application runs is decided by its host — the Studio's
+        // Preview, the hosted page — not offered to its user.
+        targetFixed: true, datalayerCreatePayload: datalayerCreatePayload, ...embed, plugins: allPlugins }));
 }
 export default AppRenderer;

package/lib/loop/embed/LoopEmbed.js

@@ -63,6 +63,10 @@ export function LoopEmbed({ agentId = '', showHeader = false, chatHeaderActions,
     [
         preset.serverUrl,
         preset.target,
+        preset.datalayerAgentSpecId,
+        preset.targetFixed,
+        // By its content: an application's spec written inline is a new object each render.
+        JSON.stringify(preset.datalayerCreatePayload ?? null),
         preset.defaultEditor,
         preset.showViewSelector,
         preset.hideChatHeader,

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

@@ -19,8 +19,9 @@ import { useOptionalSandboxService } from './useSandboxService';
 const DEFAULT_DATALAYER_AGENTSPEC = 'jupyter-tutor';
 export function DatalayerAgentBridge() {
     const reactor = useReactorPlatform();
-    const agentSpecId = reactor.getConfig(AGENTS_PLUGIN_NAME)?.datalayerAgentSpecId ??
-        DEFAULT_DATALAYER_AGENTSPEC;
+    const agentsConfig = reactor.getConfig(AGENTS_PLUGIN_NAME);
+    const agentSpecId = agentsConfig?.datalayerAgentSpecId ?? DEFAULT_DATALAYER_AGENTSPEC;
+    const createPayload = agentsConfig?.datalayerCreatePayload;
     const service = useOptionalSandboxService();
     const target = useSignalValue(service?.target ?? IDLE_SANDBOX_TARGET_SIGNAL);
     const onDatalayer = target === 'datalayer';
@@ -45,12 +46,21 @@ export function DatalayerAgentBridge() {
      * spec id in it and hands that over. Same thing, said in the place the
      * creation actually looks.
      */
+    // An application names its own agent and transport; a bare spec, the spec's.
+    const agentName = typeof createPayload?.name === 'string' ? createPayload.name : agentSpecId;
+    const protocol = createPayload?.transport === 'ag-ui' ||
+        createPayload?.transport === 'vercel-ai'
+        ? createPayload.transport
+        : undefined;
     const agentConfig = useMemo(() => ({
-        name: agentSpecId,
+        name: agentName,
+        ...(protocol ? { protocol } : {}),
         agentSpecId,
         model: AGENTSPECS[agentSpecId]?.model,
         description: AGENTSPECS[agentSpecId]?.description,
-    }), [agentSpecId]);
+        // An application's spec, when the workspace runs one.
+        ...(createPayload ? { createPayload } : {}),
+    }), [agentSpecId, agentName, protocol, createPayload]);
     const { runtime, status, error } = useAgentRuntimes({
         agentSpecId,
         agentConfig,

package/lib/loop/plugins/agents/plugin.d.ts

@@ -73,6 +73,18 @@ export type AgentsConfig = {
      * The other targets take their agent from wherever they already run one.
      */
     datalayerAgentSpecId?: string;
+    /**
+     * What the agent created on that runtime is created with besides its spec:
+     * an application's `app_spec`, so that the runtime runs the application and
+     * decides its tool calls by its rules (LOOP R-05, R-03).
+     */
+    datalayerCreatePayload?: Record<string, unknown>;
+    /**
+     * The target is the host's decision, not the reader's: started there even
+     * with the control hidden. For an application that runs where it is
+     * deployed; a workspace leaves it unset.
+     */
+    targetFixed?: boolean;
 };
 export type AgentsOutput = {
     sandbox: SwitchableSandboxService;

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

@@ -57,8 +57,10 @@ export const AgentsPlugin = definePlugin({
             sandbox: createSwitchableSandboxService({
                 serverUrl: config.serverUrl,
                 // Pinned when there is no choice to make: a host that hid the control
-                // must not be started on a target the reader cannot move off.
-                initialTarget: showVariants ? config.target : 'browser',
+                // must not be started on a target the reader cannot move off — unless
+                // the host fixed the target itself, as an application deployed on
+                // Datalayer is (AppRenderer): there is nothing for the reader to move.
+                initialTarget: showVariants || config.targetFixed ? config.target : 'browser',
                 kernelSource: config.kernelSource,
                 localAgent: config.localAgent,
                 // The capacity plugins' say, read at switch time — lazily, because a

package/lib/loop/presets.d.ts

@@ -120,6 +120,12 @@ export type LoopPresetOptions = {
     teamId?: string;
     /** What a local agent is created from, when one is. */
     localAgent?: AgentsConfig['localAgent'];
+    /** The agentspec a Datalayer runtime is allocated with (the `datalayer` target). */
+    datalayerAgentSpecId?: string;
+    /** What the agent on that runtime is created with besides its spec — an `app_spec`. */
+    datalayerCreatePayload?: Record<string, unknown>;
+    /** The target is the host's to fix, even with the agent control hidden. */
+    targetFixed?: boolean;
     /**
      * The agentspec the local agent is created from, by id.
      *

package/lib/loop/presets.js

@@ -52,7 +52,7 @@ import { LoopPageLayoutPlugin } from './plugins/page-layout';
  * be installed or signed into, and the switches a demonstration wants are off.
  */
 export function loopPlugins(options = {}) {
-    const { serverUrl, target = 'browser', defaultEditor = 'notebook', showViewSelector = true, hideChatHeader = false, chatHeaderButtons = false, promptPlacement, autoFocusPrompt = true, suggestionLabels = true, fullScreenTopOffset = 0, showAgentVariants = false, agentSummary = true, teamId, teamPicker = true, pageLayout = false, pageLayoutTurnPanel = 'below', pageLayoutPrompt = 'docked', pageLayoutPromptAnchor = 'top', pageLayoutSize, pageLayoutTurnPanelFooter = 'full', localAgent, localAgentSpec, floatingPrompt = false, editorSelector = false, editors = true, graph = false, commandPalette = false, pluginsPanel = false, windowFrame = false, firstPromptHook, } = options;
+    const { serverUrl, target = 'browser', defaultEditor = 'notebook', showViewSelector = true, hideChatHeader = false, chatHeaderButtons = false, promptPlacement, autoFocusPrompt = true, suggestionLabels = true, fullScreenTopOffset = 0, showAgentVariants = false, agentSummary = true, teamId, teamPicker = true, pageLayout = false, pageLayoutTurnPanel = 'below', pageLayoutPrompt = 'docked', pageLayoutPromptAnchor = 'top', pageLayoutSize, pageLayoutTurnPanelFooter = 'full', localAgent, localAgentSpec, datalayerAgentSpecId, datalayerCreatePayload, targetFixed, floatingPrompt = false, editorSelector = false, editors = true, graph = false, commandPalette = false, pluginsPanel = false, windowFrame = false, firstPromptHook, } = options;
     return [
         // The chat owns the editor beside it, so which one opens is its
         // configuration rather than the workspace's.
@@ -88,6 +88,9 @@ export function loopPlugins(options = {}) {
         configurePlugin(AgentsPlugin, {
             serverUrl,
             target,
+            datalayerAgentSpecId,
+            datalayerCreatePayload,
+            targetFixed,
             showAgentVariants,
             showAgentSummary: agentSummary,
             teamId,

package/lib/specs/appspecSchema.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The Appspec's JSON Schema, generated from agentspecs by
+ * `scripts/codegen/generate_apps.py`. Do not edit.
+ *
+ * @module specs/appspecSchema
+ */
+export type JsonSchema = {
+    [key: string]: unknown;
+    type?: string;
+    description?: string;
+    properties?: Record<string, JsonSchema>;
+    items?: JsonSchema;
+    enum?: readonly unknown[];
+    anyOf?: readonly JsonSchema[];
+    $ref?: string;
+    $defs?: Record<string, JsonSchema>;
+};
+export declare const APPSPEC_SCHEMA: JsonSchema;

package/lib/specs/appspecSchema.js

@@ -0,0 +1,982 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export const APPSPEC_SCHEMA = {
+    $defs: {
+        Accent: {
+            description: 'The one colour of an application; everything else is neutral.',
+            enum: ['green', 'rose', 'sky', 'lime', 'sun', 'violet'],
+            title: 'Accent',
+            type: 'string',
+        },
+        Access: {
+            description: 'How far a connection goes.',
+            enum: ['read', 'write'],
+            title: 'Access',
+            type: 'string',
+        },
+        ActsAs: {
+            description: 'In whose name a connection acts.',
+            enum: ['owner', 'user'],
+            title: 'ActsAs',
+            type: 'string',
+        },
+        AppChecks: {
+            additionalProperties: false,
+            description: 'Optional: checks from the catalogue, for a builder who wants them.',
+            properties: {
+                guards: {
+                    description: 'Guards, `id` or `id:version`',
+                    items: {
+                        type: 'string',
+                    },
+                    title: 'Guards',
+                    type: 'array',
+                },
+                gates: {
+                    description: 'Gates, `id` or `id:version`',
+                    items: {
+                        type: 'string',
+                    },
+                    title: 'Gates',
+                    type: 'array',
+                },
+                track: {
+                    default: '',
+                    description: 'A Track, `id` or `id:version`',
+                    title: 'Track',
+                    type: 'string',
+                },
+            },
+            title: 'AppChecks',
+            type: 'object',
+        },
+        AppComputer: {
+            additionalProperties: false,
+            description: 'What the application may do on its own computer. Each is off until it is turned on.',
+            properties: {
+                browse: {
+                    default: false,
+                    description: 'Open pages in a browser',
+                    title: 'Browse',
+                    type: 'boolean',
+                },
+                files: {
+                    default: false,
+                    description: 'Read and write files',
+                    title: 'Files',
+                    type: 'boolean',
+                },
+                shell: {
+                    default: false,
+                    description: 'Run commands',
+                    title: 'Shell',
+                    type: 'boolean',
+                },
+            },
+            title: 'AppComputer',
+            type: 'object',
+        },
+        AppConnection: {
+            additionalProperties: false,
+            description: 'Something the application reaches.',
+            properties: {
+                server: {
+                    description: 'An MCP server of the catalogue, `id` or `id:version`',
+                    title: 'Server',
+                    type: 'string',
+                },
+                access: {
+                    $ref: '#/$defs/Access',
+                    default: 'read',
+                    description: 'How far: `read`, or `write`',
+                },
+                as: {
+                    $ref: '#/$defs/ActsAs',
+                    default: 'owner',
+                    description: "In whose name: `owner` (the builder's account) or `user` (each user's own)",
+                },
+                only: {
+                    description: 'The tools of the server the application may use, by name or pattern (`*gmail*`: `*` is any run of characters, `?` any one); all of them when empty. A tool left out is not reached at all',
+                    items: {
+                        type: 'string',
+                    },
+                    title: 'Only',
+                    type: 'array',
+                },
+            },
+            required: ['server'],
+            title: 'AppConnection',
+            type: 'object',
+        },
+        AppCriterion: {
+            additionalProperties: false,
+            description: 'What an alternative is judged on.',
+            properties: {
+                name: {
+                    description: 'Its name',
+                    title: 'Name',
+                    type: 'string',
+                },
+                kind: {
+                    $ref: '#/$defs/CriterionKind',
+                    default: 'metric',
+                    description: '`metric`, `noul`, `choice`, `score`',
+                },
+                weight: {
+                    default: 1,
+                    description: 'How much it counts',
+                    minimum: 0,
+                    title: 'Weight',
+                    type: 'number',
+                },
+                instructions: {
+                    default: '',
+                    description: 'What a judgment model is asked, or how a metric is computed',
+                    title: 'Instructions',
+                    type: 'string',
+                },
+                options: {
+                    description: 'For a choice or a score: from the worst to the best',
+                    items: {
+                        type: 'string',
+                    },
+                    title: 'Options',
+                    type: 'array',
+                },
+                direction: {
+                    default: 'higher',
+                    description: 'Whether more counts for, or against',
+                    pattern: '^(higher|lower)$',
+                    title: 'Direction',
+                    type: 'string',
+                },
+                measure: {
+                    default: '',
+                    description: 'For a metric: what a benchmark run fills it from',
+                    pattern: '^(|pass_rate|cost_per_task|seconds_per_task)$',
+                    title: 'Measure',
+                    type: 'string',
+                },
+            },
+            required: ['name'],
+            title: 'AppCriterion',
+            type: 'object',
+        },
+        AppDecision: {
+            additionalProperties: false,
+            description: 'What a decision application decides.',
+            properties: {
+                question: {
+                    description: 'The question it answers',
+                    title: 'Question',
+                    type: 'string',
+                },
+                alternatives: {
+                    description: 'What is chosen between',
+                    items: {
+                        type: 'string',
+                    },
+                    title: 'Alternatives',
+                    type: 'array',
+                },
+                criteria: {
+                    description: 'What each is judged on',
+                    items: {
+                        $ref: '#/$defs/AppCriterion',
+                    },
+                    title: 'Criteria',
+                    type: 'array',
+                },
+                min_confidence: {
+                    default: 0,
+                    description: 'A judgment less confident than this is put to the reader',
+                    maximum: 1,
+                    minimum: 0,
+                    title: 'Min Confidence',
+                    type: 'number',
+                },
+                scenarios: {
+                    description: 'Named sets of weights',
+                    items: {
+                        $ref: '#/$defs/AppScenario',
+                    },
+                    title: 'Scenarios',
+                    type: 'array',
+                },
+                judgment_model: {
+                    default: '',
+                    description: 'The model that answers the judgments',
+                    title: 'Judgment Model',
+                    type: 'string',
+                },
+            },
+            required: ['question'],
+            title: 'AppDecision',
+            type: 'object',
+        },
+        AppDeployment: {
+            additionalProperties: false,
+            description: 'Where the application goes.',
+            properties: {
+                hosted: {
+                    anyOf: [
+                        {
+                            $ref: '#/$defs/HostedDeployment',
+                        },
+                        {
+                            type: 'null',
+                        },
+                    ],
+                    default: null,
+                    description: 'At an address of its own',
+                },
+                embedded: {
+                    anyOf: [
+                        {
+                            $ref: '#/$defs/EmbeddedDeployment',
+                        },
+                        {
+                            type: 'null',
+                        },
+                    ],
+                    default: null,
+                    description: 'Inside another product',
+                },
+            },
+            title: 'AppDeployment',
+            type: 'object',
+        },
+        AppInterface: {
+            additionalProperties: false,
+            description: 'What the user sees.',
+            properties: {
+                layout: {
+                    anyOf: [
+                        {
+                            $ref: '#/$defs/Layout',
+                        },
+                        {
+                            type: 'null',
+                        },
+                    ],
+                    default: null,
+                    description: "`chat`, `page` or `split`; the kind's own when unsaid",
+                },
+                accent: {
+                    $ref: '#/$defs/Accent',
+                    default: 'green',
+                    description: "The application's one colour",
+                },
+                welcome: {
+                    default: '',
+                    description: 'What the application says first',
+                    title: 'Welcome',
+                    type: 'string',
+                },
+                starters: {
+                    description: 'First messages offered to the user',
+                    items: {
+                        $ref: '#/$defs/AppStarter',
+                    },
+                    title: 'Starters',
+                    type: 'array',
+                },
+                settings: {
+                    description: 'What the user may set',
+                    items: {
+                        $ref: '#/$defs/AppSetting',
+                    },
+                    title: 'Settings',
+                    type: 'array',
+                },
+                components: {
+                    description: "The components of the catalog the surface may use; the kind's own when empty",
+                    items: {
+                        type: 'string',
+                    },
+                    title: 'Components',
+                    type: 'array',
+                },
+                surface: {
+                    anyOf: [
+                        {
+                            $ref: '#/$defs/AppSurface',
+                        },
+                        {
+                            type: 'null',
+                        },
+                    ],
+                    default: null,
+                    description: 'The component tree, when there is one',
+                },
+            },
+            title: 'AppInterface',
+            type: 'object',
+        },
+        AppKind: {
+            description: 'What kind of application it is: what its user meets.',
+            enum: ['chat', 'widget', 'decision', 'worker'],
+            title: 'AppKind',
+            type: 'string',
+        },
+        AppPermissions: {
+            additionalProperties: false,
+            description: 'What the application may reach beside its connections. Nothing, unless said.',
+            properties: {
+                spaces: {
+                    description: 'The Spaces it reads or writes',
+                    items: {
+                        $ref: '#/$defs/AppSpaceGrant',
+                    },
+                    title: 'Spaces',
+                    type: 'array',
+                },
+                computer: {
+                    $ref: '#/$defs/AppComputer',
+                    description: 'Its computer: browse, files, shell',
+                },
+            },
+            title: 'AppPermissions',
+            type: 'object',
+        },
+        AppRecord: {
+            additionalProperties: false,
+            description: 'What is kept of what the application did, and for how long.',
+            properties: {
+                keep_for: {
+                    default: '1_years',
+                    description: 'How long: `90_days`, `18_months`, `1_years`',
+                    title: 'Keep For',
+                    type: 'string',
+                },
+                include: {
+                    description: 'What is kept',
+                    items: {
+                        $ref: '#/$defs/RecordItem',
+                    },
+                    title: 'Include',
+                    type: 'array',
+                },
+            },
+            title: 'AppRecord',
+            type: 'object',
+        },
+        AppRule: {
+            additionalProperties: false,
+            description: 'When the application acts alone, and when it asks.',
+            properties: {
+                action: {
+                    description: 'The action, in the words a person reads: `Send an email`',
+                    title: 'Action',
+                    type: 'string',
+                },
+                applies_to: {
+                    anyOf: [
+                        {
+                            type: 'string',
+                        },
+                        {
+                            items: {
+                                type: 'string',
+                            },
+                            type: 'array',
+                        },
+                    ],
+                    description: 'What the rule applies to: a class of action (`read`, `write`, `send`, `buy`, `delete`, `publish`), or named tools (`server.tool`, or a tool id)',
+                    title: 'Applies To',
+                },
+                behaviour: {
+                    $ref: '#/$defs/Behaviour',
+                    description: '`do_it`, `if_asked`, `ask_first` or `leave_to_me`',
+                },
+            },
+            required: ['action', 'applies_to', 'behaviour'],
+            title: 'AppRule',
+            type: 'object',
+        },
+        AppScenario: {
+            additionalProperties: false,
+            description: 'A named set of weights: one way of looking at the same findings.',
+            properties: {
+                name: {
+                    description: 'Its name',
+                    title: 'Name',
+                    type: 'string',
+                },
+                weights: {
+                    additionalProperties: {
+                        type: 'number',
+                    },
+                    description: 'By criterion name',
+                    title: 'Weights',
+                    type: 'object',
+                },
+            },
+            required: ['name'],
+            title: 'AppScenario',
+            type: 'object',
+        },
+        AppSetting: {
+            additionalProperties: false,
+            description: 'Something the user may set for their session.',
+            properties: {
+                id: {
+                    description: 'The name the application reads it by',
+                    title: 'Id',
+                    type: 'string',
+                },
+                type: {
+                    $ref: '#/$defs/SettingType',
+                    description: '`select`, `text`, `toggle`, `slider` or `number`',
+                },
+                label: {
+                    description: 'What the user reads',
+                    title: 'Label',
+                    type: 'string',
+                },
+                options: {
+                    description: 'For a select: its options',
+                    items: {
+                        type: 'string',
+                    },
+                    title: 'Options',
+                    type: 'array',
+                },
+                default: {
+                    anyOf: [
+                        {
+                            type: 'string',
+                        },
+                        {
+                            type: 'boolean',
+                        },
+                        {
+                            type: 'number',
+                        },
+                        {
+                            type: 'null',
+                        },
+                    ],
+                    default: null,
+                    description: 'Its value at the start',
+                    title: 'Default',
+                },
+                min: {
+                    anyOf: [
+                        {
+                            type: 'number',
+                        },
+                        {
+                            type: 'null',
+                        },
+                    ],
+                    default: null,
+                    description: 'For a slider or a number: the least',
+                    title: 'Min',
+                },
+                max: {
+                    anyOf: [
+                        {
+                            type: 'number',
+                        },
+                        {
+                            type: 'null',
+                        },
+                    ],
+                    default: null,
+                    description: 'For a slider or a number: the most',
+                    title: 'Max',
+                },
+            },
+            required: ['id', 'type', 'label'],
+            title: 'AppSetting',
+            type: 'object',
+        },
+        AppSpaceGrant: {
+            additionalProperties: false,
+            description: 'A Space the application may reach.',
+            properties: {
+                space: {
+                    description: 'The Space, by its handle or its id',
+                    title: 'Space',
+                    type: 'string',
+                },
+                access: {
+                    $ref: '#/$defs/Access',
+                    default: 'read',
+                    description: '`read`, or `write`',
+                },
+            },
+            required: ['space'],
+            title: 'AppSpaceGrant',
+            type: 'object',
+        },
+        AppStarter: {
+            additionalProperties: false,
+            description: 'A first message offered to the user.',
+            properties: {
+                label: {
+                    description: 'What the button says',
+                    title: 'Label',
+                    type: 'string',
+                },
+                message: {
+                    description: 'What is sent when it is chosen',
+                    title: 'Message',
+                    type: 'string',
+                },
+            },
+            required: ['label', 'message'],
+            title: 'AppStarter',
+            type: 'object',
+        },
+        AppSurface: {
+            additionalProperties: false,
+            description: 'The component tree the user meets, over the approved catalog (A2UI).',
+            properties: {
+                protocol: {
+                    default: 'a2ui/v0.9',
+                    description: 'The protocol the tree is written in',
+                    title: 'Protocol',
+                    type: 'string',
+                },
+                components: {
+                    description: "The components, as the protocol's `updateComponents` carries them",
+                    items: {
+                        additionalProperties: true,
+                        type: 'object',
+                    },
+                    title: 'Components',
+                    type: 'array',
+                },
+                composed_by: {
+                    default: '',
+                    description: "Who composed it: a model's id, `developer`, `template`",
+                    title: 'Composed By',
+                    type: 'string',
+                },
+                composed_at: {
+                    default: '',
+                    description: 'When, as an ISO date',
+                    title: 'Composed At',
+                    type: 'string',
+                },
+            },
+            title: 'AppSurface',
+            type: 'object',
+        },
+        AppTestCase: {
+            additionalProperties: false,
+            description: 'An example of what the application should do, in plain words.',
+            properties: {
+                ask: {
+                    description: 'What it is asked',
+                    title: 'Ask',
+                    type: 'string',
+                },
+                expect: {
+                    description: 'What it should do',
+                    title: 'Expect',
+                    type: 'string',
+                },
+            },
+            required: ['ask', 'expect'],
+            title: 'AppTestCase',
+            type: 'object',
+        },
+        AppTests: {
+            additionalProperties: false,
+            description: 'How the application is verified.',
+            properties: {
+                ready_at: {
+                    default: 0.8,
+                    description: 'The share of tests that has to pass for the application to be ready',
+                    maximum: 1,
+                    minimum: 0,
+                    title: 'Ready At',
+                    type: 'number',
+                },
+                evalset: {
+                    default: '',
+                    description: 'An evalset its runs validate against, when one is chosen',
+                    title: 'Evalset',
+                    type: 'string',
+                },
+                cases: {
+                    description: 'Its test conversations',
+                    items: {
+                        $ref: '#/$defs/AppTestCase',
+                    },
+                    title: 'Cases',
+                    type: 'array',
+                },
+            },
+            title: 'AppTests',
+            type: 'object',
+        },
+        AppTrigger: {
+            additionalProperties: false,
+            description: "What starts a worker's work.",
+            properties: {
+                type: {
+                    $ref: '#/$defs/TriggerType',
+                    description: '`schedule`, `event` or `once`',
+                },
+                cron: {
+                    default: '',
+                    description: 'For a schedule: a cron expression, `0 8 * * *`',
+                    title: 'Cron',
+                    type: 'string',
+                },
+                event: {
+                    default: '',
+                    description: 'For an event: its name, `email_received`',
+                    title: 'Event',
+                    type: 'string',
+                },
+                at: {
+                    default: '',
+                    description: 'For once: when, as an ISO date',
+                    title: 'At',
+                    type: 'string',
+                },
+                description: {
+                    default: '',
+                    description: 'What it is, in words: `Every morning at 8`',
+                    title: 'Description',
+                    type: 'string',
+                },
+                prompt: {
+                    default: '',
+                    description: 'What the worker is told when it fires',
+                    title: 'Prompt',
+                    type: 'string',
+                },
+            },
+            required: ['type'],
+            title: 'AppTrigger',
+            type: 'object',
+        },
+        Behaviour: {
+            description: 'What an application does when it meets an action: the four a person chooses from.',
+            enum: ['do_it', 'if_asked', 'ask_first', 'leave_to_me'],
+            title: 'Behaviour',
+            type: 'string',
+        },
+        CriterionKind: {
+            description: 'How a criterion is assessed.',
+            enum: ['metric', 'noul', 'choice', 'score'],
+            title: 'CriterionKind',
+            type: 'string',
+        },
+        EmbedMode: {
+            description: "How an application sits in another product's page.",
+            enum: ['inline', 'bubble', 'panel'],
+            title: 'EmbedMode',
+            type: 'string',
+        },
+        EmbeddedDeployment: {
+            additionalProperties: false,
+            description: "The application inside another product's page.",
+            properties: {
+                mode: {
+                    $ref: '#/$defs/EmbedMode',
+                    default: 'inline',
+                    description: '`inline`, `bubble` or `panel`',
+                },
+                origins: {
+                    description: 'The origins allowed to embed it',
+                    items: {
+                        type: 'string',
+                    },
+                    title: 'Origins',
+                    type: 'array',
+                },
+            },
+            title: 'EmbeddedDeployment',
+            type: 'object',
+        },
+        HostedDeployment: {
+            additionalProperties: false,
+            description: 'The application at an address of its own.',
+            properties: {
+                visibility: {
+                    $ref: '#/$defs/Visibility',
+                    default: 'private',
+                    description: 'Who can open it',
+                },
+                slug: {
+                    default: '',
+                    description: 'The readable part of its address',
+                    title: 'Slug',
+                    type: 'string',
+                },
+            },
+            title: 'HostedDeployment',
+            type: 'object',
+        },
+        Layout: {
+            description: 'How the application is laid out.',
+            enum: ['chat', 'page', 'split'],
+            title: 'Layout',
+            type: 'string',
+        },
+        RecordItem: {
+            description: 'What an application may keep of what it did.',
+            enum: [
+                'conversations',
+                'actions',
+                'decisions',
+                'approvals',
+                'checks',
+                'sources',
+                'outputs',
+                'feedback',
+            ],
+            title: 'RecordItem',
+            type: 'string',
+        },
+        SettingType: {
+            description: 'What a setting is set with.',
+            enum: ['select', 'text', 'toggle', 'slider', 'number'],
+            title: 'SettingType',
+            type: 'string',
+        },
+        TriggerType: {
+            description: 'What starts a worker: the trigger kinds of the catalogue.',
+            enum: ['schedule', 'event', 'once'],
+            title: 'TriggerType',
+            type: 'string',
+        },
+        Visibility: {
+            description: 'Who can open a hosted application.',
+            enum: ['private', 'invited', 'organization', 'link', 'public'],
+            title: 'Visibility',
+            type: 'string',
+        },
+    },
+    additionalProperties: false,
+    description: 'Specification for an application.',
+    properties: {
+        schema: {
+            description: 'The version of the spec itself',
+            title: 'Schema',
+            const: 'loop.app/v1',
+            default: 'loop.app/v1',
+        },
+        id: {
+            description: 'Unique application identifier',
+            title: 'Id',
+            type: 'string',
+        },
+        version: {
+            default: '0.0.1',
+            description: 'Application version',
+            title: 'Version',
+            type: 'string',
+        },
+        name: {
+            description: 'Display name',
+            title: 'Name',
+            type: 'string',
+        },
+        kind: {
+            $ref: '#/$defs/AppKind',
+            description: '`chat`, `widget`, `decision` or `worker`',
+        },
+        description: {
+            default: '',
+            description: 'What it does, in a sentence',
+            title: 'Description',
+            type: 'string',
+        },
+        owner: {
+            default: '',
+            description: 'Who answers for it',
+            title: 'Owner',
+            type: 'string',
+        },
+        agent: {
+            default: '',
+            description: 'The agent or the Cog that does the work, `id` or `id:version`',
+            title: 'Agent',
+            type: 'string',
+        },
+        team: {
+            default: '',
+            description: 'Or a team of them, `id` or `id:version`',
+            title: 'Team',
+            type: 'string',
+        },
+        instructions: {
+            default: '',
+            description: 'What this application tells its agent, on top of its own',
+            title: 'Instructions',
+            type: 'string',
+        },
+        model: {
+            default: '',
+            description: "The model, when it is not the organization's default",
+            title: 'Model',
+            type: 'string',
+        },
+        skills: {
+            description: "Skills it adds to its agent's",
+            items: {
+                type: 'string',
+            },
+            title: 'Skills',
+            type: 'array',
+        },
+        tools: {
+            description: "Tools of the catalogue it adds to its agent's",
+            items: {
+                type: 'string',
+            },
+            title: 'Tools',
+            type: 'array',
+        },
+        context: {
+            description: 'The Frames it works under',
+            items: {
+                type: 'string',
+            },
+            title: 'Context',
+            type: 'array',
+        },
+        contents: {
+            description: 'The documents and datasets it answers from',
+            items: {
+                type: 'string',
+            },
+            title: 'Contents',
+            type: 'array',
+        },
+        connections: {
+            description: 'What it reaches',
+            items: {
+                $ref: '#/$defs/AppConnection',
+            },
+            title: 'Connections',
+            type: 'array',
+        },
+        rules: {
+            description: 'When it acts alone, and when it asks',
+            items: {
+                $ref: '#/$defs/AppRule',
+            },
+            title: 'Rules',
+            type: 'array',
+        },
+        permissions: {
+            $ref: '#/$defs/AppPermissions',
+            description: 'What else it may reach: Spaces, its computer. Nothing, unless said',
+        },
+        interface: {
+            $ref: '#/$defs/AppInterface',
+            description: 'What the user sees',
+        },
+        tests: {
+            $ref: '#/$defs/AppTests',
+            description: 'How it is verified',
+        },
+        record: {
+            $ref: '#/$defs/AppRecord',
+            description: 'What is kept of what it did',
+        },
+        checks: {
+            $ref: '#/$defs/AppChecks',
+            description: 'Optional checks from the catalogue',
+        },
+        deployment: {
+            $ref: '#/$defs/AppDeployment',
+            description: 'Where it goes',
+        },
+        goal: {
+            default: '',
+            description: 'For a worker: what it works toward',
+            title: 'Goal',
+            type: 'string',
+        },
+        triggers: {
+            description: 'For a worker: what starts its work',
+            items: {
+                $ref: '#/$defs/AppTrigger',
+            },
+            title: 'Triggers',
+            type: 'array',
+        },
+        memory: {
+            default: '',
+            description: 'A memory of the catalogue, when it remembers',
+            title: 'Memory',
+            type: 'string',
+        },
+        notifications: {
+            description: 'Where an approval reaches a person',
+            items: {
+                type: 'string',
+            },
+            title: 'Notifications',
+            type: 'array',
+        },
+        decision: {
+            anyOf: [
+                {
+                    $ref: '#/$defs/AppDecision',
+                },
+                {
+                    type: 'null',
+                },
+            ],
+            default: null,
+            description: 'For a decision: what it decides',
+        },
+        enabled: {
+            default: true,
+            description: 'Whether it is offered today',
+            title: 'Enabled',
+            type: 'boolean',
+        },
+        tags: {
+            items: {
+                type: 'string',
+            },
+            title: 'Tags',
+            type: 'array',
+        },
+        icon: {
+            default: 'apps',
+            description: 'Icon identifier',
+            title: 'Icon',
+            type: 'string',
+        },
+        emoji: {
+            default: '👀',
+            description: 'Its face: one emoji, shown wherever the application appears',
+            title: 'Emoji',
+            type: 'string',
+        },
+        avatar: {
+            default: '',
+            description: 'Its avatar, by name: a drawing of the set people choose theirs from on their profile. Its emoji stands for it when unsaid, and where only text goes',
+            pattern: '^\\s*([A-Z][A-Za-z0-9]{0,63})?\\s*$',
+            title: 'Avatar',
+            type: 'string',
+        },
+        banner: {
+            default: '',
+            description: 'Its banner, by name, from the set people choose theirs from on their profile. The one its id seeds when unsaid',
+            pattern: '^\\s*([A-Z][A-Za-z0-9]{0,63})?\\s*$',
+            title: 'Banner',
+            type: 'string',
+        },
+    },
+    required: ['id', 'name', 'kind'],
+    title: 'Appspec',
+    type: 'object',
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: 'https://agentspecs.datalayer.tech/schemas/loop.app/v1.json',
+};

package/lib/specs/index.d.ts

@@ -27,3 +27,4 @@ export * from './tracks';
 export * from './ops';
 export * from './apps';
 export * from './actions';
+export * from './appspecSchema';

package/lib/specs/index.js

@@ -31,3 +31,4 @@ export * from './tracks';
 export * from './ops';
 export * from './apps';
 export * from './actions';
+export * from './appspecSchema';

package/package.json

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

package/scripts/codegen/generate_apps.py

@@ -415,6 +415,49 @@ def _drop_nulls(value: Any) -> Any:
     return value
 
 
+def generate_schema_typescript_code() -> str:
+    """The Appspec's JSON Schema, for the editors of the page (LOOP S-01, S-02).
+
+    Taken from the agentspecs the catalogue is generated from, so that what
+    an editor completes and explains is what the spec accepts.
+    """
+    from agentspecs.apps import json_schema
+
+    schema = json.dumps(json_schema(), indent=2, ensure_ascii=False, sort_keys=False)
+    return "\n".join(
+        [
+            "/*",
+            " * Copyright (c) 2025-2026 Datalayer, Inc.",
+            " * Distributed under the terms of the Modified BSD License.",
+            " */",
+            "",
+            "/**",
+            " * The Appspec's JSON Schema, generated from agentspecs by",
+            " * `scripts/codegen/generate_apps.py`. Do not edit.",
+            " *",
+            " * @module specs/appspecSchema",
+            " */",
+            "",
+            "/* eslint-disable */",
+            "",
+            "export type JsonSchema = {",
+            "  [key: string]: unknown;",
+            "  type?: string;",
+            "  description?: string;",
+            "  properties?: Record<string, JsonSchema>;",
+            "  items?: JsonSchema;",
+            "  enum?: readonly unknown[];",
+            "  anyOf?: readonly JsonSchema[];",
+            "  $ref?: string;",
+            "  $defs?: Record<string, JsonSchema>;",
+            "};",
+            "",
+            f"export const APPSPEC_SCHEMA: JsonSchema = {schema};",
+            "",
+        ]
+    )
+
+
 def main() -> None:
     """Generate the application catalogue and the action classes."""
     parser = argparse.ArgumentParser(
@@ -439,6 +482,10 @@ def main() -> None:
         ),
         (args.actions_python_output, generate_actions_python_code(actions)),
         (args.actions_typescript_output, generate_actions_typescript_code(actions)),
+        (
+            args.typescript_output.with_name("appspecSchema.ts"),
+            generate_schema_typescript_code(),
+        ),
     ]
     for path, text in outputs:
         path.parent.mkdir(parents=True, exist_ok=True)