@datalayer/agent-runtimes 1.3.16 → 1.3.17

package/lib/loop/apps/appspec.js

@@ -0,0 +1,566 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { BEHAVIOURS } from './rules';
+/** The version of the spec itself. */
+export const APP_SCHEMA = 'loop.app/v1';
+/** The face of an application that has not chosen one. */
+export const DEFAULT_EMOJI = '\u{1F440}';
+export const APP_KINDS = ['chat', 'widget', 'decision', 'worker'];
+export const APP_ACCENTS = [
+    'green',
+    'rose',
+    'sky',
+    'lime',
+    'sun',
+    'violet',
+];
+const ACTION_CLASS_NAMES = [
+    'read',
+    'write',
+    'send',
+    'buy',
+    'delete',
+    'publish',
+];
+/** The layout a kind starts with. */
+export const DEFAULT_LAYOUTS = {
+    chat: 'chat',
+    widget: 'page',
+    decision: 'page',
+    worker: 'split',
+};
+/** What an application keeps of what it did, when it does not say. */
+export const DEFAULT_RECORD_INCLUDE = ['conversations', 'actions', 'approvals'];
+const DEFAULT_KEEP_FOR = '1_years';
+const DEFAULT_READY_AT = 0.8;
+const DEFAULT_PROTOCOL = 'a2ui/v0.9';
+const DEFAULT_ICON = 'apps';
+const DEFAULT_VERSION = '0.0.1';
+const isData = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+const text = (value, otherwise = '') => typeof value === 'string' ? value : otherwise;
+const flag = (value, otherwise) => typeof value === 'boolean' ? value : otherwise;
+const numberOf = (value, otherwise) => typeof value === 'number' && Number.isFinite(value) ? value : otherwise;
+const texts = (value) => Array.isArray(value)
+    ? value.filter((item) => typeof item === 'string')
+    : [];
+const records = (value) => Array.isArray(value) ? value.filter(isData) : [];
+const oneOf = (value, allowed, otherwise) => (allowed.includes(value) ? value : otherwise);
+const RETENTION = /^([1-9]\d*)_(day|days|month|months|year|years)$/;
+const DAYS = { day: 1, month: 30, year: 365 };
+/** A retention as days: `90_days`, `18_months`, `1_years`; 0 when it cannot be read. */
+export function retentionDays(keepFor) {
+    const matched = RETENTION.exec(keepFor.trim());
+    return matched ? Number(matched[1]) * DAYS[matched[2].replace(/s$/, '')] : 0;
+}
+/** An application with nothing said: what *Start blank* opens. */
+export function emptyAppspec(kind = 'chat') {
+    return {
+        schema: APP_SCHEMA,
+        id: '',
+        version: DEFAULT_VERSION,
+        name: '',
+        kind,
+        description: '',
+        owner: '',
+        agent: '',
+        team: '',
+        instructions: '',
+        model: '',
+        skills: [],
+        tools: [],
+        context: [],
+        contents: [],
+        connections: [],
+        rules: [],
+        permissions: {
+            spaces: [],
+            computer: { browse: false, files: false, shell: false },
+        },
+        interface: {
+            layout: DEFAULT_LAYOUTS[kind],
+            accent: 'green',
+            welcome: '',
+            starters: [],
+            settings: [],
+            components: [],
+        },
+        tests: { readyAt: DEFAULT_READY_AT, evalset: '', cases: [] },
+        record: {
+            keepFor: DEFAULT_KEEP_FOR,
+            retentionDays: retentionDays(DEFAULT_KEEP_FOR),
+            include: [...DEFAULT_RECORD_INCLUDE],
+        },
+        checks: { guards: [], gates: [], track: '' },
+        deployment: {},
+        goal: '',
+        triggers: [],
+        memory: '',
+        notifications: [],
+        setup: [],
+        enabled: true,
+        tags: [],
+        icon: DEFAULT_ICON,
+        emoji: DEFAULT_EMOJI,
+    };
+}
+// --- reading --------------------------------------------------------------------------
+const KNOWN_KEYS = [
+    'schema',
+    'id',
+    'version',
+    'name',
+    'kind',
+    'description',
+    'owner',
+    'agent',
+    'team',
+    'instructions',
+    'model',
+    'skills',
+    'tools',
+    'context',
+    'contents',
+    'connections',
+    'rules',
+    'permissions',
+    'interface',
+    'tests',
+    'record',
+    'checks',
+    'deployment',
+    'goal',
+    'triggers',
+    'memory',
+    'notifications',
+    'decision',
+    'enabled',
+    'tags',
+    'icon',
+    'emoji',
+];
+function parseConnection(data) {
+    return {
+        server: text(data.server),
+        access: oneOf(data.access, ['read', 'write'], 'read'),
+        as: oneOf(data.as, ['owner', 'user'], 'owner'),
+        only: texts(data.only),
+    };
+}
+function parseRule(data) {
+    return {
+        action: text(data.action),
+        appliesTo: typeof data.applies_to === 'string'
+            ? [data.applies_to]
+            : texts(data.applies_to),
+        behaviour: oneOf(data.behaviour, BEHAVIOURS, 'ask_first'),
+    };
+}
+function parseSetting(data) {
+    const setting = {
+        id: text(data.id),
+        type: oneOf(data.type, ['select', 'text', 'toggle', 'slider', 'number'], 'text'),
+        label: text(data.label),
+        options: texts(data.options),
+    };
+    if (['string', 'boolean', 'number'].includes(typeof data.default)) {
+        setting.default = data.default;
+    }
+    if (typeof data.min === 'number') {
+        setting.min = data.min;
+    }
+    if (typeof data.max === 'number') {
+        setting.max = data.max;
+    }
+    return setting;
+}
+function parseSurface(data) {
+    return {
+        protocol: text(data.protocol, DEFAULT_PROTOCOL),
+        components: records(data.components).filter(component => typeof component.id === 'string' &&
+            typeof component.component === 'string'),
+        composedBy: text(data.composed_by),
+        composedAt: text(data.composed_at),
+    };
+}
+function parseInterface(data, kind) {
+    const parsed = {
+        layout: oneOf(data.layout, ['chat', 'page', 'split'], DEFAULT_LAYOUTS[kind]),
+        accent: oneOf(data.accent, APP_ACCENTS, 'green'),
+        welcome: text(data.welcome),
+        starters: records(data.starters).map(starter => ({
+            label: text(starter.label),
+            message: text(starter.message),
+        })),
+        settings: records(data.settings).map(parseSetting),
+        components: texts(data.components),
+    };
+    if (isData(data.surface)) {
+        parsed.surface = parseSurface(data.surface);
+    }
+    return parsed;
+}
+function parseCriterion(data) {
+    return {
+        name: text(data.name),
+        kind: oneOf(data.kind, ['metric', 'noul', 'choice', 'score'], 'metric'),
+        weight: Math.max(0, numberOf(data.weight, 1)),
+        instructions: text(data.instructions),
+        options: texts(data.options),
+        direction: data.direction === 'lower' ? 'lower' : 'higher',
+        measure: oneOf(data.measure, ['', 'pass_rate', 'cost_per_task', 'seconds_per_task'], ''),
+    };
+}
+function parseDecision(data) {
+    return {
+        question: text(data.question),
+        alternatives: texts(data.alternatives),
+        criteria: records(data.criteria).map(parseCriterion),
+        minConfidence: Math.min(1, Math.max(0, numberOf(data.min_confidence, 0))),
+        scenarios: records(data.scenarios).map(scenario => ({
+            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),
+    };
+}
+function parseDeployment(data) {
+    const deployment = {};
+    if (isData(data.hosted)) {
+        deployment.hosted = {
+            visibility: oneOf(data.hosted.visibility, ['private', 'invited', 'organization', 'link', 'public'], 'private'),
+            slug: text(data.hosted.slug),
+        };
+    }
+    if (isData(data.embedded)) {
+        deployment.embedded = {
+            mode: oneOf(data.embedded.mode, ['inline', 'bubble', 'panel'], 'inline'),
+            origins: texts(data.embedded.origins),
+        };
+    }
+    return deployment;
+}
+function parseTrigger(data) {
+    return {
+        type: oneOf(data.type, ['schedule', 'event', 'once'], 'schedule'),
+        cron: text(data.cron),
+        event: text(data.event),
+        at: text(data.at),
+        description: text(data.description),
+        prompt: text(data.prompt),
+    };
+}
+/**
+ * An application from a document in the spec's own words.
+ *
+ * Tolerant: what is missing takes its default, and what cannot be read is
+ * reported in `problems` — a key the spec does not know, a version of the
+ * spec this does not read, a kind that is not one. The application returned
+ * is always whole, so an editor can open it and show what is wrong.
+ */
+export function parseAppspec(document) {
+    const problems = [];
+    if (!isData(document)) {
+        return {
+            app: emptyAppspec(),
+            problems: ['The document is not an application.'],
+        };
+    }
+    const data = document;
+    for (const key of Object.keys(data)) {
+        if (!KNOWN_KEYS.includes(key)) {
+            problems.push(`\`${key}\` is not a field of the spec.`);
+        }
+    }
+    const schema = text(data.schema, APP_SCHEMA);
+    if (schema !== APP_SCHEMA) {
+        problems.push(`This reads ${APP_SCHEMA}; the application is written in ${schema}.`);
+    }
+    if (!APP_KINDS.includes(data.kind)) {
+        problems.push(data.kind === undefined
+            ? 'The application does not say its `kind`.'
+            : `\`${String(data.kind)}\` is not a kind: chat, widget, decision or worker.`);
+    }
+    const kind = oneOf(data.kind, APP_KINDS, 'chat');
+    const base = emptyAppspec(kind);
+    const permissions = isData(data.permissions) ? data.permissions : {};
+    const computer = isData(permissions.computer) ? permissions.computer : {};
+    const tests = isData(data.tests) ? data.tests : {};
+    const record = isData(data.record) ? data.record : {};
+    const checks = isData(data.checks) ? data.checks : {};
+    const keepFor = text(record.keep_for, DEFAULT_KEEP_FOR);
+    if (retentionDays(keepFor) === 0) {
+        problems.push(`Cannot read the retention \`${keepFor}\`: write 90_days, 18_months or 1_years.`);
+    }
+    const app = {
+        ...base,
+        schema: APP_SCHEMA,
+        id: text(data.id),
+        version: text(data.version, DEFAULT_VERSION),
+        name: text(data.name),
+        kind,
+        description: text(data.description),
+        owner: text(data.owner),
+        agent: text(data.agent),
+        team: text(data.team),
+        instructions: text(data.instructions),
+        model: text(data.model),
+        skills: texts(data.skills),
+        tools: texts(data.tools),
+        context: texts(data.context),
+        contents: texts(data.contents),
+        connections: records(data.connections).map(parseConnection),
+        rules: records(data.rules).map(parseRule),
+        permissions: {
+            spaces: records(permissions.spaces).map(grant => ({
+                space: text(grant.space),
+                access: oneOf(grant.access, ['read', 'write'], 'read'),
+            })),
+            computer: {
+                browse: flag(computer.browse, false),
+                files: flag(computer.files, false),
+                shell: flag(computer.shell, false),
+            },
+        },
+        interface: parseInterface(isData(data.interface) ? data.interface : {}, kind),
+        tests: {
+            readyAt: Math.min(1, Math.max(0, numberOf(tests.ready_at, DEFAULT_READY_AT))),
+            evalset: text(tests.evalset),
+            cases: records(tests.cases).map(testCase => ({
+                ask: text(testCase.ask),
+                expect: text(testCase.expect),
+            })),
+        },
+        record: {
+            keepFor,
+            retentionDays: retentionDays(keepFor),
+            include: Array.isArray(record.include)
+                ? texts(record.include)
+                : [...DEFAULT_RECORD_INCLUDE],
+        },
+        checks: {
+            guards: texts(checks.guards),
+            gates: texts(checks.gates),
+            track: text(checks.track),
+        },
+        deployment: parseDeployment(isData(data.deployment) ? data.deployment : {}),
+        goal: text(data.goal),
+        triggers: records(data.triggers).map(parseTrigger),
+        memory: text(data.memory),
+        notifications: texts(data.notifications),
+        enabled: flag(data.enabled, true),
+        tags: texts(data.tags),
+        icon: text(data.icon, DEFAULT_ICON),
+        emoji: text(data.emoji, DEFAULT_EMOJI) || DEFAULT_EMOJI,
+    };
+    if (isData(data.decision)) {
+        app.decision = parseDecision(data.decision);
+    }
+    return { app, problems };
+}
+// --- writing --------------------------------------------------------------------------
+const sameList = (a, b) => a.length === b.length && a.every((item, index) => item === b[index]);
+/** A document with a key only when its value says something. */
+class Writer {
+    data = {};
+    text(key, value, otherwise = '') {
+        if (value !== otherwise) {
+            this.data[key] = value;
+        }
+        return this;
+    }
+    value(key, value, otherwise) {
+        if (value !== otherwise) {
+            this.data[key] = value;
+        }
+        return this;
+    }
+    list(key, value, otherwise = []) {
+        if (!sameList(value, otherwise)) {
+            this.data[key] = value;
+        }
+        return this;
+    }
+    /** A nested object, written only when it says something. */
+    part(key, value) {
+        if (Object.keys(value).length > 0) {
+            this.data[key] = value;
+        }
+        return this;
+    }
+    /** A nested object that is written even when empty: its presence is what it says. */
+    present(key, value) {
+        if (value !== undefined) {
+            this.data[key] = value;
+        }
+        return this;
+    }
+}
+/** A value with the keys of every mapping in it in alphabetical order. */
+function sorted(value) {
+    if (Array.isArray(value)) {
+        return value.map(sorted);
+    }
+    if (isData(value)) {
+        return Object.fromEntries(Object.keys(value)
+            .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(key => [key, sorted(value[key])]));
+    }
+    return value;
+}
+/** A component as it is written: its `id`, what it is, then the rest in alphabetical order. */
+function dumpComponent(component) {
+    const { id, component: what, ...rest } = component;
+    return { id, component: what, ...sorted(rest) };
+}
+function dumpSurface(surface) {
+    return new Writer()
+        .text('protocol', surface.protocol, DEFAULT_PROTOCOL)
+        .list('components', surface.components.map(dumpComponent))
+        .text('composed_by', surface.composedBy)
+        .text('composed_at', surface.composedAt).data;
+}
+function dumpInterface(spec, kind) {
+    const writer = new Writer()
+        // A layout is written when it is not the one its kind starts with.
+        .value('layout', spec.layout, DEFAULT_LAYOUTS[kind])
+        .value('accent', spec.accent, 'green')
+        .text('welcome', spec.welcome)
+        .list('starters', spec.starters.map(starter => ({
+        label: starter.label,
+        message: starter.message,
+    })))
+        .list('settings', spec.settings.map(setting => {
+        const written = new Writer()
+            .text('id', setting.id, '\u0000')
+            .text('type', setting.type, '\u0000')
+            .text('label', setting.label, '\u0000')
+            .list('options', setting.options);
+        for (const key of ['default', 'min', 'max']) {
+            if (setting[key] !== undefined) {
+                written.data[key] = setting[key];
+            }
+        }
+        return written.data;
+    }))
+        .list('components', spec.components);
+    if (spec.surface) {
+        writer.data.surface = dumpSurface(spec.surface);
+    }
+    return writer.data;
+}
+function dumpDecision(decision) {
+    return new Writer()
+        .text('question', decision.question, '\u0000')
+        .list('alternatives', decision.alternatives)
+        .list('criteria', decision.criteria.map(criterion => new Writer()
+        .text('name', criterion.name, '\u0000')
+        .value('kind', criterion.kind, 'metric')
+        .value('weight', criterion.weight, 1)
+        .text('instructions', criterion.instructions)
+        .list('options', criterion.options)
+        .value('direction', criterion.direction, 'higher')
+        .value('measure', criterion.measure, '').data))
+        .value('min_confidence', decision.minConfidence, 0)
+        .list('scenarios', decision.scenarios.map(scenario => new Writer()
+        .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;
+}
+/**
+ * An application as the document its file holds.
+ *
+ * The spec's own words, keys in one fixed order, nothing written that is at
+ * its default: the same application always writes the same document. What an
+ * application carries that is not the spec's — what it needs set up — is left
+ * out.
+ */
+export function dumpAppspec(app) {
+    const computer = new Writer()
+        .value('browse', app.permissions.computer.browse, false)
+        .value('files', app.permissions.computer.files, false)
+        .value('shell', app.permissions.computer.shell, false).data;
+    const writer = new Writer();
+    writer.data.schema = APP_SCHEMA;
+    writer
+        .text('id', app.id, '\u0000')
+        .text('version', app.version, DEFAULT_VERSION)
+        .text('name', app.name, '\u0000')
+        .text('kind', app.kind, '\u0000')
+        .text('description', app.description)
+        .text('owner', app.owner)
+        .text('agent', app.agent)
+        .text('team', app.team)
+        .text('instructions', app.instructions)
+        .text('model', app.model)
+        .list('skills', app.skills)
+        .list('tools', app.tools)
+        .list('context', app.context)
+        .list('contents', app.contents)
+        .list('connections', app.connections.map(connection => new Writer()
+        .text('server', connection.server, '\u0000')
+        .value('access', connection.access, 'read')
+        .value('as', connection.as, 'owner')
+        .list('only', connection.only).data))
+        .list('rules', app.rules.map(rule => ({
+        action: rule.action,
+        // One target is written alone when it is a class, as a person would.
+        applies_to: rule.appliesTo.length === 1 &&
+            ACTION_CLASS_NAMES.includes(rule.appliesTo[0])
+            ? rule.appliesTo[0]
+            : rule.appliesTo,
+        behaviour: rule.behaviour,
+    })))
+        .part('permissions', new Writer()
+        .list('spaces', app.permissions.spaces.map(grant => new Writer()
+        .text('space', grant.space, '\u0000')
+        .value('access', grant.access, 'read').data))
+        .part('computer', computer).data)
+        .part('interface', dumpInterface(app.interface, app.kind))
+        .part('tests', new Writer()
+        .value('ready_at', app.tests.readyAt, DEFAULT_READY_AT)
+        .text('evalset', app.tests.evalset)
+        .list('cases', app.tests.cases.map(testCase => ({
+        ask: testCase.ask,
+        expect: testCase.expect,
+    }))).data)
+        .part('record', new Writer()
+        .text('keep_for', app.record.keepFor, DEFAULT_KEEP_FOR)
+        .list('include', app.record.include, DEFAULT_RECORD_INCLUDE).data)
+        .part('checks', new Writer()
+        .list('guards', app.checks.guards)
+        .list('gates', app.checks.gates)
+        .text('track', app.checks.track).data)
+        .part('deployment', new Writer()
+        .present('hosted', app.deployment.hosted &&
+        new Writer()
+            .value('visibility', app.deployment.hosted.visibility, 'private')
+            .text('slug', app.deployment.hosted.slug).data)
+        .present('embedded', app.deployment.embedded &&
+        new Writer()
+            .value('mode', app.deployment.embedded.mode, 'inline')
+            .list('origins', app.deployment.embedded.origins).data).data)
+        .text('goal', app.goal)
+        .list('triggers', app.triggers.map(trigger => new Writer()
+        .text('type', trigger.type, '\u0000')
+        .text('cron', trigger.cron)
+        .text('event', trigger.event)
+        .text('at', trigger.at)
+        .text('description', trigger.description)
+        .text('prompt', trigger.prompt).data))
+        .text('memory', app.memory)
+        .list('notifications', app.notifications);
+    if (app.decision) {
+        writer.data.decision = dumpDecision(app.decision);
+    }
+    writer
+        .value('enabled', app.enabled, true)
+        .list('tags', app.tags)
+        .text('icon', app.icon ?? DEFAULT_ICON, DEFAULT_ICON)
+        .text('emoji', app.emoji, DEFAULT_EMOJI);
+    return writer.data;
+}
+/** The keys of a document in the order they are written. */
+export const APPSPEC_KEY_ORDER = KNOWN_KEYS;

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

@@ -0,0 +1,21 @@
+import type { AppSpec } from '../../types/agentspecs';
+export declare const NOT_READY = "Not ready";
+export declare const NEEDS_ATTENTION = "Needs attention";
+export declare const PASSES = "Passes the instant checks";
+export type CheckVerdict = typeof NOT_READY | typeof NEEDS_ATTENTION | typeof PASSES;
+export interface AppCheck {
+    verdict: CheckVerdict;
+    problems: string[];
+    attention: string[];
+    setup: string[];
+}
+/** The instant checks of an application as an editor holds it. */
+export declare function checkApp(app: AppSpec, read?: string[]): 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
+ * default. `loop apps validate` refuses these; so does this.
+ */
+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;