@datalayer/agent-runtimes 1.3.29 → 1.3.32

package/lib/loop/apps/AppRenderer.js

@@ -16,15 +16,30 @@ import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
  *   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.
+ * - its **layout**, as `interface.layout` says (`appLayoutOptions`, LOOP
+ *   T-07), on the workspace's own `page-layout` plugin: `chat` is the
+ *   conversation alone, with the A2UI surfaces its answers draw; `page` is
+ *   the page on a sheet with the composer over it and the conversation in a
+ *   panel the composer's display modes open; `split` is the conversation and
+ *   the page side by side, a hairline between them to drag;
+ * - its **page**, when it has one (`hasAppPage`: a chat, a widget or a worker
+ *   with a `page` or `split` layout): its A2UI surface drawn by the
+ *   `app-page` plugin, in place of the notebook and the document, fed from
+ *   the conversation and answered through it (`APP_KIND_PATHS`). A
+ *   decision's page stays the Studio's run page (R-02); its layout keeps the
+ *   editors;
+ * - its **frame**, when the host asks (`frame`): the `window-frame` plugin's
+ *   window, its title the application's face and name.
  *
  * @module loop/apps/AppRenderer
  */
 import { useMemo } from 'react';
 import { defineAgentCapacityPlugin } from '../plugins/agent-capacity';
+import { APP_PAGE_SURFACE, defineAppPagePlugin, hasAppPage, } from '../plugins/app-page';
 import { LoopEmbed } from '../embed/LoopEmbed';
 import { dumpAppspec } from './appspec';
+import { defineAppFeedbackPlugin } from './AppFeedback';
+import { keepsFeedback } from './feedback';
 /** The id of an agent or a Cog, without its version. */
 export const agentIdOf = (app) => {
     const reference = app.agent || app.team;
@@ -64,8 +79,75 @@ export function defineAppPlugin(app) {
             text: starter.label,
             message: starter.message,
         })),
+        // In the page, the agent is told what a runtime tells it: its own
+        // spec's prompt, then the application's instructions; on the
+        // application's model when it names one (`loop/apps/agent`).
+        instructions: app.instructions,
+        model: app.model,
     });
 }
