confused-ai-core 0.1.0

package/src/agentic/runner.ts

@@ -0,0 +1,386 @@
+/**
+ * Agentic runner: ReAct-style loop (reason → tool call → observe → repeat)
+ */
+
+import type { Message, ToolCall as LLMToolCall, LLMToolDefinition, GenerateResult } from '../llm/types.js';
+import type { Tool, ToolParameters, ToolResult } from '../tools/types.js';
+import type {
+    AgenticRunConfig,
+    AgenticRunResult,
+    AgenticRunnerConfig,
+    AgenticStreamHooks,
+    AgenticRetryPolicy,
+} from './types.js';
+import type { HumanInTheLoopHooks, GuardrailContext } from '../guardrails/types.js';
+import type { GuardrailEngine } from '../guardrails/types.js';
+import { LLMError } from '../errors.js';
+
+const DEFAULT_MAX_STEPS = 10;
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_RETRIES = 2;
+const DEFAULT_BACKOFF_MS = 1000;
+
+/**
+ * Convert a framework Tool to LLM tool definition.
+ * Uses a minimal JSON Schema for parameters (tool execution validates with Zod).
+ */
+function toolToLLMDef(tool: Tool<ToolParameters, unknown>): LLMToolDefinition {
+    const params = tool.parameters as { _def?: { typeName?: string }; shape?: Record<string, unknown> };
+    const properties: Record<string, { type: string; description?: string }> = {};
+    const required: string[] = [];
+
+    if (params?.shape && typeof params.shape === 'object') {
+        for (const [key, value] of Object.entries(params.shape)) {
+            const zodType = value as { _def?: { typeName?: string; checks?: unknown[] }; description?: string; isOptional?: () => boolean };
+            const typeName = zodType?._def?.typeName ?? 'unknown';
+
+            // Map Zod types to JSON Schema types
+            let jsonType = 'string';
+            switch (typeName) {
+                case 'ZodString':
+                    jsonType = 'string';
+                    break;
+                case 'ZodNumber':
+                case 'ZodBigInt':
+                    jsonType = 'number';
+                    break;
+                case 'ZodBoolean':
+                    jsonType = 'boolean';
+                    break;
+                case 'ZodArray':
+                    jsonType = 'array';
+                    break;
+                case 'ZodObject':
+                case 'ZodRecord':
+                    jsonType = 'object';
+                    break;
+                case 'ZodEnum':
+                    jsonType = 'string';
+                    break;
+                case 'ZodOptional':
+                case 'ZodNullable':
+                    jsonType = 'string'; // Simplified - actual type would need unwrapping
+                    break;
+                default:
+                    jsonType = 'string'; // Default to string for unknown types
+            }
+
+            properties[key] = {
+                type: jsonType,
+                description: zodType?.description,
+            };
+
+            // Check if field is required (not optional)
+            if (typeName !== 'ZodOptional' && !zodType?.isOptional?.()) {
+                required.push(key);
+            }
+        }
+    }
+
+    const parameters: Record<string, unknown> = {
+        type: 'object',
+        properties: Object.keys(properties).length ? properties : {},
+        additionalProperties: true,
+    };
+
+    if (required.length > 0) {
+        parameters.required = required;
+    }
+
+    return {
+        name: tool.name,
+        description: tool.description,
+        parameters,
+    };
+}
+
+/**
+ * Sleep for backoff
+ */
+function sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Execute with retry
+ */
+async function withRetry<T>(
+    fn: () => Promise<T>,
+    policy: AgenticRetryPolicy
+): Promise<T> {
+    const maxRetries = policy.maxRetries ?? DEFAULT_RETRIES;
+    const backoffMs = policy.backoffMs ?? DEFAULT_BACKOFF_MS;
+    const maxBackoffMs = policy.maxBackoffMs ?? 30_000;
+    let lastError: Error | undefined;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        } catch (err) {
+            lastError = err instanceof Error ? err : new Error(String(err));
+            if (attempt < maxRetries) {
+                const delay = Math.min(backoffMs * Math.pow(2, attempt), maxBackoffMs);
+                await sleep(delay);
+            }
+        }
+    }
+    throw lastError;
+}
+
+/**
+ * AgenticRunner runs a ReAct-style loop: LLM generates → tool calls → execute tools → feed results → repeat.
+ */
+export class AgenticRunner {
+    private config: AgenticRunnerConfig;
+    private humanInTheLoop?: HumanInTheLoopHooks;
+    private guardrails?: GuardrailEngine;
+
+    constructor(config: AgenticRunnerConfig) {
+        this.config = { ...config, toolMiddleware: config.toolMiddleware ?? [] };
+    }
+
+    /**
+     * Set human-in-the-loop hooks
+     */
+    setHumanInTheLoop(hooks: HumanInTheLoopHooks): void {
+        this.humanInTheLoop = hooks;
+    }
+
+    /**
+     * Set guardrail engine
+     */
+    setGuardrails(engine: GuardrailEngine): void {
+        this.guardrails = engine;
+    }
+
+    /**
+     * Run the agentic loop until the model returns no tool calls or max steps / timeout.
+     */
+    async run(
+        runConfig: AgenticRunConfig,
+        hooks?: AgenticStreamHooks
+    ): Promise<AgenticRunResult> {
+        const maxSteps = runConfig.maxSteps ?? this.config.maxSteps ?? DEFAULT_MAX_STEPS;
+        const timeoutMs = runConfig.timeoutMs ?? this.config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const retry = this.config.retry ?? { maxRetries: DEFAULT_RETRIES, backoffMs: DEFAULT_BACKOFF_MS };
+
+        const tools = this.config.tools.list();
+        const llmTools: LLMToolDefinition[] = tools.map((t) => toolToLLMDef(t));
+
+        const messages: Message[] = runConfig.messages?.length
+            ? [...runConfig.messages]
+            : [
+                { role: 'system', content: runConfig.instructions },
+                { role: 'user', content: runConfig.prompt },
+            ];
+
+        const startTime = Date.now();
+        let steps = 0;
+        let lastText = '';
+        let usage: AgenticRunResult['usage'];
+        let finishReason = 'stop';
+
+        const agentId = this.config.agentId ?? 'agent';
+        const sessionId = this.config.sessionId ?? `session-${Date.now()}`;
+
+        while (steps < maxSteps) {
+            if (Date.now() - startTime > timeoutMs) {
+                finishReason = 'timeout';
+                break;
+            }
+
+            steps++;
+            hooks?.onStep?.(steps);
+
+            let result: GenerateResult;
+            try {
+                result = await withRetry(
+                    () =>
+                        this.config.llm.generateText(messages, {
+                            temperature: 0.7,
+                            maxTokens: 4096,
+                            tools: llmTools.length ? llmTools : undefined,
+                            toolChoice: llmTools.length ? 'auto' : 'none',
+                        }),
+                    retry
+                );
+            } catch (err) {
+                finishReason = 'error';
+                throw err instanceof LLMError ? err : new LLMError(err instanceof Error ? err.message : String(err), { cause: err instanceof Error ? err : undefined });
+            }
+
+            lastText = result.text ?? '';
+            if (result.usage) {
+                usage = {
+                    promptTokens: result.usage.promptTokens,
+                    completionTokens: result.usage.completionTokens,
+                    totalTokens: result.usage.totalTokens,
+                };
+            }
+
+            if (result.text) {
+                messages.push({ role: 'assistant', content: result.text });
+                hooks?.onChunk?.(result.text);
+            }
+
+            if (!result.toolCalls?.length) {
+                // Check beforeFinish hook
+                const guardrailContext: GuardrailContext = {
+                    agentId,
+                    sessionId,
+                    output: lastText,
+                };
+
+                if (this.humanInTheLoop?.beforeFinish) {
+                    const approved = await this.humanInTheLoop.beforeFinish(lastText, guardrailContext);
+                    if (!approved) {
+                        finishReason = 'human_rejected';
+                        break;
+                    }
+                }
+
+                finishReason = 'stop';
+                break;
+            }
+
+            messages.push({
+                role: 'assistant',
+                content: result.text || '',
+                toolCalls: result.toolCalls,
+            } as Message & { toolCalls: LLMToolCall[] });
+
+            for (const tc of result.toolCalls) {
+                const tool = this.config.tools.getByName(tc.name);
+                if (!tool) {
+                    messages.push({
+                        role: 'tool',
+                        content: JSON.stringify({ error: `Unknown tool: ${tc.name}` }),
+                        toolCallId: tc.id,
+                    } as Message & { toolCallId: string });
+                    continue;
+                }
+
+                // Check guardrails
+                const guardrailContext: GuardrailContext = {
+                    agentId,
+                    sessionId,
+                    toolName: tc.name,
+                    toolArgs: tc.arguments,
+                };
+
+                if (this.guardrails) {
+                    const results = await this.guardrails.checkToolCall(tc.name, tc.arguments, guardrailContext);
+                    const violations = this.guardrails.getViolations(results);
+                    if (violations.length > 0) {
+                        const errorMsg = `Guardrail violation: ${violations.map(v => v.message).join(', ')}`;
+                        messages.push({
+                            role: 'tool',
+                            content: JSON.stringify({ error: errorMsg }),
+                            toolCallId: tc.id,
+                        } as Message & { toolCallId: string });
+                        if (this.humanInTheLoop?.onViolation) {
+                            for (const v of violations) {
+                                await this.humanInTheLoop.onViolation(v, guardrailContext);
+                            }
+                        }
+                        continue;
+                    }
+                }
+
+                // Check human-in-the-loop before tool call
+                if (this.humanInTheLoop?.beforeToolCall) {
+                    const approved = await this.humanInTheLoop.beforeToolCall(tc.name, tc.arguments, guardrailContext);
+                    if (!approved) {
+                        messages.push({
+                            role: 'tool',
+                            content: JSON.stringify({ error: 'Tool call rejected by human' }),
+                            toolCallId: tc.id,
+                        } as Message & { toolCallId: string });
+                        continue;
+                    }
+                }
+
+                hooks?.onToolCall?.(tc.name, tc.arguments);
+
+                const toolContext = {
+                    toolId: tool.id,
+                    agentId,
+                    sessionId,
+                    timeoutMs: 30_000,
+                    permissions: tool.permissions,
+                } as import('../tools/types.js').ToolContext;
+
+                // Tool middleware: beforeExecute
+                const middleware = this.config.toolMiddleware ?? [];
+                for (const m of middleware) {
+                    if (m.beforeExecute) await m.beforeExecute(tool, tc.arguments, toolContext);
+                }
+
+                let toolResult: unknown;
+                let toolResultObj: ToolResult<unknown> | undefined;
+                try {
+                    const out = await tool.execute(
+                        tc.arguments as Record<string, unknown>,
+                        toolContext
+                    );
+                    toolResultObj = out;
+                    toolResult = out.success ? out.data : (out.error ? { error: out.error.message } : out);
+                } catch (err) {
+                    const error = err instanceof Error ? err : new Error(String(err));
+                    for (const m of middleware) {
+                        if (m.onError) await m.onError(tool, error, toolContext);
+                    }
+                    toolResult = { error: error.message };
+                    // Do not throw: let the agent see the error and continue or respond
+                }
+
+                // Tool middleware: afterExecute
+                if (toolResultObj !== undefined) {
+                    for (const m of middleware) {
+                        if (m.afterExecute) await m.afterExecute(tool, toolResultObj, toolContext);
+                    }
+                }
+
+                // Check output guardrails
+                if (this.guardrails && toolResult !== undefined) {
+                    const outputContext: GuardrailContext = {
+                        ...guardrailContext,
+                        output: toolResult,
+                    };
+                    const results = await this.guardrails.validateOutput(toolResult, outputContext);
+                    const violations = this.guardrails.getViolations(results);
+                    if (violations.length > 0) {
+                        toolResult = { error: `Output guardrail violation: ${violations.map(v => v.message).join(', ')}` };
+                        if (this.humanInTheLoop?.onViolation) {
+                            for (const v of violations) {
+                                await this.humanInTheLoop.onViolation(v, outputContext);
+                            }
+                        }
+                    }
+                }
+
+                hooks?.onToolResult?.(tc.name, toolResult);
+
+                const resultContent =
+                    typeof toolResult === 'string' ? toolResult : JSON.stringify(toolResult);
+
+                messages.push({
+                    role: 'tool',
+                    content: resultContent,
+                    toolCallId: tc.id,
+                } as Message & { toolCallId: string });
+            }
+
+            if (steps >= maxSteps) {
+                finishReason = 'max_steps';
+            }
+        }
+
+        return {
+            text: lastText,
+            messages,
+            steps,
+            finishReason,
+            usage,
+        };
+    }
+}

