@datalayer/agent-runtimes 1.3.81 → 1.3.83

package/lib/specs/appspecSchema.js

@@ -52,6 +52,33 @@ export const APPSPEC_SCHEMA = {
             title: 'AppChecks',
             type: 'object',
         },
+        AppCommand: {
+            additionalProperties: false,
+            description: "A slash command the user picks in the composer (LOOP P-19).\n\nTyping `/` lists the application's commands; picking one sends its\n`prompt`, `{input}` replaced by the words typed after the command.",
+            properties: {
+                name: {
+                    description: 'What follows the slash: lower-case letters, digits and hyphens, a letter first (`summarise`)',
+                    pattern: '^[a-z](?:[a-z0-9-]{0,30}[a-z0-9])?$',
+                    title: 'Name',
+                    type: 'string',
+                },
+                description: {
+                    description: "What the composer's menu says it does",
+                    minLength: 1,
+                    title: 'Description',
+                    type: 'string',
+                },
+                prompt: {
+                    description: "What is sent when it is picked: `{input}` stands for the words typed after it; without `{input}`, those words follow the prompt. An application's code answers `/<name> {input}` itself (`@app.command`)",
+                    minLength: 1,
+                    title: 'Prompt',
+                    type: 'string',
+                },
+            },
+            required: ['name', 'description', 'prompt'],
+            title: 'AppCommand',
+            type: 'object',
+        },
         AppComputer: {
             additionalProperties: false,
             description: 'What the application may do on its own computer. Each is off until it is turned on.',
@@ -269,6 +296,18 @@ export const APPSPEC_SCHEMA = {
                     default: 'green',
                     description: "The application's one colour",
                 },
+                theme: {
+                    anyOf: [
+                        {
+                            $ref: '#/$defs/AppTheme',
+                        },
+                        {
+                            type: 'null',
+                        },
+                    ],
+                    default: null,
+                    description: "The theme it runs in by default, at its address, embedded, in the Studio's Preview and as an example: a `variant` and, optionally, a colour `mode`. The person's own when unsaid. Its `accent` colours the `loop` theme only",
+                },
                 welcome: {
                     default: '',
                     description: 'What the application says first',
@@ -283,14 +322,36 @@ export const APPSPEC_SCHEMA = {
                     title: 'Starters',
                     type: 'array',
                 },
-                settings: {
-                    description: 'What the user may set',
+                commands: {
+                    description: 'Slash commands the user picks in the composer: typing `/` lists them (LOOP P-19)',
                     items: {
-                        $ref: '#/$defs/AppSetting',
+                        $ref: '#/$defs/AppCommand',
                     },
-                    title: 'Settings',
+                    title: 'Commands',
+                    type: 'array',
+                },
+                modes: {
+                    description: 'Mode switches in the composer: the option picked goes with every run, its instructions told to the agent and its model run on (LOOP P-19)',
+                    items: {
+                        $ref: '#/$defs/AppMode',
+                    },
+                    title: 'Modes',
                     type: 'array',
                 },
+                settings: {
+                    anyOf: [
+                        {
+                            additionalProperties: true,
+                            type: 'object',
+                        },
+                        {
+                            type: 'null',
+                        },
+                    ],
+                    default: null,
+                    description: "What the user may set: the JSON Schema of a form, an object of named fields, each with its `title` and its `default` (LOOP C-16). Drawn with `@datalayer/primer-rjsf` beside the conversation and on a deployment's Ship card, its values go with every run and are checked by the runtime against the same schema. None when unsaid",
+                    title: 'Settings',
+                },
                 components: {
                     description: "The components of the catalog the surface may use; the kind's own when empty",
                     items: {
@@ -362,6 +423,95 @@ export const APPSPEC_SCHEMA = {
             title: 'AppKind',
             type: 'string',
         },
+        AppMode: {
+            additionalProperties: false,
+            description: 'A mode switch in the composer (LOOP P-19): the person picks one of its options.',
+            properties: {
+                id: {
+                    description: 'Its id, the key a run says its option under',
+                    pattern: '^[a-z][a-z0-9_-]{0,39}$',
+                    title: 'Id',
+                    type: 'string',
+                },
+                label: {
+                    description: 'What the switch is called',
+                    minLength: 1,
+                    title: 'Label',
+                    type: 'string',
+                },
+                options: {
+                    description: 'Its positions, two at least',
+                    items: {
+                        $ref: '#/$defs/AppModeOption',
+                    },
+                    minItems: 2,
+                    title: 'Options',
+                    type: 'array',
+                },
+                default: {
+                    anyOf: [
+                        {
+                            type: 'string',
+                        },
+                        {
+                            type: 'null',
+                        },
+                    ],
+                    default: null,
+                    description: 'The option it starts on; the first when unsaid',
+                    title: 'Default',
+                },
+            },
+            required: ['id', 'label', 'options'],
+            title: 'AppMode',
+            type: 'object',
+        },
+        AppModeOption: {
+            additionalProperties: false,
+            description: 'One position of a mode switch (LOOP P-19): what the agent is told, the model it runs on.',
+            properties: {
+                id: {
+                    description: 'Its id, what a run says it is in',
+                    pattern: '^[a-z][a-z0-9_-]{0,39}$',
+                    title: 'Id',
+                    type: 'string',
+                },
+                label: {
+                    description: 'What the switch says',
+                    minLength: 1,
+                    title: 'Label',
+                    type: 'string',
+                },
+                description: {
+                    default: '',
+                    description: 'What it changes, in a sentence',
+                    title: 'Description',
+                    type: 'string',
+                },
+                instructions: {
+                    default: '',
+                    description: 'What the agent is told besides its instructions, in every run in this mode',
+                    title: 'Instructions',
+                    type: 'string',
+                },
+                model: {
+                    anyOf: [
+                        {
+                            type: 'string',
+                        },
+                        {
+                            type: 'null',
+                        },
+                    ],
+                    default: null,
+                    description: "The model a run in this mode runs on, in place of the application's",
+                    title: 'Model',
+                },
+            },
+            required: ['id', 'label'],
+            title: 'AppModeOption',
+            type: 'object',
+        },
         AppPermissions: {
             additionalProperties: false,
             description: 'What the application may reach beside its connections. Nothing, unless said.',
@@ -465,82 +615,6 @@ export const APPSPEC_SCHEMA = {
             title: 'AppScenario',
             type: 'object',
         },
-        AppSetting: {
-            additionalProperties: false,
-            description: 'Something the user may set for their session.',
-            properties: {
-                id: {
-                    description: 'The name the application reads it by',
-                    title: 'Id',
-                    type: 'string',
-                },
-                type: {
-                    $ref: '#/$defs/SettingType',
-                    description: '`select`, `text`, `toggle`, `slider` or `number`',
-                },
-                label: {
-                    description: 'What the user reads',
-                    title: 'Label',
-                    type: 'string',
-                },
-                options: {
-                    description: 'For a select: its options',
-                    items: {
-                        type: 'string',
-                    },
-                    title: 'Options',
-                    type: 'array',
-                },
-                default: {
-                    anyOf: [
-                        {
-                            type: 'string',
-                        },
-                        {
-                            type: 'boolean',
-                        },
-                        {
-                            type: 'number',
-                        },
-                        {
-                            type: 'null',
-                        },
-                    ],
-                    default: null,
-                    description: 'Its value at the start',
-                    title: 'Default',
-                },
-                min: {
-                    anyOf: [
-                        {
-                            type: 'number',
-                        },
-                        {
-                            type: 'null',
-                        },
-                    ],
-                    default: null,
-                    description: 'For a slider or a number: the least',
-                    title: 'Min',
-                },
-                max: {
-                    anyOf: [
-                        {
-                            type: 'number',
-                        },
-                        {
-                            type: 'null',
-                        },
-                    ],
-                    default: null,
-                    description: 'For a slider or a number: the most',
-                    title: 'Max',
-                },
-            },
-            required: ['id', 'type', 'label'],
-            title: 'AppSetting',
-            type: 'object',
-        },
         AppSpaceGrant: {
             additionalProperties: false,
             description: 'A Space the application may reach.',
@@ -667,6 +741,31 @@ export const APPSPEC_SCHEMA = {
             title: 'AppTests',
             type: 'object',
         },
+        AppTheme: {
+            additionalProperties: false,
+            description: 'The theme an application runs in by default (LOOP T-30).',
+            properties: {
+                variant: {
+                    $ref: '#/$defs/ThemeVariant',
+                    description: 'The theme: `datalayer`, `spatial`, `lovely`, `matrix`, `earth`, `sand`, `ivory`, `sun` or `loop`',
+                },
+                mode: {
+                    anyOf: [
+                        {
+                            $ref: '#/$defs/ThemeMode',
+                        },
+                        {
+                            type: 'null',
+                        },
+                    ],
+                    default: null,
+                    description: "`light`, `dark` or `auto` (the device's); the person's own when unsaid",
+                },
+            },
+            required: ['variant'],
+            title: 'AppTheme',
+            type: 'object',
+        },
         AppTrigger: {
             additionalProperties: false,
             description: "What starts a worker's work.",
@@ -937,10 +1036,26 @@ export const APPSPEC_SCHEMA = {
             title: 'RecordItem',
             type: 'string',
         },
-        SettingType: {
-            description: 'What a setting is set with.',
-            enum: ['select', 'text', 'toggle', 'slider', 'number'],
-            title: 'SettingType',
+        ThemeMode: {
+            description: 'The colour mode a theme is worn in: `auto` follows the device.',
+            enum: ['light', 'dark', 'auto'],
+            title: 'ThemeMode',
+            type: 'string',
+        },
+        ThemeVariant: {
+            description: "A theme of Datalayer's, as Appearance names it (LOOP T-30).",
+            enum: [
+                'datalayer',
+                'spatial',
+                'lovely',
+                'matrix',
+                'earth',
+                'sand',
+                'ivory',
+                'sun',
+                'loop',
+            ],
+            title: 'ThemeVariant',
             type: 'string',
         },
         TriggerType: {
@@ -1157,6 +1272,12 @@ export const APPSPEC_SCHEMA = {
             title: 'Enabled',
             type: 'boolean',
         },
+        unavailable_because: {
+            default: '',
+            description: 'Why it is not offered today, in a sentence its page shows: said when `enabled` is false, and only then',
+            title: 'Unavailable Because',
+            type: 'string',
+        },
         tags: {
             items: {
                 type: 'string',

package/lib/specs/cogs.js

@@ -242,8 +242,9 @@ const COG_CUSTOMER_INTERVIEWER_AGENTSPEC_0_0_1 = {
     description: `Conducts adaptive customer interviews under the Customer Research Frame: consent first, no leading question, and insights that each cite the interviewee's own words.`,
     tags: ['research', 'customer-support', 'analysis', 'cog'],
     domain: 'market-analyst',
-    enabled: false,
+    enabled: true,
     model: 'bedrock:us.anthropic.claude-sonnet-4-6',
+    modelAdditionals: ['alibaba:qwen-max'],
     mcpServers: [],
     skills: [
         SKILL_MAP['text-summarizer:0.0.1']
@@ -625,7 +626,7 @@ export const COG_CUSTOMER_INTERVIEWER_0_0_1 = {
     frames: ['customer-research'],
     lineage: ['datalayer', 'customer-research'],
     kind: 'context',
-    enabled: false,
+    enabled: true,
     guards: [
         {
             id: 'no-secrets',

package/lib/types/agentspecs.d.ts

@@ -386,6 +386,19 @@ export type AppBehaviour = 'do_it' | 'if_asked' | 'ask_first' | 'leave_to_me';
 export type AppLayout = 'chat' | 'page' | 'split';
 /** The one colour of an application; everything else is neutral. */
 export type AppAccent = 'green' | 'rose' | 'sky' | 'lime' | 'sun' | 'violet';
+/** A theme of Appearance's, which an application may run in (LOOP T-30). */
+export type AppThemeVariant = 'datalayer' | 'spatial' | 'lovely' | 'matrix' | 'earth' | 'sand' | 'ivory' | 'sun' | 'loop';
+/** The colour mode it is worn in: `auto` follows the device. */
+export type AppThemeMode = 'light' | 'dark' | 'auto';
+/**
+ * The theme an application runs in by default (LOOP T-30): at its address,
+ * embedded, in the Studio's Preview and as an example. The person's own
+ * when unsaid; the mode, when unsaid, is the person's.
+ */
+export interface AppThemeSpec {
+    variant: AppThemeVariant;
+    mode?: AppThemeMode;
+}
 /**
  * The character an application's floating assistant shows (LOOP T-24): the id
  * an enabled plugin contributes it under to `loop.assistant.character` —
@@ -434,15 +447,71 @@ export interface AppStarterSpec {
     label: string;
     message: string;
 }
-export interface AppSettingSpec {
+/** A slash command the user picks in the composer (LOOP P-19). */
+export interface AppCommandSpec {
+    /** What follows the slash: lower-case letters, digits and hyphens. */
+    name: string;
+    /** What the composer's menu says it does. */
+    description: string;
+    /** What picking it sends: `{input}` the words typed after it. */
+    prompt: string;
+}
+/** One position of a mode switch (LOOP P-19). */
+export interface AppModeOptionSpec {
     id: string;
-    type: 'select' | 'text' | 'toggle' | 'slider' | 'number';
     label: string;
-    options: string[];
-    default?: string | boolean | number;
-    min?: number;
-    max?: number;
+    description?: string;
+    /** What the agent is told in every run in this mode. */
+    instructions?: string;
+    /** The model a run in this mode runs on, in place of the application's. */
+    model?: string | null;
 }
+/** A mode switch in the composer (LOOP P-19). */
+export interface AppModeSpec {
+    id: string;
+    label: string;
+    /** Its positions, two at least. */
+    options: AppModeOptionSpec[];
+    /** The option it starts on; the first when unsaid. */
+    default?: string | null;
+}
+/**
+ * What a run in the modes chosen is told, and the model it runs on (LOOP
+ * P-19): agentspecs' `ModeEffect`.
+ */
+export interface AppModeEffect {
+    /** The instructions of the options chosen, in the order of the modes. */
+    instructions: string;
+    /** The model an option chosen names; the application's when unsaid. */
+    model?: string;
+}
+/**
+ * One field of a form (LOOP C-16): its JSON Schema — a `type`, the `title` a
+ * person reads, its `default`, and what it takes (`enum`, `minimum`,
+ * `maximum`…).
+ */
+export type AppFormField = {
+    type?: string;
+    title?: string;
+    description?: string;
+    default?: unknown;
+    enum?: unknown[];
+    minimum?: number;
+    maximum?: number;
+    [keyword: string]: unknown;
+};
+/**
+ * The JSON Schema of a form (LOOP C-16): an object of named fields, drawn with
+ * `@datalayer/primer-rjsf` and checked by the runtime against the same schema.
+ * An application's settings are one (`interface.settings`), as a Form block's
+ * schema is.
+ */
+export type AppFormSchema = {
+    type: 'object';
+    properties: Record<string, AppFormField>;
+    required?: string[];
+    [keyword: string]: unknown;
+};
 /** The component tree a user meets, over the approved catalog (A2UI). */
 export interface AppSurfaceSpec {
     protocol: string;
@@ -471,10 +540,21 @@ export interface AppVoiceSpec {
 /** What the user of an application sees. */
 export interface AppInterfaceSpec {
     layout: AppLayout;
+    /** Its one colour, over the `loop` theme only. */
     accent: AppAccent;
+    /** The theme it runs in by default; the person's own when unsaid (T-30). */
+    theme?: AppThemeSpec;
     welcome: string;
     starters: AppStarterSpec[];
-    settings: AppSettingSpec[];
+    /** Slash commands picked in the composer: typing `/` lists them (P-19). */
+    commands: AppCommandSpec[];
+    /** Mode switches in the composer, the option picked going with every run (P-19). */
+    modes: AppModeSpec[];
+    /**
+     * What a person may set: the JSON Schema of a form (C-16), drawn beside the
+     * conversation and on a deployment's Ship card; none when unsaid.
+     */
+    settings?: AppFormSchema;
     /** The components of the catalog the surface may use. */
     components: string[];
     surface?: AppSurfaceSpec;
@@ -652,6 +732,11 @@ export interface AppSpec {
     /** What it names that is not enabled today, in sentences. */
     setup: string[];
     enabled: boolean;
+    /**
+     * Why it is not offered today, in a sentence its page shows: said when
+     * `enabled` is false, and only then (empty otherwise).
+     */
+    unavailable_because: string;
     tags: string[];
     icon?: string;
     /** Its face: one emoji, shown wherever the application appears. */

package/lib/types/chat.d.ts

@@ -15,6 +15,7 @@ import type { AgentRuntimeConfig } from './config';
 import type { ContextSnapshotData } from './context';
 import type { InputPromptVariant } from '../chat/prompt/InputPromptBase';
 import type { MentionableAgent } from '../chat/prompt/plugins/AgentMentionPlugin';
+import type { PromptCommand } from '../chat/prompt/plugins/CommandPlugin';
 import type { Icon } from '@primer/octicons-react';
 /** One agent a chat may address, as its controls need it. */
 export interface FooterAgent {
@@ -652,6 +653,21 @@ export type ThemeOverrides = {
     light?: Record<string, string>;
     dark?: Record<string, string>;
 };
+/**
+ * A conversation the chat goes on with (LOOP D-13): an embedded
+ * application's session, reattached after its page reloaded.
+ */
+export type ResumedThread = {
+    /** Its id, AG-UI's `threadId`: the session's uid. */
+    id: string;
+    /** What it holds already; none for a new one. */
+    messages: ChatMessage[];
+    /**
+     * Told the thread a message is first sent on — this one, or a new one
+     * after the header's + — so that its host keeps it. A stable function.
+     */
+    onStarted?: (threadId: string) => void;
+};
 export interface ChatBaseProps {
     /**
      * Hands an imperative send function to the host, once the chat is able to
@@ -722,7 +738,7 @@ export interface ChatBaseProps {
     /**
      * External MCP toolsets status data for the MCP indicator.
      * When provided, the data is forwarded to the McpStatusIndicator
-     * so it shows live status instead of "No MCP Server defined".
+     * so it shows their live status; with none, it is not drawn.
      */
     mcpStatusData?: import('./mcp').McpToolsetsStatusResponse | null;
     /**
@@ -755,6 +771,11 @@ export interface ChatBaseProps {
     promptVariant?: InputPromptVariant;
     /** Agents the prompt may address by typing `@`. Lexical only. */
     mentionableAgents?: MentionableAgent[];
+    /**
+     * Commands the prompt lists while `/` is typed, before its own: an
+     * application's (LOOP P-19). Picking one writes `/<name> `. Lexical only.
+     */
+    promptCommands?: PromptCommand[];
     /**
      * Whether the prompt offers a chooser for who answers.
      *
@@ -1190,6 +1211,13 @@ export interface ChatBaseProps {
         userId?: string;
         accessToken?: string;
     }>;
+    /**
+     * The conversation to go on with (LOOP D-13): its AG-UI thread — an
+     * application's session — and what it holds, drawn in place of the
+     * runtime's history, which is its agent's and not one session's. Read
+     * when the chat mounts; a new thread (the header's +) is the chat's own.
+     */
+    thread?: ResumedThread;
     /**
      * Runtime ID for conversation persistence.
      * When provided, messages are restored from websocket snapshot data on

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datalayer/agent-runtimes",
-    "version": "1.3.81",
+    "version": "1.3.83",
     "type": "module",
     "workspaces": [
         ".",

package/scripts/codegen/generate_agents.py

@@ -410,7 +410,8 @@ from agent_runtimes.types import (
                 for skill in spec.get("skills", [])
             ]
             tool_refs = [
-                versioned_ref(*split_spec_ref(tool)) for tool in spec.get("backend_tools", [])
+                versioned_ref(*split_spec_ref(tool))
+                for tool in spec.get("backend_tools", [])
             ]
             frontend_tool_refs = [
                 versioned_ref(*split_spec_ref(ft))
@@ -1032,7 +1033,8 @@ const FRONTEND_TOOL_MAP: Record<string, any> = {
 
             # Get backend tools - resolve to BackendToolSpec via TOOL_MAP
             tool_ids_list = [
-                versioned_ref(*split_spec_ref(sid)) for sid in spec.get("backend_tools", [])
+                versioned_ref(*split_spec_ref(sid))
+                for sid in spec.get("backend_tools", [])
             ]
             if has_tools and tool_ids_list:
                 tools_str = ", ".join(f"TOOL_MAP['{tid}']" for tid in tool_ids_list)

package/scripts/codegen/generate_apps.py

@@ -216,7 +216,6 @@ def generate_python_code(specs: list[dict[str, Any]], built: dict[str, str]) ->
         "",
         "from agent_runtimes.types import AppSpec",
         "",
-        "",
         "# " + "=" * 76,
         "# Application Definitions",
         "# " + "=" * 76,

package/scripts/codegen/generate_backend_tools.py

@@ -110,9 +110,7 @@ def generate_python_code(specs: list[dict[str, Any]]) -> str:
     for spec in specs:
         tool_id = spec["id"]
         version = spec["version"]
-        const_name = (
-            f"{tool_id.upper().replace('-', '_')}_BACKEND_TOOL_SPEC{version_suffix(version)}"
-        )
+        const_name = f"{tool_id.upper().replace('-', '_')}_BACKEND_TOOL_SPEC{version_suffix(version)}"
         runtime = _require_runtime(spec)
         requires_approval = _requires_approval(spec)
         timeout = _timeout_hms(spec)
@@ -157,9 +155,7 @@ def generate_python_code(specs: list[dict[str, Any]]) -> str:
     for spec in specs:
         tool_id = spec["id"]
         version = spec["version"]
-        const_name = (
-            f"{tool_id.upper().replace('-', '_')}_BACKEND_TOOL_SPEC{version_suffix(version)}"
-        )
+        const_name = f"{tool_id.upper().replace('-', '_')}_BACKEND_TOOL_SPEC{version_suffix(version)}"
         lines.append(f'    "{tool_id}": {const_name},')
 
     lines.extend(
@@ -215,9 +211,7 @@ def generate_typescript_code(specs: list[dict[str, Any]]) -> str:
     for spec in specs:
         tool_id = spec["id"]
         version = spec["version"]
-        const_name = (
-            f"{tool_id.upper().replace('-', '_')}_BACKEND_TOOL_SPEC{version_suffix(version)}"
-        )
+        const_name = f"{tool_id.upper().replace('-', '_')}_BACKEND_TOOL_SPEC{version_suffix(version)}"
         runtime = _require_runtime(spec)
         requires_approval = _requires_approval(spec)
         timeout = _timeout_hms(spec)
@@ -264,9 +258,7 @@ def generate_typescript_code(specs: list[dict[str, Any]]) -> str:
     for spec in specs:
         tool_id = spec["id"]
         version = spec["version"]
-        const_name = (
-            f"{tool_id.upper().replace('-', '_')}_BACKEND_TOOL_SPEC{version_suffix(version)}"
-        )
+        const_name = f"{tool_id.upper().replace('-', '_')}_BACKEND_TOOL_SPEC{version_suffix(version)}"
         lines.append(f"  '{tool_id}': {const_name},")
 
     lines.extend(

package/scripts/codegen/generate_cogs.py

@@ -208,7 +208,9 @@ def generate_typescript_code(specs: list[dict[str, Any]], specs_dir: Path) -> st
     # is one directory up, beside the catalogues it imports.
     head = head.replace("from '../../types'", "from '../types'")
     head = re.sub(
-        r"from '\.\./(mcpServers|skills|backendTools|frontendTools)'", r"from './\1'", head
+        r"from '\.\./(mcpServers|skills|backendTools|frontendTools)'",
+        r"from './\1'",
+        head,
     )
 
     lines = [