@kadi.build/core 0.15.4 → 0.15.6

package/dist/react-loop.d.ts

@@ -0,0 +1,251 @@
+/**
+ * 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 type { KadiClient } from './client.js';
+import type { ToolDefinition } from './types.js';
+/** 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>;
+}
+/** 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;
+}
+/**
+ * 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 declare class ReActLoop {
+    private readonly config;
+    private readonly emitter;
+    private readonly customTools;
+    constructor(config: ReActConfig);
+    /**
+     * 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
+     */
+    run(prompt: string): Promise<ReActResult>;
+    /**
+     * 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;
+    private executeLoop;
+    private callModel;
+    /**
+     * Resolve available tool definitions.
+     * Priority: custom → native → broker → definitions
+     */
+    private resolveToolDefinitions;
+    /**
+     * Execute a tool by name.
+     * Routing priority: router → custom → broker
+     */
+    private executeTool;
+    /**
+     * Compact the message history by summarizing older messages.
+     * Preserves the system prompt and most recent messages.
+     */
+    private compactContext;
+    private handleError;
+    private emitEvent;
+    private buildResult;
+}
+//# sourceMappingURL=react-loop.d.ts.map

package/dist/react-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react-loop.d.ts","sourceRoot":"","sources":["../src/react-loop.ts"],"names":[],"mappings":"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"}