@moltium/core 0.1.19 → 0.1.21

package/README.md

@@ -18,6 +18,7 @@ npm install @moltium/core
 - **Social adapters** for Moltbook and Twitter
 - **Action system** with built-in actions, custom actions, and markdown-interpreted skills
 - **HTTP server** (Express) with REST endpoints for monitoring and control
+- **A2A Protocol support** for agent-to-agent communication (JSON-RPC, HTTP+JSON/REST)
 - **Config loader** supporting both TypeScript and Markdown configurations
 
 ## Quick Start
@@ -60,6 +61,13 @@ const agent = new Agent(config);
 startServer(agent, { port: 3000 });
 ```
 
+The agent automatically exposes **A2A Protocol endpoints** for agent-to-agent communication:
+- `/.well-known/agent-card.json` - Agent discovery
+- `/a2a/jsonrpc` - JSON-RPC transport
+- `/a2a/rest` - HTTP+JSON/REST transport (v0.3.0)
+
+To enable A2A communication actions, add an `a2a` configuration section (see A2A Protocol Integration below).
+
 ## Agent Lifecycle
 
 Agents follow a strict lifecycle: `idle` -> `initializing` -> `running` -> `stopping` -> `stopped`.
@@ -286,6 +294,220 @@ const { config, type } = await loader.load('./my-agent');
 // type is 'code' or 'markdown'
 ```
 
+## A2A Protocol Integration
+
+Moltium includes full support for the [A2A Protocol](https://a2a.ai/) v0.3.0, enabling seamless agent-to-agent communication with automatic action registration and zero boilerplate.
+
+### Quick Start
+
+Add the `a2a` config section to automatically register communication actions:
+
+```typescript
+export default {
+  name: 'My Agent',
+  // ... other config
+
+  a2a: {
+    enabled: true,
+    defaultPeerUrl: 'http://localhost:3001', // Optional default peer
+    verbose: true, // Enable detailed logging
+  },
+
+  actions: [
+    'talk_to_agent', // Automatically registered when a2a is enabled
+  ],
+} satisfies AgentConfig;
+```
+
+Configure your server with A2A support:
+
+```typescript
+const port = parseInt(process.env.PORT || '3000', 10);
+
+startServer(agent, {
+  port,
+  enableA2A: true,
+  a2aConfig: {
+    enabled: true,
+    baseUrl: `http://0.0.0.0:${port}`,
+  },
+});
+```
+
+Your agent now exposes:
+- Agent Card at `/.well-known/agent-card.json`
+- JSON-RPC endpoint at `/a2a/jsonrpc`
+- Auto-registered `talk_to_agent` action
+
+### Multiple Peer Agents
+
+Define specific peer agents for targeted communication:
+
+```typescript
+a2a: {
+  enabled: true,
+  peers: {
+    talk_to_analyst: 'http://localhost:3001',
+    talk_to_researcher: 'http://localhost:3002',
+    talk_to_trader: 'http://localhost:3003',
+  },
+  verbose: false,
+},
+
+actions: [
+  'talk_to_analyst',   // Auto-registered with pre-configured URL
+  'talk_to_researcher', // Auto-registered
+  'talk_to_trader',    // Auto-registered
+],
+```
+
+### Programmatic A2A Client
+
+For custom actions or advanced use cases:
+
+```typescript
+import { createA2AClient, A2AClient } from '@moltium/core';
+
+// Simple usage
+const client = createA2AClient('http://localhost:3001');
+const response = await client.sendMessage({
+  text: 'What are your thoughts on this strategy?',
+});
+
+if (response.success) {
+  console.log('Reply:', response.reply);
+}
+
+// Advanced usage
+const client = new A2AClient({
+  agentUrl: 'http://localhost:3001',
+  agentCardPath: '.well-known/agent-card.json',
+  timeout: 30000,
+});
+
+const response = await client.sendMessage({
+  text: 'Analyze this data',
+  contextId: 'analysis-session-123',
+  metadata: { priority: 'high' },
+});
+```
+
+### Custom A2A Actions
+
+Use action builders for maximum flexibility:
+
+```typescript
+import { createA2ACommunicationAction, createMultipleA2AActions } from '@moltium/core';
+
+// Single action
+const talkToAnalyst = createA2ACommunicationAction({
+  actionName: 'consult_analyst',
+  defaultAgentUrl: 'http://localhost:3001',
+  description: 'Consult with the business analyst for strategic advice',
+  verbose: true,
+});
+
+// Multiple actions at once
+const a2aActions = createMultipleA2AActions({
+  ask_technical: {
+    defaultAgentUrl: 'http://localhost:3001',
+    description: 'Ask technical engineering questions',
+  },
+  ask_business: {
+    defaultAgentUrl: 'http://localhost:3002',
+    description: 'Ask business strategy questions',
+  },
+});
+
+export default {
+  customActions: [...a2aActions, talkToAnalyst],
+  actions: ['ask_technical', 'ask_business', 'consult_analyst'],
+};
+```
+
+### A2A API Reference
+
+#### `A2AClient`
+
+```typescript
+class A2AClient {
+  constructor(config: A2AClientConfig)
+  sendMessage(options: A2AMessageOptions): Promise<A2AMessageResponse>
+  getAgentCard(): Promise<AgentCard>
+  getAgentUrl(): string
+}
+
+interface A2AClientConfig {
+  agentUrl: string;
+  agentCardPath?: string;  // Default: .well-known/agent-card.json
+  timeout?: number;        // Default: 30000ms
+}
+
+interface A2AMessageOptions {
+  text: string;
+  contextId?: string;
+  metadata?: Record<string, unknown>;
+}
+
+interface A2AMessageResponse {
+  success: boolean;
+  reply?: string;
+  agentUrl?: string;
+  error?: string;
+  raw?: any;
+}
+```
+
+#### Action Builders
+
+```typescript
+// Single action builder
+function createA2ACommunicationAction(config: {
+  defaultAgentUrl?: string;
+  actionName?: string;      // Default: 'talk_to_agent'
+  description?: string;
+  verbose?: boolean;
+}): Action
+
+// Multiple actions builder
+function createMultipleA2AActions(
+  configs: Record<string, A2ACommunicationActionConfig>
+): Action[]
+```
+
+### Best Practices
+
+**Use environment variables for URLs:**
+```typescript
+a2a: {
+  peers: {
+    talk_to_analyst: process.env.ANALYST_URL || 'http://localhost:3001',
+  },
+},
+```
+
+**Enable verbose logging during development:**
+```typescript
+a2a: {
+  verbose: true, // Detailed A2A logs
+},
+```
+
+**Use 0.0.0.0 for local development:**
+```typescript
+a2aConfig: {
+  baseUrl: `http://0.0.0.0:${port}`, // Accessible from other agents
+},
+```
+
+**Handle errors gracefully:**
+```typescript
+const response = await client.sendMessage({ text: 'Hello' });
+if (!response.success) {
+  console.error('Communication failed:', response.error);
+}
+```
+
 ## AgentConfig Reference
 
 ```typescript