+/**
+ * The workspace an application's layout asks for (LOOP T-07).
+ *
+ * - `chat`: the conversation alone — no editor, no page, no strip.
+ * - `page`: the page layout — its page (or, without one, the editors) on the
+ *   sheet; the composer a card over it, starting at the bottom, whose display
+ *   modes put it in the conversation panel beside, over or in the corner of
+ *   the page; the current turn under the composer, its copy and dismiss only.
+ * - `split`: the page layout's split — the conversation on the left with its
+ *   composer, the page on the right, a hairline between them to drag.
+ *
+ * With a page, the page is the one editor, opened, without a strip to swap
+ * it; without one (a decision, whose page is the Studio's), the editors stay.
+ */
+export function appLayoutOptions(app) {
+    const layout = app.interface.layout;
+    if (layout === 'chat') {
+        return { editors: false, showViewSelector: false };
+    }
+    const withPage = hasAppPage(app);
+    return {
+        editors: !withPage,
+        showViewSelector: !withPage,
+        ...(withPage ? { defaultEditor: APP_PAGE_SURFACE } : {}),
+        pageLayout: true,
+        pageLayoutArrangement: layout === 'split' ? 'split' : 'page',
+        pageLayoutPrompt: 'floating',
+        pageLayoutPromptAnchor: 'bottom',
+        pageLayoutTurnPanelFooter: 'actions',
+    };
+}
+/**
+ * What an application's agent is created with on a Datalayer runtime: under
+ * the application's id, over AG-UI, with the application's own document —
+ * 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. One payload for every
+ * place it runs: the workspace (`AppRenderer`) and the embed's floating
+ * modes (`AppEmbed`).
+ */
+export function appDatalayerCreatePayload(app, instance) {
+    return {
+        // Under the application's id, over AG-UI: what the workspace's
+        // chat addresses (`AppRenderer` gives it as `agentId`).
+        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),
+        ...(instance
+            ? {
+                app_instance: {
+                    app_uid: instance.appUid ?? '',
+                    deployment_uid: instance.deploymentUid ?? '',
+                    version: instance.version ?? 0,
+                },
+            }
+            : {}),
+    };
+}
 /**
  * An application in a LOOP workspace: its agent, its starters, its layout.
  *
@@ -76,8 +158,7 @@ export function defineAppPlugin(app) {
 /** 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, instance, onPresence, ...embed }) {
-    const chatOnly = app.interface.layout === 'chat';
+export function AppRenderer({ app, plugins = NO_PLUGINS, instance, onPresence, frame = false, ...embed }) {
     /*
      * The application plugin, made once per application. `LoopEmbed` rebuilds
      * its whole reactor when its plugins change, so a new plugin on every
@@ -88,36 +169,33 @@ export function AppRenderer({ app, plugins = NO_PLUGINS, instance, onPresence, .
     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]);
+    const withPage = hasAppPage(app);
+    const pagePlugin = useMemo(() => (withPage ? defineAppPagePlugin(app) : null), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [source, withPage]);
+    /*
+     * A thumb and a comment on each answer, kept in its record (LOOP V-18):
+     * only for an application whose record keeps feedback.
+     */
+    const keeps = keepsFeedback(app);
+    const feedbackPlugin = useMemo(() => (keeps ? defineAppFeedbackPlugin(app) : null), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [source, keeps]);
+    const allPlugins = useMemo(() => appPlugin
+        ? [
+            appPlugin,
+            ...(pagePlugin ? [pagePlugin] : []),
+            ...(feedbackPlugin ? [feedbackPlugin] : []),
+            ...plugins,
+        ]
+        : plugins, [appPlugin, pagePlugin, feedbackPlugin, 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),
-            ...(instance
-                ? {
-                    app_instance: {
-                        app_uid: instance.appUid ?? '',
-                        deployment_uid: instance.deploymentUid ?? '',
-                        version: instance.version ?? 0,
-                    },
-                }
-                : {}),
-        }
-        : undefined, 
+    const datalayerCreatePayload = useMemo(() => (app.agent ? appDatalayerCreatePayload(app, instance) : undefined), 
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [source, instance?.appUid, instance?.deploymentUid, instance?.version]);
     if (!appPlugin) {
@@ -129,7 +207,11 @@ export function AppRenderer({ app, plugins = NO_PLUGINS, instance, onPresence, .
     , { 
         // 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, datalayerAgentSpecId: DATALAYER_BOOTSTRAP_AGENTSPEC, 
+        agentId: app.id, ...appLayoutOptions(app), ...(frame
+            ? {
+                frameTitle: [app.emoji, app.name].filter(Boolean).join(' '),
+            }
+            : {}), 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, 

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

@@ -0,0 +1,15 @@
+import type { Agentspec } from '../../types/agentspecs';
+/** An agent of the catalogue, or a Cog's agent, by `id` or `id:version`. */
+export declare function resolveAgentspec(reference: string): Agentspec | undefined;
+/**
+ * What the agent is told: its spec's system prompt, then what the
+ * application tells it on top — as the runtime joins them.
+ */
+export declare function agentInstructions(spec: Pick<Agentspec, 'systemPrompt'> | undefined, extra?: string): string | undefined;
+/**
+ * Why an agent turned in the page cannot run, or undefined when it can.
+ *
+ * An agent named by a reference that resolves to nothing would answer with
+ * no instructions — bare — which is not the agent that was asked for.
+ */
+export declare function inPageAgentRefusal(reference: string | undefined, spec: Agentspec | undefined): string | undefined;

package/lib/loop/apps/agent.js

@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The agent an application runs, as the page turns it (LOOP H-01, E-11).
+ *
+ * On a runtime, an application's agent is its agent's spec — an agent of the
+ * catalogue, or a Cog's, which is an agent equipped with Frames, their
+ * context already in its system prompt — and the application's own
+ * instructions on top of it (`get_library_agent_spec` and the create route
+ * in `agent_runtimes/routes/agents.py`). The page turns the same agent in the
+ * browser, so it resolves it the same way: an application on a Cog that the
+ * page looked up among the agentspecs alone ran with no instructions at all.
+ *
+ * @module loop/apps/agent
+ */
+import { getAgentspecs } from '../../specs/agents';
+import { getCog } from '../../specs/cogs';
+/** An agent of the catalogue, or a Cog's agent, by `id` or `id:version`. */
+export function resolveAgentspec(reference) {
+    return getAgentspecs(reference) ?? getCog(reference)?.spec;
+}
+/**
+ * What the agent is told: its spec's system prompt, then what the
+ * application tells it on top — as the runtime joins them.
+ */
+export function agentInstructions(spec, extra) {
+    const parts = [spec?.systemPrompt?.trim(), extra?.trim()].filter((part) => Boolean(part));
+    return parts.length > 0 ? parts.join('\n\n') : undefined;
+}
+/**
+ * Why an agent turned in the page cannot run, or undefined when it can.
+ *
+ * An agent named by a reference that resolves to nothing would answer with
+ * no instructions — bare — which is not the agent that was asked for.
+ */
+export function inPageAgentRefusal(reference, spec) {
+    return reference && !spec
+        ? `There is no agent or Cog named “${reference}” in this page, so it cannot answer here.`
+        : undefined;
+}

package/lib/loop/apps/appspec.js

@@ -105,6 +105,7 @@ export function emptyAppspec(kind = 'chat') {
             keepFor: DEFAULT_KEEP_FOR,
             retentionDays: retentionDays(DEFAULT_KEEP_FOR),
             include: [...DEFAULT_RECORD_INCLUDE],
+            suggestTests: false,
         },
         checks: { guards: [], gates: [], track: '' },
         deployment: {},
@@ -243,7 +244,7 @@ function parseDecision(data) {
             name: text(scenario.name),
             weights: Object.fromEntries(Object.entries(isData(scenario.weights) ? scenario.weights : {}).filter((entry) => typeof entry[1] === 'number')),
         })),
-        judgmentModel: text(data.judgment_model),
+        decisionModel: text(data.decision_model),
     };
 }
 function parseDeployment(data) {
@@ -359,6 +360,7 @@ export function parseAppspec(document) {
             include: Array.isArray(record.include)
                 ? texts(record.include)
                 : [...DEFAULT_RECORD_INCLUDE],
+            suggestTests: record.suggest_tests === true,
         },
         checks: {
             guards: texts(checks.guards),
@@ -493,7 +495,7 @@ function dumpDecision(decision) {
         .text('name', scenario.name, '\u0000')
         // By criterion name, in alphabetical order: the spec declares no order.
         .part('weights', sorted(scenario.weights)).data))
-        .text('judgment_model', decision.judgmentModel).data;
+        .text('decision_model', decision.decisionModel).data;
 }
 /**
  * An application as the document its file holds.
@@ -554,7 +556,8 @@ export function dumpAppspec(app) {
     }))).data)
         .part('record', new Writer()
         .text('keep_for', app.record.keepFor, DEFAULT_KEEP_FOR)
-        .list('include', app.record.include, DEFAULT_RECORD_INCLUDE).data)
+        .list('include', app.record.include, DEFAULT_RECORD_INCLUDE)
+        .value('suggest_tests', app.record.suggestTests, false).data)
         .part('checks', new Writer()
         .list('guards', app.checks.guards)
         .list('gates', app.checks.gates)

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

@@ -16,8 +16,16 @@ export interface AppCheck {
 export declare const componentNamed: (name: string) => ComponentSpec | undefined;
 /** The Guards the runtime executes (agent-runtimes `loop/apps/guards.py`). */
 export declare const EXECUTED_GUARDS: readonly string[];
