@datalayer/agent-runtimes 1.3.27 → 1.3.29

package/lib/chat/assistant/formats/clippy.js

@@ -0,0 +1,167 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The clippy.js character format: an `agent.js` that registers the
+ * character's data (`clippy.ready('Name', {...})`), a `map.png` sprite sheet
+ * the frames index into, and optionally a `sounds-*.js` that registers its
+ * sounds as data URLs (`clippy.soundsReady('Name', {...})`). The JavaScript
+ * is read as data, never run.
+ *
+ * @module chat/assistant/formats/clippy
+ */
+import { blobBytes, imageTypeOf, objectUrl } from './blobs';
+import { readRegistrationCall } from './objectLiteral';
+import { AssistantCharacterFormatError, } from './types';
+function fail(message) {
+    throw new AssistantCharacterFormatError(message);
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isCount(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+}
+function readFrame(raw, where, frameCount, overlayCount) {
+    if (!isObject(raw))
+        fail(`agent.js: ${where} is not an object.`);
+    const duration = raw.duration;
+    if (typeof duration !== 'number' ||
+        !Number.isFinite(duration) ||
+        duration < 0) {
+        fail(`agent.js: ${where} has no duration in milliseconds.`);
+    }
+    const frame = { duration, images: [] };
+    if (raw.images !== undefined) {
+        if (!Array.isArray(raw.images))
+            fail(`agent.js: the images of ${where} are not a list.`);
+        if (overlayCount > 0 && raw.images.length > overlayCount) {
+            fail(`agent.js: ${where} layers ${raw.images.length} images, more than its overlayCount of ${overlayCount}.`);
+        }
+        frame.images = raw.images.map((image, k) => {
+            if (!Array.isArray(image) ||
+                image.length !== 2 ||
+                !isCount(image[0]) ||
+                !isCount(image[1])) {
+                return fail(`agent.js: image ${k} of ${where} is not an [x, y] sprite offset.`);
+            }
+            return { x: image[0], y: image[1] };
+        });
+    }
+    if (raw.sound !== undefined && raw.sound !== null) {
+        if (typeof raw.sound !== 'string' && typeof raw.sound !== 'number') {
+            fail(`agent.js: the sound of ${where} is not a sound id.`);
+        }
+        frame.sound = String(raw.sound);
+    }
+    if (raw.exitBranch !== undefined && raw.exitBranch !== null) {
+        if (!isCount(raw.exitBranch) || raw.exitBranch >= frameCount) {
+            fail(`agent.js: the exitBranch of ${where} is not a frame of its animation.`);
+        }
+        frame.exitBranch = raw.exitBranch;
+    }
+    if (raw.branching !== undefined && raw.branching !== null) {
+        const branches = isObject(raw.branching)
+            ? raw.branching.branches
+            : undefined;
+        if (!Array.isArray(branches)) {
+            fail(`agent.js: the branching of ${where} has no list of branches.`);
+        }
+        frame.branching = branches.map((branch, k) => {
+            if (!isObject(branch) ||
+                !isCount(branch.frameIndex) ||
+                branch.frameIndex >= frameCount ||
+                typeof branch.weight !== 'number' ||
+                branch.weight < 0) {
+                return fail(`agent.js: branch ${k} of ${where} is not a frame of its animation with a weight.`);
+            }
+            return { frameIndex: branch.frameIndex, weight: branch.weight };
+        });
+    }
+    return frame;
+}
+/** Read the character data of an `agent.js` (no sprite, no sounds). */
+export function readClippyAgent(agentJs) {
+    const { name, data } = readRegistrationCall(agentJs, /(?:[A-Za-z_$][\w$]*\.)*ready/, 'agent.js');
+    if (!isObject(data))
+        fail('agent.js does not register an object of character data.');
+    const size = data.framesize;
+    if (!Array.isArray(size) ||
+        size.length !== 2 ||
+        !isCount(size[0]) ||
+        !isCount(size[1]) ||
+        size[0] === 0 ||
+        size[1] === 0) {
+        fail('agent.js has no framesize: a [width, height] in pixels is required.');
+    }
+    let overlayCount = 1;
+    if (data.overlayCount !== undefined) {
+        if (!isCount(data.overlayCount) || data.overlayCount === 0) {
+            fail('agent.js: overlayCount is not a positive whole number.');
+        }
+        overlayCount = data.overlayCount;
+    }
+    if (!isObject(data.animations))
+        fail('agent.js has no animations.');
+    const animations = {};
+    for (const [animationName, raw] of Object.entries(data.animations)) {
+        if (!isObject(raw) ||
+            !Array.isArray(raw.frames) ||
+            raw.frames.length === 0) {
+            fail(`agent.js: the animation ${animationName} has no frames.`);
+        }
+        const frames = raw.frames;
+        animations[animationName] = {
+            frames: frames.map((frame, k) => readFrame(frame, `frame ${k} of the animation ${animationName}`, frames.length, overlayCount)),
+        };
+    }
+    if (Object.keys(animations).length === 0)
+        fail('agent.js has no animations.');
+    return {
+        name: name?.trim() || 'Character',
+        frameSize: { width: size[0], height: size[1] },
+        animations,
+        overlayCount,
+    };
+}
+/** Read the sounds of a `sounds-*.js`: sound id to (data) URL. */
+export function readClippySounds(soundsJs) {
+    const { data } = readRegistrationCall(soundsJs, /(?:[A-Za-z_$][\w$]*\.)*soundsReady/, 'The sounds file');
+    if (!isObject(data))
+        fail('The sounds file does not register an object of sounds.');
+    const sounds = {};
+    for (const [id, url] of Object.entries(data)) {
+        if (typeof url !== 'string' || !/^data:audio\//.test(url)) {
+            fail(`The sounds file: sound ${id} is not an audio data URL.`);
+        }
+        sounds[id] = url;
+    }
+    return sounds;
+}
+/**
+ * Read a clippy.js character from the files a person picked. Everything
+ * stays in the page: the sprite becomes an object URL.
+ */
+export async function readClippyCharacter(files) {
+    const agent = readClippyAgent(files.agentJs);
+    const sounds = files.soundsJs !== undefined ? readClippySounds(files.soundsJs) : undefined;
+    if (sounds) {
+        for (const [animationName, animation] of Object.entries(agent.animations)) {
+            animation.frames.forEach((frame, k) => {
+                if (frame.sound !== undefined && !(frame.sound in sounds)) {
+                    fail(`Frame ${k} of the animation ${animationName} plays the sound ${frame.sound}, which the sounds file does not hold.`);
+                }
+            });
+        }
+    }
+    const head = await blobBytes(files.mapPng.slice(0, 16));
+    const type = imageTypeOf(head);
+    if (!type)
+        fail('map.png is not an image (PNG, GIF, JPEG or WebP).');
+    const sprite = objectUrl(files.mapPng.type === type
+        ? files.mapPng
+        : new Blob([files.mapPng], { type }));
+    const { overlayCount: _overlays, ...character } = agent;
+    return { ...character, sprite, ...(sounds ? { sounds } : {}) };
+}

package/lib/chat/assistant/formats/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Character files a person brings (LOOP T-26): clippy.js sprite maps and
+ * Microsoft Agent `.acs` files, read in the page into one shape.
+ *
+ * @module chat/assistant/formats
+ */
+export * from './types';
+export { readClippyCharacter, readClippyAgent, readClippySounds, } from './clippy';
+export type { ClippyCharacterFiles } from './clippy';
+export { readAcsCharacter, parseAcs, decodeAcsImage, layoutAcsSprite, composeAcsCell, } from './acs';
+export type { AcsFile, AcsAnimation, AcsFrame, AcsImage } from './acs';
+export { decompressAgentData } from './agentCompression';
+export { stateAnimations } from './stateAnimations';

package/lib/chat/assistant/formats/index.js

@@ -0,0 +1,15 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Character files a person brings (LOOP T-26): clippy.js sprite maps and
+ * Microsoft Agent `.acs` files, read in the page into one shape.
+ *
+ * @module chat/assistant/formats
+ */
+export * from './types';
+export { readClippyCharacter, readClippyAgent, readClippySounds, } from './clippy';
+export { readAcsCharacter, parseAcs, decodeAcsImage, layoutAcsSprite, composeAcsCell, } from './acs';
+export { decompressAgentData } from './agentCompression';
+export { stateAnimations } from './stateAnimations';

package/lib/chat/assistant/formats/objectLiteral.d.ts

@@ -0,0 +1,23 @@
+export type LiteralValue = string | number | boolean | null | undefined | LiteralValue[] | {
+    [key: string]: LiteralValue;
+};
+/** The result of reading one value: the value and where the text goes on. */
+export interface LiteralRead {
+    value: LiteralValue;
+    end: number;
+}
+/**
+ * Read the literal value starting at `start` (whitespace and comments
+ * skipped). `what` names the file in error messages.
+ */
+export declare function readObjectLiteral(text: string, start: number, what: string): LiteralRead;
+/**
+ * The name and the data of a `ready('Name', {...})` call — the way clippy.js
+ * agent and sound files register themselves (`clippy.ready`,
+ * `clippy.agent.ready`, `clippy.soundsReady`) — or of a file that is only
+ * the object literal (JSON).
+ */
+export declare function readRegistrationCall(text: string, callee: RegExp, what: string): {
+    name?: string;
+    data: LiteralValue;
+};

package/lib/chat/assistant/formats/objectLiteral.js

@@ -0,0 +1,233 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Reads a JavaScript object literal from text without running it: JSON, plus
+ * what hand-written JavaScript adds — unquoted keys, single quotes, comments,
+ * trailing commas. Anything that would need evaluating (a call, a variable,
+ * an expression) is refused.
+ *
+ * @module chat/assistant/formats/objectLiteral
+ */
+import { AssistantCharacterFormatError } from './types';
+const IDENTIFIER_START = /[A-Za-z_$]/;
+const IDENTIFIER_PART = /[A-Za-z0-9_$]/;
+const MAX_DEPTH = 64;
+/**
+ * Read the literal value starting at `start` (whitespace and comments
+ * skipped). `what` names the file in error messages.
+ */
+export function readObjectLiteral(text, start, what) {
+    let i = start;
+    const fail = (message) => {
+        const line = text.slice(0, i).split('\n').length;
+        throw new AssistantCharacterFormatError(`${what} cannot be read at line ${line}: ${message}.`);
+    };
+    const skip = () => {
+        for (;;) {
+            const c = text[i];
+            if (c === ' ' ||
+                c === '\t' ||
+                c === '\n' ||
+                c === '\r' ||
+                c === '\uFEFF') {
+                i++;
+            }
+            else if (c === '/' && text[i + 1] === '/') {
+                while (i < text.length && text[i] !== '\n')
+                    i++;
+            }
+            else if (c === '/' && text[i + 1] === '*') {
+                const close = text.indexOf('*/', i + 2);
+                if (close < 0)
+                    fail('a comment is never closed');
+                i = close + 2;
+            }
+            else {
+                return;
+            }
+        }
+    };
+    const readString = () => {
+        const quote = text[i++];
+        let out = '';
+        for (;;) {
+            if (i >= text.length)
+                fail('a string is never closed');
+            const c = text[i++];
+            if (c === quote)
+                return out;
+            if (c === '\n')
+                fail('a string runs past the end of its line');
+            if (c !== '\\') {
+                out += c;
+                continue;
+            }
+            const e = text[i++];
+            switch (e) {
+                case 'n':
+                    out += '\n';
+                    break;
+                case 't':
+                    out += '\t';
+                    break;
+                case 'r':
+                    out += '\r';
+                    break;
+                case 'b':
+                    out += '\b';
+                    break;
+                case 'f':
+                    out += '\f';
+                    break;
+                case 'v':
+                    out += '\v';
+                    break;
+                case '0':
+                    out += '\0';
+                    break;
+                case 'x': {
+                    const hex = text.slice(i, i + 2);
+                    if (!/^[0-9a-fA-F]{2}$/.test(hex))
+                        fail('a \\x escape is malformed');
+                    out += String.fromCharCode(parseInt(hex, 16));
+                    i += 2;
+                    break;
+                }
+                case 'u': {
+                    const hex = text.slice(i, i + 4);
+                    if (!/^[0-9a-fA-F]{4}$/.test(hex))
+                        fail('a \\u escape is malformed');
+                    out += String.fromCharCode(parseInt(hex, 16));
+                    i += 4;
+                    break;
+                }
+                case '\r':
+                    if (text[i] === '\n')
+                        i++;
+                    break;
+                case '\n':
+                    break;
+                case undefined:
+                    fail('a string is never closed');
+                    break;
+                default:
+                    out += e;
+            }
+        }
+    };
+    const readNumber = () => {
+        const match = /^[+-]?(?:0[xX][0-9a-fA-F]+|(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?)/.exec(text.slice(i, i + 64));
+        if (!match)
+            return fail('a number is malformed');
+        i += match[0].length;
+        const n = Number(match[0]);
+        if (!Number.isFinite(n))
+            fail('a number is malformed');
+        return n;
+    };
+    const readIdentifier = () => {
+        const begin = i;
+        while (i < text.length && IDENTIFIER_PART.test(text[i]))
+            i++;
+        return text.slice(begin, i);
+    };
+    const readValue = (depth) => {
+        if (depth > MAX_DEPTH)
+            fail('it nests too deeply');
+        skip();
+        const c = text[i];
+        if (c === undefined)
+            fail('the text ends where a value was expected');
+        if (c === '{') {
+            i++;
+            const obj = Object.create(null);
+            for (;;) {
+                skip();
+                if (text[i] === '}') {
+                    i++;
+                    return obj;
+                }
+                let key;
+                const k = text[i];
+                if (k === '"' || k === "'")
+                    key = readString();
+                else if (k !== undefined && /[0-9]/.test(k))
+                    key = String(readNumber());
+                else if (k !== undefined && IDENTIFIER_START.test(k))
+                    key = readIdentifier();
+                else
+                    return fail(`a key was expected, found "${k ?? 'the end'}"`);
+                skip();
+                if (text[i] !== ':')
+                    fail(`a ":" was expected after the key "${key}"`);
+                i++;
+                obj[key] = readValue(depth + 1);
+                skip();
+                if (text[i] === ',')
+                    i++;
+                else if (text[i] !== '}')
+                    fail('a "," or "}" was expected in an object');
+            }
+        }
+        if (c === '[') {
+            i++;
+            const arr = [];
+            for (;;) {
+                skip();
+                if (text[i] === ']') {
+                    i++;
+                    return arr;
+                }
+                arr.push(readValue(depth + 1));
+                skip();
+                if (text[i] === ',')
+                    i++;
+                else if (text[i] !== ']')
+                    fail('a "," or "]" was expected in a list');
+            }
+        }
+        if (c === '"' || c === "'")
+            return readString();
+        if (/[-+.0-9]/.test(c))
+            return readNumber();
+        if (IDENTIFIER_START.test(c)) {
+            const word = readIdentifier();
+            if (word === 'true')
+                return true;
+            if (word === 'false')
+                return false;
+            if (word === 'null')
+                return null;
+            if (word === 'undefined')
+                return undefined;
+            return fail(`"${word}" is code, not data, and is not run`);
+        }
+        return fail(`"${c}" is not the start of a value`);
+    };
+    const value = readValue(0);
+    return { value, end: i };
+}
+/**
+ * The name and the data of a `ready('Name', {...})` call — the way clippy.js
+ * agent and sound files register themselves (`clippy.ready`,
+ * `clippy.agent.ready`, `clippy.soundsReady`) — or of a file that is only
+ * the object literal (JSON).
+ */
+export function readRegistrationCall(text, callee, what) {
+    const call = new RegExp(`(?:^|[^A-Za-z0-9_$])(?:${callee.source})\\s*\\(\\s*(["'])((?:\\\\.|(?!\\1).)*)\\1\\s*,`).exec(text);
+    if (call) {
+        const { value } = readObjectLiteral(text, call.index + call[0].length, what);
+        return { name: call[2], data: value };
+    }
+    const first = text.replace(/^\uFEFF/, '').trimStart();
+    if (first.startsWith('{')) {
+        const { value, end } = readObjectLiteral(text, text.indexOf('{'), what);
+        if (text.slice(end).trim().replace(/;$/, '') !== '') {
+            throw new AssistantCharacterFormatError(`${what} holds more than one object: only the character's data is read.`);
+        }
+        return { data: value };
+    }
+    throw new AssistantCharacterFormatError(`${what} is not a clippy.js file: it has no ready('Name', {...}) call and is not a JSON object.`);
+}

package/lib/chat/assistant/formats/stateAnimations.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Which of a character's animations act each state of the assistant (T-22),
+ * by the names the characters of Office use — the same in clippy.js maps and
+ * in Microsoft Agent files — and by the states an Agent character declares.
+ *
+ * @module chat/assistant/formats/stateAnimations
+ */
+import type { AssistantState } from '../state';
+import type { AssistantCharacterData } from './types';
+/**
+ * For each state, the animation names to pick from, by what the character
+ * offers: the names Office characters use, then the states an Agent file
+ * declares; failing both, the idle animations; failing those, the first
+ * animation. Never empty.
+ */
+export declare function stateAnimations(character: AssistantCharacterData): Record<AssistantState, string[]>;

package/lib/chat/assistant/formats/stateAnimations.js

@@ -0,0 +1,115 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** Names, in order of preference, matched without case. */
+const NAMES = {
+    idle: [],
+    thinking: [
+        'Thinking',
+        'Think',
+        'CheckingSomething',
+        'Searching',
+        'Search',
+        'Uncertain',
+    ],
+    working: [
+        'Processing',
+        'Working',
+        'Writing',
+        'Write',
+        'Searching',
+        'Search',
+        'GetTechy',
+        'CheckingSomething',
+        'Read',
+        'Reading',
+    ],
+    waiting: [
+        'GetAttention',
+        'Alert',
+        'Suggest',
+        'LookDown',
+        'GestureDown',
+        'Acknowledge',
+    ],
+    greeting: ['Greeting', 'Greet', 'Show', 'Wave'],
+    speaking: [
+        'Explain',
+        'Speak',
+        'Speaking',
+        'Announce',
+        'GestureRight',
+        'GestureLeft',
+    ],
+    goodbye: ['GoodBye', 'Goodbye', 'Hide', 'Wave'],
+};
+/** States a Microsoft Agent character declares, for each assistant state. */
+const AUTHORED = {
+    idle: ['IdlingLevel1', 'IdlingLevel2', 'IdlingLevel3'],
+    thinking: [],
+    working: [],
+    waiting: ['Listening'],
+    greeting: ['Showing'],
+    speaking: ['Speaking'],
+    goodbye: ['Hiding'],
+};
+const IDLE = /^(idle|rest ?pose)/i;
+const STATES = [
+    'idle',
+    'thinking',
+    'working',
+    'waiting',
+    'greeting',
+    'speaking',
+    'goodbye',
+];
+/**
+ * For each state, the animation names to pick from, by what the character
+ * offers: the names Office characters use, then the states an Agent file
+ * declares; failing both, the idle animations; failing those, the first
+ * animation. Never empty.
+ */
+export function stateAnimations(character) {
+    const names = Object.keys(character.animations);
+    if (names.length === 0) {
+        throw new Error(`The character ${character.name} has no animations.`);
+    }
+    const byLower = new Map();
+    for (const name of names) {
+        if (!byLower.has(name.toLowerCase()))
+            byLower.set(name.toLowerCase(), name);
+    }
+    const authored = new Map();
+    for (const [state, list] of Object.entries(character.authoredStates ?? {})) {
+        authored.set(state.toLowerCase().replace(/\s+/g, ''), list);
+    }
+    const pick = (wanted) => {
+        const out = [];
+        for (const want of wanted) {
+            const name = byLower.get(want.toLowerCase());
+            if (name && !out.includes(name))
+                out.push(name);
+        }
+        return out;
+    };
+    const idleByName = names.filter(name => IDLE.test(name));
+    const idleAuthored = pick(AUTHORED.idle.flatMap(s => authored.get(s.toLowerCase()) ?? []));
+    const idle = [...new Set([...idleByName, ...idleAuthored])];
+    const fallback = idle.length > 0 ? idle : [names[0]];
+    const result = {};
+    for (const state of STATES) {
+        if (state === 'idle') {
+            result.idle = fallback;
+            continue;
+        }
+        const found = [
+            ...new Set([
+                ...pick(NAMES[state]),
+                ...pick(AUTHORED[state].flatMap(s => authored.get(s.toLowerCase()) ?? [])),
+            ]),
+        ];
+        result[state] = found.length > 0 ? found : fallback;
+    }
+    return result;
+}

package/lib/chat/assistant/formats/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The one shape a character file is read into (LOOP T-26), whatever its
+ * format: a sprite sheet, frames that index into it, animations by name.
+ *
+ * @module chat/assistant/formats/types
+ */
+/** One frame of an animation. */
+export interface AssistantCharacterFrame {
+    /** How long the frame shows, in milliseconds. */
+    duration: number;
+    /**
+     * The sprite offsets of the frame's images, layered bottom to top: each is
+     * the top-left corner, in the sprite sheet, of a `frameSize` cell (drawn as
+     * `background-position: -x px -y px`). An empty list is an empty frame.
+     */
+    images: Array<{
+        x: number;
+        y: number;
+    }>;
+    /** The id of the sound played when the frame shows, a key of `sounds`. */
+    sound?: string;
+    /** Where the animation may jump after this frame, weights in percent. */
+    branching?: {
+        frameIndex: number;
+        weight: number;
+    }[];
+    /** The frame to go to when the animation is asked to end early. */
+    exitBranch?: number;
+}
+/** A named sequence of frames. */
+export interface AssistantCharacterAnimation {
+    frames: AssistantCharacterFrame[];
+}
+/** A character, read from a file a person holds the rights to. */
+export interface AssistantCharacterData {
+    name: string;
+    frameSize: {
+        width: number;
+        height: number;
+    };
+    /** The sprite sheet: a URL (object URL or data URL) the frames' offsets index into. */
+    sprite: string;
+    animations: Record<string, AssistantCharacterAnimation>;
+    /** Sound id to URL. */
+    sounds?: Record<string, string>;
+    /**
+     * The character's own grouping of its animations into states, when the
+     * format carries one (a Microsoft Agent character does: `Showing`,
+     * `Hiding`, `Speaking`, `IdlingLevel1`…). Read by `stateAnimations`.
+     */
+    authoredStates?: Record<string, string[]>;
+}
+/** A character file that cannot be read: the message says what is wrong. */
+export declare class AssistantCharacterFormatError extends Error {
+    constructor(message: string);
+}

package/lib/chat/assistant/formats/types.js

@@ -0,0 +1,11 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** A character file that cannot be read: the message says what is wrong. */
+export class AssistantCharacterFormatError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AssistantCharacterFormatError';
+    }
+}