@@ -329,6 +551,15 @@ interface AgentConfig {
   actions: string[];                // Built-in action names
   customActions?: Action[];         // User-defined actions
   plugins?: Plugin[];
+  
+  // A2A Protocol configuration (optional)
+  a2a?: {
+    enabled?: boolean;              // Enable A2A support
+    peers?: Record<string, string>; // Peer agents: { actionName: 'url' }
+    defaultPeerUrl?: string;        // Default peer URL
+    verbose?: boolean;              // Enable detailed logging
+    genericActionName?: string;     // Custom name for generic action
+  };
 }
 ```
 

package/dist/index.d.cts

@@ -1,5 +1,7 @@
 import * as express_serve_static_core from 'express-serve-static-core';
-import { Router } from 'express';
+import { AgentCard } from '@a2a-js/sdk';
+import { RequestHandler, Router } from 'express';
+import { AgentExecutor, RequestContext, ExecutionEventBus } from '@a2a-js/sdk/server';
 import winston from 'winston';
 
 interface MoltbookConfig {
@@ -82,6 +84,35 @@ interface AgentConfig {
         systemPrompt?: string;
     };
     social: SocialConfig;
+    /**
+     * A2A Protocol Configuration
+     * When enabled, automatically registers A2A communication actions
+     * @optional
+     */
+    a2a?: {
+        /**
+         * Enable A2A protocol support (defaults to true when a2a config exists)
+         */
+        enabled?: boolean;
+        /**
+         * Peer agents this agent can communicate with
+         * Key is the action name, value is the agent URL
+         * @example { talk_to_analyst: 'http://localhost:3001' }
+         */
+        peers?: Record<string, string>;
+        /**
+         * Default peer agent URL (used when peers not specified)
+         */
+        defaultPeerUrl?: string;
+        /**
+         * Enable verbose A2A logging
+         */
+        verbose?: boolean;
+        /**
+         * Custom action name for generic A2A communication (defaults to 'talk_to_agent')
+         */
+        genericActionName?: string;
+    };
     behaviors: {
         autonomous: boolean;
         decisionMaking: 'llm-driven' | 'rule-based' | 'hybrid';
@@ -102,6 +133,15 @@ interface AgentConfig {
     actions: string[];
     customActions?: Action[];
     scheduling?: ScheduledTask[];
+    /** World SDK integration — connect this agent to a world */
+    world?: {
+        /** URL of the world to join */
+        url: string;
+        /** Wallet address for blockchain-enabled worlds */
+        walletAddress?: string;
+        /** Auto-join the world when agent starts (default: true) */
+        autoJoin?: boolean;
+    };
     webhooks?: {
         onAction?: string | ((action: any, result: any) => Promise<void>);
         onError?: string;
@@ -507,6 +547,7 @@ declare class Agent {
     private scheduledPost;
     private executeScheduledTask;
     private logPlatformError;
+    private autoJoinWorld;
     private startAutonomousLoop;
     private isSleeping;
     private gatherContext;
@@ -554,6 +595,7 @@ declare class MarkdownParser {
     private parseSocial;
     private parseBehaviors;
     private parseMemory;
+    private parseWorld;
     private parseSleepSchedule;
     private parseKeyValueLines;
     private parseScheduling;
@@ -737,17 +779,302 @@ declare function createMarkdownAction(name: string, description: string, llmProv
 /** All Moltbook-specific actions */
 declare const moltbookActions: Action[];
 
+/**
+ * ============================================================================
+ * WORLD SDK BUILT-IN ACTIONS
+ * ============================================================================
+ *
+ * Built-in actions for agents to interact with worlds created using
+ * @moltium/world-core. These use plain HTTP to call the world's REST endpoints.
+ */
+/**
+ * Creates a join_world action that POSTs to a world's /world/join endpoint
+ */
+declare function createJoinWorldAction(config?: {
+    defaultWorldUrl?: string;
+}): Action;
+/**
+ * Creates a leave_world action that DELETEs from a world's /world/agents endpoint
+ */
+declare function createLeaveWorldAction(config?: {
+    defaultWorldUrl?: string;
+}): Action;
+/**
+ * Creates a query_world action that GETs world state and info
+ */
+declare function createQueryWorldAction(config?: {
+    defaultWorldUrl?: string;
+}): Action;
+/**
+ * Creates a send_world_message action for agent-to-agent messaging through a world
+ */
+declare function createSendWorldMessageAction(config?: {
+    defaultWorldUrl?: string;
+}): Action;
+/**
+ * All world actions as a convenience array
+ */
+declare const worldActions: {
+    createJoinWorldAction: typeof createJoinWorldAction;
+    createLeaveWorldAction: typeof createLeaveWorldAction;
+    createQueryWorldAction: typeof createQueryWorldAction;
+    createSendWorldMessageAction: typeof createSendWorldMessageAction;
+};
+
 declare const builtInActions: Action[];
 
+interface A2AConfig {
+    enabled: boolean;
+    baseUrl: string;
+    port?: number;
+    pushNotifications?: boolean;
+    streaming?: boolean;
+    stateTransitionHistory?: boolean;
+}
+/**
+ * Builds an A2A-compliant AgentCard from a Moltium AgentConfig.
+ */
+declare class AgentCardBuilder {
+    /**
+     * Creates an A2A AgentCard from Moltium configuration.
+     * @param config The Moltium agent configuration
+     * @param a2aConfig A2A-specific configuration (URLs, capabilities)
+     * @returns A2A-compliant AgentCard
+     */
+    static build(config: AgentConfig, a2aConfig: A2AConfig): AgentCard;
+    /**
+     * Converts Moltium actions to A2A skills.
+     */
+    private static buildSkills;
+    /**
+     * Updates an agent card with runtime information.
+     */
+    static updateWithRuntime(agentCard: AgentCard, actualPort: number, actualHost?: string): AgentCard;
+}
+
+/**
+ * Adapts a Moltium Agent to the A2A AgentExecutor interface.
+ * This allows Moltium agents to respond to A2A protocol requests.
+ */
+declare class MoltiumExecutor implements AgentExecutor {
+    private agent;
+    private cancelledTasks;
+    constructor(agent: Agent);
+    /**
+     * Executes an A2A request using the Moltium agent.
+     * Converts A2A messages to Moltium actions and publishes results back via the event bus.
+     */
+    execute(requestContext: RequestContext, eventBus: ExecutionEventBus): Promise<void>;
+    /**
+     * Handles task cancellation requests.
+     */
+    cancelTask(taskId: string, eventBus: ExecutionEventBus): Promise<void>;
+    /**
+     * Extracts text content from an A2A message.
+     */
+    private extractMessageContent;
+    /**
+     * Determines if the user message is requesting a specific action.
+     */
+    private isActionRequest;
+    /**
+     * Executes a chat interaction using the agent's LLM.
+     */
+    private executeChat;
+    /**
+     * Executes an action based on the user's request.
+     */
+    private executeAction;
+    /**
+     * Publishes a successful result as an A2A artifact.
+     */
+    private publishResult;
+    /**
+     * Publishes an error as an A2A artifact.
+     */
+    private publishError;
+    /**
+     * Publishes a status update event.
+     */
+    private publishStatusUpdate;
+    /**
+     * Publishes a cancellation status.
+     */
+    private publishCancellation;
+}
+
+interface A2AServerOptions {
+    a2aConfig: A2AConfig;
+    authToken?: string;
+}
+/**
+ * Creates A2A-compliant Express routes for a Moltium agent.
+ * These routes implement the Agent-to-Agent (A2A) protocol.
+ */
+declare class A2AIntegration {
+    private agent;
+    private agentCard;
+    private requestHandler;
+    private moltiumExecutor;
+    constructor(agent: Agent, options: A2AServerOptions);
+    /**
+     * Creates Express middleware handlers for A2A endpoints.
+     * Returns an object with individual handlers that can be mounted on specific routes.
+     */
+    getHandlers(): {
+        agentCard: RequestHandler;
+        jsonRpc: RequestHandler;
+        rest: RequestHandler;
+    };
+    /**
+     * Updates the agent card with actual runtime information (host/port).
+     */
+    updateAgentCard(actualPort: number, actualHost?: string): void;
+    /**
+     * Gets the current agent card.
+     */
+    getAgentCard(): AgentCard;
+    /**
+     * Logs A2A endpoint information.
+     */
+    logEndpoints(host: string, port: number): void;
+}
+/**
+ * Helper function to create and configure A2A integration for a Moltium agent.
+ */
+declare function createA2AIntegration(agent: Agent, options?: Partial<A2AServerOptions>): A2AIntegration;
+
+/**
+ * Configuration for A2A client operations
+ */
+interface A2AClientConfig {
+    /**
+     * The base URL of the target agent
+     * @example 'http://localhost:3001'
+     */
+    agentUrl: string;
+    /**
+     * Path to the agent card (defaults to '.well-known/agent-card.json')
+     */
+    agentCardPath?: string;
+    /**
+     * Timeout for requests in milliseconds (optional)
+     */
+    timeout?: number;
+}
+/**
+ * Options for sending messages via A2A
+ */
+interface A2AMessageOptions {
+    /**
+     * The text message to send
+     */
+    text: string;
+    /**
+     * Optional context ID to group related messages
+     */
+    contextId?: string;
+    /**
+     * Optional metadata for extensions
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Response from an A2A message
+ */
+interface A2AMessageResponse {
+    /**
+     * Whether the message was successfully sent and received
+     */
+    success: boolean;
+    /**
+     * The reply text from the agent (if successful)
+     */
+    reply?: string;
+    /**
+     * The agent URL that responded
+     */
+    agentUrl?: string;
+    /**
+     * Error message (if failed)
+     */
+    error?: string;
+    /**
+     * Raw response from the A2A protocol (for advanced use)
+     */
+    raw?: any;
+}
+/**
+ * Wrapper around A2A Client SDK with improved developer experience
+ *
+ * @example
+ * ```typescript
+ * const client = new A2AClient({ agentUrl: 'http://localhost:3001' });
+ * const response = await client.sendMessage({ text: 'Hello!' });
+ * console.log(response.reply);
+ * ```
+ */
+declare class A2AClient {
+    private sdkClient;
+    private config;
+    constructor(config: A2AClientConfig);
+    /**
+     * Send a text message to the agent and get a response
+     *
+     * @param options Message options including text content
+     * @returns Promise resolving to the agent's response
+     *
+     * @example
+     * ```typescript
+     * const response = await client.sendMessage({
+     *   text: 'What are your thoughts on AI?',
+     *   contextId: 'conversation-123'
+     * });
+     *
+     * if (response.success) {
+     *   console.log('Agent replied:', response.reply);
+     * }
+     * ```
+     */
+    sendMessage(options: A2AMessageOptions): Promise<A2AMessageResponse>;
+    /**
+     * Extract text reply from A2A protocol response
+     * Handles both Message and Task response types
+     */
+    private extractReply;
+    /**
+     * Get the agent card information
+     *
+     * @returns Promise resolving to the agent card
+     */
+    getAgentCard(): Promise<any>;
+    /**
+     * Get the base URL of the agent
+     */
+    getAgentUrl(): string;
+}
+/**
+ * Factory function to create A2A clients easily
+ *
+ * @example
+ * ```typescript
+ * const client = createA2AClient('http://localhost:3001');
+ * const response = await client.sendMessage({ text: 'Hello!' });
+ * ```
+ */
+declare function createA2AClient(agentUrlOrConfig: string | A2AClientConfig): A2AClient;
+
 interface ServerOptions {
     port?: number;
     host?: string;
+    enableA2A?: boolean;
+    a2aConfig?: A2AServerOptions['a2aConfig'];
 }
-declare function createApp(agent: Agent): express_serve_static_core.Express;
+declare function createApp(agent: Agent, options?: ServerOptions): express_serve_static_core.Express;
 declare function startServer(agent: Agent, options?: ServerOptions): Promise<void>;
 
 declare function createRoutes(agent: Agent): Router;
 
 declare function createLogger(label: string): winston.Logger;
 
-export { type Action, type ActionContext, ActionHandler, ActionRegistry, type ActionResult, Agent, type AgentConfig, type AgentState, AnthropicProvider, type BehaviorTrigger, type Comment, ConfigLoader, type ConfigType, type Conversation, type ConversationDetail, type CustomAPIConfig, type CustomCLIConfig, type CustomDeploymentConfig, type CustomDockerConfig, type CustomSSHConfig, type DMCheckResult, type DMRequest, type Decision, type DeploymentConfig, type DeploymentResult, type DeploymentStatus, type DirectMessage, type Experience, type FeedOptions, type GenerateOptions, LLMProvider, type LifecycleEvent, type LifecycleHooks, LongTermMemory, MarkdownParser, Memory, type Mention, type Message, MoltbookAdapter, type MoltbookConfig, type MoltbookRegistration, type MoltbookStatus, OpenAIProvider, type Plugin, type Post, type PostResult, type PostgresConfig, type Profile, type RedisConfig, type ReplyResult, type ScheduledJob, type ScheduledTask, Scheduler, type SearchOptions, type SearchResult, ShortTermMemory, SocialAdapter, type SocialConfig, type SocialPlatformConfig, type StructuredSchema, type Submolt, type SubmoltSettings, type TimelineOptions, TwitterAdapter, type TwitterConfig, buildDecisionPrompt, buildSkillPrompt, buildSystemPrompt, builtInActions, createApp, createLogger, createMarkdownAction, createRoutes, moltbookActions, startServer, validateConfig };
+export { A2AClient, type A2AClientConfig, type A2AConfig, A2AIntegration, type A2AMessageOptions, type A2AMessageResponse, type A2AServerOptions, type Action, type ActionContext, ActionHandler, ActionRegistry, type ActionResult, Agent, AgentCardBuilder, type AgentConfig, type AgentState, AnthropicProvider, type BehaviorTrigger, type Comment, ConfigLoader, type ConfigType, type Conversation, type ConversationDetail, type CustomAPIConfig, type CustomCLIConfig, type CustomDeploymentConfig, type CustomDockerConfig, type CustomSSHConfig, type DMCheckResult, type DMRequest, type Decision, type DeploymentConfig, type DeploymentResult, type DeploymentStatus, type DirectMessage, type Experience, type FeedOptions, type GenerateOptions, LLMProvider, type LifecycleEvent, type LifecycleHooks, LongTermMemory, MarkdownParser, Memory, type Mention, type Message, MoltbookAdapter, type MoltbookConfig, type MoltbookRegistration, type MoltbookStatus, MoltiumExecutor, OpenAIProvider, type Plugin, type Post, type PostResult, type PostgresConfig, type Profile, type RedisConfig, type ReplyResult, type ScheduledJob, type ScheduledTask, Scheduler, type SearchOptions, type SearchResult, type ServerOptions, ShortTermMemory, SocialAdapter, type SocialConfig, type SocialPlatformConfig, type StructuredSchema, type Submolt, type SubmoltSettings, type TimelineOptions, TwitterAdapter, type TwitterConfig, buildDecisionPrompt, buildSkillPrompt, buildSystemPrompt, builtInActions, createA2AClient, createA2AIntegration, createApp, createJoinWorldAction, createLeaveWorldAction, createLogger, createMarkdownAction, createQueryWorldAction, createRoutes, createSendWorldMessageAction, moltbookActions, startServer, validateConfig, worldActions };