+/**
+ * Where an application is checked: the plugins its organization has turned
+ * off (catalogue ids, `plugins_off` in IAM), none when it has decided nothing
+ * or the checks run with no organization.
+ */
+export interface CheckContext {
+    pluginsOff: readonly string[];
+}
 /** The instant checks of an application as an editor holds it. */
-export declare function checkApp(app: AppSpec, read?: string[]): AppCheck;
+export declare function checkApp(app: AppSpec, read?: string[], context?: CheckContext): AppCheck;
 /**
  * What the document says in a shape the spec refuses — a list where a list is
  * not, a word where a choice is — which the tolerant reader replaces with a
@@ -25,4 +33,4 @@ export declare function checkApp(app: AppSpec, read?: string[]): AppCheck;
  */
 export declare function documentShapeProblems(document: unknown): string[];
 /** The instant checks of an application's document, what reading it found included. */
-export declare function checkAppspec(document: unknown): AppCheck;
+export declare function checkAppspec(document: unknown, context?: CheckContext): AppCheck;

package/lib/loop/apps/checks.js

@@ -38,6 +38,7 @@ import { getSkillSpec } from '../../specs/skills';
 import { getTeamSpec } from '../../specs/teams';
 import { getToolSpec } from '../../specs/tools';
 import { getTrack } from '../../specs/tracks';
