@datalayer/agent-runtimes 1.0.2 → 1.0.3

package/lib/types/eventspecs.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Event type specification types for agent lifecycle and guardrail events.
+ *
+ * @module types/eventspecs
+ */
+/**
+ * Dynamic field definition for an event type specification.
+ */
+export interface EventField {
+    /** Field key */
+    name: string;
+    /** Human-readable label */
+    label: string;
+    /** Field type */
+    type: 'string' | 'boolean' | 'number';
+    /** Whether the field is required */
+    required: boolean;
+    /** Field description */
+    description?: string;
+    /** Placeholder text */
+    placeholder?: string;
+}
+/**
+ * Event type specification for agent lifecycle and guardrail events.
+ */
+export interface EventSpec {
+    /** Unique event type identifier */
+    id: string;
+    /** Version */
+    version: string;
+    /** Display name */
+    name: string;
+    /** Description of the event type */
+    description: string;
+    /** Event kind constant */
+    kind: string;
+    /** Payload fields for this event type */
+    fields: EventField[];
+}

package/lib/types/eventspecs.js

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

package/lib/types/examples.d.ts

@@ -0,0 +1,31 @@
+import { Protocol } from './protocol';
+/**
+ * Status of an example agent (for UI demos).
+ */
+export type ExampleAgentStatus = 'starting' | 'running' | 'paused' | 'terminated' | 'archived';
+export interface ExampleAgent {
+    id: string;
+    name: string;
+    description: string;
+    author: string;
+    lastEdited: string;
+    screenshot: string;
+    status?: ExampleAgentStatus;
+    protocol: Protocol;
+    avatarUrl: string;
+    notebookFile: string;
+    lexicalFile: string;
+    stars: number;
+    notifications: number;
+}
+export type ExampleAgentsState = {
+    agents: readonly ExampleAgent[];
+    getAgentById: (id: string) => ExampleAgent | undefined;
+    updateAgentStatus: (id: string, status: ExampleAgentStatus) => void;
+    toggleAgentStatus: (id: string) => void;
+};
+export interface ConversationEntry {
+    id: string;
+    firstMessage?: string;
+    timestamp: number;
+}

package/lib/types/examples.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}/execution.d.ts

@@ -2,7 +2,7 @@
  * Execution types for code/skills execution results.
  * Maps to the Python code-sandboxes ExecutionResult model.
  *
- * @module components/chat/types/execution
+ * @module types/execution
  */
 /**
  * Code error information when Python code raises an exception.
@@ -76,3 +76,12 @@ export declare function getExitCodeMessage(result: ExecutionResult): string | nu
  * Format a code error for display, optionally including traceback.
  */
 export declare function formatCodeError(error: CodeError, includeTraceback?: boolean): string;
+/**
+ * Validation configuration for an agent spec.
+ */
+export interface AgentValidationConfig {
+    timeout?: string;
+    retryOnFailure?: boolean;
+    maxRetries?: number;
+    [key: string]: string | number | boolean | undefined;
+}

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

@@ -2,11 +2,11 @@
  * Extension types for chat component.
  * Extensions add pluggable UI and protocol capabilities.
  *
- * @module components/chat/types/extension
+ * @module types/extension
  */
 import type { ReactNode } from 'react';
