@runtypelabs/timely-a2a 0.3.3

package/dist/index.d.ts

@@ -0,0 +1,402 @@
+import { Application } from 'express';
+
+/**
+ * A2A Protocol Types
+ *
+ * Based on A2A Protocol v0.3
+ * https://a2a-protocol.org/v0.3.0/specification/
+ */
+interface AgentInterface {
+    url: string;
+    protocolBinding: string;
+    protocolVersion: string;
+    tenant?: string;
+}
+interface AgentCard {
+    name: string;
+    description: string;
+    /** @deprecated Use supportedInterfaces */
+    url?: string;
+    supportedInterfaces?: AgentInterface[];
+    version: string;
+    /** @deprecated Use supportedInterfaces[].protocolVersion */
+    protocolVersion?: string;
+    defaultInputModes: string[];
+    defaultOutputModes: string[];
+    iconUrl?: string;
+    provider?: {
+        organization: string;
+        url?: string;
+    };
+    capabilities: {
+        streaming: boolean;
+        pushNotifications: boolean;
+        statefulness?: 'none' | 'session' | 'task';
+    };
+    skills: Skill[];
+    authentication?: {
+        type: 'none' | 'bearer' | 'api_key';
+        bearerAuth?: {
+            scopes: string[];
+        };
+        apiKeyAuth?: {
+            headerName: string;
+        };
+    };
+}
+interface Skill {
+    id: string;
+    name: string;
+    description: string;
+    inputModes?: string[];
+    outputModes?: string[];
+    tags: string[];
+    examples?: string[];
+    inputSchema?: Record<string, unknown>;
+}
+interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id?: string | number;
+    method: string;
+    params?: unknown;
+}
+interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id?: string | number;
+    result?: unknown;
+    error?: JsonRpcError;
+}
+interface JsonRpcError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+declare const JSON_RPC_ERRORS: {
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+    readonly TASK_NOT_FOUND: -32001;
+    readonly TASK_NOT_CANCELABLE: -32002;
+    readonly PUSH_NOTIFICATION_NOT_SUPPORTED: -32003;
+    readonly UNSUPPORTED_OPERATION: -32004;
+    readonly CONTENT_TYPE_NOT_SUPPORTED: -32005;
+    readonly INVALID_AGENT_RESPONSE: -32006;
+    /** @deprecated Use TASK_NOT_CANCELABLE */
+    readonly SKILL_NOT_FOUND: -32002;
+    /** @deprecated */
+    readonly UNAUTHORIZED: -32003;
+    /** @deprecated */
+    readonly RATE_LIMITED: -32004;
+    /** @deprecated */
+    readonly TASK_CANCELED: -32005;
+};
+/**
+ * Internal message part representation.
+ * `type` is used internally for routing; the A2A spec uses a oneOf model
+ * where the presence of `text`, `data`, or `url` determines the kind.
+ */
+interface MessagePart {
+    type?: 'text' | 'file' | 'data';
+    text?: string;
+    data?: unknown;
+    mimeType?: string;
+    mediaType?: string;
+    uri?: string;
+    url?: string;
+    filename?: string;
+    metadata?: Record<string, unknown>;
+}
+interface A2AMessage {
+    role: 'user' | 'agent';
+    messageId?: string;
+    parts: MessagePart[];
+    contextId?: string;
+    taskId?: string;
+    metadata?: Record<string, unknown>;
+    referenceTaskIds?: string[];
+}
+/**
+ * A2A spec SendMessageRequest (the params for message/send and message/stream)
+ */
+interface SendMessageRequest {
+    message: A2AMessage & {
+        role: string;
+    };
+    configuration?: {
+        acceptedOutputModes?: string[];
+        historyLength?: number;
+        blocking?: boolean;
+    };
+    metadata?: Record<string, unknown>;
+}
+type TaskState = 'submitted' | 'working' | 'completed' | 'failed' | 'canceled' | 'input-required' | 'rejected' | 'auth-required';
+/** @deprecated Use TaskState */
+type TaskStatus = TaskState;
+interface TaskStatusObject {
+    state: TaskState;
+    message?: A2AMessage;
+    timestamp?: string;
+}
+interface Task {
+    id: string;
+    contextId?: string;
+    status: TaskStatusObject | TaskState;
+    artifacts?: Artifact[];
+    error?: {
+        message: string;
+    };
+    metadata?: Record<string, unknown>;
+    history?: A2AMessage[];
+}
+interface Artifact {
+    artifactId?: string;
+    name?: string;
+    description?: string;
+    parts: MessagePart[];
+    index?: number;
+    append?: boolean;
+    lastChunk?: boolean;
+    metadata?: Record<string, unknown>;
+}
+interface TaskHistoryEntry {
+    status: TaskStatus;
+    message: string;
+    timestamp: string;
+}
+interface TasksSendParams {
+    skill?: string;
+    message: A2AMessage & {
+        role: string;
+    };
+    contextId?: string;
+    pushNotification?: {
+        url: string;
+        authentication?: {
+            type: 'bearer' | 'api_key';
+            token?: string;
+            headerName?: string;
+        };
+    };
+    metadata?: Record<string, unknown>;
+    configuration?: {
+        acceptedOutputModes?: string[];
+        historyLength?: number;
+        blocking?: boolean;
+    };
+}
+interface TasksGetParams {
+    id?: string;
+    taskId?: string;
+    historyLength?: number;
+    includeHistory?: boolean;
+}
+interface TasksCancelParams {
+    id?: string;
+    taskId?: string;
+    reason?: string;
+    metadata?: Record<string, unknown>;
+}
+interface TaskStatusUpdateEvent {
+    taskId: string;
+    contextId: string;
+    status: TaskStatusObject;
+    metadata?: Record<string, unknown>;
+}
+interface TaskArtifactUpdateEvent {
+    taskId: string;
+    contextId: string;
+    artifact: Artifact;
+    append?: boolean;
+    lastChunk?: boolean;
+    metadata?: Record<string, unknown>;
+}
+interface StreamResponse {
+    task?: Task;
+    message?: A2AMessage;
+    statusUpdate?: TaskStatusUpdateEvent;
+    artifactUpdate?: TaskArtifactUpdateEvent;
+}
+/** @deprecated Use TaskStatusUpdateEvent */
+type TaskStatusEvent = TaskStatusUpdateEvent;
+/** @deprecated Use TaskArtifactUpdateEvent */
+type TaskArtifactEvent = TaskArtifactUpdateEvent;
+interface TaskErrorEvent {
+    taskId: string;
+    error: {
+        code: number;
+        message: string;
+    };
+}
+interface AgentConfig {
+    name: string;
+    description?: string;
+    version?: string;
+    port?: number;
+    host?: string;
+    provider?: {
+        organization: string;
+        url?: string;
+    };
+    skills?: SkillConfig[];
+    defaultInputModes?: Array<'text' | 'file' | 'data'>;
+    defaultOutputModes?: Array<'text' | 'file' | 'data'>;
+    llm?: LLMConfig;
+}
+interface SkillConfig {
+    id: string;
+    name: string;
+    description: string;
+    systemPrompt?: string;
+    inputSchema?: Record<string, unknown>;
+    tags?: string[];
+}
+interface LLMConfig {
+    provider: 'openai' | 'anthropic';
+    model: string;
+    /** Gateway model string (e.g. alibaba/qwen3.5-flash) when using Vercel AI Gateway */
+    gatewayModel?: string;
+    apiKey?: string;
+    temperature?: number;
+    maxOutputTokens?: number;
+}
+interface ExecutorContext {
+    taskId: string;
+    contextId?: string;
+    skill: SkillConfig;
+    message: A2AMessage;
+    metadata?: Record<string, unknown>;
+}
+interface ExecutorResult {
+    text: string;
+    artifacts?: Artifact[];
+}
+interface StreamCallbacks {
+    onChunk: (text: string) => Promise<void>;
+    onComplete: () => Promise<void>;
+    onError: (error: Error) => Promise<void>;
+}
+
+/**
+ * A2A Protocol Server
+ *
+ * Express server implementing the A2A (Agent-to-Agent) protocol v0.3.
+ * Provides agent card discovery and JSON-RPC task execution endpoints.
+ *
+ * Supports both legacy method names (tasks/send, tasks/sendSubscribe) and
+ * spec-compliant names (message/send, message/stream, SendMessage, etc.).
+ */
+
+interface A2AServerOptions {
+    config: AgentConfig;
+    llmConfig?: LLMConfig;
+    echoMode?: boolean;
+}
+interface A2AServer {
+    app: Application;
+    start: () => Promise<void>;
+    stop: () => Promise<void>;
+}
+declare function createA2AServer(options: A2AServerOptions): A2AServer;
+
+/**
+ * A2A Client
+ *
+ * Client for testing A2A protocol endpoints, including Runtype's A2A surfaces.
+ * Supports both legacy (tasks/send) and spec-compliant (message/send) method names.
+ */
+
+interface A2AClientOptions {
+    /** Base URL of the A2A endpoint (with or without /a2a suffix) */
+    baseUrl: string;
+    /** API key for authentication (optional) */
+    apiKey?: string;
+    /** Custom headers to include in requests */
+    headers?: Record<string, string>;
+}
+declare class A2AClient {
+    private baseUrl;
+    private rpcUrl;
+    private agentCardUrl;
+    private apiKey?;
+    private headers;
+    constructor(options: A2AClientOptions);
+    getAgentCard(): Promise<AgentCard>;
+    sendTask(params: TasksSendParams): Promise<Task>;
+    sendTaskStreaming(params: TasksSendParams, callbacks: {
+        onStatus?: (status: string, data: TaskStatusUpdateEvent) => void;
+        onArtifact?: (artifact: Artifact) => void;
+        onError?: (error: JsonRpcError) => void;
+        onChunk?: (text: string) => void;
+    }): Promise<void>;
+    getTask(taskId: string, historyLength?: number): Promise<Task>;
+    cancelTask(taskId: string, reason?: string): Promise<Task>;
+    /**
+     * Convert legacy TasksSendParams to spec SendMessageRequest format
+     */
+    private toSendMessageRequest;
+    private sendJsonRpc;
+    private getHeaders;
+}
+/**
+ * Create a client for testing a Runtype A2A surface
+ */
+declare function createRuntypeA2AClient(options: {
+    productId: string;
+    surfaceId: string;
+    apiKey: string;
+    environment?: 'production' | 'staging' | 'local';
+}): A2AClient;
+
+/**
+ * Agent Executor
+ *
+ * Executes tasks using the Vercel AI SDK for LLM integration.
+ * Supports both streaming and non-streaming responses.
+ */
+
+/**
+ * Execute a task without streaming
+ */
+declare function executeTask(context: ExecutorContext, llmConfig: LLMConfig, skillsCatalog?: SkillConfig[]): Promise<ExecutorResult>;
+/**
+ * Execute a task with streaming
+ */
+declare function executeTaskStreaming(context: ExecutorContext, llmConfig: LLMConfig, callbacks: StreamCallbacks, skillsCatalog?: SkillConfig[]): Promise<void>;
+/**
+ * Simple executor for testing (no LLM, just echoes)
+ */
+declare function executeEcho(context: ExecutorContext): Promise<ExecutorResult>;
+/**
+ * Simple streaming executor for testing
+ */
+declare function executeEchoStreaming(context: ExecutorContext, callbacks: StreamCallbacks): Promise<void>;
+
+/**
+ * Deterministic Time Executor
+ *
+ * Computes temporal data using date-fns and the system clock.
+ * No LLM generation — all results are deterministic.
+ */
+
+declare function executeTimeSkill(context: ExecutorContext): Promise<ExecutorResult>;
+
+/**
+ * Default Skills Configuration
+ *
+ * Shared skill definitions for A2A agents. Import these in your agent
+ * configuration to avoid duplication across different deployment targets.
+ */
+
+/**
+ * Default skills available to A2A agents.
+ * Includes deterministic time tools and LLM-powered skills.
+ */
+declare const DEFAULT_SKILLS: SkillConfig[];
+/**
+ * Default LLM configuration for A2A agents.
+ */
+declare const DEFAULT_LLM_CONFIG: LLMConfig;
+
+export { A2AClient, type A2AClientOptions, type A2AMessage, type A2AServer, type A2AServerOptions, type AgentCard, type AgentConfig, type AgentInterface, type Artifact, DEFAULT_LLM_CONFIG, DEFAULT_SKILLS, type ExecutorContext, type ExecutorResult, JSON_RPC_ERRORS, type JsonRpcError, type JsonRpcRequest, type JsonRpcResponse, type LLMConfig, type MessagePart, type SendMessageRequest, type Skill, type SkillConfig, type StreamCallbacks, type StreamResponse, type Task, type TaskArtifactEvent, type TaskArtifactUpdateEvent, type TaskErrorEvent, type TaskHistoryEntry, type TaskState, type TaskStatus, type TaskStatusEvent, type TaskStatusObject, type TaskStatusUpdateEvent, type TasksCancelParams, type TasksGetParams, type TasksSendParams, createA2AServer, createRuntypeA2AClient, executeEcho, executeEchoStreaming, executeTask, executeTaskStreaming, executeTimeSkill };

