@moltium/world-core 0.1.18 → 0.1.20

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 import { AgentCard } from '@a2a-js/sdk';
 import { z } from 'zod';
 import winston from 'winston';
+import { A2AMessageResponse } from '@moltium/core';
 import { Express } from 'express';
 
 /**
@@ -47,6 +48,34 @@ interface WorldConfig {
     rules?: WorldRule[];
     /** Pre-configured agent URLs to discover on startup */
     agentUrls?: string[];
+    /** World-defined actions that agents can execute */
+    actions?: WorldAction$1[];
+    /** Tick orchestration configuration */
+    orchestration?: {
+        /** Whether to broadcast tick context to agents (default: true) */
+        broadcastOnTick?: boolean;
+        /** Timeout for agent responses in ms (default: 10000) */
+        tickTimeout?: number;
+        /** Custom prompt template for tick broadcasts */
+        promptTemplate?: string;
+    };
+}
+/**
+ * ============================================================================
+ * WORLD ACTIONS
+ * ============================================================================
+ */
+interface WorldAction$1 {
+    /** Action name (unique identifier) */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** Parameter definitions */
+    parameters?: Record<string, {
+        type: 'string' | 'number' | 'boolean' | 'object';
+        required?: boolean;
+        description?: string;
+    }>;
 }
 /**
  * ============================================================================
@@ -774,6 +803,52 @@ declare const WorldConfigSchema: z.ZodObject<{
     }>>;
     rules: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
     agentUrls: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            type: z.ZodEnum<["string", "number", "boolean", "object"]>;
+            required: z.ZodOptional<z.ZodBoolean>;
+            description: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            type: "string" | "number" | "boolean" | "object";
+            description?: string | undefined;
+            required?: boolean | undefined;
+        }, {
+            type: "string" | "number" | "boolean" | "object";
+            description?: string | undefined;
+            required?: boolean | undefined;
+        }>>>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        description: string;
+        parameters?: Record<string, {
+            type: "string" | "number" | "boolean" | "object";
+            description?: string | undefined;
+            required?: boolean | undefined;
+        }> | undefined;
+    }, {
+        name: string;
+        description: string;
+        parameters?: Record<string, {
+            type: "string" | "number" | "boolean" | "object";
+            description?: string | undefined;
+            required?: boolean | undefined;
+        }> | undefined;
+    }>, "many">>;
+    orchestration: z.ZodOptional<z.ZodObject<{
+        broadcastOnTick: z.ZodOptional<z.ZodBoolean>;
+        tickTimeout: z.ZodOptional<z.ZodNumber>;
+        promptTemplate: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        broadcastOnTick?: boolean | undefined;
+        tickTimeout?: number | undefined;
+        promptTemplate?: string | undefined;
+    }, {
+        broadcastOnTick?: boolean | undefined;
+        tickTimeout?: number | undefined;
+        promptTemplate?: string | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     name: string;
     server: {
@@ -852,6 +927,20 @@ declare const WorldConfigSchema: z.ZodObject<{
     } | undefined;
     rules?: any[] | undefined;
     agentUrls?: string[] | undefined;
+    actions?: {
+        name: string;
+        description: string;
+        parameters?: Record<string, {
+            type: "string" | "number" | "boolean" | "object";
+            description?: string | undefined;
+            required?: boolean | undefined;
+        }> | undefined;
+    }[] | undefined;
+    orchestration?: {
+        broadcastOnTick?: boolean | undefined;
+        tickTimeout?: number | undefined;
+        promptTemplate?: string | undefined;
+    } | undefined;
 }, {
     name: string;
     server: {
@@ -930,6 +1019,20 @@ declare const WorldConfigSchema: z.ZodObject<{
     } | undefined;
     rules?: any[] | undefined;
     agentUrls?: string[] | undefined;
+    actions?: {
+        name: string;
+        description: string;
+        parameters?: Record<string, {
+            type: "string" | "number" | "boolean" | "object";
+            description?: string | undefined;
+            required?: boolean | undefined;
+        }> | undefined;
+    }[] | undefined;
+    orchestration?: {
+        broadcastOnTick?: boolean | undefined;
+        tickTimeout?: number | undefined;
+        promptTemplate?: string | undefined;
+    } | undefined;
 }>;
 /**
  * Validate world configuration
@@ -1054,6 +1157,138 @@ declare const logger: winston.Logger;
  */
 declare function createLogger(moduleName: string): winston.Logger;
 