-import type { ChatMessage } from './message';
-import type { ToolRenderProps } from './tool';
+import type { ChatMessage } from './messages';
+import type { ToolRenderProps } from './tools';
 import type { ProtocolEvent } from './protocol';
 /**
  * Extension type identifiers

package/lib/types/guardrails.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Permission flags for a guardrail identity.
+ */
+export interface GuardrailPermissions {
+    'read:data': boolean;
+    'write:data': boolean;
+    'execute:code': boolean;
+    'access:internet': boolean;
+    'send:email': boolean;
+    'deploy:production': boolean;
+}
+/**
+ * Token usage limits for a guardrail.
+ */
+export interface GuardrailTokenLimits {
+    per_run: string;
+    per_day: string;
+    per_month: string;
+}
+/**
+ * Data scope restrictions — which systems/objects are accessible.
+ */
+export interface GuardrailDataScope {
+    allowed_systems: string[];
+    allowed_objects: string[];
+    denied_objects: string[];
+    denied_fields: string[];
+}
+/**
+ * Data handling policies — aggregation, row-level, PII, redaction.
+ */
+export interface GuardrailDataHandling {
+    default_aggregation: boolean;
+    allow_row_level_output: boolean;
+    max_rows_in_output: number;
+    redact_fields: string[];
+    hash_fields: string[];
+    pii_detection: boolean;
+    pii_action: string;
+}
+/**
+ * Approval policy for sensitive operations.
+ */
+export interface GuardrailApprovalPolicy {
+    require_manual_approval_for: string[];
+    auto_approved: string[];
+}
+/**
+ * Tool invocation limits.
+ */
+export interface GuardrailToolLimits {
+    max_tool_calls: number;
+    max_query_rows: number;
+    max_query_runtime: string;
+    max_time_window_days: number;
+}
+/**
+ * Audit trail configuration.
+ */
+export interface GuardrailAudit {
+    log_tool_calls: boolean;
+    log_query_metadata_only: boolean;
+    retain_days: number;
+    require_lineage_in_report: boolean;
+}
+/**
+ * Content safety settings.
+ */
+export interface GuardrailContentSafety {
+    treat_crm_text_fields_as_untrusted: boolean;
+    do_not_follow_instructions_from_data: boolean;
+}
+/**
+ * Full guardrail specification.
+ */
+export interface GuardrailSpec {
+    /** Unique guardrail identifier */
+    id?: string;
+    /** Version */
+    version?: string;
+    /** Display name */
+    name?: string;
+    /** Description of the guardrail */
+    description?: string;
+    /** Identity provider (e.g., 'datalayer', 'github', 'azure-ad', 'google') */
+    identity_provider?: string;
+    /** Identity name within the provider */
+    identity_name?: string;
+    /** Permission flags */
+    permissions?: GuardrailPermissions | Record<string, boolean>;
+    /** Token usage limits */
+    token_limits?: GuardrailTokenLimits | Record<string, string>;
+    /** Data scope restrictions */
+    data_scope?: GuardrailDataScope | Record<string, unknown>;
+    /** Data handling policies */
+    data_handling?: GuardrailDataHandling | Record<string, unknown>;
+    /** Approval policy */
+    approval_policy?: GuardrailApprovalPolicy | Record<string, unknown>;
+    /** Tool invocation limits */
+    tool_limits?: GuardrailToolLimits | Record<string, unknown>;
+    /** Audit trail configuration */
+    audit?: GuardrailAudit | Record<string, unknown>;
+    /** Content safety settings */
+    content_safety?: GuardrailContentSafety | Record<string, unknown>;
+    [key: string]: unknown;
+}

package/lib/types/guardrails.js

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

package/lib/types/index.d.ts

@@ -1,2 +1,36 @@
-export * from './AIAgent';
-export * from './Types';
+export * from './a2a';
+export * from './acp';
+export * from './ag-ui';
+export * from './agents';
+export * from './agents-lifecycle';
+export * from './agentspecs';
+export * from './chat';
+export * from './checkpoints';
+export * from './config';
+export * from './connection';
+export * from './context';
+export * from './cost';
+export * from './envvars';
+export * from './events';
+export * from './eventspecs';
+export * from './evals';
+export * from './examples';
+export * from './execution';
+export * from './extensions';
+export * from './guardrails';
+export * from './inference';
+export * from './mcp';
+export * from './memory';
+export * from './messages';
+export * from './middleware';
+export * from './models';
+export * from './notifications';
+export * from './outputs';
+export * from './protocol';
+export * from './sandbox';
+export * from './skills';
+export * from './teams';
+export * from './tool-approvals';
+export * from './tools';
+export * from './triggers';
+export type { AgentUsageSummary } from './usage';

package/lib/types/index.js

@@ -2,5 +2,38 @@
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-export * from './AIAgent';
-export * from './Types';
+export * from './a2a';
+export * from './acp';
+export * from './ag-ui';
+export * from './agents';
+export * from './agents-lifecycle';
+export * from './agentspecs';
+export * from './chat';
+export * from './checkpoints';
+export * from './config';
+export * from './connection';
+export * from './context';
+export * from './cost';
+export * from './envvars';
+export * from './events';
+export * from './eventspecs';
+export * from './evals';
+export * from './examples';
+export * from './execution';
+export * from './extensions';
+export * from './guardrails';
+export * from './inference';
+export * from './mcp';
+export * from './memory';
+export * from './messages';
+export * from './middleware';
+export * from './models';
+export * from './notifications';
+export * from './outputs';
+export * from './protocol';
+export * from './sandbox';
+export * from './skills';
+export * from './teams';
+export * from './tool-approvals';
+export * from './tools';
+export * from './triggers';

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

@@ -2,10 +2,10 @@
  * Inference provider types for chat component.
  * Supports multiple backends: Datalayer, OpenAI, Anthropic, self-hosted.
  *
- * @module components/chat/types/inference
+ * @module types/inference
  */
