@tuttiai/core 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -1,6 +1,158 @@
+import { TuttiHooks, TokenUsage, ScoreConfig, TelemetryConfig, TuttiEventType, TuttiEvent, AgentResult, Session, LLMProvider, SessionStore, AgentConfig, ChatMessage, Voice, Permission, BudgetConfig, ChatRequest, ChatResponse, StreamChunk } from '@tuttiai/types';
+export { AgentConfig, AgentMemoryConfig, AgentResult, BudgetConfig, ChatMessage, ChatRequest, ChatResponse, ContentBlock, HookContext, LLMProvider, MemoryConfig, Permission, ScoreConfig, Session, SessionStore, StopReason, StreamChunk, TelemetryConfig, TextBlock, TokenUsage, Tool, ToolContext, ToolDefinition, ToolMemoryHelpers, ToolResult, ToolResultBlock, ToolUseBlock, TuttiEvent, TuttiEventHandler, TuttiEventType, TuttiHooks, Voice, VoiceContext } from '@tuttiai/types';
 import pino from 'pino';
-import { TelemetryConfig, TuttiEventType, TuttiEvent, ScoreConfig, AgentResult, Session, LLMProvider, SessionStore, AgentConfig, ChatMessage, Voice, Permission, BudgetConfig, ChatRequest, ChatResponse, StreamChunk } from '@tuttiai/types';
-export { AgentConfig, AgentMemoryConfig, AgentResult, BudgetConfig, ChatMessage, ChatRequest, ChatResponse, ContentBlock, LLMProvider, MemoryConfig, Permission, ScoreConfig, Session, SessionStore, StopReason, StreamChunk, TelemetryConfig, TextBlock, TokenUsage, Tool, ToolContext, ToolDefinition, ToolMemoryHelpers, ToolResult, ToolResultBlock, ToolUseBlock, TuttiEvent, TuttiEventHandler, TuttiEventType, Voice, VoiceContext } from '@tuttiai/types';
+
+/**
+ * Typed error hierarchy for Tutti. All errors extend TuttiError.
+ */
+declare class TuttiError extends Error {
+    readonly code: string;
+    readonly context: Record<string, unknown>;
+    constructor(code: string, message: string, context?: Record<string, unknown>);
+}
+declare class ScoreValidationError extends TuttiError {
+    constructor(message: string, context?: {
+        field?: string;
+        value?: unknown;
+    });
+}
+declare class AgentNotFoundError extends TuttiError {
+    constructor(agentId: string, available: string[]);
+}
+declare class PermissionError extends TuttiError {
+    constructor(voice: string, required: string[], granted: string[]);
+}
+declare class BudgetExceededError extends TuttiError {
+    constructor(tokens: number, costUsd: number, limit: string);
+}
+declare class ToolTimeoutError extends TuttiError {
+    constructor(tool: string, timeoutMs: number);
+}
+declare class ProviderError extends TuttiError {
+    constructor(message: string, context?: {
+        provider: string;
+        status?: number;
+    } & Record<string, unknown>);
+}
+declare class AuthenticationError extends ProviderError {
+    constructor(provider: string);
+}
+declare class RateLimitError extends ProviderError {
+    readonly retryAfter?: number;
+    constructor(provider: string, retryAfter?: number);
+}
+declare class ContextWindowError extends ProviderError {
+    readonly maxTokens?: number;
+    constructor(provider: string, maxTokens?: number);
+}
+declare class VoiceError extends TuttiError {
+    constructor(message: string, context: {
+        voice: string;
+        tool?: string;
+    } & Record<string, unknown>);
+}
+declare class PathTraversalError extends VoiceError {
+    constructor(path: string);
+}
+declare class UrlValidationError extends VoiceError {
+    constructor(url: string);
+}
+
+/**
+ * Built-in hook factories for common patterns.
+ */
+
+/**
+ * Logs all LLM calls and tool executions via a pino logger.
+ */
+declare function createLoggingHook(log: pino.Logger): TuttiHooks;
+/**
+ * Caches tool results by tool name + input hash.
+ * The `store` is a simple Map or any get/set interface.
+ */
+declare function createCacheHook(store: {
+    get(key: string): string | undefined;
+    set(key: string, value: string): void;
+}): TuttiHooks;
+/**
+ * Blocks specific tool names from being called.
+ */
+declare function createBlocklistHook(blockedTools: string[]): TuttiHooks;
+/**
+ * Blocks LLM calls once estimated cost exceeds the given USD limit.
+ * Tracks cost across the lifetime of the hook instance.
+ */
+declare function createMaxCostHook(maxUsd: number): TuttiHooks;
+
+/** Evaluation framework types. */
+
+interface EvalAssertion {
+    type: "contains" | "not_contains" | "matches_regex" | "tool_called" | "tool_not_called" | "turns_lte" | "cost_lte";
+    value: string | number;
+    description?: string;
+}
+interface EvalCase {
+    id: string;
+    name: string;
+    agent_id: string;
+    input: string;
+    assertions: EvalAssertion[];
+}
+interface EvalSuite {
+    name: string;
+    cases: EvalCase[];
+}
+interface AssertionResult {
+    assertion: EvalAssertion;
+    passed: boolean;
+    actual: string | number;
+}
+interface EvalResult {
+    case_id: string;
+    case_name: string;
+    passed: boolean;
+    score: number;
+    output: string;
+    turns: number;
+    usage: TokenUsage;
+    cost_usd: number;
+    duration_ms: number;
+    assertions: AssertionResult[];
+    error?: string;
+}
+interface EvalSummary {
+    total: number;
+    passed: number;
+    failed: number;
+    avg_score: number;
+    total_cost_usd: number;
+    total_duration_ms: number;
+}
+interface EvalReport {
+    suite_name: string;
+    results: EvalResult[];
+    summary: EvalSummary;
+}
+
+/** Evaluation runner — executes test suites against a score. */
+
+declare class EvalRunner {
+    private runtime;
+    constructor(score: ScoreConfig);
+    run(suite: EvalSuite): Promise<EvalReport>;
+    private runCase;
+    private checkAssertion;
+    private summarize;
+}
+
+/** Evaluation report formatting — table, JSON, Markdown. */
+
+/** Print a formatted results table to stdout. */
+declare function printTable(report: EvalReport): void;
+/** Convert report to a plain JSON object for storage or CI. */
+declare function toJSON(report: EvalReport): string;
+/** Convert report to a GitHub-friendly markdown table. */
+declare function toMarkdown(report: EvalReport): string;
 
 declare const createLogger: (name: string) => pino.Logger<never, boolean>;
 declare const logger: pino.Logger<never, boolean>;
