@datalayer/agent-runtimes 1.0.2 → 1.0.3

package/lib/types/notifications.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Dynamic field definition for a notification channel.
+ */
+export interface NotificationField {
+    /** Field key */
+    name: string;
+    /** Human-readable label */
+    label: string;
+    /** Field type */
+    type: 'string' | 'boolean' | 'number';
+    /** Whether the field is required */
+    required: boolean;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Default value */
+    default?: string | boolean | number;
+}
+/**
+ * Notification channel specification.
+ */
+export interface NotificationChannelSpec {
+    /** Unique channel identifier */
+    id: string;
+    /** Version */
+    version?: string;
+    /** Display name */
+    name: string;
+    /** Description of the channel */
+    description: string;
+    /** Icon identifier */
+    icon: string;
+    /** Whether this channel is currently available */
+    available: boolean;
+    /** Whether this channel is marked as coming soon */
+    coming_soon?: boolean;
+    /** Dynamic configuration fields for this channel */
+    fields: NotificationField[];
+}
+/**
+ * Notification configuration for an agent spec.
+ */
+export interface AgentNotificationConfig {
+    email?: string;
+    slack?: string;
+    teams?: string;
+    webhook?: string;
+    [key: string]: string | number | boolean | undefined;
+}
+export interface AgentNotification {
+    /** Unique notification ID */
+    id: string;
+    /** Agent that generated the notification */
+    agentId: string;
+    /** Pod running the agent */
+    podName: string;
+    /** Notification severity */
+    level: NotificationLevel;
+    /** Notification title */
+    title: string;
+    /** Notification body (markdown) */
+    body: string;
+    /** Whether the user has read this notification */
+    read: boolean;
+    /** When the notification was created */
+    createdAt: string;
+    /** Category for grouping */
+    category: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+export type NotificationLevel = 'info' | 'warning' | 'error' | 'success';
+export interface NotificationFilters {
+    /** Filter by agent ID */
+    agentId?: string;
+    /** Filter by level */
+    level?: NotificationLevel;
+    /** Only unread notifications */
+    unreadOnly?: boolean;
+    /** Filter by category */
+    category?: string;
+    /** Maximum results */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}

package/lib/types/notifications.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export {};

package/lib/types/outputs.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Output format specification.
+ */
+export interface OutputSpec {
+    /** Unique output identifier */
+    id: string;
+    /** Version */
+    version?: string;
+    /** Display name */
+    name: string;
+    /** Description of the output format */
+    description: string;
+    /** Icon identifier */
+    icon: string;
+    /** Whether this format supports templates */
+    supports_template: boolean;
+    /** Whether this format supports storage paths */
+    supports_storage: boolean;
+    /** MIME types produced */
+    mime_types: string[];
+}
+/**
+ * Output configuration for an agent spec.
+ */
+export interface AgentOutputConfig {
+    type?: string;
+    formats?: string[];
+    template?: string;
+    storage?: string;
+    [key: string]: unknown;
+}
+export interface OutputArtifact {
+    /** Unique artifact ID */
+    id: string;
+    /** Agent that produced the artifact */
+    agentId: string;
+    /** Artifact type (e.g. 'pdf', 'csv') */
+    type: string;
+    /** Filename for download */
+    filename: string;
+    /** Download URL */
+    url: string;
+    /** Size in bytes */
+    sizeBytes: number;
+    /** MIME content type */
+    contentType: string;
+    /** When the artifact was generated */
+    createdAt: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}

package/lib/types/outputs.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export {};

package/lib/{components/chat/types → types}/protocol.d.ts

@@ -2,32 +2,52 @@
  * Protocol adapter types for chat component.
  * Supports AG-UI (SSE), A2A (SSE), ACP (WebSocket), MCP-UI.
  *
- * @module components/chat/types/protocol
+ * @module types/protocol
  */
-import type { ChatMessage } from './message';
-import type { ToolDefinition, ToolCallRequest, ToolExecutionResult } from './tool';
+import { AgentCard } from './a2a';
+import type { ChatMessage } from './messages';
+import type { ToolDefinition, ToolCallRequest, ToolExecutionResult } from './tools';
 /**
- * Supported transport types (communication transports)
+ * Supported protocol (communication protocols with agent backends)
  */
-export type TransportType = 'ag-ui' | 'a2a' | 'acp' | 'vercel-ai';
+export type Protocol = 'ag-ui' | 'a2a' | 'acp' | 'vercel-ai' | 'vercel-ai-jupyter';
 /**
- * UI format for interactive elements
+ * Protocol connection state
  */
-export type Extension = 'mcp-ui' | 'a2ui';
+export type ProtocolConnectionState = 'disconnected' | 'connecting' | 'connected' | 'error' | 'reconnecting';
 /**
  * Protocol transport mechanism
  */
 export type ProtocolTransport = 'sse' | 'websocket' | 'http';
 /**
- * Protocol connection state
+ * UI format for interactive elements
  */
-export type ProtocolConnectionState = 'disconnected' | 'connecting' | 'connected' | 'error' | 'reconnecting';
+export type Extension = 'mcp-ui' | 'a2ui';
+/**
+ * Protocol configuration for ChatBase
+ */
+export interface ProtocolConfig {
+    /** Protocol/transport type */
+    type: Protocol;
+    /** Endpoint URL */
+    endpoint: string;
+    /** Authentication token */
+    authToken?: string;
+    /** Agent ID */
+    agentId?: string;
+    /** Enable config query for models and tools */
+    enableConfigQuery?: boolean;
+    /** Config endpoint URL for non-Jupyter protocols (if not set, uses Jupyter requestAPI) */
+    configEndpoint?: string;
+    /** Additional protocol options */
+    options?: Record<string, unknown>;
+}
 /**
  * Transport adapter configuration
  */
 export interface ProtocolAdapterConfig {
     /** Transport type */
-    type: TransportType;
+    protocol: Protocol;
     /** Base URL for the protocol endpoint */
     baseUrl: string;
     /** Authentication token/key */
@@ -45,10 +65,6 @@ export interface ProtocolAdapterConfig {
     /** Additional protocol-specific options */
     options?: Record<string, unknown>;
 }
-/**
- * Protocol event types
- */
-export type ProtocolEventType = 'connected' | 'disconnected' | 'message' | 'tool-call' | 'tool-result' | 'activity' | 'state-update' | 'error';
 /**
  * Token usage statistics from a protocol event
  */
@@ -76,36 +92,21 @@ export interface ProtocolEvent {
     timestamp: Date;
 }
 /**
- * Callback for handling protocol events
+ * Protocol event types
  */
-export type ProtocolEventHandler = (event: ProtocolEvent) => void;
+export type ProtocolEventType = 'connected' | 'disconnected' | 'message' | 'tool-call' | 'tool-result' | 'activity' | 'state-update' | 'done' | 'error';
 /**
- * Agent card for A2A protocol
+ * Callback for handling protocol events
  */
-export interface AgentCard {
-    name: string;
-    description?: string;
-    url: string;
-    version?: string;
-    capabilities?: {
-        streaming?: boolean;
-        extensions?: string[];
-    };
-    skills?: Array<{
-        id: string;
-        name: string;
-        description?: string;
-        examples?: string[];
-    }>;
-}
+export type ProtocolEventHandler = (event: ProtocolEvent) => void;
 /**
  * Abstract protocol adapter interface
  */
 export interface ProtocolAdapter {
-    /** Transport type */
-    readonly type: TransportType;
+    /** Protocol */
+    readonly protocol: Protocol;
     /** Transport mechanism used */
-    readonly transport: ProtocolTransport;
+    readonly protocolTransport: ProtocolTransport;
     /** Current connection state */
     readonly connectionState: ProtocolConnectionState;
     /**
@@ -167,66 +168,3 @@ export interface ProtocolMessageConverter {
     /** Convert protocol message to internal format */
     fromProtocol(data: unknown): ChatMessage | null;
 }
-/**
- * AG-UI specific types
- */
-export declare namespace AGUI {
-    interface RunAgentInput {
-        threadId: string;
-        runId: string;
-        messages: ChatMessage[];
-        state: Record<string, unknown> | null;
-        tools: ToolDefinition[];
-        context: Array<{
-            type: string;
-            content: string;
-        }>;
-        forwardedProps: Record<string, unknown> | null;
-        /** Optional model override for per-request model selection */
-        model?: string;
-    }
-    interface Event {
-        type: string;
-        data?: unknown;
-    }
-}
-/**
- * A2A specific types
- */
-export declare namespace A2A {
-    interface Task {
-        id: string;
-        status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
-        messages: ChatMessage[];
-        result?: unknown;
-    }
-    interface Message {
-        role: string;
-        parts: Array<{
-            type: string;
-            text?: string;
-            data?: unknown;
-        }>;
-    }
-}
-/**
- * ACP specific types (WebSocket-based)
- */
-export declare namespace ACP {
-    interface JsonRpcRequest {
-        jsonrpc: '2.0';
-        method: string;
-        params?: unknown;
-        id: string | number;
-    }
-    interface JsonRpcResponse {
-        jsonrpc: '2.0';
-        result?: unknown;
-        error?: {
-            code: number;
-            message: string;
-            data?: unknown;
-        };
-        id: string | number;
-    }
-}

package/lib/types/protocol.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export {};

package/lib/types/sandbox.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Status message pushed by the `/configure/sandbox/ws` WebSocket.
+ */
+export interface SandboxWsStatus {
+    variant: string;
+    sandbox_running: boolean;
+    is_executing: boolean;
+    jupyter_url?: string | null;
+    /** Present only on error. */
+    error?: string;
+}
+/**
+ * Acknowledge message when the client sends an interrupt action.
+ */
+export interface SandboxInterruptAck {
+    action: 'interrupt';
+    success: boolean;
+    error?: string;
+}
+/** Union of all messages the server can send. */
+export type SandboxWsMessage = SandboxWsStatus | SandboxInterruptAck;
+/**
+ * Derived aggregate status for display purposes.
+ */
+export type SandboxAggregateStatus = 'unavailable' | 'stopped' | 'idle' | 'executing';
+export declare const SANDBOX_STATUS_COLORS: Record<SandboxAggregateStatus, string>;
+export declare const SANDBOX_STATUS_LABELS: Record<SandboxAggregateStatus, string>;

package/lib/types/sandbox.js

@@ -0,0 +1,24 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Sandbox-related types for WebSocket status streaming and
+ * the SandboxStatusIndicator component.
+ *
+ * @module types/sandbox
+ */
+import { defaultIndicatorColors } from '@datalayer/primer-addons/lib/theme';
+/* ── Visual constants ──────────────────────────────────── */
+export const SANDBOX_STATUS_COLORS = {
+    unavailable: defaultIndicatorColors.muted,
+    stopped: defaultIndicatorColors.muted,
+    idle: defaultIndicatorColors.success,
+    executing: defaultIndicatorColors.info,
+};
+export const SANDBOX_STATUS_LABELS = {
+    unavailable: 'Sandbox unavailable',
+    stopped: 'Sandbox not running',
+    idle: 'Sandbox idle',
+    executing: 'Sandbox executing code',
+};

package/lib/types/skills.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Skill information from backend
+ */
+export interface SkillInfo {
+    id: string;
+    name: string;
+    description?: string;
+    version?: string;
+    tags?: string[];
+    has_scripts?: boolean;
+    has_resources?: boolean;
+}
+/**
+ * Skills response from backend
+ */
+export interface SkillsResponse {
+    skills: SkillInfo[];
+    total: number;
+    skills_path?: string;
+}
+/**
+ * Specification for a skill.
+ *
+ * Supports three variants:
+ * - Variant 1 (name-based): Uses `module` to discover and load a skill
+ *   from a Python module path (e.g. `agent_skills.events`).
+ * - Variant 2 (package-based): Uses `package` and `method` to reference
+ *   a callable in an installable Python package.  Attributes such as
+ *   `license`, `compatibility`, `allowedTools`, and `skillMetadata`
+ *   are discovered at runtime from the `SKILL.md` packaged inside the
+ *   Python package — they should NOT be duplicated in the YAML spec.
+ * - Variant 3 (path-based): Uses `path` to load a local skill directory
+ *   containing `SKILL.md` (relative to the configured skills folder).
+ */
+export interface SkillSpec {
+    /** Unique skill identifier */
+    id: string;
+    /** Skill version */
+    version: string;
+    /** Display name for the skill */
+    name: string;
+    /** Skill description */
+    description: string;
+    /** Python module path for name-based discovery (variant 1) */
+    module?: string;
+    /** Python package containing the skill implementation (variant 2) */
+    package?: string;
+    /** Callable/function name in the package (variant 2) */
+    method?: string;
+    /** Path to a local skill directory or SKILL.md file (variant 3) */
+    path?: string;
+    /** License name or reference (agentskills.io spec) */
+    license?: string;
+    /** Environment requirements (agentskills.io spec) */
+    compatibility?: string;
+    /** Pre-approved tools the skill may use (agentskills.io spec) */
+    allowedTools?: string[];
+    /** Arbitrary key-value metadata (agentskills.io spec) */
+    skillMetadata?: Record<string, string>;
+    /** Environment variables required by this skill */
+    requiredEnvVars: string[];
+    /** Optional environment variables */
+    optionalEnvVars?: string[];
+    /** Python package dependencies */
+    dependencies?: string[];
+    /** Tags for categorization */
+    tags: string[];
+    /** Icon identifier */
+    icon?: string;
+    /** Emoji identifier */
+    emoji?: string;
+    /** Whether the skill is enabled */
+    enabled: boolean;
+}

package/lib/types/skills.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export {};

package/lib/types/teams.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Specification for an agent within a team.
+ */
+export interface TeamAgentSpec {
+    /** Agent identifier within the team */
+    id: string;
+    /** Display name for the team agent */
+    name: string;
+    /** Role within the team (e.g., 'Primary · Initiator', 'Secondary', 'Final') */
+    role?: string;
+    /** Goal or objective for this agent */
+    goal?: string;
+    /** AI model identifier */
+    model?: string;
+    /** MCP server used by this agent */
+    mcpServer?: string;
+    /** Tools available to this agent */
+    tools?: string[];
+    /** Trigger condition for this agent */
+    trigger?: string;
+    /** Approval policy: 'auto' or 'manual' */
+    approval?: string;
+}
+/**
+ * Supervisor agent configuration for a team.
+ */
+export interface TeamSupervisorSpec {
+    /** Supervisor agent name */
+    name: string;
+    /** AI model used by the supervisor */
+    model?: string;
+}
+/**
+ * Validation settings for a team.
+ */
+export interface TeamValidationSpec {
+    /** Maximum execution time (e.g., '300s') */
+    timeout?: string;
+    /** Whether to retry on failure */
+    retryOnFailure?: boolean;
+    /** Maximum number of retries */
+    maxRetries?: number;
+}
+/**
+ * A reaction rule for automatic team event handling.
+ */
+export interface TeamReactionRule {
+    /** Rule identifier */
+    id: string;
+    /** Trigger event (e.g., 'task-failed', 'member-unresponsive') */
+    trigger: string;
+    /** Action to take (e.g., 'send-to-agent', 'restart-member', 'notify') */
+    action: string;
+    /** Whether the action is automatic */
+    auto: boolean;
+    /** Maximum number of retries */
+    maxRetries: number;
+    /** Escalate after this many retries */
+    escalateAfterRetries: number;
+    /** Priority level (e.g., 'warning', 'action', 'urgent') */
+    priority: string;
+}
+/**
+ * Health monitoring configuration for a team.
+ */
+export interface TeamHealthMonitoring {
+    /** Duration between expected heartbeats (e.g. '30s', '1m') */
+    heartbeatInterval: string;
+    /** Member marked stale after this duration (e.g. '120s') */
+    staleThreshold: string;
+    /** Member marked unresponsive after this duration (e.g. '300s') */
+    unresponsiveThreshold: string;
+    /** Member marked stuck after this duration (e.g. '600s') */
+    stuckThreshold: string;
+    /** Maximum restart attempts before giving up */
+    maxRestartAttempts: number;
+}
+/**
+ * Output configuration for a team.
+ */
+export interface TeamOutputSpec {
+    /** Output formats (e.g., 'JSON', 'PDF', 'CSV') */
+    formats: string[];
+    /** Output template name */
+    template?: string;
+    /** Storage location */
+    storage?: string;
+}
+/**
+ * Specification for a multi-agent team.
+ */
+export interface TeamSpec {
+    /** Unique team identifier */
+    id: string;
+    /** Version */
+    version?: string;
+    /** Display name for the team */
+    name: string;
+    /** Team description */
+    description: string;
+    /** Classification tags */
+    tags: string[];
+    /** Whether the team is enabled */
+    enabled: boolean;
+    /** Icon identifier */
+    icon?: string;
+    /** Emoji representation */
+    emoji?: string;
+    /** Theme color (hex) */
+    color?: string;
+    /** ID of the associated agent spec */
+    agentSpecId: string;
+    /** Orchestration protocol (e.g., 'datalayer') */
+    orchestrationProtocol: string;
+    /** Execution mode: 'sequential' or 'parallel' */
+    executionMode: string;
+    /** Supervisor agent configuration */
+    supervisor?: TeamSupervisorSpec;
+    /** Instructions for routing tasks between agents */
+    routingInstructions?: string;
+    /** Validation settings for the team */
+    validation?: TeamValidationSpec;
+    /** List of agents in the team */
+    agents: TeamAgentSpec[];
+    /** Reaction rules for automatic event handling */
+    reactionRules?: TeamReactionRule[];
+    /** Health monitoring configuration */
+    healthMonitoring?: TeamHealthMonitoring;
+    /** Notification channel configuration */
+    notifications?: Record<string, boolean>;
+    /** Output configuration */
+    output?: TeamOutputSpec;
+}

package/lib/types/teams.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export {};

package/lib/types/tool-approvals.d.ts

@@ -0,0 +1,39 @@
+export interface ToolApproval {
+    /** Unique approval request ID */
+    id: string;
+    /** Agent that requested the tool call */
+    agentId: string;
+    /** Pod running the agent */
+    podName: string;
+    /** Tool being requested */
+    toolName: string;
+    /** Tool call arguments */
+    toolArgs: Record<string, unknown>;
+    /** Current approval status */
+    status: ToolApprovalStatus;
+    /** When the request was created */
+    createdAt: string;
+    /** When the request was resolved */
+    resolvedAt?: string;
+    /** Who resolved the request */
+    resolvedBy?: string;
+    /** Optional note from the approver */
+    note?: string;
+    /** Whether the approval has been marked as read */
+    read?: boolean;
+    /** Time limit for the approval (ISO timestamp) */
+    expiresAt?: string;
+}
+export type ToolApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired' | 'auto_approved' | 'deleted';
+export interface ToolApprovalFilters {
+    /** Filter by agent ID */
+    agentId?: string;
+    /** Filter by status */
+    status?: ToolApprovalStatus;
+    /** Filter by tool name */
+    toolName?: string;
+    /** Maximum results to return */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}

package/lib/types/tool-approvals.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export {};