package/dist/index.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import {
+  A2AClient,
+  DEFAULT_LLM_CONFIG,
+  DEFAULT_SKILLS,
+  JSON_RPC_ERRORS,
+  createA2AServer,
+  createRuntypeA2AClient,
+  executeEcho,
+  executeEchoStreaming,
+  executeTask,
+  executeTaskStreaming,
+  executeTimeSkill
+} from "./chunk-KIZQKOZR.js";
+export {
+  A2AClient,
+  DEFAULT_LLM_CONFIG,
+  DEFAULT_SKILLS,
+  JSON_RPC_ERRORS,
+  createA2AServer,
+  createRuntypeA2AClient,
+  executeEcho,
+  executeEchoStreaming,
+  executeTask,
+  executeTaskStreaming,
+  executeTimeSkill
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/vercel/index.d.ts

@@ -0,0 +1,149 @@
+interface Skill {
+    id: string;
+    name: string;
+    description: string;
+    inputModes?: string[];
+    outputModes?: string[];
+    tags: string[];
+    examples?: string[];
+    inputSchema?: Record<string, unknown>;
+}
+interface SkillConfig {
+    id: string;
+    name: string;
+    description: string;
+    systemPrompt?: string;
+    inputSchema?: Record<string, unknown>;
+    tags?: string[];
+}
+interface LLMConfig {
+    provider: 'openai' | 'anthropic';
+    model: string;
+    /** Gateway model string (e.g. alibaba/qwen3.5-flash) when using Vercel AI Gateway */
+    gatewayModel?: string;
+    apiKey?: string;
+    temperature?: number;
+    maxOutputTokens?: number;
+}
+
+/**
+ * Default Skills Configuration
+ *
+ * Shared skill definitions for A2A agents. Import these in your agent
+ * configuration to avoid duplication across different deployment targets.
+ */
+
+/**
+ * Default skills available to A2A agents.
+ * Includes deterministic time tools and LLM-powered skills.
+ */
+declare const DEFAULT_SKILLS: SkillConfig[];
+/**
+ * Default LLM configuration for A2A agents.
+ */
+declare const DEFAULT_LLM_CONFIG: LLMConfig;
+
+/**
+ * Vercel A2A Configuration
+ *
+ * Configuration types and helpers for deploying A2A agents to Vercel.
+ */
+
+interface VercelA2AConfig {
+    /** Agent name displayed in the agent card */
+    name: string;
+    /** Agent description */
+    description?: string;
+    /** Agent version (default: "1.0.0") */
+    version?: string;
+    /** Custom skills (defaults to time/*, chat, echo) */
+    skills?: SkillConfig[];
+    /** Provider information */
+    provider?: {
+        organization: string;
+        url?: string;
+    };
+    /** URL where the agent is deployed (for agent card) */
+    agentUrl?: string;
+    /** Default input modes for agent card (MIME types) */
+    defaultInputModes?: string[];
+    /** Default output modes for agent card (MIME types) */
+    defaultOutputModes?: string[];
+    /** Run in echo mode (no LLM, for testing) */
+    echoMode?: boolean;
+    /** LLM configuration (required unless echoMode is true) */
+    llmConfig?: LLMConfig;
+}
+/**
+ * Resolve configuration with defaults
+ */
+declare function resolveConfig(config: VercelA2AConfig): Required<Pick<VercelA2AConfig, 'name' | 'description' | 'version' | 'skills' | 'echoMode' | 'defaultInputModes' | 'defaultOutputModes'>> & {
+    provider: {
+        organization: string;
+        url?: string;
+    };
+    llmConfig: LLMConfig;
+    agentUrl?: string;
+};
+/**
+ * Convert SkillConfig to A2A Skill format for agent card
+ */
+declare function toAgentCardSkills(skills: SkillConfig[]): Skill[];
+
+/**
+ * Vercel A2A Request Handlers
+ *
+ * Stateless request handlers for Vercel serverless/edge functions.
+ * These handlers implement the A2A protocol v0.3 using Web standard Request/Response APIs.
+ */
+
+/**
+ * Create a handler for the agent card endpoint (GET /.well-known/agent.json)
+ *
+ * @example
+ * ```typescript
+ * // app/.well-known/agent.json/route.ts (Next.js App Router)
+ * import { createAgentCardHandler } from '@runtypelabs/timely-a2a/vercel'
+ *
+ * export const GET = createAgentCardHandler({
+ *   name: 'My Agent',
+ *   echoMode: true,
+ * })
+ * ```
+ */
+declare function createAgentCardHandler(config: VercelA2AConfig): (_request: Request) => Promise<Response>;
+/**
+ * Create a handler for the A2A JSON-RPC endpoint (POST /api/a2a)
+ *
+ * Gateway models (provider/model format like 'alibaba/qwen3.5-flash') require
+ * AI_GATEWAY_API_KEY to be set in the environment.
+ *
+ * @example
+ * ```typescript
+ * // app/api/a2a/route.ts (Next.js App Router)
+ * import { createA2AHandler } from '@runtypelabs/timely-a2a/vercel'
+ *
+ * export const POST = createA2AHandler({
+ *   name: 'My Agent',
+ *   llmConfig: { provider: 'openai', model: 'alibaba/qwen3.5-flash' },
+ * })
+ * ```
+ */
+declare function createA2AHandler(config: VercelA2AConfig): (request: Request) => Promise<Response>;
+/**
+ * Create both handlers with shared configuration
+ *
+ * @example
+ * ```typescript
+ * const { agentCardHandler, a2aHandler } = createHandlers({
+ *   name: 'My Agent',
+ *   echoMode: true,
+ * })
+ * ```
+ */
+declare function createHandlers(config: VercelA2AConfig): {
+    agentCardHandler: (_request: Request) => Promise<Response>;
+    a2aHandler: (request: Request) => Promise<Response>;
+};
+
+export { DEFAULT_LLM_CONFIG, DEFAULT_SKILLS, type VercelA2AConfig, createA2AHandler, createAgentCardHandler, createHandlers, resolveConfig, toAgentCardSkills };