-import type { ChatMessage, ChatMessageDelta } from './message';
-import type { ToolDefinition, ToolCallRequest, ToolExecutionResult } from './tool';
+import type { ChatMessage, ChatMessageDelta } from './messages';
+import type { ToolDefinition, ToolCallRequest, ToolExecutionResult } from './tools';
 /**
  * Type alias for MCP server identifier
  */

package/lib/types/inference.js

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

package/lib/types/mcp.d.ts

@@ -0,0 +1,117 @@
+/**
+ * A tool provided by an MCP server.
+ */
+export interface MCPServerTool {
+    /** Tool name/identifier */
+    name: string;
+    /** Tool description */
+    description: string;
+    /** Whether the tool is enabled */
+    enabled: boolean;
+    /** JSON schema for tool input parameters */
+    inputSchema?: Record<string, unknown>;
+}
+/**
+ * Configuration for an MCP server.
+ */
+export interface MCPServer {
+    /** Unique server identifier */
+    id: string;
+    /** Version */
+    version?: string;
+    /** Display name for the server */
+    name: string;
+    /** Server description */
+    description?: string;
+    /** Server URL (for HTTP-based servers) */
+    url: string;
+    /** Whether the server is enabled */
+    enabled: boolean;
+    /** List of available tools */
+    tools: MCPServerTool[];
+    /** Command to run the MCP server (e.g., 'npx', 'uvx') */
+    command?: string;
+    /** Command arguments for the MCP server */
+    args: string[];
+    /** Whether the server is available (based on tool discovery) */
+    isAvailable: boolean;
+    /** Transport type: 'stdio' or 'http' */
+    transport: 'stdio' | 'http';
+    /** Environment variables required by this server (e.g., API keys) */
+    requiredEnvVars?: string[];
+    /** Icon identifier for the server */
+    icon?: string;
+    /** Emoji identifier for the server */
+    emoji?: string;
+}
+/**
+ * MCP server tool configuration for an agent spec.
+ */
+export interface AgentMCPServerToolConfig {
+    server?: string;
+    tool?: string;
+    enabled?: boolean;
+    approval_required?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Lightweight MCP server tool shape used by MCP management views.
+ */
+export interface MCPServerManagerTool {
+    name: string;
+    description?: string;
+}
+/**
+ * Aggregate status of all MCP servers.
+ */
+export type McpAggregateStatus = 'none' | 'not_started' | 'starting' | 'failed' | 'started';
+/**
+ * Per-server status entry returned by the MCP toolsets-status endpoint.
+ */
+export interface McpServerStatus {
+    id: string;
+    status: 'none' | 'not_started' | 'starting' | 'failed' | 'started';
+    error?: string;
+    tools_count?: number;
+}
+/**
+ * Full response from `/api/v1/configure/mcp-toolsets-status`.
+ */
+export interface McpToolsetsStatusResponse {
+    initialized: boolean;
+    ready_count: number;
+    failed_count: number;
+    ready_servers: string[];
+    failed_servers: Record<string, string>;
+    servers: McpServerStatus[];
+}
+/**
+ * Primer-addon indicator colours for each aggregate MCP status.
+ * Uses the shared indicator palette so colours stay consistent
+ * across themes and components.
+ */
+export declare const MCP_STATUS_COLORS: Record<McpAggregateStatus, string>;
+/**
+ * Human-readable labels for each aggregate MCP status.
+ */
+export declare const MCP_STATUS_LABELS: Record<McpAggregateStatus, string>;
+/**
+ * MCP server shape used by MCP management views and /available endpoint payloads.
+ */
+export interface MCPServerManager {
+    id: string;
+    name: string;
+    description?: string;
+    url?: string;
+    enabled: boolean;
+    tools: MCPServerManagerTool[];
+    command?: string;
+    args?: string[];
+    requiredEnvVars?: string[];
+    isAvailable?: boolean;
+    transport?: string;
+    /** True if this server is from mcp.json config (not in catalog) */
+    isConfig?: boolean;
+    /** True if this server is currently running */
+    isRunning?: boolean;
+}

package/lib/types/mcp.js

@@ -0,0 +1,27 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { defaultIndicatorColors } from '@datalayer/primer-addons/lib/theme';
+/**
+ * Primer-addon indicator colours for each aggregate MCP status.
+ * Uses the shared indicator palette so colours stay consistent
+ * across themes and components.
+ */
+export const MCP_STATUS_COLORS = {
+    none: defaultIndicatorColors.neutral,
+    not_started: defaultIndicatorColors.muted,
+    starting: defaultIndicatorColors.warning,
+    failed: defaultIndicatorColors.danger,
+    started: defaultIndicatorColors.success,
+};
+/**
+ * Human-readable labels for each aggregate MCP status.
+ */
+export const MCP_STATUS_LABELS = {
+    none: 'No MCP servers',
+    not_started: 'MCP servers not started',
+    starting: 'MCP servers starting\u2026',
+    failed: 'MCP server error',
+    started: 'MCP servers ready',
+};

package/lib/types/memory.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Specification for a memory backend.
+ */
+export interface MemorySpec {
+    /** Unique memory identifier (e.g., 'ephemeral', 'mem0') */
+    id: string;
+    /** Version */
+    version: string;
+    /** Display name for the memory backend */
+    name: string;
+    /** Memory backend description */
+    description: string;
+    /** Persistence level: none, session, cross-session, permanent */
+    persistence: string;
+    /** Memory scope: agent, team, repository, user, global */
+    scope: string;
+    /** Storage backend identifier */
+    backend: string;
+    /** Icon identifier */
+    icon: string;
+    /** Emoji representation */
+    emoji: string;
+}

package/lib/types/memory.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/message.d.ts → types/messages.d.ts}

