@multi-agent-protocol/sdk 0.0.2

package/dist/testing.d.ts

@@ -0,0 +1,367 @@
+import { P as ParticipantCapabilities, dy as SystemExposure, d as FederationRoutingConfig, S as Stream, aC as BaseConnection, f as SessionId, A as AgentId, m as Agent, l as ScopeId, n as Scope, c as Message, q as Event, j as ParticipantId, L as SubscriptionId, aI as ClientConnectionOptions, aH as ClientConnection, ae as AgentsListRequestParams, ct as ScopesListRequestParams, p as SubscriptionFilter, cR as Subscription, e as EventType, Y as AgentConnectionOptions, X as AgentConnection } from './index-C7XPWnxS.js';
+
+/**
+ * Test MAP Server Implementation
+ *
+ * A simple in-memory MAP server for testing purposes.
+ * Implements the core MAP protocol methods.
+ */
+
+/**
+ * Options for test server
+ */
+interface TestServerOptions {
+    name?: string;
+    version?: string;
+    capabilities?: ParticipantCapabilities;
+    /** Maximum number of events to retain for replay. Default: 10000 */
+    maxEventHistory?: number;
+    /** System exposure configuration for permission filtering */
+    exposure?: SystemExposure;
+    /** Federation routing configuration for envelope validation */
+    federationRouting?: FederationRoutingConfig;
+}
+/**
+ * Stored event for replay capability
+ */
+interface StoredEvent {
+    eventId: string;
+    timestamp: number;
+    event: Event;
+    /** Event IDs that caused this event */
+    causedBy?: string[];
+}
+/**
+ * Test MAP Server
+ *
+ * Provides a fully functional MAP server for integration testing.
+ */
+declare class TestServer {
+    #private;
+    constructor(options?: TestServerOptions);
+    /**
+     * Accept a new connection
+     */
+    acceptConnection(stream: Stream): BaseConnection;
+    /**
+     * Get current session ID
+     */
+    get sessionId(): SessionId;
+    /**
+     * Get all registered agents
+     */
+    get agents(): ReadonlyMap<AgentId, Agent>;
+    /**
+     * Get all scopes
+     */
+    get scopes(): ReadonlyMap<ScopeId, Scope>;
+    /**
+     * Get all messages sent through the server
+     */
+    get messages(): readonly Message[];
+    /**
+     * Get connected participant count
+     */
+    get participantCount(): number;
+    /**
+     * Get event history for replay testing
+     */
+    get eventHistory(): readonly StoredEvent[];
+    /**
+     * Emit an event to subscribers
+     * @param event - The event to emit (without id/timestamp)
+     * @param causedBy - Optional array of event IDs that caused this event
+     * @returns The generated event ID
+     */
+    emitEvent(event: Omit<Event, 'id' | 'timestamp'>, causedBy?: string[]): string;
+    /**
+     * Deliver a message notification to a participant
+     */
+    deliverMessage(participantId: ParticipantId, message: Message): void;
+    /**
+     * Get ack state for a subscription (for testing assertions)
+     */
+    getSubscriptionAckState(subscriptionId: SubscriptionId): {
+        sequenceNumber: number;
+        lastAckedSequence?: number;
+    } | undefined;
+}
+
+/**
+ * Test Client Helper
+ *
+ * Provides a convenient wrapper around ClientConnection for testing.
+ * Automatically manages stream pairs and connection lifecycle.
+ */
+
+/**
+ * Options for TestClient
+ */
+interface TestClientOptions extends ClientConnectionOptions {
+    /** Auto-connect on creation */
+    autoConnect?: boolean;
+}
+/**
+ * Test client for integration testing.
+ *
+ * Wraps ClientConnection with convenience methods and automatic
+ * stream management for easier testing.
+ */
+declare class TestClient {
+    #private;
+    private constructor();
+    /**
+     * Create and connect a test client
+     */
+    static create(server: TestServer, options?: TestClientOptions): Promise<TestClient>;
+    /**
+     * Get the underlying connection
+     */
+    get connection(): ClientConnection;
+    /**
+     * Whether the client is connected
+     */
+    get isConnected(): boolean;
+    /**
+     * Current session ID
+     */
+    get sessionId(): string | null;
+    /**
+     * Connect to the server
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the server
+     */
+    disconnect(): Promise<void>;
+    /**
+     * List all agents
+     */
+    listAgents(options?: AgentsListRequestParams): Promise<Agent[]>;
+    /**
+     * Get agent by ID with optional hierarchy expansion
+     */
+    getAgent(agentId: string, options?: {
+        include?: {
+            children?: boolean;
+            descendants?: boolean;
+        };
+    }): Promise<{
+        agent: Agent;
+        children?: Agent[];
+        descendants?: Agent[];
+    }>;
+    /**
+     * Find agent by name
+     */
+    findAgentByName(name: string): Promise<Agent | undefined>;
+    /**
+     * Find agents by role
+     */
+    findAgentsByRole(role: string): Promise<Agent[]>;
+    /**
+     * List all scopes
+     */
+    listScopes(options?: ScopesListRequestParams): Promise<Scope[]>;
+    /**
+     * Get scope by ID
+     */
+    getScope(scopeId: string): Promise<Scope>;
+    /**
+     * Send message to agent
+     */
+    sendTo(agentId: string, payload: unknown): Promise<string>;
+    /**
+     * Broadcast to all agents
+     */
+    broadcast(payload: unknown): Promise<string>;
+    /**
+     * Send to all agents with a specific role
+     */
+    sendToRole(role: string, payload: unknown): Promise<string>;
+    /**
+     * Send to all agents in a scope
+     */
+    sendToScope(scopeId: string, payload: unknown): Promise<string>;
+    /**
+     * Subscribe to events with automatic tracking
+     */
+    subscribe(filter?: SubscriptionFilter): Promise<Subscription>;
+    /**
+     * Collect events matching filter for a duration
+     */
+    collectEvents(filter: SubscriptionFilter, durationMs: number): Promise<Event[]>;
+    /**
+     * Wait for a specific event type
+     */
+    waitForEvent(eventType: EventType, timeoutMs?: number): Promise<Event>;
+    /**
+     * Stop an agent
+     */
+    stopAgent(agentId: string, reason?: string): Promise<void>;
+    /**
+     * Inject context into an agent
+     */
+    inject(agentId: string, content: unknown, delivery?: 'interrupt' | 'queue' | 'best-effort'): Promise<void>;
+}
+
+/**
+ * Test Agent Helper
+ *
+ * Provides a convenient wrapper around AgentConnection for testing.
+ * Automatically manages stream pairs and connection lifecycle.
+ */
+
+/**
+ * Options for TestAgent
+ */
+interface TestAgentOptions extends AgentConnectionOptions {
+    /** Auto-connect on creation */
+    autoConnect?: boolean;
+    /** Pre-assigned agent ID */
+    agentId?: AgentId;
+}
+/**
+ * Test agent for integration testing.
+ *
+ * Wraps AgentConnection with convenience methods and automatic
+ * stream management for easier testing.
+ */
+declare class TestAgent {
+    #private;
+    private constructor();
+    /**
+     * Create and connect a test agent
+     */
+    static create(server: TestServer, options?: TestAgentOptions): Promise<TestAgent>;
+    /**
+     * Get the underlying connection
+     */
+    get connection(): AgentConnection;
+    /**
+     * Whether the agent is connected
+     */
+    get isConnected(): boolean;
+    /**
+     * Agent ID
+     */
+    get id(): AgentId | null;
+    /**
+     * Current state
+     */
+    get state(): string;
+    /**
+     * Session ID
+     */
+    get sessionId(): string | null;
+    /**
+     * All messages received by this agent
+     */
+    get receivedMessages(): readonly Message[];
+    /**
+     * Get the last received message
+     */
+    get lastMessage(): Message | undefined;
+    /**
+     * Clear received messages
+     */
+    clearMessages(): void;
+    /**
+     * Connect to the server
+     */
+    connect(agentId?: AgentId): Promise<Agent>;
+    /**
+     * Disconnect from the server
+     */
+    disconnect(reason?: string): Promise<void>;
+    /**
+     * Update state
+     */
+    setState(state: 'idle' | 'busy' | 'suspended' | 'stopping' | 'stopped'): Promise<Agent>;
+    /**
+     * Mark as busy
+     */
+    busy(): Promise<Agent>;
+    /**
+     * Mark as idle
+     */
+    idle(): Promise<Agent>;
+    /**
+     * Mark as done
+     */
+    done(exitCode?: number, exitReason?: string): Promise<void>;
+    /**
+     * Update metadata
+     */
+    setMetadata(metadata: Record<string, unknown>): Promise<Agent>;
+    /**
+     * Spawn a child agent
+     */
+    spawn(options?: {
+        name?: string;
+        role?: string;
+        agentId?: AgentId;
+    }): Promise<Agent>;
+    /**
+     * Spawn and return a connected TestAgent for the child
+     */
+    spawnTestAgent(server: TestServer, options?: TestAgentOptions): Promise<TestAgent>;
+    /**
+     * Create a scope
+     */
+    createScope(name: string, options?: {
+        description?: string;
+    }): Promise<Scope>;
+    /**
+     * Join a scope
+     */
+    joinScope(scopeId: ScopeId): Promise<{
+        scope: Scope;
+        agent: Agent;
+    }>;
+    /**
+     * Leave a scope
+     */
+    leaveScope(scopeId: ScopeId): Promise<{
+        scope: Scope;
+        agent: Agent;
+    }>;
+    /**
+     * Send to another agent
+     */
+    sendTo(agentId: AgentId, payload: unknown): Promise<string>;
+    /**
+     * Send to parent
+     */
+    sendToParent(payload: unknown): Promise<string>;
+    /**
+     * Send to children
+     */
+    sendToChildren(payload: unknown): Promise<string>;
+    /**
+     * Send to siblings
+     */
+    sendToSiblings(payload: unknown): Promise<string>;
+    /**
+     * Send to scope
+     */
+    sendToScope(scopeId: ScopeId, payload: unknown): Promise<string>;
+    /**
+     * Reply to a message
+     */
+    reply(message: Message, payload: unknown): Promise<string>;
+    /**
+     * Wait for a message
+     */
+    waitForMessage(timeoutMs?: number): Promise<Message>;
+    /**
+     * Subscribe to events
+     */
+    subscribe(filter?: SubscriptionFilter): Promise<Subscription>;
+    /**
+     * Wait for a specific event
+     */
+    waitForEvent(eventType: EventType, timeoutMs?: number): Promise<Event>;
+}
+
+export { TestAgent, type TestAgentOptions, TestClient, type TestClientOptions, TestServer, type TestServerOptions };