+/**
+ * ============================================================================
+ * WORLD ACTION DEFINITIONS
+ * ============================================================================
+ *
+ * Worlds define what actions agents can take. These are sent as context
+ * during tick broadcasts so agents know their available options.
+ */
+interface WorldAction {
+    /** Action name (unique identifier) */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** Parameter definitions */
+    parameters?: Record<string, WorldActionParam>;
+}
+interface WorldActionParam {
+    type: 'string' | 'number' | 'boolean' | 'object';
+    required?: boolean;
+    description?: string;
+}
+/**
+ * Registry for world-defined actions.
+ * Agents receive the registered actions as available options during tick broadcasts.
+ */
+declare class WorldActionsRegistry {
+    private actions;
+    /**
+     * Register a world action
+     */
+    register(action: WorldAction): void;
+    /**
+     * Register multiple actions at once
+     */
+    registerAll(actions: WorldAction[]): void;
+    /**
+     * Get all registered actions
+     */
+    getAll(): WorldAction[];
+    /**
+     * Get a specific action by name
+     */
+    get(name: string): WorldAction | undefined;
+    /**
+     * Check if an action exists
+     */
+    has(name: string): boolean;
+    /**
+     * Validate an action name and its parameters
+     */
+    validate(actionName: string, params: Record<string, any>): {
+        valid: boolean;
+        error?: string;
+    };
+    /**
+     * Get action names as a simple list (for tick context)
+     */
+    getActionNames(): string[];
+    /**
+     * Get actions as a serializable summary (for tick context)
+     */
+    toSummary(): Array<{
+        name: string;
+        description: string;
+        parameters?: Record<string, WorldActionParam>;
+    }>;
+}
+
+/**
+ * ============================================================================
+ * WORLD A2A CLIENT
+ * ============================================================================
+ *
+ * Manages a pool of A2A clients for all admitted agents.
+ * Used by the TickOrchestrator to broadcast tick context and collect responses,
+ * and by the MessageRouter for agent-to-agent communication.
+ */
+declare class WorldA2AClient {
+    private clients;
+    /**
+     * Add an agent to the client pool
+     */
+    addAgent(agentUrl: string): void;
+    /**
+     * Remove an agent from the client pool
+     */
+    removeAgent(agentUrl: string): void;
+    /**
+     * Send an A2A message to a specific agent
+     */
+    sendToAgent(agentUrl: string, message: string, metadata?: Record<string, unknown>): Promise<A2AMessageResponse>;
+    /**
+     * Broadcast an A2A message to all agents in the pool
+     */
+    broadcastToAll(message: string, metadata?: Record<string, unknown>): Promise<Map<string, A2AMessageResponse>>;
+    /**
+     * Get the number of agents in the pool
+     */
+    get size(): number;
+    /**
+     * Check if an agent is in the pool
+     */
+    has(agentUrl: string): boolean;
+    /**
+     * Get all agent URLs in the pool
+     */
+    getAgentUrls(): string[];
+}
+
+/**
+ * ============================================================================
+ * MESSAGE ROUTER
+ * ============================================================================
+ *
+ * Routes agent-to-agent messages through the world hub.
+ * Agents send messages to the world's /world/message endpoint,
+ * and the router forwards them to the target agent(s) via A2A.
+ */
+declare class MessageRouter {
+    private a2aClient;
+    private getAgents;
+    constructor(a2aClient: WorldA2AClient, getAgents: () => AgentProfile[]);
+    /**
+     * Route a message from one agent to another
+     */
+    route(fromAgentUrl: string, toAgentUrl: string, message: string): Promise<A2AMessageResponse>;
+    /**
+     * Broadcast a message from one agent to all other agents in the world
+     */
+    routeToAll(fromAgentUrl: string, message: string): Promise<Map<string, A2AMessageResponse>>;
+}
+
 /**
  * ============================================================================
  * WORLD ENGINE
@@ -1076,6 +1311,10 @@ declare class World {
     private evaluator;
     private tickInterval;
     private autoSaveInterval;
+    private a2aClient;
+    private actionsRegistry;
+    private orchestrator;
+    private messageRouter;
     constructor(config: WorldConfig);
     /**
      * Initialize the world (connect persistence, restore state, discover agents)
@@ -1105,6 +1344,14 @@ declare class World {
      * Get current world state
      */
     getState(): WorldStateSnapshot;
+    /**
+     * Get the message router (for agent-to-agent communication via server)
+     */
+    getMessageRouter(): MessageRouter;
+    /**
+     * Get the actions registry
+     */
+    getActionsRegistry(): WorldActionsRegistry;
     /**
      * Log an event
      */
@@ -1262,6 +1509,103 @@ declare class BlockchainClient {
     getEntryFee(): Promise<string>;
 }
 
