@tuttiai/core 0.7.0 → 0.8.0

package/dist/index.d.ts

@@ -1,6 +1,88 @@
+import { TuttiHooks, 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, 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;
 
 declare const createLogger: (name: string) => pino.Logger<never, boolean>;
 declare const logger: pino.Logger<never, boolean>;
@@ -74,6 +156,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 +170,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 +336,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, 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, initTelemetry, logger, shutdownTelemetry, validateScore };