@datalayer/agent-runtimes 1.3.15 → 1.3.17

package/lib/loop/apps/rules.js

@@ -0,0 +1,289 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * What an application does when its agent calls a tool.
+ *
+ * A rule is written in a person's words — *ask me before it sends anything* —
+ * and applies to what a tool does: a class of action (read, write, send, buy,
+ * delete, publish) or named tools. The classes are the catalogue's
+ * (`specs/actions`), written on every tool by somebody who looked; a tool
+ * nobody classed is unknown, and unknown is the most restricted.
+ *
+ * The decision, in order:
+ *
+ * 1. a tool of a server the application is not connected to, or that its
+ *    connection leaves out (`only`), is left to the person: an application
+ *    reaches nothing it does not name;
+ * 2. a tool that can act, on a connection that only reads, is left to the person;
+ * 3. a rule that names the tool decides what the tool does of its own — and
+ *    what the arguments of the call make it do *besides* is still decided by
+ *    its class: *label a message: do it* does not become *trash it: do it*;
+ * 4. a tool nobody classed is left to the person;
+ * 5. otherwise each of its classes is decided by the rule on that class — or,
+ *    with no rule, reading is done and anything that acts waits for a person —
+ *    and the most restricted wins.
+ *
+ * The same decision is written in Python, in `agentspecs.apps.behaviour_for`
+ * and in `agent_runtimes.loop.apps.rules`. `APP_BEHAVIOURS`, generated from
+ * agentspecs, is what all three have to agree on. The server enforces; this
+ * one shows the decision before it is made.
+ *
+ * Pure: nothing here calls a tool or renders.
+ *
+ * @module loop/apps/rules
+ */
+import { SERVER_ACTIONS, TOOL_ACTIONS } from '../../specs/actions';
+/** The four behaviours, from the freest to the most restricted. */
+export const BEHAVIOURS = [
+    'do_it',
+    'if_asked',
+    'ask_first',
+    'leave_to_me',
+];
+/**
+ * What an application does about a class no rule of its own covers. Reading
+ * needs no rule; anything that acts waits for a person: never `do_it`.
+ */
+export const DEFAULT_BEHAVIOURS = {
+    read: 'do_it',
+    write: 'ask_first',
+    send: 'ask_first',
+    buy: 'ask_first',
+    delete: 'ask_first',
+    publish: 'ask_first',
+};
+const SERVER_TOOL = /^([A-Za-z0-9_-]+)(?::\d+(?:\.\d+)*)?\.([A-Za-z_][A-Za-z0-9_-]*)$/;
+const own = (record, key) => Object.prototype.hasOwnProperty.call(record, key) ? record[key] : undefined;
+/** The id of a reference, `id` or `id:version`. */
+const idOf = (ref) => {
+    const at = ref.lastIndexOf(':');
+    return at > 0 && ref.slice(at + 1).includes('.') ? ref.slice(0, at) : ref;
+};
+/** A tool reference as [server, tool]: `tavily.tavily_search`, or a tool id alone. */
+export function splitRef(ref) {
+    const matched = SERVER_TOOL.exec(ref);
+    return matched ? [matched[1], matched[2]] : [undefined, idOf(ref)];
+}
+/** Whether a tool name is a pattern: it stands for several. */
+export const isPattern = (name) => /[*?]/.test(name);
+/**
+ * Whether a name matches a pattern: `*` is any run of characters, `?` any one.
+ *
+ * Nothing else is special — no bracket expressions — and case counts: the
+ * same pattern means the same thing here and in Python.
+ */
+export function matchesPattern(name, pattern) {
+    const expression = Array.from(pattern, character => character === '*'
+        ? '[\\s\\S]*'
+        : character === '?'
+            ? '[\\s\\S]'
+            : character.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('');
+    return new RegExp(`^${expression}$`).test(name);
+}
+/**
+ * Whether a value is one every reader compares the same way: a word, true or
+ * false, or a number that is finite and — when it is whole — held exactly.
+ * Beyond `Number.MAX_SAFE_INTEGER` two different integers are one number
+ * here and two in Python.
+ */
+export const isComparable = (value) => typeof value === 'string' ||
+    typeof value === 'boolean' ||
+    (typeof value === 'number' &&
+        Number.isFinite(value) &&
+        (!Number.isInteger(value) || Number.isSafeInteger(value)));
+/** Whether an argument's value is the one a condition names; words whatever their case. */
+const same = (value, wanted) => typeof value === 'string' && typeof wanted === 'string'
+    ? value.trim().toLowerCase() === wanted.trim().toLowerCase()
+    : isComparable(value) && isComparable(wanted) && value === wanted;
+/** Whether the arguments of a call make a condition true. */
+export function conditionHolds(condition, args) {
+    if (!Object.prototype.hasOwnProperty.call(args, condition.argument)) {
+        return false;
+    }
+    const value = args[condition.argument];
+    if (condition.equals?.some(wanted => same(value, wanted))) {
+        return true;
+    }
+    if (condition.includes?.length) {
+        const values = Array.isArray(value) ? value : [value];
+        return values.some(item => condition.includes.some(wanted => same(item, wanted)));
+    }
+    return false;
+}
+/** What answers for a tool of a server: its own classes, and its conditions. */
+function entryOf(server, name) {
+    const actions = own(SERVER_ACTIONS, server);
+    if (!actions) {
+        return [[], []];
+    }
+    const exact = own(actions.tools, name);
+    if (exact) {
+        return [[...exact], own(actions.conditions, name) ?? []];
+    }
+    for (const [pattern, classes] of Object.entries(actions.tools)) {
+        if (isPattern(pattern) && matchesPattern(name, pattern)) {
+            return [[...classes], own(actions.conditions, pattern) ?? []];
+        }
+    }
+    return [[...actions.default], []];
+}
+/**
+ * The classes of a tool, by reference; empty when nobody classed it.
+ *
+ * With the arguments of a call, the classes of that call. Without them,
+ * everything the tool can do: nobody said what it is asked.
+ */
+export function classesOf(ref, args) {
+    const [server, name] = splitRef(ref);
+    if (server === undefined) {
+        return [...(own(TOOL_ACTIONS, name) ?? [])];
+    }
+    const [classes, conditions] = entryOf(server, name);
+    for (const condition of conditions) {
+        if (args === undefined || conditionHolds(condition, args)) {
+            for (const item of condition.classes) {
+                if (!classes.includes(item)) {
+                    classes.push(item);
+                }
+            }
+        }
+    }
+    return classes;
+}
+/** Whether a tool only reads. An unknown tool — no class — does not. */
+export const isReadOnly = (classes) => classes.length > 0 && classes.every(item => item === 'read');
+/** The most restricted of several behaviours. */
+export const strictest = (behaviours) => behaviours.reduce((worst, behaviour) => BEHAVIOURS.indexOf(behaviour) > BEHAVIOURS.indexOf(worst)
+    ? behaviour
+    : worst);
+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));
+const isClass = (target) => Object.prototype.hasOwnProperty.call(DEFAULT_BEHAVIOURS, target);
+/** What a rule applies to, versions aside. */
+const normal = (target) => {
+    if (isClass(target)) {
+        return target;
+    }
+    const [server, name] = splitRef(target);
+    return server !== undefined ? `${server}.${name}` : name;
+};
+/** What the rules on classes decide for each of these classes. */
+const byClasses = (app, classes) => {
+    const byClass = {};
+    for (const rule of app.rules) {
+        for (const target of rule.appliesTo) {
+            if (isClass(target)) {
+                byClass[target] = rule.behaviour;
+            }
+        }
+    }
+    return classes.map(item => byClass[item] ?? DEFAULT_BEHAVIOURS[item]);
+};
+/**
+ * What an application does when its agent calls a tool.
+ *
+ * `tool` is `server.tool` for a tool of an MCP server, or the id of a tool
+ * of the catalogue. Its classes are the catalogue's, unless given.
+ */
+export function behaviourFor(app, tool, options = {}) {
+    const [server, name] = splitRef(tool);
+    let ownClasses;
+    let besides = [];
+    let possible;
+    if (options.classes) {
+        ownClasses = possible = [...options.classes];
+    }
+    else {
+        possible = classesOf(tool);
+        ownClasses = classesOf(tool, {});
+        const now = options.arguments === undefined
+            ? possible
+            : classesOf(tool, options.arguments);
+        besides = now.filter(item => !ownClasses.includes(item));
+    }
+    if (server !== undefined) {
+        const connection = connectionTo(app, server);
+        if (!connection || !reaches(connection, name)) {
+            return 'leave_to_me';
+        }
+        if (connection.access === 'read' &&
+            possible.some(item => item !== 'read')) {
+            return 'leave_to_me';
+        }
+    }
+    const wanted = server !== undefined ? `${server}.${name}` : name;
+    for (const rule of app.rules) {
+        if (rule.appliesTo.some(target => !isClass(target) && normal(target) === wanted)) {
+            return strictest([rule.behaviour, ...byClasses(app, besides)]);
+        }
+    }
+    if (ownClasses.length === 0 && besides.length === 0) {
+        return 'leave_to_me';
+    }
+    return strictest(byClasses(app, [...ownClasses, ...besides]));
+}
+/**
+ * What the application does about every classed tool of the servers it
+ * connects to, each in its plain use — no argument that makes it do more; see
+ * {@link toolEscalations} for those. A server that classes its tools by a
+ * pattern is reported by that pattern.
+ */
+export function toolBehaviours(app) {
+    const behaviours = {};
+    for (const connection of app.connections) {
+        const server = idOf(connection.server);
+        const actions = own(SERVER_ACTIONS, server);
+        if (!actions) {
+            continue;
+        }
+        for (const [name, found] of Object.entries(actions.tools)) {
+            const ref = `${server}.${name}`;
+            if (!isPattern(name)) {
+                behaviours[ref] = behaviourFor(app, ref, { arguments: {} });
+            }
+            else if (connection.access === 'read' &&
+                found.some(item => item !== 'read')) {
+                behaviours[ref] = 'leave_to_me';
+            }
+            else {
+                behaviours[ref] =
+                    found.length > 0 ? strictest(byClasses(app, found)) : 'leave_to_me';
+            }
+        }
+    }
+    return behaviours;
+}
+/** Where what a tool is asked changes what the application does about it. */
+export function toolEscalations(app) {
+    const escalations = {};
+    for (const connection of app.connections) {
+        const server = idOf(connection.server);
+        const actions = own(SERVER_ACTIONS, server);
+        if (!actions) {
+            continue;
+        }
+        for (const [name, conditions] of Object.entries(actions.conditions)) {
+            if (isPattern(name)) {
+                continue;
+            }
+            const ref = `${server}.${name}`;
+            const plain = behaviourFor(app, ref, { arguments: {} });
+            for (const condition of conditions) {
+                const values = condition.includes?.length
+                    ? condition.includes
+                    : (condition.equals ?? []);
+                const value = condition.includes?.length ? [values[0]] : values[0];
+                const then = behaviourFor(app, ref, {
+                    arguments: { [condition.argument]: value },
+                });
+                if (then !== plain) {
+                    (escalations[ref] ??= []).push({ ...condition, behaviour: then });
+                }
+            }
+        }
+    }
+    return escalations;
+}

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