+/**
+ * ============================================================================
+ * ACTION PROCESSOR
+ * ============================================================================
+ *
+ * Validates agent tick responses against world rules before applying.
+ * Ensures agents only execute valid, permitted actions.
+ */
+interface AgentTickResponse {
+    agentUrl: string;
+    action?: string;
+    parameters?: Record<string, any>;
+    message?: string;
+    error?: string;
+}
+interface ProcessResult {
+    accepted: boolean;
+    violations: RuleViolation[];
+    stateUpdates?: Record<string, any>;
+    events?: WorldEvent[];
+}
+declare class ActionProcessor {
+    private rules;
+    private actionsRegistry;
+    constructor(rules: WorldRule[], actionsRegistry: WorldActionsRegistry);
+    /**
+     * Process an agent's tick response: validate action and check rules
+     */
+    process(response: AgentTickResponse, agent: AgentProfile, worldContext: {
+        phase: WorldPhase;
+        tick: number;
+        agents: Map<string, AgentProfile>;
+    }): Promise<ProcessResult>;
+    /**
+     * Update the rules list
+     */
+    setRules(rules: WorldRule[]): void;
+}
+
+/**
+ * ============================================================================
+ * TICK ORCHESTRATOR
+ * ============================================================================
+ *
+ * Orchestrates the world tick loop:
+ * 1. Build tick context (state, actions, agents)
+ * 2. Broadcast to all agents via A2A
+ * 3. Collect and parse responses
+ * 4. Validate responses against rules
+ * 5. Apply state updates and log events
+ */
+interface TickResult {
+    tick: number;
+    responses: Map<string, AgentTickResponse>;
+    events: WorldEvent[];
+    stateUpdates: Record<string, any>;
+    errors: Array<{
+        agentUrl: string;
+        error: string;
+    }>;
+}
+interface OrchestrationConfig {
+    /** Whether to broadcast tick context to agents (default: true) */
+    broadcastOnTick?: boolean;
+    /** Timeout for agent responses in ms (default: 10000) */
+    tickTimeout?: number;
+    /** Custom prompt template for tick broadcasts */
+    promptTemplate?: string;
+}
+declare class TickOrchestrator {
+    private a2aClient;
+    private actionsRegistry;
+    private actionProcessor;
+    private orchestrationConfig;
+    constructor(a2aClient: WorldA2AClient, actionsRegistry: WorldActionsRegistry, rules: WorldRule[], config?: OrchestrationConfig);
+    /**
+     * Execute a single world tick
+     */
+    executeTick(tick: number, agents: AgentProfile[], state: WorldStateSnapshot, worldName: string): Promise<TickResult>;
+    /**
+     * Build the tick context that gets sent to each agent
+     */
+    private buildTickContext;
+    /**
+     * Parse an A2A response into an AgentTickResponse
+     */
+    private parseAgentResponse;
+    /**
+     * Update orchestration config
+     */
+    setConfig(config: Partial<OrchestrationConfig>): void;
+    /**
+     * Update rules on the action processor
+     */
+    setRules(rules: WorldRule[]): void;
+}
+
 /**
  * ============================================================================
  * WORLD HTTP SERVER
@@ -1281,4 +1625,4 @@ declare function createWorldApp(world: World): Express;
  */
 declare function startWorldServer(world: World): Promise<void>;
 
-export { type AdmissionDecision, type AdmissionRules, AdmissionRulesSchema, AgentEvaluator, type AgentProfile, BlockchainClient, type BlockchainConfig, BlockchainConfigSchema, CardFetcher, type EventFilter$1 as EventFilter, type FetchResult, InMemoryAdapter, type PersistenceAdapter, type PersistenceConfig, PersistenceConfigSchema, type RuleContext, type RuleViolation, type TokenConfig, TokenConfigSchema, World, type WorldConfig, WorldConfigSchema, type WorldEvent, type WorldPhase, type WorldRule, type WorldStateSnapshot, type WorldTypeModule, createLogger, createPersistence, createWorldApp, isValidWorldConfig, logger, normalizeAgentUrl, profileFromCard, startWorldServer, validateWorldConfig };
+export { ActionProcessor, type AdmissionDecision, type AdmissionRules, AdmissionRulesSchema, AgentEvaluator, type AgentProfile, type AgentTickResponse, BlockchainClient, type BlockchainConfig, BlockchainConfigSchema, CardFetcher, type EventFilter$1 as EventFilter, type FetchResult, InMemoryAdapter, MessageRouter, type OrchestrationConfig, type PersistenceAdapter, type PersistenceConfig, PersistenceConfigSchema, type ProcessResult, type RuleContext, type RuleViolation, TickOrchestrator, type TickResult, type TokenConfig, TokenConfigSchema, World, WorldA2AClient, type WorldAction$1 as WorldAction, type WorldActionParam, WorldActionsRegistry, type WorldConfig, WorldConfigSchema, type WorldEvent, type WorldPhase, type WorldRule, type WorldStateSnapshot, type WorldTypeModule, createLogger, createPersistence, createWorldApp, isValidWorldConfig, logger, normalizeAgentUrl, profileFromCard, startWorldServer, validateWorldConfig };