@@ -74,6 +226,11 @@ declare class TuttiRuntime {
      * Optionally pass a session_id to continue a conversation.
      */
     run(agent_name: string, input: string, session_id?: string): Promise<AgentResult>;
+    /**
+     * Provide an answer to a pending human-in-the-loop request.
+     * Call this when a `hitl:requested` event fires to resume the agent.
+     */
+    answer(sessionId: string, answer: string): void;
     /** Retrieve an existing session. */
     getSession(id: string): Session | undefined;
 }
@@ -83,10 +240,16 @@ declare class AgentRunner {
     private events;
     private sessions;
     private semanticMemory?;
-    constructor(provider: LLMProvider, events: EventBus, sessions: SessionStore, semanticMemory?: SemanticMemoryStore | undefined);
+    private globalHooks?;
+    private pendingHitl;
+    constructor(provider: LLMProvider, events: EventBus, sessions: SessionStore, semanticMemory?: SemanticMemoryStore | undefined, globalHooks?: TuttiHooks | undefined);
+    private safeHook;
+    /** Resolve a pending human-in-the-loop request for a session. */
+    answer(sessionId: string, answer: string): void;
     run(agent: AgentConfig, input: string, session_id?: string): Promise<AgentResult>;
     private executeWithTimeout;
     private streamToResponse;
+    private createHitlTool;
     private executeTool;
 }
 
@@ -243,4 +406,4 @@ declare class GeminiProvider implements LLMProvider {
     stream(request: ChatRequest): AsyncGenerator<StreamChunk>;
 }
 
-export { AgentRouter, AgentRunner, AnthropicProvider, type AnthropicProviderOptions, EventBus, GeminiProvider, type GeminiProviderOptions, InMemorySemanticStore, InMemorySessionStore, type MemoryEntry, OpenAIProvider, type OpenAIProviderOptions, PermissionGuard, PostgresSessionStore, PromptGuard, ScoreLoader, SecretsManager, type SemanticMemoryStore, TokenBudget, TuttiRuntime, TuttiTracer, createLogger, defineScore, initTelemetry, logger, shutdownTelemetry, validateScore };
+export { AgentNotFoundError, AgentRouter, AgentRunner, AnthropicProvider, type AnthropicProviderOptions, AuthenticationError, BudgetExceededError, ContextWindowError, type EvalAssertion, type EvalCase, type EvalReport, type EvalResult, EvalRunner, type EvalSuite, type EvalSummary, EventBus, GeminiProvider, type GeminiProviderOptions, InMemorySemanticStore, InMemorySessionStore, type MemoryEntry, OpenAIProvider, type OpenAIProviderOptions, PathTraversalError, PermissionError, PermissionGuard, PostgresSessionStore, PromptGuard, ProviderError, RateLimitError, ScoreLoader, ScoreValidationError, SecretsManager, type SemanticMemoryStore, TokenBudget, ToolTimeoutError, TuttiError, TuttiRuntime, TuttiTracer, UrlValidationError, VoiceError, createBlocklistHook, createCacheHook, createLogger, createLoggingHook, createMaxCostHook, defineScore, toJSON as evalToJSON, toMarkdown as evalToMarkdown, initTelemetry, logger, printTable as printEvalTable, shutdownTelemetry, validateScore };