@@ -0,0 +1,17 @@
+import type { AppSpec } from '../../types/agentspecs';
+import { type ParsedAppspec } from './appspec';
+/**
+ * An application from its YAML file.
+ *
+ * What YAML itself refuses is reported with its line, before anything the
+ * spec has to say; the application returned is whole either way.
+ */
+export declare function readAppspecYaml(text: string): ParsedAppspec;
+/**
+ * An application as its YAML file.
+ *
+ * Into `previous` when there is one and it reads: what did not change keeps
+ * its comments, its order and its style. Afresh otherwise, as the canonical
+ * document. Either way the file reads back as the application.
+ */
+export declare function writeAppspecYaml(app: AppSpec, previous?: string): string;

package/lib/loop/apps/yaml.js

@@ -0,0 +1,185 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The Appspec as a YAML file a person also edits.
+ *
+ * An application's file is reviewed like code: it has comments, an order
+ * somebody chose, a way of quoting. When the Canvas changes one field and
+ * writes the file back, all of that has to still be there — a comment that
+ * disappears on a save is a reason never to open the Canvas again.
+ *
+ * {@link writeAppspecYaml} therefore does not write the application afresh
+ * when there is a file already: it writes it **into** that file. What did not
+ * change keeps its node — its comment, its style, its place — and only what
+ * changed is replaced. Two things are the writer's own and are
+ * settled by the first save: one space before a comment at the end of a
+ * line, and long text folded at eighty columns. A file written once is
+ * given back untouched when nothing changed. An item of a list is followed by what identifies it
+ * (a connection's server, a rule's action, a component's id), so that a
+ * comment stays with its item when the list is reordered or grows.
+ *
+ * With no file to write into, the document is the canonical one
+ * (`dumpAppspec`): the spec's keys in the spec's order.
+ *
+ * Pure: nothing here reads or writes a disk.
+ *
+ * @module loop/apps/yaml
+ */
+import { Document, isMap, isScalar, isSeq, parseDocument, } from 'yaml';
+import { dumpAppspec, parseAppspec } from './appspec';
+const isData = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+/**
+ * How the file is written. Long text is folded at eighty columns, and a
+ * list written on one line stays `[a, b]`.
+ */
+const WRITING = {
+    indent: 2,
+    lineWidth: 80,
+    flowCollectionPadding: false,
+};
+/**
+ * An application from its YAML file.
+ *
+ * What YAML itself refuses is reported with its line, before anything the
+ * spec has to say; the application returned is whole either way.
+ */
+export function readAppspecYaml(text) {
+    const document = parseDocument(text, { prettyErrors: true });
+    if (document.errors.length > 0) {
+        const parsed = parseAppspec({});
+        return {
+            app: parsed.app,
+            problems: document.errors.map(error => {
+                const at = error.linePos?.[0];
+                const where = at ? `Line ${at.line}: ` : '';
+                return `${where}${error.message.split('\n')[0]}`;
+            }),
+        };
+    }
+    return parseAppspec(document.toJS());
+}
+/** What identifies an item of a list, when its items are mappings. */
+const IDENTITIES = ['id', 'server', 'action', 'space', 'name', 'label', 'ask'];
+/** The key every item of both lists has, with a different value each — or none. */
+function identityOf(items, nodes) {
+    const ofNode = (node, key) => isMap(node) ? node.get(key) : undefined;
+    return IDENTITIES.find(key => {
+        const values = items.map(item => (isData(item) ? item[key] : undefined));
+        const existing = nodes.map(node => ofNode(node, key));
+        const distinct = (list) => list.every(value => typeof value === 'string') &&
+            new Set(list).size === list.length;
+        return items.length > 0 && distinct(values) && distinct(existing);
+    });
+}
+/** A value as a node of a document, as the document would write it new. */
+const nodeOf = (document, value) => document.createNode(value);
+/**
+ * A node saying a value: the node itself when it already does, changed in
+ * place where it can be, and a new one only when it is not the same kind of
+ * thing any more.
+ *
+ * `before` is what the file said at this place, in the canonical form: a key
+ * the canonical form leaves out both before and now — a default written out
+ * by its author, `enabled: true`, `access: read` — is kept as it was written.
+ */
+function merged(document, node, value, before) {
+    if (isData(value) && isMap(node)) {
+        mergeMap(document, node, value, isData(before) ? before : {});
+        return node;
+    }
+    if (Array.isArray(value) && isSeq(node)) {
+        mergeSeq(document, node, value, Array.isArray(before) ? before : []);
+        return node;
+    }
+    if (!isData(value) && !Array.isArray(value) && isScalar(node)) {
+        const scalar = node;
+        if (scalar.value !== value) {
+            scalar.value = value;
+        }
+        return scalar;
+    }
+    return nodeOf(document, value);
+}
+const keyOf = (pair) => isScalar(pair.key) ? String(pair.key.value) : String(pair.key);
+const has = (data, key) => Object.prototype.hasOwnProperty.call(data, key);
+/**
+ * A mapping made to say `value`: its own pairs kept, changed, removed or
+ * joined.
+ *
+ * A pair is removed only when the application stopped saying it: when the
+ * canonical form had it before and has it no more. One the canonical form
+ * never had — a default spelled out, a key this reader does not know — stays
+ * as it was written.
+ *
+ * A key that is new goes after the key the canonical form puts just before
+ * it, among those that are there, wherever the person put that one; first
+ * when nothing comes before it. The canonical form writes its keys in the
+ * spec's order, at every depth.
+ */
+function mergeMap(document, map, value, before) {
+    map.items = map.items.filter(pair => {
+        const key = keyOf(pair);
+        return has(value, key) || !has(before, key);
+    });
+    const order = Object.keys(value);
+    for (const [key, item] of Object.entries(value)) {
+        const pair = map.items.find(existing => keyOf(existing) === key);
+        if (pair) {
+            pair.value = merged(document, pair.value, item, before[key]);
+            continue;
+        }
+        const created = document.createPair(key, item);
+        const rank = order.indexOf(key);
+        let after = -1;
+        let best = -1;
+        map.items.forEach((existing, index) => {
+            const other = order.indexOf(keyOf(existing));
+            if (other >= 0 && other < rank && other > best) {
+                best = other;
+                after = index;
+            }
+        });
+        map.items.splice(after + 1, 0, created);
+    }
+}
+/** A list made to say `value`: an item keeps its node when it can be told which it was. */
+function mergeSeq(document, seq, value, before) {
+    const nodes = seq.items;
+    const identity = identityOf(value, nodes);
+    if (identity) {
+        const byIdentity = new Map(nodes.map(node => [node.get(identity), node]));
+        const beforeByIdentity = new Map(before.filter(isData).map(item => [item[identity], item]));
+        seq.items = value.map(item => {
+            const key = item[identity];
+            const existing = byIdentity.get(key);
+            return existing
+                ? merged(document, existing, item, beforeByIdentity.get(key))
+                : nodeOf(document, item);
+        });
+        return;
+    }
+    // Nothing tells the items apart: they are followed by their place.
+    seq.items = value.map((item, index) => index < nodes.length
+        ? merged(document, nodes[index], item, before[index])
+        : nodeOf(document, item));
+}
+/**
+ * An application as its YAML file.
+ *
+ * Into `previous` when there is one and it reads: what did not change keeps
+ * its comments, its order and its style. Afresh otherwise, as the canonical
+ * document. Either way the file reads back as the application.
+ */
+export function writeAppspecYaml(app, previous) {
+    const data = dumpAppspec(app);
+    if (previous !== undefined && previous.trim() !== '') {
+        const document = parseDocument(previous);
+        if (document.errors.length === 0 && isMap(document.contents)) {
+            mergeMap(document, document.contents, data, dumpAppspec(parseAppspec(document.toJS()).app));
+            return document.toString(WRITING);
+        }
+    }
+    return new Document(data).toString(WRITING);
+}

package/lib/loop/embed/LoopEmbed.d.ts

@@ -29,6 +29,11 @@ export type LoopEmbedProps = LoopPresetOptions & {
     chatHeaderActions?: ReactNode;
     /** The host's own controls for the workspace header row. */
     headerActions?: ReactNode;
+    /**
+     * An element in the host's own bar to render the header's controls in,
+     * instead of a header row. See `LoopWorkspaceProps.headerContainer`.
+     */
+    headerContainer?: HTMLElement | null;
     /**
      * Draw the workspace inside a window frame with this title bar.
      *
@@ -53,5 +58,5 @@ export type LoopEmbedProps = LoopPresetOptions & {
      */
     plugins?: PluginRef[];
 };
-export declare function LoopEmbed({ agentId, showHeader, chatHeaderActions, headerActions, frameTitle, frameHeight, plugins, ...preset }: LoopEmbedProps): React.JSX.Element;
+export declare function LoopEmbed({ agentId, showHeader, chatHeaderActions, headerActions, headerContainer, frameTitle, frameHeight, plugins, ...preset }: LoopEmbedProps): React.JSX.Element;
 export default LoopEmbed;

package/lib/loop/embed/LoopEmbed.js

@@ -30,7 +30,7 @@ import { internalQueryClient } from '../../utils';
 import { buildLoopReactor, LoopWorkspace } from '../shell';
 import { loopPlugins } from '../presets';
 import { WindowFrame } from '../plugins/window-frame';
-export function LoopEmbed({ agentId = '', showHeader = false, chatHeaderActions, headerActions, frameTitle, frameHeight, plugins = [], ...preset }) {
+export function LoopEmbed({ agentId = '', showHeader = false, chatHeaderActions, headerActions, headerContainer, frameTitle, frameHeight, plugins = [], ...preset }) {
     /*
      * The latest `firstPromptHook`, kept in a ref rather than closed over
      * directly.
@@ -69,6 +69,7 @@ export function LoopEmbed({ agentId = '', showHeader = false, chatHeaderActions,
         preset.chatHeaderButtons,
         preset.promptPlacement,
         preset.autoFocusPrompt,
+        preset.suggestionLabels,
         preset.fullScreenTopOffset,
         preset.showAgentVariants,
         preset.agentSummary,
@@ -119,7 +120,7 @@ export function LoopEmbed({ agentId = '', showHeader = false, chatHeaderActions,
      * view and the workspace draws "No view is available yet".
      */
     useReactor(reactor);
-    const shell = (_jsx(LoopWorkspace, { serverUrl: preset.serverUrl ?? '', agentId: agentId, reactor: reactor, manageReactor: false, showViewSelector: preset.showViewSelector, showHeader: showHeader, chatHeaderActions: chatHeaderActions, headerActions: headerActions }));
+    const shell = (_jsx(LoopWorkspace, { serverUrl: preset.serverUrl ?? '', agentId: agentId, reactor: reactor, manageReactor: false, showViewSelector: preset.showViewSelector, showHeader: showHeader, chatHeaderActions: chatHeaderActions, headerActions: headerActions, headerContainer: headerContainer }));
     return (_jsx(QueryClientProvider, { client: internalQueryClient, children: frameTitle !== undefined ? (_jsx(WindowFrame, { title: frameTitle, height: frameHeight, children: shell })) : (_jsx(Box, { sx: { height: '100%', minHeight: 0 }, children: shell })) }));
 }
 export default LoopEmbed;

package/lib/loop/index.d.ts

@@ -66,3 +66,4 @@ export { LoopEmbed, type LoopEmbedProps } from './embed/LoopEmbed';
 export { SubagentActivityPlugin, SubagentPulse, SUBAGENT_ACTIVITY_PLUGIN_NAME, } from './plugins/subagent-activity';
 export { loopPlugins, type LoopPresetOptions } from './presets';
 export { DocumentExtension, NotebookExtension } from './extensions';
+export { BEHAVIOURS as APP_BEHAVIOUR_ORDER, DEFAULT_BEHAVIOURS as APP_DEFAULT_BEHAVIOURS, behaviourFor, classesOf, isReadOnly, toolBehaviours, toolEscalations, type BehaviourOptions, type ToolArguments, APP_SCHEMA, APPSPEC_KEY_ORDER, DEFAULT_LAYOUTS as APP_DEFAULT_LAYOUTS, dumpAppspec, emptyAppspec, parseAppspec, AppRenderer, checkApp, checkAppspec, type AppCheck, defineAppPlugin, type AppRendererProps, readAppspecYaml, writeAppspecYaml, type ParsedAppspec, } from './apps';

package/lib/loop/index.js

@@ -88,3 +88,6 @@ export { loopPlugins } from './presets';
 // The extensions that group them, for hosts that would rather install a
 // capability than assemble one.
 export { DocumentExtension, NotebookExtension } from './extensions';
+// Applications: what one does when its agent calls a tool — the rules a
+// person wrote, decided on what the tool does.
+export { BEHAVIOURS as APP_BEHAVIOUR_ORDER, DEFAULT_BEHAVIOURS as APP_DEFAULT_BEHAVIOURS, behaviourFor, classesOf, isReadOnly, toolBehaviours, toolEscalations, APP_SCHEMA, APPSPEC_KEY_ORDER, DEFAULT_LAYOUTS as APP_DEFAULT_LAYOUTS, dumpAppspec, emptyAppspec, parseAppspec, AppRenderer, checkApp, checkAppspec, defineAppPlugin, readAppspecYaml, writeAppspecYaml, } from './apps';

package/lib/loop/plugins/chat/ChatView.js

@@ -37,7 +37,7 @@ import { agentRuntimeStore, useAgentRuntimeContextSnapshot, } from '../../../sto
 import { useIAMStore } from '../../../state';
 import { useConfig } from '../../../hooks/useConfig';
 import { useSkills, useSkillActions } from '../../../hooks/useSkills';
-import { AI_MODEL_CATALOGUE } from '../../../specs/models';
+import { AI_MODEL_CATALOGUE, isChatModel } from '../../../specs/models';
 import { LoopAgentBlueprint, LoopAgentGate, LoopChatComposer, LoopChatExtras, LoopChatHeader, LoopChatLayout, LoopChatSuggestion, LoopChatSurface, LoopChatTurn, LoopFrontendTool, LoopSlots, canOpenView, onPromptFocusRequest, onSurfaceRequest, useLoopPromptStore, } from '../../core';
 import { turnWritersOf } from './turnState';
 import { isInactiveSurfaceContribution, orderToolContributions, toolsForChatView, } from './chatViewTools';
@@ -1153,7 +1153,8 @@ export default function ChatView({ workspace }) {
     const offeredModels = useMemo(() => catalogModels.length > 0
         ? catalogModels
         : Object.values(AI_MODEL_CATALOGUE)
-            .filter(model => model.available)
+            // A typed-judgment model answers typed questions, not a chat.
+            .filter(model => model.available && isChatModel(model))
             .map(model => ({
             id: model.id,
             name: model.name,
@@ -1475,7 +1476,9 @@ export default function ChatView({ workspace }) {
                         // With the prompt on top the openers are already chips under
                         // it; the empty state repeating them was the same three buttons
                         // twice on one screen.
-                        suggestions: topPrompt || layout ? [] : chatSuggestions, 
+                        suggestions: topPrompt || layout || config?.suggestionLabels === false
+                            ? []
+                            : chatSuggestions, 
                         /*
                             The title bar arrives as a plugin: the chat-header plugin
                             contributes the component, this view hands it the assembled
@@ -1598,7 +1601,9 @@ export default function ChatView({ workspace }) {
                         // through the extras channel — the A2UI examples draw their
                         // surface here. Wins over the notebook surfaces in ChatBase.
                         renderToolResult: chatExtras.renderToolResult, showTurnFooter: chatExtras.showTokenUsage ?? true, onContextSnapshot: handleContextSnapshot, onLoadingChange: handleLoadingChange, onItemsChange: handleMessagesChange, onDisplayItemsChange: handleDisplayItemsChange, enableStreaming: true }) }), besideChat && !promptHidden ? prompt : null] }) }));
-    const chipsEl = chatSuggestions.length > 0 ? (_jsx(Box, { "aria-label": "Suggested prompts", sx: { display: 'flex', flexWrap: 'wrap', gap: 2, px: 2, pb: '6px' }, children: chatSuggestions.map(item => (_jsx(Box, { as: "button", type: "button", 
+    // Off when the host asked for the menu alone: the composer's suggestions
+    // control carries the same openers (`suggestions` above).
+    const chipsEl = config?.suggestionLabels !== false && chatSuggestions.length > 0 ? (_jsx(Box, { "aria-label": "Suggested prompts", sx: { display: 'flex', flexWrap: 'wrap', gap: 2, px: 2, pb: '6px' }, children: chatSuggestions.map(item => (_jsx(Box, { as: "button", type: "button", 
             // The whole request, where the chip shows only its summary.
             title: item.message, disabled: busy || chatDisabled, onClick: () => void handleSend(item.message), sx: {
                 appearance: 'none',

package/lib/loop/plugins/chat/index.d.ts

@@ -105,6 +105,16 @@ export type ChatPluginConfig = {
      * them. Such a host passes `false` and lets the reader arrive at the prompt.
      */
     autoFocusPrompt: boolean;
+    /**
+     * Whether the openers are drawn as a row of labels by the composer.
+     *
+     * On by default: a person who has just opened the workspace sees what it is
+     * worth asking without opening anything. The same openers are always behind
+     * the composer's own suggestions menu, so a host with little room — a frame
+     * on a landing page, where the labels would be a row of the first screen —
+     * turns the labels off and loses nothing.
+     */
+    suggestionLabels: boolean;
     /**
      * Pixels to reserve at the top of the workspace when it goes full screen —
      * room for a host's own fixed header, drawn outside the workspace

package/lib/loop/plugins/chat/index.js

@@ -48,6 +48,7 @@ export const ChatPlugin = definePlugin({
         hidePrompt: false,
         promptPlacement: 'bottom',
         autoFocusPrompt: true,
+        suggestionLabels: true,
         fullScreenTopOffset: 0,
     },
     displayName: 'Chat',

package/lib/loop/presets.d.ts

@@ -54,6 +54,12 @@ export type LoopPresetOptions = {
      * does not scroll the reader into the middle of the page.
      */
     autoFocusPrompt?: boolean;
+    /**
+     * Whether the openers show as labels by the composer. True by default; the
+     * composer's suggestions menu offers them either way. See
+     * `ChatPluginConfig.suggestionLabels`.
+     */
+    suggestionLabels?: boolean;
     /**
      * Pixels to reserve at the top of the workspace when it goes full screen,
      * for a host's own fixed header. Passed through to the chat plugin — see

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, 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, 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.
@@ -66,6 +66,7 @@ export function loopPlugins(options = {}) {
             headerButtons: { newChat: chatHeaderButtons, clear: chatHeaderButtons },
             promptPlacement: floatingPrompt ? 'floating' : promptPlacement,
             autoFocusPrompt,
+            suggestionLabels,
             fullScreenTopOffset,
         }),
         // The composer and the title bar are plugins of their own: the chat