claude-flow-novice 1.6.3 → 1.6.5

package/.claude-flow-novice/dist/src/coordination/archives/v2-sdk-typescript/v2/messaging/channels/state-channel.js

@@ -0,0 +1,295 @@
+/**
+ * Agent Coordination V2 - State Channel
+ *
+ * Specialized channel for broadcasting agent state change events.
+ * Integrates with Phase 1 state machine to publish state transitions
+ * across the coordination system.
+ *
+ * @module coordination/v2/messaging/channels/state-channel
+ */ import { AgentState, AGENT_STATE_METADATA } from '../../core/agent-state.js';
+import { MessagePriority } from '../../core/message.js';
+/**
+ * State channel validation error.
+ */ export class StateChannelError extends Error {
+    constructor(message){
+        super(message);
+        this.name = 'StateChannelError';
+    }
+}
+/**
+ * State Channel Implementation.
+ *
+ * Specialized messaging channel for agent state transitions with:
+ * - Type-safe state change payloads
+ * - Automatic priority assignment based on state criticality
+ * - Integration with Phase 1 state machine
+ * - Validation of state transitions
+ * - Monitoring and observability hooks
+ *
+ * @example
+ * ```typescript
+ * const stateChannel = new StateChannel(messageBroker);
+ *
+ * // Subscribe to all state changes
+ * await stateChannel.subscribeToStateChanges(async (payload) => {
+ *   console.log(`Agent ${payload.agentId}: ${payload.fromState} -> ${payload.toState}`);
+ * });
+ *
+ * // Publish state change
+ * await stateChannel.publishStateChange({
+ *   agentId: 'agent-1',
+ *   fromState: AgentState.IDLE,
+ *   toState: AgentState.WORKING
+ * });
+ * ```
+ */ export class StateChannel {
+    /** Base topic for all state change messages */ static BASE_TOPIC = 'agent.state';
+    broker;
+    /**
+   * Creates a new state channel instance.
+   *
+   * @param broker - Message broker for publishing/subscribing
+   */ constructor(broker){
+        if (!broker) {
+            throw new StateChannelError('Message broker is required');
+        }
+        this.broker = broker;
+    }
+    // ============================================
+    // Publishing
+    // ============================================
+    /**
+   * Publishes an agent state change event.
+   *
+   * @param config - State change configuration
+   * @returns Promise resolving to published message
+   * @throws {StateChannelError} If validation fails
+   *
+   * @example
+   * ```typescript
+   * await stateChannel.publishStateChange({
+   *   agentId: 'agent-1',
+   *   fromState: AgentState.WORKING,
+   *   toState: AgentState.COMPLETED,
+   *   reason: 'Task finished successfully'
+   * });
+   * ```
+   */ async publishStateChange(config) {
+        this.validateStateChange(config);
+        const payload = {
+            agentId: config.agentId,
+            fromState: config.fromState,
+            toState: config.toState,
+            timestamp: Date.now(),
+            reason: config.reason,
+            metadata: config.metadata,
+            durationInPreviousState: config.durationInPreviousState
+        };
+        const priority = this.calculatePriority(config.toState);
+        const topic = this.buildTopic(config.agentId, config.toState);
+        const messageConfig = {
+            topic,
+            payload,
+            priority,
+            senderId: config.agentId,
+            metadata: {
+                channel: 'state',
+                stateChange: true,
+                fromState: config.fromState,
+                toState: config.toState
+            }
+        };
+        return this.broker.publish(messageConfig);
+    }
+    /**
+   * Publishes a batch of state changes (for efficiency).
+   *
+   * @param changes - Array of state change configurations
+   * @returns Promise resolving to array of published messages
+   */ async publishBatchStateChanges(changes) {
+        const results = [];
+        for (const change of changes){
+            const message = await this.publishStateChange(change);
+            results.push(message);
+        }
+        return results;
+    }
+    // ============================================
+    // Subscribing
+    // ============================================
+    /**
+   * Subscribes to all state change events.
+   *
+   * @param handler - Callback function for state changes
+   * @returns Subscription handle
+   *
+   * @example
+   * ```typescript
+   * const sub = await stateChannel.subscribeToStateChanges(async (payload) => {
+   *   console.log(`State change: ${payload.agentId} ${payload.fromState} -> ${payload.toState}`);
+   * });
+   * ```
+   */ async subscribeToStateChanges(handler) {
+        return this.broker.subscribe({
+            topic: `${StateChannel.BASE_TOPIC}.*.*`,
+            handler: async (message)=>{
+                await handler(message.payload);
+            }
+        });
+    }
+    /**
+   * Subscribes to state changes for a specific agent.
+   *
+   * @param agentId - Agent ID to monitor
+   * @param handler - Callback function for state changes
+   * @returns Subscription handle
+   *
+   * @example
+   * ```typescript
+   * const sub = await stateChannel.subscribeToAgent('agent-1', async (payload) => {
+   *   console.log(`Agent 1 state: ${payload.toState}`);
+   * });
+   * ```
+   */ async subscribeToAgent(agentId, handler) {
+        this.validateAgentId(agentId);
+        return this.broker.subscribe({
+            topic: `${StateChannel.BASE_TOPIC}.${agentId}.*`,
+            handler: async (message)=>{
+                await handler(message.payload);
+            }
+        });
+    }
+    /**
+   * Subscribes to a specific state across all agents.
+   *
+   * @param state - Agent state to monitor
+   * @param handler - Callback function for state changes
+   * @returns Subscription handle
+   *
+   * @example
+   * ```typescript
+   * const sub = await stateChannel.subscribeToState(AgentState.ERROR, async (payload) => {
+   *   console.error(`Agent ${payload.agentId} entered ERROR state`);
+   * });
+   * ```
+   */ async subscribeToState(state, handler) {
+        return this.broker.subscribe({
+            topic: `${StateChannel.BASE_TOPIC}.*.${state}`,
+            handler: async (message)=>{
+                await handler(message.payload);
+            }
+        });
+    }
+    /**
+   * Subscribes to error states (ERROR, BLOCKED).
+   *
+   * @param handler - Callback function for error state changes
+   * @returns Subscription handle
+   *
+   * @example
+   * ```typescript
+   * const sub = await stateChannel.subscribeToErrors(async (payload) => {
+   *   console.error(`Agent ${payload.agentId} error: ${payload.reason}`);
+   * });
+   * ```
+   */ async subscribeToErrors(handler) {
+        return this.broker.subscribe({
+            topic: `${StateChannel.BASE_TOPIC}.*.*`,
+            handler: async (message)=>{
+                const payload = message.payload;
+                const metadata = AGENT_STATE_METADATA[payload.toState];
+                if (metadata.isError) {
+                    await handler(payload);
+                }
+            }
+        });
+    }
+    // ============================================
+    // Validation
+    // ============================================
+    /**
+   * Validates state change configuration.
+   *
+   * @param config - State change to validate
+   * @throws {StateChannelError} If validation fails
+   */ validateStateChange(config) {
+        this.validateAgentId(config.agentId);
+        if (!config.fromState || !Object.values(AgentState).includes(config.fromState)) {
+            throw new StateChannelError(`Invalid fromState: ${config.fromState}`);
+        }
+        if (!config.toState || !Object.values(AgentState).includes(config.toState)) {
+            throw new StateChannelError(`Invalid toState: ${config.toState}`);
+        }
+        if (config.fromState === config.toState) {
+            throw new StateChannelError(`Cannot transition to same state: ${config.fromState} -> ${config.toState}`);
+        }
+        if (config.reason !== undefined && typeof config.reason !== 'string') {
+            throw new StateChannelError('Reason must be a string');
+        }
+        if (config.durationInPreviousState !== undefined) {
+            if (typeof config.durationInPreviousState !== 'number' || config.durationInPreviousState < 0) {
+                throw new StateChannelError('Duration must be a non-negative number');
+            }
+        }
+    }
+    /**
+   * Validates agent ID.
+   *
+   * @param agentId - Agent ID to validate
+   * @throws {StateChannelError} If validation fails
+   */ validateAgentId(agentId) {
+        if (!agentId || typeof agentId !== 'string') {
+            throw new StateChannelError('Agent ID must be a non-empty string');
+        }
+        if (agentId.length > 256) {
+            throw new StateChannelError('Agent ID exceeds 256 characters');
+        }
+    }
+    // ============================================
+    // Utility Methods
+    // ============================================
+    /**
+   * Builds topic string for state change message.
+   *
+   * Format: agent.state.{agentId}.{toState}
+   *
+   * @param agentId - Agent identifier
+   * @param state - Target state
+   * @returns Topic string
+   */ buildTopic(agentId, state) {
+        return `${StateChannel.BASE_TOPIC}.${agentId}.${state}`;
+    }
+    /**
+   * Calculates message priority based on state criticality.
+   *
+   * Priority mapping:
+   * - CRITICAL (10): ERROR, BLOCKED
+   * - HIGH (8): COMPLETED, TERMINATED
+   * - NORMAL (5): WORKING, HELPING
+   * - LOW (2): IDLE, WAITING, PAUSED
+   *
+   * @param state - Target state
+   * @returns Priority level (0-10)
+   */ calculatePriority(state) {
+        const metadata = AGENT_STATE_METADATA[state];
+        if (metadata.isError) {
+            return MessagePriority.CRITICAL; // ERROR, BLOCKED
+        }
+        if (metadata.isTerminal) {
+            return MessagePriority.HIGH; // COMPLETED, TERMINATED
+        }
+        if (metadata.isActive) {
+            return MessagePriority.NORMAL; // WORKING, HELPING
+        }
+        return MessagePriority.LOW; // IDLE, WAITING, PAUSED
+    }
+    /**
+   * Gets the base topic for all state changes.
+   *
+   * @returns Base topic string
+   */ static getBaseTopic() {
+        return StateChannel.BASE_TOPIC;
+    }
+}
+
+//# sourceMappingURL=state-channel.js.map

package/.claude-flow-novice/dist/src/coordination/archives/v2-sdk-typescript/v2/messaging/channels/state-channel.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../../src/coordination/archives/v2-sdk-typescript/v2/messaging/channels/state-channel.ts"],"names":["AgentState","AGENT_STATE_METADATA","MessagePriority","StateChannelError","Error","message","name","StateChannel","BASE_TOPIC","broker","publishStateChange","config","validateStateChange","payload","agentId","fromState","toState","timestamp","Date","now","reason","metadata","durationInPreviousState","priority","calculatePriority","topic","buildTopic","messageConfig","senderId","channel","stateChange","publish","publishBatchStateChanges","changes","results","change","push","subscribeToStateChanges","handler","subscribe","subscribeToAgent","validateAgentId","subscribeToState","state","subscribeToErrors","isError","Object","values","includes","undefined","length","CRITICAL","isTerminal","HIGH","isActive","NORMAL","LOW","getBaseTopic"],"mappings":"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"}