@datalayer/agent-runtimes 1.0.2 → 1.0.4

package/lib/specs/agents/index.js

@@ -2,22 +2,27 @@
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-import { AGENT_SPECS as CODEAI_AGENTS } from './codeai';
-import { AGENT_SPECS as CODEMODE_PAPER_AGENTS } from './codemode-paper';
-import { AGENT_SPECS as DATALAYER_AI_AGENTS } from './datalayer-ai';
-import { AGENT_SPECS as MOCKS_AGENTS } from './mocks';
+import { AGENT_SPECS as ROOT_AGENTS } from './agents';
 // Merge all agent specs from subfolders
 export const AGENT_SPECS = {
-    ...CODEAI_AGENTS,
-    ...CODEMODE_PAPER_AGENTS,
-    ...DATALAYER_AI_AGENTS,
-    ...MOCKS_AGENTS,
+    ...ROOT_AGENTS,
 };
+function resolveAgentId(agentId) {
+    if (agentId in AGENT_SPECS)
+        return agentId;
+    const idx = agentId.lastIndexOf(':');
+    if (idx > 0) {
+        const base = agentId.slice(0, idx);
+        if (base in AGENT_SPECS)
+            return base;
+    }
+    return agentId;
+}
 /**
  * Get an agent specification by ID.
  */
 export function getAgentSpecs(agentId) {
-    return AGENT_SPECS[agentId];
+    return AGENT_SPECS[resolveAgentId(agentId)];
 }
 /**
  * List all available agent specifications.
@@ -26,9 +31,7 @@ export function getAgentSpecs(agentId) {
  */
 export function listAgentSpecs(prefix) {
     const specs = Object.values(AGENT_SPECS);
-    return prefix !== undefined
-        ? specs.filter(s => s.id.startsWith(prefix))
-        : specs;
+    return prefix !== undefined ? specs.filter(s => s.id.startsWith(prefix)) : specs;
 }
 /**
  * Collect all required environment variables for an agent spec.

package/lib/specs/envvars.d.ts

@@ -6,24 +6,16 @@
  * This file is AUTO-GENERATED from YAML specifications.
  * DO NOT EDIT MANUALLY - run 'make specs' to regenerate.
  */
-export interface EnvvarSpec {
-    id: string;
-    name: string;
-    description: string;
-    registrationUrl?: string;
-    tags: string[];
-    icon?: string;
-    emoji?: string;
-}
-export declare const ALPHAVANTAGE_API_KEY_SPEC: EnvvarSpec;
-export declare const GITHUB_TOKEN_SPEC: EnvvarSpec;
-export declare const GOOGLE_OAUTH_CLIENT_ID_SPEC: EnvvarSpec;
-export declare const GOOGLE_OAUTH_CLIENT_SECRET_SPEC: EnvvarSpec;
-export declare const HF_TOKEN_SPEC: EnvvarSpec;
-export declare const KAGGLE_TOKEN_SPEC: EnvvarSpec;
-export declare const SLACK_BOT_TOKEN_SPEC: EnvvarSpec;
-export declare const SLACK_CHANNEL_IDS_SPEC: EnvvarSpec;
-export declare const SLACK_TEAM_ID_SPEC: EnvvarSpec;
-export declare const TAVILY_API_KEY_SPEC: EnvvarSpec;
+import type { EnvvarSpec } from '../types';
+export declare const ALPHAVANTAGE_API_KEY_SPEC_0_0_1: EnvvarSpec;
+export declare const GITHUB_TOKEN_SPEC_0_0_1: EnvvarSpec;
+export declare const GOOGLE_OAUTH_CLIENT_ID_SPEC_0_0_1: EnvvarSpec;
+export declare const GOOGLE_OAUTH_CLIENT_SECRET_SPEC_0_0_1: EnvvarSpec;
+export declare const HF_TOKEN_SPEC_0_0_1: EnvvarSpec;
+export declare const KAGGLE_TOKEN_SPEC_0_0_1: EnvvarSpec;
+export declare const SLACK_BOT_TOKEN_SPEC_0_0_1: EnvvarSpec;
+export declare const SLACK_CHANNEL_IDS_SPEC_0_0_1: EnvvarSpec;
+export declare const SLACK_TEAM_ID_SPEC_0_0_1: EnvvarSpec;
+export declare const TAVILY_API_KEY_SPEC_0_0_1: EnvvarSpec;
 export declare const ENVVAR_CATALOG: Record<string, EnvvarSpec>;
 export declare function getEnvvarSpec(envvarId: string): EnvvarSpec;

package/lib/specs/envvars.js

