@datalayer/agent-runtimes 1.0.4 → 1.0.5

package/lib/types/stream.d.ts

@@ -0,0 +1,110 @@
+import type { ContextSnapshotData } from './context';
+import type { McpToolsetsStatusResponse } from './mcp';
+import type { SkillStatus } from './skills';
+export type AgentStreamEventType = 'agent.snapshot' | 'tool_approval_created' | 'tool_approval_approved' | 'tool_approval_rejected';
+export interface AgentStreamMessage<TPayload = Record<string, unknown>> {
+    version: string;
+    type: AgentStreamEventType | string;
+    agentId?: string;
+    timestamp: string;
+    payload: TPayload;
+    event?: string;
+    data?: unknown;
+}
+export interface AgentStreamToolApprovalPayload {
+    id: string;
+    agent_id?: string;
+    pod_name?: string;
+    tool_name: string;
+    tool_call_id?: string;
+    tool_args?: Record<string, unknown>;
+    status?: string;
+    note?: string | null;
+    created_at?: string;
+    updated_at?: string;
+}
+export interface AgentStreamSnapshotPayload {
+    agentId?: string;
+    approvals: AgentStreamToolApprovalPayload[];
+    pendingApprovalCount: number;
+    contextSnapshot?: ContextSnapshotData | null;
+    costUsage?: ContextSnapshotData['costUsage'];
+    mcpStatus?: McpToolsetsStatusResponse | null;
+    codemodeStatus?: CodemodeStatusData | null;
+    fullContext?: Record<string, unknown> | null;
+    graphTelemetry?: GraphTelemetryData | null;
+}
+/** Graph-level telemetry data from pydantic-graph execution. */
+export interface GraphTelemetryData {
+    agentId?: string;
+    graphName?: string | null;
+    /** Static topology: graph node definitions. */
+    nodes: GraphTelemetryNode[];
+    /** Static topology: edges between nodes. */
+    edges: GraphTelemetryEdge[];
+    /** Dynamic execution trace: per-node events. */
+    events: GraphNodeEvent[];
+    totalNodesExecuted: number;
+    totalDurationMs: number;
+    lastRunStartMs: number;
+    lastRunEndMs: number;
+    runCount: number;
+}
+export interface GraphTelemetryNode {
+    id: string;
+    name: string;
+    category: string;
+}
+export interface GraphTelemetryEdge {
+    source: string;
+    target: string;
+    label?: string | null;
+    edgeType: string;
+}
+export interface GraphNodeEvent {
+    nodeId: string;
+    nodeType: string;
+    status: string;
+    timestampMs: number;
+    durationMs?: number | null;
+    parentNodeId?: string | null;
+    error?: string | null;
+}
+/** Codemode status as pushed via the monitoring WebSocket. */
+export interface CodemodeStatusData {
+    enabled: boolean;
+    skills: Array<{
+        id?: string;
+        name: string;
+        description?: string;
+        tags?: string[];
+        has_scripts?: boolean;
+        has_resources?: boolean;
+        status?: SkillStatus;
+        approved?: boolean;
+        skill_definition?: string | null;
+        source_variant?: 'module' | 'package' | 'path' | 'unknown';
+        module?: string;
+        package?: string;
+        method?: string;
+        path?: string;
+    }>;
+    available_skills: Array<{
+        id?: string;
+        name: string;
+        description?: string;
+        tags?: string[];
+        has_scripts?: boolean;
+        has_resources?: boolean;
+        status?: SkillStatus;
+        approved?: boolean;
+        skill_definition?: string | null;
+        source_variant?: 'module' | 'package' | 'path' | 'unknown';
+        module?: string;
+        package?: string;
+        method?: string;
+        path?: string;
+    }>;
+    sandbox?: Record<string, unknown> | null;
+}
+export declare function parseAgentStreamMessage(raw: unknown): AgentStreamMessage | null;

package/lib/types/stream.js