@@ -2,7 +2,7 @@
  * Message types for chat component.
  * Based on AG-UI protocol message format for interoperability.
  *
- * @module components/chat/types/message
+ * @module types/messages
  */
 /**
  * Message role enumeration
@@ -67,6 +67,25 @@ export interface ChatMessage {
     activityType?: string;
     activityData?: unknown;
 }
+/**
+ * Streaming options for custom message handlers.
+ * Enables streaming response support with chunk callbacks.
+ */
+export interface StreamingMessageOptions {
+    /** Callback for each chunk of streamed content */
+    onChunk?: (chunk: string) => void;
+    /** Callback when streaming is complete */
+    onComplete?: (fullResponse: string) => void;
+    /** Callback on error */
+    onError?: (error: Error) => void;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Custom message handler type for props-based mode.
+ * Supports both simple and streaming response patterns.
+ */
+export type MessageHandler = (message: string, messages: ChatMessage[], options?: StreamingMessageOptions) => Promise<string | void>;
 /**
  * Message input for sending new messages
  */

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

@@ -2,10 +2,10 @@
  * Middleware types for chat component.
  * Supports request/response interception and tool call middleware.
  *
- * @module components/chat/types/middleware
+ * @module types/middleware
  */
-import type { ChatMessage } from './message';
-import type { ToolCallRequest, ToolExecutionResult } from './tool';
+import type { ChatMessage } from './messages';
+import type { ToolCallRequest, ToolExecutionResult } from './tools';
 import type { InferenceRequestOptions, InferenceResponse } from './inference';
 /**
  * Context passed to middleware functions

package/lib/types/models.d.ts

@@ -0,0 +1,63 @@
+import type { MCPServer } from './mcp';
+/**
+ * Specification for an AI model from the catalog.
+ */
+export interface AIModel {
+    /** Unique model identifier (e.g., 'anthropic:claude-sonnet-4-5-20250514') */
+    id: string;
+    /** Model spec version */
+    version: string;
+    /** Display name for the model */
+    name: string;
+    /** Model description */
+    description: string;
+    /** Provider name (anthropic, openai, bedrock, azure-openai) */
+    provider: string;
+    /** Whether this is the default model */
+    default: boolean;
+    /** Required environment variable names */
+    requiredEnvVars: string[];
+}
+/**
+ * Configuration for an AI model runtime (as returned by the server).
+ */
+export interface AIModelRuntime {
+    /** Model identifier (e.g., 'anthropic:claude-sonnet-4-5') */
+    id: string;
+    /** Display name for the model */
+    name: string;
+    /** List of builtin tool IDs */
+    builtinTools: string[];
+    /** Required environment variables for this model */
+    requiredEnvVars: string[];
+    /** Whether the model is available (based on env vars) */
+    isAvailable: boolean;
+}
+/**
+ * Configuration for a builtin tool.
+ */
+export interface BuiltinTool {
+    /** Tool identifier */
+    id: string;
+    /** Display name for the tool */
+    name: string;
+}
+/**
+ * Configuration returned to frontend.
+ */
+export interface FrontendConfig {
+    /** Available AI models */
+    models: AIModelRuntime[];
+    /** Available builtin tools */
+    builtinTools: BuiltinTool[];
+    /** Configured MCP servers */
+    mcpServers: MCPServer[];
+}
+/**
+ * Model configuration for an agent spec.
+ */
+export interface AgentModelConfig {
+    temperature?: number;
+    max_tokens?: number;
+    [key: string]: string | number | boolean | undefined;
+}

package/lib/types/models.js

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