@@ -5,99 +5,102 @@
 // ============================================================================
 // Environment Variable Definitions
 // ============================================================================
-export const ALPHAVANTAGE_API_KEY_SPEC = {
+export const ALPHAVANTAGE_API_KEY_SPEC_0_0_1 = {
     id: 'ALPHAVANTAGE_API_KEY',
+    version: '0.0.1',
     name: 'Alpha Vantage API Key',
     description: 'API key for accessing Alpha Vantage financial market data and stock information. Provides real-time and historical stock prices, forex data, and cryptocurrency information.',
     registrationUrl: 'https://www.alphavantage.co/support/#api-key',
-    tags: ['authentication', 'api-key', 'finance', 'stocks', 'market-data'],
+    tags: ["authentication", "api-key", "finance", "stocks", "market-data"],
     icon: 'key',
     emoji: '🔑',
 };
-export const GITHUB_TOKEN_SPEC = {
+export const GITHUB_TOKEN_SPEC_0_0_1 = {
     id: 'GITHUB_TOKEN',
+    version: '0.0.1',
     name: 'GitHub Token',
     description: 'GitHub API token for repository management and code operations. Required for GitHub MCP server and GitHub skill to interact with GitHub repositories programmatically.',
     registrationUrl: 'https://github.com/settings/tokens',
-    tags: ['authentication', 'token', 'github', 'git', 'mcp-server', 'skill'],
+    tags: ["authentication", "token", "github", "git", "mcp-server", "skill"],
     icon: 'key',
     emoji: '🔑',
 };
-export const GOOGLE_OAUTH_CLIENT_ID_SPEC = {
+export const GOOGLE_OAUTH_CLIENT_ID_SPEC_0_0_1 = {
     id: 'GOOGLE_OAUTH_CLIENT_ID',
+    version: '0.0.1',
     name: 'Google OAuth Client ID',
     description: 'OAuth 2.0 client ID for Google Workspace authentication. Required for Google Drive, Gmail, Calendar, and Docs integration through the Google Workspace MCP server.',
     registrationUrl: 'https://console.cloud.google.com/apis/credentials',
-    tags: ['authentication', 'oauth', 'google', 'workspace', 'client-id'],
+    tags: ["authentication", "oauth", "google", "workspace", "client-id"],
     icon: 'key',
     emoji: '🔑',
 };
-export const GOOGLE_OAUTH_CLIENT_SECRET_SPEC = {
+export const GOOGLE_OAUTH_CLIENT_SECRET_SPEC_0_0_1 = {
     id: 'GOOGLE_OAUTH_CLIENT_SECRET',
+    version: '0.0.1',
     name: 'Google OAuth Client Secret',
     description: 'OAuth 2.0 client secret for Google Workspace authentication. Used in conjunction with client ID for secure API access to Google services.',
     registrationUrl: 'https://console.cloud.google.com/apis/credentials',
-    tags: [
-        'authentication',
-        'oauth',
-        'google',
-        'workspace',
-        'client-secret',
-        'security',
-    ],
+    tags: ["authentication", "oauth", "google", "workspace", "client-secret", "security"],
     icon: 'lock',
     emoji: '🔒',
 };
-export const HF_TOKEN_SPEC = {
+export const HF_TOKEN_SPEC_0_0_1 = {
     id: 'HF_TOKEN',
+    version: '0.0.1',
     name: 'Hugging Face Token',
     description: 'Access token for Hugging Face API. Required for Hugging Face MCP server authentication. Create a READ token from your settings.',
     registrationUrl: 'https://huggingface.co/settings/tokens',
-    tags: ['authentication', 'api-key', 'huggingface', 'machine-learning'],
+    tags: ["authentication", "api-key", "huggingface", "machine-learning"],
     icon: 'key',
     emoji: '🔑',
 };
-export const KAGGLE_TOKEN_SPEC = {
+export const KAGGLE_TOKEN_SPEC_0_0_1 = {
     id: 'KAGGLE_TOKEN',
+    version: '0.0.1',
     name: 'Kaggle API Token',
     description: 'API token for accessing Kaggle datasets, competitions, notebooks, and models. Required for Kaggle MCP server authentication.',
     registrationUrl: 'https://www.kaggle.com/settings/account',
-    tags: ['authentication', 'api-key', 'kaggle', 'data'],
+    tags: ["authentication", "api-key", "kaggle", "data"],
     icon: 'key',
     emoji: '🔑',
 };
-export const SLACK_BOT_TOKEN_SPEC = {
+export const SLACK_BOT_TOKEN_SPEC_0_0_1 = {
     id: 'SLACK_BOT_TOKEN',
+    version: '0.0.1',
     name: 'Slack Bot Token',
     description: 'OAuth token for Slack bot authentication. Required for Slack MCP server to send messages, manage channels, and interact with workspace members.',
     registrationUrl: 'https://api.slack.com/apps',
-    tags: ['authentication', 'oauth', 'token', 'slack', 'messaging', 'bot'],
+    tags: ["authentication", "oauth", "token", "slack", "messaging", "bot"],
     icon: 'key',
     emoji: '🔑',
 };
-export const SLACK_CHANNEL_IDS_SPEC = {
+export const SLACK_CHANNEL_IDS_SPEC_0_0_1 = {
     id: 'SLACK_CHANNEL_IDS',
+    version: '0.0.1',
     name: 'Slack Channel IDs',
     description: 'Comma-separated list of Slack channel IDs that the bot is allowed to access. Restricts bot operations to specific channels for security and organization.',
-    tags: ['configuration', 'slack', 'channels', 'identifier'],
+    tags: ["configuration", "slack", "channels", "identifier"],
     icon: 'hash',
     emoji: undefined,
 };
-export const SLACK_TEAM_ID_SPEC = {
+export const SLACK_TEAM_ID_SPEC_0_0_1 = {
     id: 'SLACK_TEAM_ID',
+    version: '0.0.1',
     name: 'Slack Team ID',
     description: 'Unique identifier for the Slack workspace (team). Required to specify which workspace the bot should connect to.',
     registrationUrl: 'https://api.slack.com/apps',
-    tags: ['configuration', 'slack', 'workspace', 'identifier'],
+    tags: ["configuration", "slack", "workspace", "identifier"],
     icon: 'organization',
     emoji: '🏢',
 };
-export const TAVILY_API_KEY_SPEC = {
+export const TAVILY_API_KEY_SPEC_0_0_1 = {
     id: 'TAVILY_API_KEY',
+    version: '0.0.1',
     name: 'Tavily API Key',
     description: 'API key for Tavily web search and research capabilities. Required for web crawling, content extraction, and search operations.',
     registrationUrl: 'https://tavily.com/api-keys',
-    tags: ['authentication', 'api-key', 'search', 'web', 'research'],
+    tags: ["authentication", "api-key", "search", "web", "research"],
     icon: 'key',
     emoji: '🔑',
 };
@@ -105,19 +108,30 @@ export const TAVILY_API_KEY_SPEC = {
 // Environment Variable Catalog
 // ============================================================================
 export const ENVVAR_CATALOG = {
-    ALPHAVANTAGE_API_KEY: ALPHAVANTAGE_API_KEY_SPEC,
-    GITHUB_TOKEN: GITHUB_TOKEN_SPEC,
-    GOOGLE_OAUTH_CLIENT_ID: GOOGLE_OAUTH_CLIENT_ID_SPEC,
-    GOOGLE_OAUTH_CLIENT_SECRET: GOOGLE_OAUTH_CLIENT_SECRET_SPEC,
-    HF_TOKEN: HF_TOKEN_SPEC,
-    KAGGLE_TOKEN: KAGGLE_TOKEN_SPEC,
-    SLACK_BOT_TOKEN: SLACK_BOT_TOKEN_SPEC,
-    SLACK_CHANNEL_IDS: SLACK_CHANNEL_IDS_SPEC,
-    SLACK_TEAM_ID: SLACK_TEAM_ID_SPEC,
-    TAVILY_API_KEY: TAVILY_API_KEY_SPEC,
+    'ALPHAVANTAGE_API_KEY': ALPHAVANTAGE_API_KEY_SPEC_0_0_1,
+    'GITHUB_TOKEN': GITHUB_TOKEN_SPEC_0_0_1,
+    'GOOGLE_OAUTH_CLIENT_ID': GOOGLE_OAUTH_CLIENT_ID_SPEC_0_0_1,
+    'GOOGLE_OAUTH_CLIENT_SECRET': GOOGLE_OAUTH_CLIENT_SECRET_SPEC_0_0_1,
+    'HF_TOKEN': HF_TOKEN_SPEC_0_0_1,
+    'KAGGLE_TOKEN': KAGGLE_TOKEN_SPEC_0_0_1,
+    'SLACK_BOT_TOKEN': SLACK_BOT_TOKEN_SPEC_0_0_1,
+    'SLACK_CHANNEL_IDS': SLACK_CHANNEL_IDS_SPEC_0_0_1,
+    'SLACK_TEAM_ID': SLACK_TEAM_ID_SPEC_0_0_1,
+    'TAVILY_API_KEY': TAVILY_API_KEY_SPEC_0_0_1,
 };
+function resolveEnvvarId(envvarId) {
+    if (envvarId in ENVVAR_CATALOG)
+        return envvarId;
+    const idx = envvarId.lastIndexOf(':');
+    if (idx > 0) {
+        const base = envvarId.slice(0, idx);
+        if (base in ENVVAR_CATALOG)
+            return base;
+    }
+    return envvarId;
+}
 export function getEnvvarSpec(envvarId) {
-    const spec = ENVVAR_CATALOG[envvarId];
+    const spec = ENVVAR_CATALOG[resolveEnvvarId(envvarId)];
     if (!spec) {
         throw new Error(`Unknown environment variable: ${envvarId}`);
     }

package/lib/specs/evals.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Eval Catalog
+ *
+ * Predefined evaluation benchmark configurations.
+ *
+ * This file is AUTO-GENERATED from YAML specifications.
+ * DO NOT EDIT MANUALLY - run 'make specs' to regenerate.
+ */
+import type { EvalSpec } from '../types';
+export declare const AGENTBENCH_EVAL_SPEC_0_0_1: EvalSpec;
+export declare const GPQA_DIAMOND_EVAL_SPEC_0_0_1: EvalSpec;
+export declare const HUMANEVAL_EVAL_SPEC_0_0_1: EvalSpec;
+export declare const MMLU_EVAL_SPEC_0_0_1: EvalSpec;
+export declare const SWE_BENCH_VERIFIED_EVAL_SPEC_0_0_1: EvalSpec;
+export declare const SWE_BENCH_EVAL_SPEC_0_0_1: EvalSpec;
+export declare const TOOLBENCH_EVAL_SPEC_0_0_1: EvalSpec;
+export declare const TRUTHFULQA_EVAL_SPEC_0_0_1: EvalSpec;
+export declare const EVAL_CATALOG: Record<string, EvalSpec>;
+export declare function getEvalSpecs(): EvalSpec[];
+export declare function getEvalSpec(evalId: string): EvalSpec | undefined;

package/lib/specs/evals.js

@@ -0,0 +1,133 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+// ============================================================================
+// Eval Definitions
+// ============================================================================
+export const AGENTBENCH_EVAL_SPEC_0_0_1 = {
+    id: 'agentbench',
+    version: '0.0.1',
+    name: 'AgentBench',
+    description: 'Multi-dimensional LLM-as-agent evaluation across 8 diverse environments including web browsing, operating system interaction, database queries, digital card games, lateral thinking, and household tasks.',
+    category: 'Agentic',
+    task_count: 4080,
+    metric: 'success_rate',
+    source: 'https://github.com/THUDM/AgentBench',
+    difficulty: 'hard',
+    languages: ['python', 'sql', 'bash'],
+};
+export const GPQA_DIAMOND_EVAL_SPEC_0_0_1 = {
+    id: 'gpqa-diamond',
+    version: '0.0.1',
+    name: 'GPQA Diamond',
+    description: 'Graduate-level science questions crafted by domain experts. Tests advanced reasoning in physics, chemistry, and biology with questions that require PhD-level understanding to answer correctly.',
+    category: 'Reasoning',
+    task_count: 448,
+    metric: 'accuracy',
+    source: 'https://github.com/idavidrein/gpqa',
+    difficulty: 'expert',
+    languages: ['english'],
+};
+export const HUMANEVAL_EVAL_SPEC_0_0_1 = {
+    id: 'humaneval',
+    version: '0.0.1',
+    name: 'HumanEval',
+    description: 'Python function implementation from docstrings. Measures functional correctness of code generation by testing against hand-written test cases. Widely used as a baseline for code generation benchmarks.',
+    category: 'Coding',
+    task_count: 164,
+    metric: 'pass@k',
+    source: 'https://github.com/openai/human-eval',
+    difficulty: 'medium',
+    languages: ['python'],
+};
+export const MMLU_EVAL_SPEC_0_0_1 = {
+    id: 'mmlu',
+    version: '0.0.1',
+    name: 'MMLU',
+    description: 'Massive Multitask Language Understanding: 57-subject knowledge benchmark spanning STEM, humanities, social sciences, and more. Tests broad knowledge and reasoning across diverse academic domains.',
+    category: 'Knowledge',
+    task_count: 15908,
+    metric: 'accuracy',
+    source: 'https://github.com/hendrycks/test',
+    difficulty: 'medium',
+    languages: ['english'],
+};
+export const SWE_BENCH_VERIFIED_EVAL_SPEC_0_0_1 = {
+    id: 'swe-bench-verified',
+    version: '0.0.1',
+    name: 'SWE-bench Verified',
+    description: 'Human-validated subset of SWE-bench with verified ground-truth patches. Provides higher confidence evaluation of software engineering capabilities by eliminating ambiguous or flawed test cases from the full benchmark.',
+    category: 'Coding',
+    task_count: 500,
+    metric: 'pass@1',
+    source: 'https://www.swebench.com/',
+    difficulty: 'hard',
+    languages: ['python'],
+};
+export const SWE_BENCH_EVAL_SPEC_0_0_1 = {
+    id: 'swe-bench',
+    version: '0.0.1',
+    name: 'SWE-bench',
+    description: 'Real-world software engineering tasks from GitHub issues. Tests an agent\'s ability to understand bug reports and feature requests, then produce working code patches that pass existing test suites.',
+    category: 'Coding',
+    task_count: 2294,
+    metric: 'pass@1',
+    source: 'https://www.swebench.com/',
+    difficulty: 'hard',
+    languages: ['python'],
+};
+export const TOOLBENCH_EVAL_SPEC_0_0_1 = {
+    id: 'toolbench',
+    version: '0.0.1',
+    name: 'ToolBench',
+    description: 'Large-scale benchmark for tool-augmented LLMs covering 16000+ real-world APIs across 49 categories. Evaluates multi-step tool usage, API selection, argument generation, and response parsing in complex, chained workflows.',
+    category: 'Agentic',
+    task_count: 12657,
+    metric: 'pass_rate',
+    source: 'https://github.com/OpenBMB/ToolBench',
+    difficulty: 'hard',
+    languages: ['python', 'json'],
+};
+export const TRUTHFULQA_EVAL_SPEC_0_0_1 = {
+    id: 'truthfulqa',
+    version: '0.0.1',
+    name: 'TruthfulQA',
+    description: 'Benchmark measuring whether a language model generates truthful answers to questions spanning 38 categories including health, law, finance, and politics. Designed to test resilience against common human misconceptions and falsehoods that models may have learned from training data.',
+    category: 'Safety',
+    task_count: 817,
+    metric: 'truthful_informative',
+    source: 'https://github.com/sylinrl/TruthfulQA',
+    difficulty: 'medium',
+    languages: ['english'],
+};
+// ============================================================================
+// Eval Catalog
+// ============================================================================
+export const EVAL_CATALOG = {
+    'agentbench': AGENTBENCH_EVAL_SPEC_0_0_1,
+    'gpqa-diamond': GPQA_DIAMOND_EVAL_SPEC_0_0_1,
+    'humaneval': HUMANEVAL_EVAL_SPEC_0_0_1,
+    'mmlu': MMLU_EVAL_SPEC_0_0_1,
+    'swe-bench-verified': SWE_BENCH_VERIFIED_EVAL_SPEC_0_0_1,
+    'swe-bench': SWE_BENCH_EVAL_SPEC_0_0_1,
+    'toolbench': TOOLBENCH_EVAL_SPEC_0_0_1,
+    'truthfulqa': TRUTHFULQA_EVAL_SPEC_0_0_1,
+};
+export function getEvalSpecs() {
+    return Object.values(EVAL_CATALOG);
+}
+function resolveEvalId(evalId) {
+    if (evalId in EVAL_CATALOG)
+        return evalId;
+    const idx = evalId.lastIndexOf(':');
+    if (idx > 0) {
+        const base = evalId.slice(0, idx);
+        if (base in EVAL_CATALOG)
+            return base;
+    }
+    return evalId;
+}
+export function getEvalSpec(evalId) {
+    return EVAL_CATALOG[resolveEvalId(evalId)];
+}

package/lib/specs/events.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Event Catalog
+ *
+ * Predefined event type specifications for agent lifecycle and guardrail events.
+ *
+ * This file is AUTO-GENERATED from YAML specifications.
+ * DO NOT EDIT MANUALLY - run 'make specs' to regenerate.
+ */
+import type { EventSpec } from '../types';
+export declare const AGENT_ASSIGNED_EVENT_SPEC_0_0_1: EventSpec;
+export declare const AGENT_OUTPUT_EVENT_SPEC_0_0_1: EventSpec;
+export declare const AGENT_START_REQUESTED_EVENT_SPEC_0_0_1: EventSpec;
+export declare const AGENT_STARTED_EVENT_SPEC_0_0_1: EventSpec;
+export declare const AGENT_TERMINATED_EVENT_SPEC_0_0_1: EventSpec;
+export declare const AGENT_TERMINATION_REQUESTED_EVENT_SPEC_0_0_1: EventSpec;
+export declare const TOOL_APPROVAL_REQUESTED_EVENT_SPEC_0_0_1: EventSpec;
+export declare const EVENT_KIND_AGENT_ASSIGNED = "agent-assigned";
+export declare const EVENT_KIND_AGENT_OUTPUT = "agent-output";
+export declare const EVENT_KIND_AGENT_START_REQUESTED = "agent-start-requested";
+export declare const EVENT_KIND_AGENT_STARTED = "agent-started";
+export declare const EVENT_KIND_AGENT_TERMINATED = "agent-terminated";
+export declare const EVENT_KIND_AGENT_TERMINATION_REQUESTED = "agent-termination-requested";
+export declare const EVENT_KIND_TOOL_APPROVAL_REQUESTED = "tool-approval-requested";
+export declare const EVENT_CATALOG: Record<string, EventSpec>;
+export declare function getEventSpecs(): EventSpec[];
+export declare function getEventSpec(eventId: string): EventSpec | undefined;

package/lib/specs/events.js

@@ -0,0 +1,140 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+// ============================================================================
+// Event Definitions
+// ============================================================================
+export const AGENT_ASSIGNED_EVENT_SPEC_0_0_1 = {
+    id: 'agent-assigned',
+    version: '0.0.1',
+    name: 'Agent Assigned',
+    description: 'Emitted when an agent runtime is assigned/configured by the companion through the MCP servers start API.',
+    kind: 'agent-assigned',
+    fields: [
+        { name: 'agent_runtime_id', label: 'Agent Runtime ID', type: 'string', required: true, description: 'Runtime pod or instance identifier.' },
+        { name: 'assignment_source', label: 'Assignment Source', type: 'string', required: false, description: 'Source that initiated the assignment (for example companion).' },
+        { name: 'assigned_at', label: 'Assigned At', type: 'string', required: false, description: 'ISO 8601 timestamp when assignment/configuration completed.' },
+        { name: 'origin', label: 'Origin', type: 'string', required: false, description: 'Producer origin (endpoint, companion, runtime, or agent-runtime).' },
+    ],
+};
+export const AGENT_OUTPUT_EVENT_SPEC_0_0_1 = {
+    id: 'agent-output',
+    version: '0.0.1',
+    name: 'Agent Output',
+    description: 'Emitted when an agent produces output. Contains timing information, exit status, optional output summary, and error details if applicable.',
+    kind: 'agent-output',
+    fields: [
+        { name: 'agent_runtime_id', label: 'Agent Runtime ID', type: 'string', required: true, description: 'Runtime pod or instance identifier.' },
+        { name: 'agent_spec_id', label: 'Agent Spec ID', type: 'string', required: true, description: 'Identifier of the agent specification that was executed.' },
+        { name: 'started_at', label: 'Started At', type: 'string', required: true, description: 'ISO 8601 timestamp when the agent started.' },
+        { name: 'ended_at', label: 'Ended At', type: 'string', required: true, description: 'ISO 8601 timestamp when the agent ended.' },
+        { name: 'duration_ms', label: 'Duration (ms)', type: 'number', required: true, description: 'Total execution time in milliseconds.' },
+        { name: 'exit_status', label: 'Exit Status', type: 'string', required: true, description: 'Final status of the agent run (e.g. completed, error).' },
+        { name: 'outputs', label: 'Outputs', type: 'string', required: false, description: 'Summary of the agent output or generated artifacts.' },
+        { name: 'error_message', label: 'Error Message', type: 'string', required: false, description: 'Error description if the agent run failed.' },
+        { name: 'origin', label: 'Origin', type: 'string', required: false, description: 'Producer origin (endpoint, companion, runtime, or agent-runtime).' },
+    ],
+};
+export const AGENT_START_REQUESTED_EVENT_SPEC_0_0_1 = {
+    id: 'agent-start-requested',
+    version: '0.0.1',
+    name: 'Agent Start Requested',
+    description: 'Emitted when the API endpoint receives a request to start an agent runtime.',
+    kind: 'agent-start-requested',
+    fields: [
+        { name: 'agent_runtime_id', label: 'Agent Runtime ID', type: 'string', required: false, description: 'Runtime pod or instance identifier.' },
+        { name: 'started_at', label: 'Requested At', type: 'string', required: false, description: 'ISO 8601 timestamp when the start was requested.' },
+        { name: 'origin', label: 'Origin', type: 'string', required: false, description: 'Producer origin (endpoint, companion, runtime, or agent-runtime).' },
+    ],
+};
+export const AGENT_STARTED_EVENT_SPEC_0_0_1 = {
+    id: 'agent-started',
+    version: '0.0.1',
+    name: 'Agent Started',
+    description: 'Emitted when an agent begins execution. Contains the runtime identifier, agent spec, trigger type, and the prompt being executed.',
+    kind: 'agent-started',
+    fields: [
+        { name: 'agent_runtime_id', label: 'Agent Runtime ID', type: 'string', required: true, description: 'Runtime pod or instance identifier.' },
+        { name: 'agent_spec_id', label: 'Agent Spec ID', type: 'string', required: true, description: 'Identifier of the agent specification being executed.' },
+        { name: 'started_at', label: 'Started At', type: 'string', required: true, description: 'ISO 8601 timestamp when the agent started.' },
+        { name: 'trigger_type', label: 'Trigger Type', type: 'string', required: true, description: 'Type of trigger that launched the agent (e.g. once, cron, webhook).' },
+        { name: 'trigger_prompt', label: 'Trigger Prompt', type: 'string', required: false, description: 'The prompt passed to the agent by the trigger.' },
+        { name: 'origin', label: 'Origin', type: 'string', required: false, description: 'Producer origin (endpoint, companion, runtime, or agent-runtime).' },
+    ],
+};
+export const AGENT_TERMINATED_EVENT_SPEC_0_0_1 = {
+    id: 'agent-terminated',
+    version: '0.0.1',
+    name: 'Agent Terminated',
+    description: 'Emitted when an agent runtime is fully terminated.',
+    kind: 'agent-terminated',
+    fields: [
+        { name: 'agent_runtime_id', label: 'Agent Runtime ID', type: 'string', required: true, description: 'Runtime pod or instance identifier.' },
+        { name: 'ended_at', label: 'Ended At', type: 'string', required: false, description: 'ISO 8601 timestamp when the runtime termination completed.' },
+        { name: 'origin', label: 'Origin', type: 'string', required: false, description: 'Producer origin (endpoint, companion, runtime, or agent-runtime).' },
+    ],
+};
+export const AGENT_TERMINATION_REQUESTED_EVENT_SPEC_0_0_1 = {
+    id: 'agent-termination-requested',
+    version: '0.0.1',
+    name: 'Agent Termination Requested',
+    description: 'Emitted when the API endpoint receives a request to terminate an agent runtime.',
+    kind: 'agent-termination-requested',
+    fields: [
+        { name: 'agent_runtime_id', label: 'Agent Runtime ID', type: 'string', required: true, description: 'Runtime pod or instance identifier.' },
+        { name: 'reason', label: 'Reason', type: 'string', required: false, description: 'Optional reason associated with the termination request.' },
+        { name: 'origin', label: 'Origin', type: 'string', required: false, description: 'Producer origin (endpoint, companion, runtime, or agent-runtime).' },
+    ],
+};
+export const TOOL_APPROVAL_REQUESTED_EVENT_SPEC_0_0_1 = {
+    id: 'tool-approval-requested',
+    version: '0.0.1',
+    name: 'Tool Approval Requested',
+    description: 'Emitted when an agent invokes a tool that requires manual approval before execution. The agent pauses until the request is approved or rejected.',
+    kind: 'tool-approval-requested',
+    fields: [
+        { name: 'agent_runtime_id', label: 'Agent Runtime ID', type: 'string', required: true, description: 'Runtime pod or instance identifier.' },
+        { name: 'agent_spec_id', label: 'Agent Spec ID', type: 'string', required: false, description: 'Identifier of the agent specification requesting approval.' },
+        { name: 'tool_name', label: 'Tool Name', type: 'string', required: true, description: 'Name of the tool requiring approval.' },
+        { name: 'tool_args', label: 'Tool Arguments', type: 'string', required: false, description: 'JSON-serialized arguments passed to the tool.' },
+        { name: 'origin', label: 'Origin', type: 'string', required: false, description: 'Producer origin (endpoint, companion, runtime, or agent-runtime).' },
+    ],
+};
+// Event kind constants for programmatic use
+export const EVENT_KIND_AGENT_ASSIGNED = 'agent-assigned';
+export const EVENT_KIND_AGENT_OUTPUT = 'agent-output';
+export const EVENT_KIND_AGENT_START_REQUESTED = 'agent-start-requested';
+export const EVENT_KIND_AGENT_STARTED = 'agent-started';
+export const EVENT_KIND_AGENT_TERMINATED = 'agent-terminated';
+export const EVENT_KIND_AGENT_TERMINATION_REQUESTED = 'agent-termination-requested';
+export const EVENT_KIND_TOOL_APPROVAL_REQUESTED = 'tool-approval-requested';
+// ============================================================================
+// Event Catalog
+// ============================================================================
+export const EVENT_CATALOG = {
+    'agent-assigned': AGENT_ASSIGNED_EVENT_SPEC_0_0_1,
+    'agent-output': AGENT_OUTPUT_EVENT_SPEC_0_0_1,
+    'agent-start-requested': AGENT_START_REQUESTED_EVENT_SPEC_0_0_1,
+    'agent-started': AGENT_STARTED_EVENT_SPEC_0_0_1,
+    'agent-terminated': AGENT_TERMINATED_EVENT_SPEC_0_0_1,
+    'agent-termination-requested': AGENT_TERMINATION_REQUESTED_EVENT_SPEC_0_0_1,
+    'tool-approval-requested': TOOL_APPROVAL_REQUESTED_EVENT_SPEC_0_0_1,
+};
+export function getEventSpecs() {
+    return Object.values(EVENT_CATALOG);
+}
+function resolveEventIdTs(eventId) {
+    if (eventId in EVENT_CATALOG)
+        return eventId;
+    const idx = eventId.lastIndexOf(':');
+    if (idx > 0) {
+        const base = eventId.slice(0, idx);
+        if (base in EVENT_CATALOG)
+            return base;
+    }
+    return eventId;
+}
+export function getEventSpec(eventId) {
+    return EVENT_CATALOG[resolveEventIdTs(eventId)];
+}

package/lib/specs/frontendTools.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Frontend Tool Catalog
+ *
+ * Predefined frontend tool sets that can be attached to agents.
+ *
+ * This file is AUTO-GENERATED from YAML specifications.
+ * DO NOT EDIT MANUALLY - run 'make specs' to regenerate.
+ */
+import type { FrontendToolSpec } from '../types';
+export declare const JUPYTER_NOTEBOOK_FRONTEND_TOOL_SPEC_0_0_1: FrontendToolSpec;
+export declare const LEXICAL_DOCUMENT_FRONTEND_TOOL_SPEC_0_0_1: FrontendToolSpec;
+export declare const FRONTEND_TOOL_CATALOG: Record<string, FrontendToolSpec>;
+export declare function getFrontendToolSpecs(): FrontendToolSpec[];
+export declare function getFrontendToolSpec(toolId: string): FrontendToolSpec | undefined;

package/lib/specs/frontendTools.js

@@ -0,0 +1,53 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+// ============================================================================
+// Frontend Tool Definitions
+// ============================================================================
+export const JUPYTER_NOTEBOOK_FRONTEND_TOOL_SPEC_0_0_1 = {
+    id: 'jupyter-notebook',
+    version: '0.0.1',
+    name: 'Jupyter Notebook',
+    description: 'Frontend tools for interacting with Jupyter notebooks.',
+    tags: ["frontend", "notebook", "jupyter"],
+    enabled: true,
+    toolset: 'all',
+    icon: 'notebook',
+    emoji: '📓',
+};
+export const LEXICAL_DOCUMENT_FRONTEND_TOOL_SPEC_0_0_1 = {
+    id: 'lexical-document',
+    version: '0.0.1',
+    name: 'Lexical Document',
+    description: 'Frontend tools for interacting with Lexical documents.',
+    tags: ["frontend", "document", "lexical"],
+    enabled: true,
+    toolset: 'all',
+    icon: 'file',
+    emoji: '📄',
+};
+// ============================================================================
+// Frontend Tool Catalog
+// ============================================================================
+export const FRONTEND_TOOL_CATALOG = {
+    'jupyter-notebook': JUPYTER_NOTEBOOK_FRONTEND_TOOL_SPEC_0_0_1,
+    'lexical-document': LEXICAL_DOCUMENT_FRONTEND_TOOL_SPEC_0_0_1,
+};
+export function getFrontendToolSpecs() {
+    return Object.values(FRONTEND_TOOL_CATALOG);
+}
+function resolveFrontendToolId(toolId) {
+    if (toolId in FRONTEND_TOOL_CATALOG)
+        return toolId;
+    const idx = toolId.lastIndexOf(':');
+    if (idx > 0) {
+        const base = toolId.slice(0, idx);
+        if (base in FRONTEND_TOOL_CATALOG)
+            return base;
+    }
+    return toolId;
+}
+export function getFrontendToolSpec(toolId) {
+    return FRONTEND_TOOL_CATALOG[resolveFrontendToolId(toolId)];
+}