+import { pluginsOffSetupNotes } from '../plugins/canvas-blocks';
 import { parseAppspec } from './appspec';
 import { classesOf, splitRef, toolBehaviours } from './rules';
 export const NOT_READY = 'Not ready';
@@ -192,14 +193,14 @@ function referenceProblems(app) {
             problems.push(`The surface's “${String(node.id)}” is a “${String(node.component)}”, which the catalog does not have.`);
         }
     }
-    const judge = app.decision?.judgmentModel;
-    if (judge) {
-        const model = getModel(judge);
+    const decider = app.decision?.decisionModel;
+    if (decider) {
+        const model = getModel(decider);
         if (!model) {
-            problems.push(`There is no model named “${judge}” to judge with.`);
+            problems.push(`There is no model named “${decider}” to decide with.`);
         }
-        else if (!(model.capabilities ?? []).includes('judgments')) {
-            problems.push(`The model “${judge}” does not answer typed judgments.`);
+        else if (!(model.capabilities ?? []).includes('decisions')) {
+            problems.push(`The model “${decider}” does not answer typed decisions.`);
         }
     }
     const run = new Set(app.checks.guards.map(idOf));
@@ -336,10 +337,16 @@ function setupNotes(app) {
         note('notification', ref, getNotificationSpec(idOf(ref)));
     return setup;
 }
+const NO_ORGANIZATION = { pluginsOff: [] };
 /** The instant checks of an application as an editor holds it. */
-export function checkApp(app, read = []) {
+export function checkApp(app, read = [], context = NO_ORGANIZATION) {
     const problems = [...read, ...shapeProblems(app), ...referenceProblems(app)];
-    const setup = setupNotes(app);
+    // A block its page uses from a plugin its organization turned off is said
+    // with the rest of what is not enabled today (C-12).
+    const setup = [
+        ...setupNotes(app),
+        ...pluginsOffSetupNotes(app, context.pluginsOff),
+    ];
     if (problems.length > 0) {
         return { verdict: NOT_READY, problems, attention: [], setup };
     }
@@ -540,6 +547,10 @@ export function documentShapeProblems(document) {
             else
                 record.include.forEach((item, index) => oneOf(item, ENUMS.record, `record.include.${index}`));
         }
+        if (record.suggest_tests !== undefined &&
+            typeof record.suggest_tests !== 'boolean') {
+            at('record.suggest_tests', 'is true or false');
+        }
     });
     mapping(d.checks, 'checks', checks => {
         texts(checks.guards, 'checks.guards');
@@ -596,7 +607,7 @@ export function documentShapeProblems(document) {
     return problems;
 }
 /** The instant checks of an application's document, what reading it found included. */
-export function checkAppspec(document) {
+export function checkAppspec(document, context = NO_ORGANIZATION) {
     const { app, problems } = parseAppspec(document);
-    return checkApp(app, [...problems, ...documentShapeProblems(document)]);
+    return checkApp(app, [...problems, ...documentShapeProblems(document)], context);
 }

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

@@ -0,0 +1,51 @@
+/**
+ * Feedback from the people who use an application (LOOP V-18): a thumb up or
+ * down on an answer, and a comment, kept in the application's record.
+ *
+ * Kept only when the application's `record.include` names `feedback` — its
+ * builder says what its record keeps, and the chat offers nothing it would
+ * not keep. Sent to the runtime the conversation runs on
+ * (`POST /api/v1/apps/feedback`), which writes it through the recorder of
+ * that conversation, under its session: the conversation's AG-UI thread.
+ *
+ * Pure: no React; the network is the `fetch` it is handed.
+ *
+ * @module loop/apps/feedback
+ */
+import type { AppSpec } from '../../types/agentspecs';
+/** The longest comment kept, as the runtime holds it (`COMMENT_LIMIT`). */
+export declare const FEEDBACK_COMMENT_LIMIT = 2000;
+/** What a person says of an answer. */
+export type Feedback = {
+    /** The conversation, as the runtime knows it. */
+    session: string;
+    liked: boolean;
+    comment: string;
+};
+/** What the feedback strip says, in a person's words. */
+export declare const FEEDBACK_WORDS: {
+    readonly ask: "Was this answer useful?";
+    readonly liked: "Useful";
+    readonly disliked: "Not useful";
+    readonly comment: "Anything to add? (optional)";
+    readonly send: "Send";
+    readonly kept: (app: string) => string;
+    readonly where: (app: string) => string;
+    readonly tooLong: "A comment is at most 2000 characters.";
+    readonly noSession: "This conversation has no name the application knows yet: send a message first.";
+};
+/** Whether an application keeps feedback: its record names it. */
+export declare const keepsFeedback: (app: Pick<AppSpec, "record">) => boolean;
+/** Where feedback is sent, on the runtime an application runs on. */
+export declare const feedbackEndpoint: (agentBaseUrl: string) => string;
+/** Why feedback cannot be sent as it is; nothing when it can. */
+export declare function feedbackProblems(feedback: Feedback): string[];
+/**
+ * Send feedback to the runtime, and say what it kept: the entry, in a
+ * sentence. A refusal throws the runtime's own sentence.
+ */
+export declare function sendFeedback(feedback: Feedback, { agentBaseUrl, token, fetcher, }: {
+    agentBaseUrl: string;
+    token?: string | null;
+    fetcher?: typeof fetch;
+}): Promise<string>;

package/lib/loop/apps/feedback.js

@@ -0,0 +1,61 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** The longest comment kept, as the runtime holds it (`COMMENT_LIMIT`). */
+export const FEEDBACK_COMMENT_LIMIT = 2000;
+/** What the feedback strip says, in a person's words. */
+export const FEEDBACK_WORDS = {
+    ask: 'Was this answer useful?',
+    liked: 'Useful',
+    disliked: 'Not useful',
+    comment: 'Anything to add? (optional)',
+    send: 'Send',
+    kept: (app) => `Thank you. Kept in ${app}’s record.`,
+    where: (app) => `What you say is kept with this conversation in ${app}’s record, for its builder to read.`,
+    tooLong: `A comment is at most ${FEEDBACK_COMMENT_LIMIT} characters.`,
+    noSession: 'This conversation has no name the application knows yet: send a message first.',
+};
+/** Whether an application keeps feedback: its record names it. */
+export const keepsFeedback = (app) => (app.record?.include ?? []).includes('feedback');
+/** Where feedback is sent, on the runtime an application runs on. */
+export const feedbackEndpoint = (agentBaseUrl) => `${agentBaseUrl.replace(/\/+$/, '')}/api/v1/apps/feedback`;
+/** Why feedback cannot be sent as it is; nothing when it can. */
+export function feedbackProblems(feedback) {
+    const problems = [];
+    if (!feedback.session.trim()) {
+        problems.push(FEEDBACK_WORDS.noSession);
+    }
+    if (feedback.comment.trim().length > FEEDBACK_COMMENT_LIMIT) {
+        problems.push(FEEDBACK_WORDS.tooLong);
+    }
+    return problems;
+}
+/**
+ * Send feedback to the runtime, and say what it kept: the entry, in a
+ * sentence. A refusal throws the runtime's own sentence.
+ */
+export async function sendFeedback(feedback, { agentBaseUrl, token, fetcher = fetch, }) {
+    const problems = feedbackProblems(feedback);
+    if (problems.length) {
+        throw new Error(problems.join(' '));
+    }
+    const response = await fetcher(feedbackEndpoint(agentBaseUrl), {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        },
+        body: JSON.stringify({
+            session: feedback.session,
+            liked: feedback.liked,
+            comment: feedback.comment.trim(),
+        }),
+    });
+    const body = (await response.json().catch(() => ({})));
+    if (!response.ok) {
+        const detail = typeof body.detail === 'string' ? body.detail : `${response.status}`;
+        throw new Error(`The feedback was not kept: ${detail}`);
+    }
+    return String(body.summary ?? '');
+}

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

@@ -3,8 +3,11 @@
  *
  * @module loop/apps
  */
+export * from './agent';
+export * from './AppFeedback';
 export * from './AppRenderer';
 export * from './appspec';
 export * from './checks';
+export * from './feedback';
 export * from './rules';
 export * from './yaml';

package/lib/loop/apps/index.js

@@ -7,8 +7,11 @@
  *
  * @module loop/apps
  */
+export * from './agent';
+export * from './AppFeedback';
 export * from './AppRenderer';
 export * from './appspec';
 export * from './checks';
+export * from './feedback';
 export * from './rules';
 export * from './yaml';

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

@@ -39,6 +39,20 @@ export declare function classesOf(ref: string, args?: ToolArguments): ActionClas
 export declare const isReadOnly: (classes: ActionClass[]) => boolean;
 /** The most restricted of several behaviours. */
 export declare const strictest: (behaviours: AppBehaviour[]) => AppBehaviour;
+/**
+ * Whether the application is given a tool of a server: its connection's
+ * level (LOOP U-15). A connection gives the tools of its server it reaches
+ * (`only`); one that only reads gives only the tools that only read — a tool
+ * nobody classed is taken to write, so a read connection does not give it.
+ * A tool of a server the application is not connected to is not given.
+ *
+ * The runtime gives its agent only these (`AppRulesCapability.prepare_tools`,
+ * through `agent_runtimes.loop.apps.rules.gives`, its Python twin).
+ *
+ * @throws When `tool` names no server: a catalogue tool is given by the
+ *   spec's `tools`, not by a connection.
+ */
+export declare function gives(app: Pick<AppSpec, 'connections'>, tool: string): boolean;
 /** What `behaviourFor` may be told about the call. */
 export interface BehaviourOptions {
     /** The arguments of the call; without them the decision is for the worst the tool can do. */

package/lib/loop/apps/rules.js

@@ -161,6 +161,30 @@ export const strictest = (behaviours) => behaviours.reduce((worst, behaviour) =>
 const connectionTo = (app, server) => app.connections.find(connection => idOf(connection.server) === server);
 const reaches = (connection, tool) => connection.only.length === 0 ||
     connection.only.some(pattern => matchesPattern(tool, pattern));
+/**
+ * Whether the application is given a tool of a server: its connection's
+ * level (LOOP U-15). A connection gives the tools of its server it reaches
+ * (`only`); one that only reads gives only the tools that only read — a tool
+ * nobody classed is taken to write, so a read connection does not give it.
+ * A tool of a server the application is not connected to is not given.
+ *
+ * The runtime gives its agent only these (`AppRulesCapability.prepare_tools`,
+ * through `agent_runtimes.loop.apps.rules.gives`, its Python twin).
+ *
+ * @throws When `tool` names no server: a catalogue tool is given by the
+ *   spec's `tools`, not by a connection.
+ */
+export function gives(app, tool) {
+    const [server, name] = splitRef(tool);
+    if (server === undefined) {
+        throw new Error(`\`${tool}\` is not a tool of a server (\`server.tool\`).`);
+    }
+    const connection = connectionTo(app, server);
+    if (!connection || !reaches(connection, name)) {
+        return false;
+    }
+    return (connection.access !== 'read' || isReadOnly(classesOf(`${server}.${name}`)));
+}
 const isClass = (target) => Object.prototype.hasOwnProperty.call(DEFAULT_BEHAVIOURS, target);
 /** What a rule applies to, versions aside. */
 const normal = (target) => {

package/lib/loop/core/canvasBlocks.d.ts

@@ -0,0 +1,16 @@
+import type { ComponentSpec } from '../../types/agentspecs';
+/**
+ * A block the Canvas may place (LOOP C-12): one component of the catalog of
+ * visual components (C-13), contributed by the plugin of the UI plugin that
+ * renders it. The Canvas's palette is what the enabled plugins contribute
+ * here, and nothing else: a plugin disabled takes its blocks off it, and an
+ * application that uses one of them says so in its setup notes.
+ */
+export type CanvasBlockContribution = {
+    /** The name a surface gives it, the component's id (e.g. 'Table'). */
+    id: string;
+    /** The UI plugin of the catalogue that renders it (e.g. 'a2ui'). */
+    uiPlugin: string;
+    component: ComponentSpec;
+};
+export declare const LoopCanvasBlock: import("@datalayer/reactor").ContributionPoint<CanvasBlockContribution>;

package/lib/loop/core/canvasBlocks.js

@@ -0,0 +1,13 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The Canvas's palette as a contribution point (LOOP C-12), re-exported by
+ * `loop/core`: kept apart so that reading the palette loads the reactor and
+ * the catalogue, and nothing of the workspace.
+ *
+ * @module loop/core/canvasBlocks
+ */
+import { defineContributionPoint } from '@datalayer/reactor';
+export const LoopCanvasBlock = defineContributionPoint('loop.canvas.block');

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

@@ -483,6 +483,14 @@ export type AgentBlueprintContribution = {
     specId?: string;
     /** Extra fields merged into the server's create-agent payload. */
     createPayload?: Record<string, unknown>;
+    /**
+     * What the agent is told on top of its spec's system prompt — an
+     * application's instructions — when the page turns it, as a runtime
+     * appends them.
+     */
+    instructions?: string;
+    /** The model it runs on in the page, in place of its spec's. */
+    model?: string;
 };
 export declare const LoopAgentBlueprint: import("@datalayer/reactor").ContributionPoint<AgentBlueprintContribution>;
 /** One conversation opener a plugin offers on the empty chat. */
@@ -518,6 +526,7 @@ export type AssistantCharacterContribution = {
     character: AssistantCharacter | AssistantCharacterData;
 };
 export declare const LoopAssistantCharacter: import("@datalayer/reactor").ContributionPoint<AssistantCharacterContribution>;
+export { LoopCanvasBlock, type CanvasBlockContribution } from './canvasBlocks';
 /**
  * The per-example chat extras a host feeds the loop's conversation live.
  *
@@ -927,6 +936,12 @@ export type ChatTurnSnapshot = {
     user?: string;
     /** What the agent has said so far. */
     assistant?: string;
+    /**
+     * The conversation the turn belongs to, as the runtime knows it (AG-UI's
+     * thread) — what an application's record keeps its session under, and
+     * what feedback on it names (LOOP V-18). Absent when the chat does not say.
+     */
+    thread?: string;
     status: ChatTurnStatus;
     /**
      * The context window as the agent last reported it — what a turn footer

package/lib/loop/core/index.js

@@ -142,6 +142,9 @@ export const LoopChatHeader = defineContributionPoint('loop.chat.header');
 export const LoopAgentBlueprint = defineContributionPoint('loop.agent.blueprint');
 export const LoopChatSuggestion = defineContributionPoint('loop.chat.suggestion');
 export const LoopAssistantCharacter = defineContributionPoint('loop.assistant.character');
+// A block the Canvas may place (LOOP C-12), in a module of its own so that
+// the palette is read without the rest of the contracts.
+export { LoopCanvasBlock } from './canvasBlocks';
 export const LoopChatExtras = defineContributionPoint('loop.chat.extras');
 export const LoopOpeningNotebook = defineContributionPoint('loop.notebook.opening');
 export const LoopOpeningDocument = defineContributionPoint('loop.document.opening');