@kadi.build/core 0.15.4 → 0.15.6

package/src/react-loop.ts

@@ -0,0 +1,792 @@
+/**
+ * ReActLoop — SDK Primitive for Agent Execution
+ *
+ * The ReAct (Reason + Act) loop is the core agent execution primitive.
+ * It handles: tool routing, model calls, turn management, context compaction,
+ * event hooks, stop conditions, steering, and event emission.
+ *
+ * It does NOT handle: planning, sub-agents, filesystem management, or skills.
+ * Those are engine ability concerns.
+ *
+ * @example
+ * ```typescript
+ * import { KadiClient, ReActLoop } from '@kadi.build/core';
+ *
+ * const client = new KadiClient({ name: 'my-agent' });
+ * await client.connect();
+ *
+ * const loop = new ReActLoop({
+ *   client,
+ *   model: { routing: 'broker', model: 'claude-sonnet-4-6' },
+ *   tools: { broker: true },
+ *   maxTurns: 50,
+ *   systemPrompt: 'You are a research assistant...',
+ * });
+ *
+ * const result = await loop.run('Analyze the test results');
+ * ```
+ *
+ * @see docs/kadi-harness-spec-v5.md §8 (ReActLoop)
+ */
+
+import { EventEmitter } from 'events';
+import type { KadiClient } from './client.js';
+import type { ToolDefinition } from './types.js';
+
+// ═══════════════════════════════════════════════════════════════
+// TYPES
+// ═══════════════════════════════════════════════════════════════
+
+/** Model routing and configuration */
+export interface ModelConfig {
+  /** How to route model calls: 'broker' (via model-provider) or 'direct' */
+  routing: 'broker' | 'direct';
+  /** Provider name (used when routing: 'direct') */
+  provider?: string;
+  /** Model identifier (e.g. 'claude-sonnet-4-6') */
+  model: string;
+  /** Sampling temperature */
+  temperature?: number;
+  /** Max tokens for model response */
+  maxTokens?: number;
+}
+
+/** Tool routing configuration */
+export interface ToolsConfig {
+  /** Include all tools from connected broker networks */
+  broker?: boolean;
+  /** Local tools to include by name */
+  native?: string[];
+  /** Additional custom tool definitions with handlers */
+  custom?: CustomTool[];
+  /** Pre-configured tool router (from bridge) */
+  router?: ToolRouter;
+  /** Pre-resolved tool definitions (bypass discovery) */
+  definitions?: ToolDefinition[];
+}
+
+/** A custom tool with definition and handler */
+export interface CustomTool {
+  definition: ToolDefinition;
+  handler: (params: unknown) => Promise<unknown>;
+}
+
+/** Tool router interface — resolves and executes tool calls */
+export interface ToolRouter {
+  resolve(toolName: string): Promise<ToolDefinition | undefined>;
+  execute(toolName: string, params: unknown): Promise<unknown>;
+}
+
+/** Event emission configuration */
+export interface EventsConfig {
+  /** Whether to emit events */
+  enabled?: boolean;
+  /** Which network to emit events on */
+  network?: string;
+  /** Event channel prefix (default: 'kadi.agent') */
+  prefix?: string;
+}
+
+/** Lifecycle hooks */
+export interface ReActHooks {
+  /** Called before each LLM call */
+  beforeTurn?: (turn: TurnInfo) => Promise<void>;
+  /** Called after each tool execution */
+  afterTurn?: (turn: TurnInfo, result: TurnResult) => Promise<void>;
+  /** Intercept/modify tool calls before execution */
+  onToolCall?: (toolName: string, params: unknown) => Promise<unknown | void>;
+  /** Handle errors — return 'retry', 'skip', or 'abort' */
+  onError?: (error: Error, turn: TurnInfo) => Promise<'retry' | 'skip' | 'abort'>;
+  /** Return false to stop the loop */
+  shouldContinue?: (turn: TurnInfo, result: TurnResult) => Promise<boolean>;
+}
+
+/** Full configuration for the ReActLoop */
+export interface ReActConfig {
+  /** KadiClient instance for broker communication */
+  client?: KadiClient;
+
+  /** Model configuration */
+  model: ModelConfig;
+
+  /** Tools available to the loop */
+  tools?: ToolsConfig;
+
+  /** Maximum number of turns (default: 100) */
+  maxTurns?: number;
+
+  /** Maximum wall-clock time (e.g. '2h', '30m', '500ms') */
+  timeout?: string;
+
+  /** System prompt prepended to context */
+  systemPrompt?: string;
+
+  /** Context compaction strategy (default: 'auto') */
+  compaction?: 'auto' | 'manual' | 'off';
+
+  /** Token threshold for compaction trigger (default: 128000) */
+  maxContextTokens?: number;
+
+  /** Model for compaction summaries (null = same model) */
+  summaryModel?: string;
+
+  /** Lifecycle hooks */
+  hooks?: ReActHooks;
+
+  /** Event emission configuration */
+  events?: EventsConfig;
+
+  /** Auth context */
+  auth?: {
+    token?: string;
+  };
+
+  /** Model call function — override for testing or custom providers */
+  modelCall?: (messages: Message[], tools: ToolDefinition[]) => Promise<ModelResponse>;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// MESSAGE & RESPONSE TYPES
+// ═══════════════════════════════════════════════════════════════
+
+/** A message in the conversation context */
+export interface Message {
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content: string;
+  /** Tool call ID (for tool results) */
+  toolCallId?: string;
+  /** Tool calls requested by the model */
+  toolCalls?: ToolCall[];
+}
+
+/** A tool call from the model */
+export interface ToolCall {
+  id: string;
+  name: string;
+  arguments: unknown;
+}
+
+/** Response from a model call */
+export interface ModelResponse {
+  /** Text content of the response */
+  content?: string;
+  /** Tool calls requested by the model */
+  toolCalls?: ToolCall[];
+  /** Estimated tokens used */
+  tokensUsed?: number;
+  /** Whether the model considers the task done */
+  done?: boolean;
+}
+
+/** Information about the current turn */
+export interface TurnInfo {
+  /** Turn number (1-indexed) */
+  number: number;
+  /** When this turn started */
+  startedAt: Date;
+  /** Cumulative tokens used so far */
+  tokensUsed: number;
+  /** Cumulative tool calls so far */
+  toolCalls: number;
+}
+
+/** Result of a single turn */
+export interface TurnResult {
+  /** Tool that was called (if any) */
+  toolName?: string;
+  /** Parameters passed to the tool */
+  toolParams?: unknown;
+  /** Result returned by the tool */
+  toolResult?: unknown;
+  /** Text response from the model */
+  modelResponse?: string;
+  /** Tokens used in this turn */
+  tokensUsed: number;
+  /** Whether the loop is complete */
+  completed: boolean;
+  /** Reason for completion (if completed) */
+  reason?: StopReason;
+}
+
+/** Reasons the loop can stop */
+export type StopReason = 'max_turns' | 'timeout' | 'should_continue' | 'model_done' | 'error' | 'cancelled';
+
+/** Final result of the loop execution */
+export interface ReActResult {
+  /** How the loop ended */
+  status: 'completed' | 'cancelled' | 'error' | 'max_turns' | 'timeout';
+  /** Total turns executed */
+  turns: number;
+  /** Total tokens used */
+  totalTokens: number;
+  /** Artifacts produced during execution */
+  artifacts: unknown[];
+  /** Last model response text */
+  lastResponse?: string;
+  /** Error that caused the loop to stop (if applicable) */
+  error?: Error;
+}
+
+/** Handle for controlling a running loop */
+export interface LoopHandle {
+  /** Inject a steering message into the loop */
+  steer(message: string): Promise<void>;
+  /** Cancel the loop */
+  cancel(): Promise<void>;
+  /** Promise that resolves when the loop completes */
+  completion: Promise<ReActResult>;
+  /** Listen for loop events */
+  on(event: string, handler: (...args: unknown[]) => void): void;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// CONSTANTS
+// ═══════════════════════════════════════════════════════════════
+
+const DEFAULT_MAX_TURNS = 100;
+const DEFAULT_MAX_CONTEXT_TOKENS = 128000;
+const DEFAULT_COMPACTION = 'auto';
+const DEFAULT_EVENT_PREFIX = 'kadi.agent';
+/** Compaction triggers at this fraction of maxContextTokens */
+const COMPACTION_THRESHOLD = 0.8;
+/** Rough estimate: 1 token ≈ 4 characters */
+const CHARS_PER_TOKEN = 4;
+
+// ═══════════════════════════════════════════════════════════════
+// HELPER: Parse timeout string to ms
+// ═══════════════════════════════════════════════════════════════
+
+function parseTimeout(timeout: string): number {
+  const match = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h)$/.exec(timeout.trim());
+  if (!match || !match[1] || !match[2]) {
+    throw new Error(`Invalid timeout format: "${timeout}". Use e.g. '500ms', '30s', '2m', '2h'`);
+  }
+  const value = parseFloat(match[1]);
+  switch (match[2]) {
+    case 'ms': return value;
+    case 's': return value * 1000;
+    case 'm': return value * 60_000;
+    case 'h': return value * 3_600_000;
+    default: return value;
+  }
+}
+
+/** Estimate token count from message content */
+function estimateTokens(messages: Message[]): number {
+  let chars = 0;
+  for (const msg of messages) {
+    chars += msg.content.length;
+    if (msg.toolCalls) {
+      chars += JSON.stringify(msg.toolCalls).length;
+    }
+  }
+  return Math.ceil(chars / CHARS_PER_TOKEN);
+}
+
+// ═══════════════════════════════════════════════════════════════
+// REACT LOOP CLASS
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * The ReAct (Reason + Act) loop — core agent execution primitive.
+ *
+ * Runs a loop: call model → if tool call → execute tool → feed result → repeat.
+ * Stops when: max turns reached, timeout, shouldContinue returns false,
+ * model indicates done (no tool call), or an error causes abort.
+ */
+export class ReActLoop {
+  private readonly config: Required<Pick<ReActConfig, 'maxTurns' | 'compaction' | 'maxContextTokens'>> & ReActConfig;
+  private readonly emitter = new EventEmitter();
+
+  // Custom tool handlers indexed by name
+  private readonly customTools = new Map<string, (params: unknown) => Promise<unknown>>();
+
+  constructor(config: ReActConfig) {
+    // Validate required fields
+    if (!config.model) {
+      throw new Error('ReActConfig.model is required');
+    }
+    if (!config.model.model) {
+      throw new Error('ReActConfig.model.model is required');
+    }
+    if (!config.model.routing) {
+      throw new Error('ReActConfig.model.routing is required');
+    }
+
+    this.config = {
+      ...config,
+      maxTurns: config.maxTurns ?? DEFAULT_MAX_TURNS,
+      compaction: config.compaction ?? DEFAULT_COMPACTION,
+      maxContextTokens: config.maxContextTokens ?? DEFAULT_MAX_CONTEXT_TOKENS,
+    };
+
+    // Register custom tools
+    if (config.tools?.custom) {
+      for (const tool of config.tools.custom) {
+        this.customTools.set(tool.definition.name, tool.handler);
+      }
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // PUBLIC API
+  // ─────────────────────────────────────────────────────────────
+
+  /**
+   * Run the loop synchronously (blocks until complete).
+   *
+   * @param prompt - User prompt to start the loop with
+   * @returns Final result with status, turn count, and artifacts
+   */
+  async run(prompt: string): Promise<ReActResult> {
+    return this.executeLoop(prompt);
+  }
+
+  /**
+   * Start the loop in interactive mode (supports steering).
+   *
+   * @param prompt - User prompt to start the loop with
+   * @returns Handle for steering, cancellation, and completion
+   */
+  start(prompt: string): LoopHandle {
+    const steeringQueue: string[] = [];
+    let cancelled = false;
+
+    const completion = this.executeLoop(prompt, {
+      getSteeringMessages: () => {
+        const messages = [...steeringQueue];
+        steeringQueue.length = 0;
+        return messages;
+      },
+      isCancelled: () => cancelled,
+    });
+
+    return {
+      steer: async (message: string) => {
+        steeringQueue.push(message);
+      },
+      cancel: async () => {
+        cancelled = true;
+      },
+      completion,
+      on: (event: string, handler: (...args: unknown[]) => void) => {
+        this.emitter.on(event, handler);
+      },
+    };
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // CORE LOOP
+  // ─────────────────────────────────────────────────────────────
+
+  private async executeLoop(
+    prompt: string,
+    control?: {
+      getSteeringMessages?: () => string[];
+      isCancelled?: () => boolean;
+    }
+  ): Promise<ReActResult> {
+    const messages: Message[] = [];
+    const artifacts: unknown[] = [];
+    let totalTokens = 0;
+    let totalToolCalls = 0;
+    let lastResponse: string | undefined;
+    let timeoutMs: number | undefined;
+
+    // Build initial context
+    if (this.config.systemPrompt) {
+      messages.push({ role: 'system', content: this.config.systemPrompt });
+    }
+    messages.push({ role: 'user', content: prompt });
+
+    // Parse timeout
+    if (this.config.timeout) {
+      timeoutMs = parseTimeout(this.config.timeout);
+    }
+    const startTime = Date.now();
+
+    // Resolve available tool definitions
+    const toolDefs = await this.resolveToolDefinitions();
+
+    // ─── Main loop ──────────────────────────────────────────
+
+    for (let turn = 1; turn <= this.config.maxTurns; turn++) {
+      // Check cancellation
+      if (control?.isCancelled?.()) {
+        return this.buildResult('cancelled', turn - 1, totalTokens, artifacts, lastResponse);
+      }
+
+      // Check timeout
+      if (timeoutMs && (Date.now() - startTime) >= timeoutMs) {
+        this.emitEvent('timeout', { turn: turn - 1, totalTokens });
+        return this.buildResult('timeout', turn - 1, totalTokens, artifacts, lastResponse);
+      }
+
+      // Inject steering messages
+      const steeringMsgs = control?.getSteeringMessages?.() ?? [];
+      for (const msg of steeringMsgs) {
+        messages.push({ role: 'user', content: msg });
+      }
+
+      // Build turn info
+      const turnInfo: TurnInfo = {
+        number: turn,
+        startedAt: new Date(),
+        tokensUsed: totalTokens,
+        toolCalls: totalToolCalls,
+      };
+
+      // beforeTurn hook
+      if (this.config.hooks?.beforeTurn) {
+        await this.config.hooks.beforeTurn(turnInfo);
+      }
+
+      // ─── Compaction check ──────────────────────────────
+      if (this.config.compaction === 'auto') {
+        const estimatedTokens = estimateTokens(messages);
+        if (estimatedTokens > this.config.maxContextTokens * COMPACTION_THRESHOLD) {
+          await this.compactContext(messages);
+          this.emitEvent('compaction', { turn, estimatedTokens });
+        }
+      }
+
+      // ─── Call model ────────────────────────────────────
+      let modelResponse: ModelResponse;
+      try {
+        modelResponse = await this.callModel(messages, toolDefs);
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        const action = await this.handleError(error, turnInfo);
+        if (action === 'retry') continue;
+        if (action === 'skip') {
+          const skipResult: TurnResult = {
+            modelResponse: undefined,
+            tokensUsed: 0,
+            completed: false,
+          };
+          if (this.config.hooks?.afterTurn) {
+            await this.config.hooks.afterTurn(turnInfo, skipResult);
+          }
+          continue;
+        }
+        // abort
+        this.emitEvent('error', { turn, error: error.message });
+        return this.buildResult('error', turn, totalTokens, artifacts, lastResponse, error);
+      }
+
+      totalTokens += modelResponse.tokensUsed ?? 0;
+      lastResponse = modelResponse.content;
+
+      // ─── No tool calls → model is done ─────────────────
+      if (!modelResponse.toolCalls || modelResponse.toolCalls.length === 0) {
+        // Model returned text only — task is done
+        if (modelResponse.content) {
+          messages.push({ role: 'assistant', content: modelResponse.content });
+        }
+
+        const turnResult: TurnResult = {
+          modelResponse: modelResponse.content,
+          tokensUsed: modelResponse.tokensUsed ?? 0,
+          completed: true,
+          reason: 'model_done',
+        };
+
+        this.emitEvent('turn', { turn, result: turnResult });
+
+        if (this.config.hooks?.afterTurn) {
+          await this.config.hooks.afterTurn(turnInfo, turnResult);
+        }
+
+        return this.buildResult('completed', turn, totalTokens, artifacts, lastResponse);
+      }
+
+      // ─── Execute tool calls ────────────────────────────
+      // Add assistant message with tool calls
+      messages.push({
+        role: 'assistant',
+        content: modelResponse.content ?? '',
+        toolCalls: modelResponse.toolCalls,
+      });
+
+      for (const toolCall of modelResponse.toolCalls) {
+        totalToolCalls++;
+
+        // onToolCall hook — can modify params
+        let params = toolCall.arguments;
+        if (this.config.hooks?.onToolCall) {
+          const modified = await this.config.hooks.onToolCall(toolCall.name, params);
+          if (modified !== undefined) {
+            params = modified;
+          }
+        }
+
+        // Execute the tool
+        let toolResult: unknown;
+        try {
+          toolResult = await this.executeTool(toolCall.name, params);
+        } catch (err) {
+          const error = err instanceof Error ? err : new Error(String(err));
+          const action = await this.handleError(error, turnInfo);
+          if (action === 'retry') {
+            // Re-run this turn
+            break;
+          }
+          if (action === 'skip') {
+            toolResult = { error: error.message };
+          } else {
+            // abort
+            this.emitEvent('error', { turn, error: error.message, toolName: toolCall.name });
+            return this.buildResult('error', turn, totalTokens, artifacts, lastResponse, error);
+          }
+        }
+
+        // Feed tool result back to context
+        messages.push({
+          role: 'tool',
+          content: typeof toolResult === 'string' ? toolResult : JSON.stringify(toolResult),
+          toolCallId: toolCall.id,
+        });
+
+        const turnResult: TurnResult = {
+          toolName: toolCall.name,
+          toolParams: params,
+          toolResult,
+          modelResponse: modelResponse.content,
+          tokensUsed: modelResponse.tokensUsed ?? 0,
+          completed: false,
+        };
+
+        this.emitEvent('turn', { turn, result: turnResult });
+
+        if (this.config.hooks?.afterTurn) {
+          await this.config.hooks.afterTurn(turnInfo, turnResult);
+        }
+
+        // shouldContinue hook
+        if (this.config.hooks?.shouldContinue) {
+          const shouldContinue = await this.config.hooks.shouldContinue(turnInfo, turnResult);
+          if (!shouldContinue) {
+            return this.buildResult('completed', turn, totalTokens, artifacts, lastResponse);
+          }
+        }
+      }
+    }
+
+    // Exceeded maxTurns
+    this.emitEvent('max_turns', { maxTurns: this.config.maxTurns, totalTokens });
+    return this.buildResult('max_turns', this.config.maxTurns, totalTokens, artifacts, lastResponse);
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // MODEL CALLS
+  // ─────────────────────────────────────────────────────────────
+
+  private async callModel(messages: Message[], tools: ToolDefinition[]): Promise<ModelResponse> {
+    // If a custom modelCall is provided (for testing or direct providers), use it
+    if (this.config.modelCall) {
+      return this.config.modelCall(messages, tools);
+    }
+
+    // Broker-routed model call via model-provider ability
+    if (this.config.model.routing === 'broker' && this.config.client) {
+      return this.config.client.invokeRemote<ModelResponse>('model-call', {
+        model: this.config.model.model,
+        messages,
+        tools,
+        temperature: this.config.model.temperature,
+        maxTokens: this.config.model.maxTokens,
+      });
+    }
+
+    throw new Error(
+      'No model call method available. Provide config.modelCall, or configure ' +
+      'config.model.routing = "broker" with a connected KadiClient.'
+    );
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // TOOL ROUTING
+  // ─────────────────────────────────────────────────────────────
+
+  /**
+   * Resolve available tool definitions.
+   * Priority: custom → native → broker → definitions
+   */
+  private async resolveToolDefinitions(): Promise<ToolDefinition[]> {
+    const toolDefs: ToolDefinition[] = [];
+    const seenNames = new Set<string>();
+
+    // Custom tools
+    if (this.config.tools?.custom) {
+      for (const tool of this.config.tools.custom) {
+        if (!seenNames.has(tool.definition.name)) {
+          toolDefs.push(tool.definition);
+          seenNames.add(tool.definition.name);
+        }
+      }
+    }
+
+    // Pre-resolved definitions
+    if (this.config.tools?.definitions) {
+      for (const def of this.config.tools.definitions) {
+        if (!seenNames.has(def.name)) {
+          toolDefs.push(def);
+          seenNames.add(def.name);
+        }
+      }
+    }
+
+    return toolDefs;
+  }
+
+  /**
+   * Execute a tool by name.
+   * Routing priority: router → custom → broker
+   */
+  private async executeTool(toolName: string, params: unknown): Promise<unknown> {
+    // 1. Pre-configured router (from bridge)
+    if (this.config.tools?.router) {
+      const def = await this.config.tools.router.resolve(toolName);
+      if (def) {
+        return this.config.tools.router.execute(toolName, params);
+      }
+    }
+
+    // 2. Custom tools
+    const customHandler = this.customTools.get(toolName);
+    if (customHandler) {
+      return customHandler(params);
+    }
+
+    // 3. Broker (remote) tools
+    if (this.config.client && this.config.tools?.broker) {
+      return this.config.client.invokeRemote(toolName, params);
+    }
+
+    throw new Error(`Tool "${toolName}" not found in any configured tool source`);
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // CONTEXT COMPACTION
+  // ─────────────────────────────────────────────────────────────
+
+  /**
+   * Compact the message history by summarizing older messages.
+   * Preserves the system prompt and most recent messages.
+   */
+  private async compactContext(messages: Message[]): Promise<void> {
+    // Keep system prompt (first message if role is 'system')
+    const firstMsg = messages[0];
+    const hasSystemPrompt = firstMsg !== undefined && firstMsg.role === 'system';
+    const systemPrompt = hasSystemPrompt ? firstMsg : null;
+
+    // Keep the most recent messages (last 4)
+    const keepRecent = 4;
+    const recentStart = Math.max(hasSystemPrompt ? 1 : 0, messages.length - keepRecent);
+    const recentMessages = messages.slice(recentStart);
+
+    // Messages to summarize (everything between system prompt and recent)
+    const startIdx = hasSystemPrompt ? 1 : 0;
+    const toSummarize = messages.slice(startIdx, recentStart);
+
+    if (toSummarize.length === 0) return; // Nothing to compact
+
+    // Build summary prompt
+    const summaryText = toSummarize
+      .map(m => `[${m.role}]: ${m.content}`)
+      .join('\n');
+
+    const summaryPrompt: Message[] = [
+      {
+        role: 'system',
+        content: 'Summarize the following conversation history concisely, preserving key facts, tool results, and decisions:',
+      },
+      {
+        role: 'user',
+        content: summaryText,
+      },
+    ];
+
+    let summary: string;
+    try {
+      const response = await this.callModel(summaryPrompt, []);
+      summary = response.content ?? 'Unable to summarize conversation.';
+    } catch {
+      // If summarization fails, create a simple summary
+      summary = `[Compacted ${toSummarize.length} messages]`;
+    }
+
+    // Rebuild messages array
+    messages.length = 0;
+    if (systemPrompt) {
+      messages.push(systemPrompt);
+    }
+    messages.push({
+      role: 'assistant',
+      content: `[Context Summary]: ${summary}`,
+    });
+    messages.push(...recentMessages);
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // ERROR HANDLING
+  // ─────────────────────────────────────────────────────────────
+
+  private async handleError(error: Error, turnInfo: TurnInfo): Promise<'retry' | 'skip' | 'abort'> {
+    if (this.config.hooks?.onError) {
+      return this.config.hooks.onError(error, turnInfo);
+    }
+    return 'abort';
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // EVENT EMISSION
+  // ─────────────────────────────────────────────────────────────
+
+  private emitEvent(event: string, data: unknown): void {
+    const prefix = this.config.events?.prefix ?? DEFAULT_EVENT_PREFIX;
+    const fullEvent = `${prefix}.${event}`;
+
+    // Local event emission (only if there are listeners — avoids Node's
+    // special 'error' event behavior which throws if unhandled)
+    if (this.emitter.listenerCount(event) > 0) {
+      this.emitter.emit(event, data);
+    }
+    if (this.emitter.listenerCount(fullEvent) > 0) {
+      this.emitter.emit(fullEvent, data);
+    }
+
+    // Broker event emission (if configured)
+    if (this.config.events?.enabled && this.config.client) {
+      const network = this.config.events.network;
+      this.config.client.publish(fullEvent, data, { network }).catch(() => {
+        // Ignore publish errors — events are best-effort
+      });
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // RESULT BUILDER
+  // ─────────────────────────────────────────────────────────────
+
+  private buildResult(
+    status: ReActResult['status'],
+    turns: number,
+    totalTokens: number,
+    artifacts: unknown[],
+    lastResponse?: string,
+    error?: Error,
+  ): ReActResult {
+    const result: ReActResult = {
+      status,
+      turns,
+      totalTokens,
+      artifacts,
+      lastResponse,
+      error,
+    };
+
+    this.emitEvent('completed', result);
+    return result;
+  }
+}