@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+const isObject = (value) => !!value && typeof value === 'object';
+export function parseAgentStreamMessage(raw) {
+    if (!isObject(raw)) {
+        return null;
+    }
+    // New envelope format.
+    if (typeof raw.type === 'string' && isObject(raw.payload)) {
+        return {
+            version: typeof raw.version === 'string' ? raw.version : '1.0',
+            type: raw.type,
+            agentId: typeof raw.agentId === 'string' ? raw.agentId : undefined,
+            timestamp: typeof raw.timestamp === 'string'
+                ? raw.timestamp
+                : new Date().toISOString(),
+            payload: raw.payload,
+            event: typeof raw.event === 'string' ? raw.event : undefined,
+            data: raw.data,
+        };
+    }
+    // Legacy event/data format.
+    if (typeof raw.event === 'string' && isObject(raw.data)) {
+        return {
+            version: '1.0',
+            type: raw.event,
+            timestamp: new Date().toISOString(),
+            payload: raw.data,
+            event: raw.event,
+            data: raw.data,
+        };
+    }
+    return null;
+}

package/lib/utils/utils.d.ts

@@ -47,11 +47,15 @@ export declare function convertHistoryToDisplayItems(messages: ChatMessage[]): D
  */
 export declare function formatTokenCount(tokens: number): string;
 /**
- * Derive the API base URL from a configEndpoint.
- * configEndpoint may look like:
- *   "http://host:port/api/v1/config"     (from agentRuntimeConfig)
- *   "http://host:port/api/v1/configure"   (from Chat component)
- * We strip the trailing path segment to get "http://host:port/api/v1".
+ * Derives the API base URL from a config endpoint URL.
+ *
+ * The config endpoint may be `{base}/api/v1/config` (from agentRuntimeConfig)
+ * or `{base}/api/v1/configure` (from the Chat component). This function
+ * strips the trailing path segment to yield `{base}/api/v1`.
+ *
+ * @param configEndpoint - Full config endpoint URL.
+ *
+ * @returns The API base URL without the trailing config segment.
  */
 export declare function getApiBaseFromConfig(configEndpoint: string): string;
 /**

package/lib/utils/utils.js

@@ -166,11 +166,15 @@ export function formatTokenCount(tokens) {
     return tokens.toString();
 }
 /**
- * Derive the API base URL from a configEndpoint.
- * configEndpoint may look like:
- *   "http://host:port/api/v1/config"     (from agentRuntimeConfig)
- *   "http://host:port/api/v1/configure"   (from Chat component)
- * We strip the trailing path segment to get "http://host:port/api/v1".
+ * Derives the API base URL from a config endpoint URL.
+ *
+ * The config endpoint may be `{base}/api/v1/config` (from agentRuntimeConfig)
+ * or `{base}/api/v1/configure` (from the Chat component). This function
+ * strips the trailing path segment to yield `{base}/api/v1`.
+ *
+ * @param configEndpoint - Full config endpoint URL.
+ *
+ * @returns The API base URL without the trailing config segment.
  */
 export function getApiBaseFromConfig(configEndpoint) {
     return configEndpoint.replace(/\/(config|configure)\/?$/, '');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datalayer/agent-runtimes",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "type": "module",
   "workspaces": [
     ".",
@@ -60,16 +60,16 @@
     "build:lib": "npm run clean:lib && gulp resources-to-lib && tsc -b",
     "build:nextjs": "npm run build --workspace=nextjs-notebook-example",
     "build:types": "npm run clean:lib && tsc -b",
-    "check": "npm run format:check && npm run lint:all && npm run type-check:all",
+    "check": "npm run format:check && npm run lint:all && npm run type-check:all && npm run typedoc",
     "check:fix": "npm run format:all && npm run lint:fix && npm run type-check:all",
     "clean": "rimraf lib dist build tsconfig.tsbuildinfo",
     "clean:cache": "rimraf node_modules/.vite",
     "clean:dist": "rimraf dist",
     "clean:lib": "rimraf lib tsconfig.tsbuildinfo",
     "create:patches": "bash scripts/create-patches.sh",
-    "examples": "run-p server:start jupyter:start examples:vite",
+    "examples": "run-p server:start server:start:codemode jupyter:start examples:vite",
     "examples:fresh": "npm run clean:cache && npm run examples",
-    "examples:jupyter": "run-p jupyter:start server:start examples:vite",
+    "examples:jupyter": "run-p jupyter:start server:start server:start:codemode examples:vite",
     "examples:nextjs": "npm run dev --workspace=nextjs-notebook-example",
     "examples:vite": "VITE_APP_TARGET=examples VITE_DATALAYER_RUN_URL=http://localhost:8888 vite",
     "format": "prettier --write \"src/**/*.{js,jsx,ts,tsx,css,json,md}\" \"examples/**/*.{js,jsx,ts,tsx,css,json,md,mjs}\"",
@@ -90,6 +90,8 @@
     "rebuild:fresh": "npm run create:patches && npm install && npm run build && npm run clean:cache",
     "server": "python -m agent_runtimes serve",
     "server:start": "PYTHONIOENCODING=utf-8 AGENT_RUNTIMES_DEBUG=false AGENT_RUNTIMES_LOG_LEVEL=info python -m agent_runtimes serve --port 8765 --log-level info",
+    "server:start:codemode": "PYTHONIOENCODING=utf-8 AGENT_RUNTIMES_DEBUG=false AGENT_RUNTIMES_LOG_LEVEL=info python -m agent_runtimes serve --port 8766 --log-level info",
+    "examples:codemode": "run-p server:start server:start:codemode examples:vite",
     "start": "vite",
     "start:acp": "run-p server:start start:acp:vite",
     "start:acp:prod": "run-p server start:acp:vite",
@@ -120,7 +122,7 @@
   },
   "dependencies": {
     "@a2a-js/sdk": "^0.3.6",
-    "@a2ui/react": "^0.8.0",
+    "@a2ui/react": "^0.9.1",
     "@ag-ui/client": "^0.0.42",
     "@ag-ui/core": "^0.0.42",
     "@ag-ui/encoder": "^0.0.42",
@@ -128,12 +130,12 @@
     "@agentclientprotocol/sdk": "^0.8.0",
     "@ai-sdk/react": "^4.0.0-beta.33",
     "@anthropic-ai/sdk": "^0.52.0",
-    "@datalayer/core": "^1.0.13",
-    "@datalayer/icons-react": "^1.0.6",
+    "@datalayer/core": "^1.0.20",
+    "@datalayer/icons-react": "^1.0.7",
     "@datalayer/jupyter-lexical": "^1.0.16",
     "@datalayer/jupyter-react": "^2.0.7",
-    "@datalayer/primer-addons": "^1.0.10",
-    "@datalayer/primer-rjsf": "^1.0.1",
+    "@datalayer/primer-addons": "^1.0.15",
+    "@datalayer/primer-rjsf": "^1.0.3",
     "@excalidraw/excalidraw": "^0.18.0",
     "@jupyter-widgets/base-manager": "^1.0.12",
     "@jupyter-widgets/schema": "^0.5.6",
@@ -301,6 +303,7 @@
     "vitest": "^3.2.4"
   },
   "resolutions": {
+    "@langchain/core": "^0.3.80",
     "@ai-sdk/react": "^4.0.0-beta.33",
     "@microsoft/fast-colors": "5.3.1",
     "@microsoft/fast-components": "2.30.6",
@@ -318,6 +321,7 @@
     "typescript": "^5.8.3"
   },
   "overrides": {
+    "@langchain/core": "^0.3.80",
     "@ai-sdk/react": "^4.0.0-beta.33",
     "@microsoft/fast-colors": "5.3.1",
     "@microsoft/fast-components": "2.30.6",

package/scripts/codegen/generate_agents.py

@@ -27,7 +27,7 @@ def _fmt_list(items: list[str]) -> str:
     """Format a list of strings with double quotes for ruff compliance."""
     if not items:
         return "[]"
-    return "[" + ", ".join(f'"{item}"' for item in items) + "]"
+    return "[" + ", ".join(_fmt_py_literal(item) for item in items) + "]"
 
 
 def _fmt_py_literal(value: Any) -> str:
@@ -44,6 +44,44 @@ def _fmt_ts_literal(value: Any) -> str:
     return json.dumps(value, ensure_ascii=False)
 
 
+def _normalize_subagents_for_typescript(value: Any) -> Any:
+    """Convert subagents config keys from YAML snake_case to TS camelCase."""
+    if not isinstance(value, dict):
+        return value
+
+    top_level_map = {
+        "default_model": "defaultModel",
+        "include_general_purpose": "includeGeneralPurpose",
+        "max_nesting_depth": "maxNestingDepth",
+    }
+    subagent_map = {
+        "can_ask_questions": "canAskQuestions",
+        "max_questions": "maxQuestions",
+        "preferred_mode": "preferredMode",
+        "typical_complexity": "typicalComplexity",
+        "typically_needs_context": "typicallyNeedsContext",
+    }
+
+    normalized: dict[str, Any] = {}
+    for key, raw_val in value.items():
+        mapped_key = top_level_map.get(key, key)
+        if mapped_key == "subagents" and isinstance(raw_val, list):
+            normalized_subagents: list[Any] = []
+            for subagent in raw_val:
+                if isinstance(subagent, dict):
+                    normalized_subagent: dict[str, Any] = {}
+                    for sa_key, sa_val in subagent.items():
+                        normalized_subagent[subagent_map.get(sa_key, sa_key)] = sa_val
+                    normalized_subagents.append(normalized_subagent)
+                else:
+                    normalized_subagents.append(subagent)
+            normalized[mapped_key] = normalized_subagents
+        else:
+            normalized[mapped_key] = raw_val
+
+    return normalized
+
+
 def load_yaml_specs(specs_dir: Path) -> List[tuple[str, Dict[str, Any]]]:
     """
     Load all YAML agent specifications from directory and subdirectories.
@@ -91,7 +129,7 @@ Generated from YAML specifications in specs/agents/
 from typing import Dict
 
 from agent_runtimes.mcp.catalog_mcp_servers import MCP_SERVER_CATALOG
-from agent_runtimes.types import AgentSpec
+from agent_runtimes.types import AgentSpec, SubAgentSpecConfig, SubAgentsConfig
 
 # ============================================================================
 # Agent Specs
@@ -166,7 +204,7 @@ from agent_runtimes.types import AgentSpec
             suggestions = spec.get("suggestions", [])
             suggestions_str = (
                 "[\n        "
-                + ",\n        ".join(f'"{s}"' for s in suggestions)
+                + ",\n        ".join(_fmt_py_literal(s) for s in suggestions)
                 + ",\n    ]"
                 if suggestions
                 else "[]"
@@ -217,11 +255,12 @@ from agent_runtimes.types import AgentSpec
 
             # New flow-level fields
             goal_raw = spec.get("goal")
-            goal_str = (
-                f'"{goal_raw.replace(chr(10), " ").replace("  ", " ").strip()}"'
+            goal_clean = (
+                goal_raw.replace(chr(10), " ").replace("  ", " ").strip()
                 if goal_raw
-                else "None"
+                else None
             )
+            goal_str = _fmt_py_literal(goal_clean)
             protocol_val = spec.get("protocol")
             protocol_str = f'"{protocol_val}"' if protocol_val else "None"
             ui_ext = spec.get("ui_extension")
@@ -239,6 +278,48 @@ from agent_runtimes.types import AgentSpec
             notifs = spec.get("notifications")
             memory_val = spec.get("memory")
             memory_str = f'"{memory_val}"' if memory_val else "None"
+            pre_hooks_val = spec.get("pre_hooks")
+            post_hooks_val = spec.get("post_hooks")
+            parameters_val = spec.get("parameters")
+            subagents_val = spec.get("subagents")
+
+            # Build subagents code if present
+            subagents_str = "None"
+            if isinstance(subagents_val, dict) and subagents_val.get("subagents"):
+                sa_items = []
+                for sa in subagents_val["subagents"]:
+                    sa_fields = [
+                        f"name={_fmt_py_literal(sa['name'])}",
+                        f"description={_fmt_py_literal(sa['description'])}",
+                        f"instructions={_fmt_py_literal(sa['instructions'])}",
+                    ]
+                    for opt_key in (
+                        "model",
+                        "can_ask_questions",
+                        "max_questions",
+                        "preferred_mode",
+                        "typical_complexity",
+                        "typically_needs_context",
+                    ):
+                        opt_val = sa.get(opt_key)
+                        if opt_val is not None:
+                            sa_fields.append(f"{opt_key}={_fmt_py_literal(opt_val)}")
+                    sa_items.append("SubAgentSpecConfig(" + ", ".join(sa_fields) + ")")
+                sa_list_str = "[" + ", ".join(sa_items) + "]"
+                cfg_parts = [f"subagents={sa_list_str}"]
+                if subagents_val.get("default_model") is not None:
+                    cfg_parts.append(
+                        f"default_model={_fmt_py_literal(subagents_val['default_model'])}"
+                    )
+                if subagents_val.get("include_general_purpose") is not None:
+                    cfg_parts.append(
+                        f"include_general_purpose={_fmt_py_literal(subagents_val['include_general_purpose'])}"
+                    )
+                if subagents_val.get("max_nesting_depth") is not None:
+                    cfg_parts.append(
+                        f"max_nesting_depth={_fmt_py_literal(subagents_val['max_nesting_depth'])}"
+                    )
+                subagents_str = "SubAgentsConfig(" + ", ".join(cfg_parts) + ")"
 
             code += f'''{const_name} = AgentSpec(
     id="{full_agent_id}",
@@ -277,6 +358,10 @@ from agent_runtimes.types import AgentSpec
     authorization_policy={auth_policy_str},
     notifications={_fmt_py_literal(notifs)},
     memory={memory_str},
+    pre_hooks={_fmt_py_literal(pre_hooks_val)},
+    post_hooks={_fmt_py_literal(post_hooks_val)},
+    parameters={_fmt_py_literal(parameters_val)},
+    subagents={subagents_str},
 )
 
 '''
@@ -764,6 +849,13 @@ const FRONTEND_TOOL_MAP: Record<string, any> = {
             notifs = spec.get("notifications")
             memory_val = spec.get("memory")
             memory_ts = f"'{memory_val}'" if memory_val else "undefined"
+            pre_hooks_val = spec.get("pre_hooks")
+            post_hooks_val = spec.get("post_hooks")
+            parameters_val = spec.get("parameters")
+            subagents_val = spec.get("subagents")
+            subagents_ts = _fmt_ts_literal(
+                _normalize_subagents_for_typescript(subagents_val)
+            )
 
             code += f"""export const {const_name}: AgentSpec = {{
   id: '{full_agent_id}',
@@ -802,6 +894,10 @@ const FRONTEND_TOOL_MAP: Record<string, any> = {
   authorizationPolicy: {auth_policy_ts},
   notifications: {_fmt_ts_literal(notifs)},
   memory: {memory_ts},
+  preHooks: {_fmt_ts_literal(pre_hooks_val)},
+  postHooks: {_fmt_ts_literal(post_hooks_val)},
+  parameters: {_fmt_ts_literal(parameters_val)},
+  subagents: {subagents_ts},
 }};
 
 """

package/scripts/codegen/generate_events.py

@@ -43,18 +43,22 @@ def load_specs(specs_dir: Path) -> list[dict[str, Any]]:
 
 
 def _py_field(f: dict[str, Any]) -> str:
-    """Format an EventField as a Python dict literal."""
+    """Format an EventField dict body.
+
+    Returns the lines inside ``EventField(\n    **{\n        ...\n    }\n)``
+    so that the generated output matches ``ruff format`` exactly.
+    """
     parts = [
-        f'"name": "{f["name"]}"',
-        f'"label": "{f["label"]}"',
-        f'"type": "{f["type"]}"',
-        f'"required": {str(f["required"])}',
+        f'                "name": "{f["name"]}"',
+        f'                "label": "{f["label"]}"',
+        f'                "type": "{f["type"]}"',
+        f'                "required": {str(f["required"])}',
     ]
     if "description" in f:
-        parts.append(f'"description": "{_esc_dq(f["description"])}"')
+        parts.append(f'                "description": "{_esc_dq(f["description"])}"')
     if "placeholder" in f:
-        parts.append(f'"placeholder": "{_esc_dq(f["placeholder"])}"')
-    return "{" + ", ".join(parts) + "}"
+        parts.append(f'                "placeholder": "{_esc_dq(f["placeholder"])}"')
+    return ",\n".join(parts)
 
 
 def _ts_field(f: dict[str, Any]) -> str:
@@ -118,10 +122,18 @@ def generate_python_code(specs: list[dict[str, Any]]) -> str:
             ]
         )
         if fields:
-            field_strs = [_py_field(f) for f in fields]
             lines.append("    fields=[")
-            for fs in field_strs:
-                lines.append(f"        EventField(**{fs}),")
+            for f in fields:
+                field_body = _py_field(f)
+                lines.extend(
+                    [
+                        "        EventField(",
+                        "            **{",
+                        field_body + ",",
+                        "            }",
+                        "        ),",
+                    ]
+                )
             lines.append("    ],")
         lines.extend([")", ""])
 
@@ -149,10 +161,17 @@ def generate_python_code(specs: list[dict[str, Any]]) -> str:
             "# Event kind constants for programmatic use",
         ]
     )
+
+    spec_kinds = {spec.get("kind", spec["id"]) for spec in specs}
+
     for spec in specs:
         kind = spec.get("kind", spec["id"])
         const = kind.upper().replace("-", "_")
         lines.append(f'EVENT_KIND_{const} = "{kind}"')
+
+    # Backward-compat constants used by older runtime code paths.
+    if "agent-assigned" not in spec_kinds:
+        lines.append('EVENT_KIND_AGENT_ASSIGNED = "agent-assigned"')
     lines.extend(
         [
             "",
@@ -162,8 +181,8 @@ def generate_python_code(specs: list[dict[str, Any]]) -> str:
             "    spec = EVENT_CATALOG.get(event_id)",
             "    if spec is not None:",
             "        return spec",
-            "    base, _, ver = event_id.rpartition(':')",
-            "    if base and '.' in ver:",
+            '    base, _, ver = event_id.rpartition(":")',
+            '    if base and "." in ver:',
             "        return EVENT_CATALOG.get(base)",
             "    return None",
             "",
@@ -233,11 +252,14 @@ def generate_typescript_code(specs: list[dict[str, Any]]) -> str:
         lines.extend(["};", ""])
 
     # Event kind constants
+    spec_kinds = {spec.get("kind", spec["id"]) for spec in specs}
     lines.append("// Event kind constants for programmatic use")
     for spec in specs:
         kind = spec.get("kind", spec["id"])
         const = kind.upper().replace("-", "_")
         lines.append(f"export const EVENT_KIND_{const} = '{kind}';")
+    if "agent-assigned" not in spec_kinds:
+        lines.append("export const EVENT_KIND_AGENT_ASSIGNED = 'agent-assigned';")
     lines.append("")
 
     lines.extend(