package/src/agentic/types.ts

@@ -0,0 +1,91 @@
+/**
+ * Agentic loop (ReAct-style) types
+ */
+
+import type { Message, LLMToolDefinition } from '../llm/types.js';
+import type { LLMProvider } from '../llm/types.js';
+import type { ToolRegistry, ToolMiddleware } from '../tools/types.js';
+import type { EntityId } from '../core/types.js';
+
+/** Observability: optional tracer and metrics for production monitoring */
+export interface RunObservability {
+    readonly tracer?: import('../observability/types.js').Tracer;
+    readonly metrics?: import('../observability/types.js').MetricsCollector;
+}
+
+export interface AgenticRunConfig {
+    /** System prompt / instructions for the agent */
+    readonly instructions: string;
+    /** User prompt for this run */
+    readonly prompt: string;
+    /** Optional conversation history to continue */
+    readonly messages?: Message[];
+    /** Max reasoning steps (LLM + tool calls per step). Default 10 */
+    readonly maxSteps?: number;
+    /** Timeout for the entire run (ms). Default 60000 */
+    readonly timeoutMs?: number;
+    /** Optional run ID for tracing and logs */
+    readonly runId?: string;
+    /** Optional trace ID for distributed tracing */
+    readonly traceId?: string;
+    /** AbortSignal to cancel the run */
+    readonly signal?: AbortSignal;
+}
+
+/** AbortSignal-compatible (subset for cancellation) */
+export type AbortSignal = { aborted: boolean; addEventListener?: (type: 'abort', handler: () => void) => void; removeEventListener?: (type: 'abort', handler: () => void) => void };
+
+export interface AgenticRunResult {
+    /** Final assistant text response */
+    readonly text: string;
+    /** All messages in the conversation (including tool calls/results) */
+    readonly messages: Message[];
+    /** Number of steps taken */
+    readonly steps: number;
+    /** Finish reason: 'stop' | 'max_steps' | 'timeout' | 'error' | 'human_rejected' */
+    readonly finishReason: string;
+    /** Optional usage stats */
+    readonly usage?: { promptTokens?: number; completionTokens?: number; totalTokens?: number };
+    /** Run ID when provided in config */
+    readonly runId?: string;
+    /** Trace ID when provided in config */
+    readonly traceId?: string;
+}
+
+/** Retry policy for LLM and tool calls in the agentic loop */
+export interface AgenticRetryPolicy {
+    readonly maxRetries?: number;
+    readonly backoffMs?: number;
+    readonly maxBackoffMs?: number;
+}
+
+/** Stream / progress hooks */
+export interface AgenticStreamHooks {
+    onChunk?: (text: string) => void;
+    onToolCall?: (name: string, args: Record<string, unknown>) => void;
+    onToolResult?: (name: string, result: unknown) => void;
+    onStep?: (step: number) => void;
+}
+
+export interface AgenticRunnerConfig {
+    readonly llm: LLMProvider;
+    readonly tools: ToolRegistry;
+    readonly agentId?: EntityId;
+    readonly sessionId?: string;
+    readonly maxSteps?: number;
+    readonly timeoutMs?: number;
+    readonly retry?: AgenticRetryPolicy;
+    /** Optional tool middleware for cross-tool integration (logging, rate limit, etc.) */
+    readonly toolMiddleware?: ToolMiddleware[];
+    /** Optional observability for production (tracer + metrics) */
+    readonly observability?: RunObservability;
+}
+
+/** Convert a framework Tool to LLM tool definition (name, description, parameters as JSON Schema) */
+export function toolToLLMDefinition(
+    name: string,
+    description: string,
+    parametersSchema: Record<string, unknown>
+): LLMToolDefinition {
+    return { name, description, parameters: parametersSchema };
+}