@datalayer/agent-runtimes 1.3.16 → 1.3.18

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/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/specs/actions.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Action Classes.
+ *
+ * What every tool does to the world: read, write, send, buy, delete, publish.
+ * A tool with no class is unknown, and unknown is the most restricted.
+ *
+ * This file is AUTO-GENERATED from YAML specifications.
+ * DO NOT EDIT MANUALLY - run 'make specs' to regenerate.
+ */
+import type { ActionClass, AppBehaviour, AppEscalation, ServerActionsSpec } from '../types/agentspecs';
+/** The classes of action, from the one that changes nothing. */
+export declare const ACTION_CLASSES: ActionClass[];
+/** What each tool of the tools catalogue does, by id. */
+export declare const TOOL_ACTIONS: Record<string, ActionClass[]>;
+/**
+ * What each MCP server's tools do, by server id. `checked` is the day the
+ * names were read off the running server; absent when nobody looked.
+ */
+export declare const SERVER_ACTIONS: Record<string, ServerActionsSpec>;
+/**
+ * What each application of the catalogue does about each classed tool of the
+ * servers it connects to, as agentspecs decides it. What the rules engine has
+ * to reproduce.
+ */
+export declare const APP_BEHAVIOURS: Record<string, Record<string, AppBehaviour>>;
+/**
+ * Where what a tool is asked changes what an application does about it: by
+ * application and tool, each condition and the behaviour when it holds.
+ */
+export declare const APP_ESCALATIONS: Record<string, Record<string, AppEscalation[]>>;