@tuttiai/core 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { TuttiEventType, TuttiEvent, ScoreConfig, AgentResult, Session, LLMProvider, SessionStore, AgentConfig, ChatMessage, ChatRequest, ChatResponse } from '@tuttiai/types';
-export { AgentConfig, AgentResult, ChatMessage, ChatRequest, ChatResponse, ContentBlock, LLMProvider, ScoreConfig, Session, SessionStore, StopReason, TextBlock, TokenUsage, Tool, ToolContext, ToolDefinition, ToolResult, ToolResultBlock, ToolUseBlock, TuttiEvent, TuttiEventHandler, TuttiEventType, Voice, VoiceContext } from '@tuttiai/types';
+import { TuttiEventType, TuttiEvent, ScoreConfig, AgentResult, Session, LLMProvider, SessionStore, AgentConfig, ChatMessage, Voice, Permission, BudgetConfig, ChatRequest, ChatResponse } from '@tuttiai/types';
+export { AgentConfig, AgentMemoryConfig, AgentResult, BudgetConfig, ChatMessage, ChatRequest, ChatResponse, ContentBlock, LLMProvider, MemoryConfig, Permission, ScoreConfig, Session, SessionStore, StopReason, TextBlock, TokenUsage, Tool, ToolContext, ToolDefinition, ToolMemoryHelpers, ToolResult, ToolResultBlock, ToolUseBlock, TuttiEvent, TuttiEventHandler, TuttiEventType, Voice, VoiceContext } from '@tuttiai/types';
 
 declare class EventBus {
     private listeners;
@@ -14,12 +14,46 @@ declare class EventBus {
     onAny(handler: (event: TuttiEvent) => void): () => void;
 }
 
+/**
+ * Semantic (long-term) memory — facts agents remember across sessions.
+ *
+ * Session memory = conversation history within a session.
+ * Semantic memory = persistent facts that survive across sessions.
+ *
+ * Example: a user tells the coder agent "I prefer 2-space indentation".
+ * Next session, the agent already knows this preference.
+ */
+interface MemoryEntry {
+    id: string;
+    agent_name: string;
+    content: string;
+    metadata: Record<string, unknown>;
+    created_at: Date;
+}
+interface SemanticMemoryStore {
+    /** Store a new memory entry. Returns the entry with generated id and timestamp. */
+    add(entry: Omit<MemoryEntry, "id" | "created_at">): Promise<MemoryEntry>;
+    /** Search for relevant memories by keyword overlap. Returns top N by relevance. */
+    search(query: string, agent_name: string, limit?: number): Promise<MemoryEntry[]>;
+    /** Delete a single memory by ID. */
+    delete(id: string): Promise<void>;
+    /** Clear all memories for a specific agent. */
+    clear(agent_name: string): Promise<void>;
+}
+
 declare class TuttiRuntime {
     readonly events: EventBus;
+    readonly semanticMemory: SemanticMemoryStore;
     private _sessions;
     private _runner;
     private _score;
     constructor(score: ScoreConfig);
+    /**
+     * Create a runtime with async initialization (required for Postgres).
+     * Prefer this over `new TuttiRuntime()` when using a database-backed store.
+     */
+    static create(score: ScoreConfig): Promise<TuttiRuntime>;
+    private static createStore;
     /** The score configuration this runtime was created with. */
     get score(): ScoreConfig;
     /**
@@ -35,8 +69,10 @@ declare class AgentRunner {
     private provider;
     private events;
     private sessions;
-    constructor(provider: LLMProvider, events: EventBus, sessions: SessionStore);
+    private semanticMemory?;
+    constructor(provider: LLMProvider, events: EventBus, sessions: SessionStore, semanticMemory?: SemanticMemoryStore | undefined);
     run(agent: AgentConfig, input: string, session_id?: string): Promise<AgentResult>;
+    private executeWithTimeout;
     private executeTool;
 }
 
@@ -69,6 +105,41 @@ declare class InMemorySessionStore implements SessionStore {
     update(id: string, messages: ChatMessage[]): void;
 }
 
+declare class PostgresSessionStore implements SessionStore {
+    private pool;
+    constructor(connectionString: string);
+    /**
+     * Create the tutti_sessions table if it doesn't exist.
+     * Call this once before using the store.
+     */
+    initialize(): Promise<void>;
+    create(agent_name: string): Session;
+    get(id: string): Session | undefined;
+    /**
+     * Async version of get() that queries Postgres directly.
+     * Use this when you need to load a session from the database.
+     */
+    getAsync(id: string): Promise<Session | undefined>;
+    update(id: string, messages: ChatMessage[]): void;
+    /** Close the connection pool. Call on shutdown. */
+    close(): Promise<void>;
+}
+
+/**
+ * In-memory semantic memory store using keyword overlap scoring.
+ *
+ * search() tokenises both the query and each stored entry into words,
+ * then scores by the number of overlapping tokens. No embeddings
+ * needed — simple and predictable for v1.
+ */
+declare class InMemorySemanticStore implements SemanticMemoryStore {
+    private entries;
+    add(entry: Omit<MemoryEntry, "id" | "created_at">): Promise<MemoryEntry>;
+    search(query: string, agent_name: string, limit?: number): Promise<MemoryEntry[]>;
+    delete(id: string): Promise<void>;
+    clear(agent_name: string): Promise<void>;
+}
+
 declare class ScoreLoader {
     /**
      * Dynamically import a tutti.score.ts file and return its config.
@@ -83,6 +154,47 @@ declare class ScoreLoader {
  */
 declare function defineScore(config: ScoreConfig): ScoreConfig;
 
+declare class SecretsManager {
+    private static redactPatterns;
+    static redact(text: string): string;
+    static redactObject(obj: unknown): unknown;
+    static require(key: string): string;
+    static optional(key: string, fallback?: string): string | undefined;
+}
+
+declare class PermissionGuard {
+    static check(voice: Voice, granted: Permission[]): void;
+    static warn(voice: Voice): void;
+}
+
+declare class PromptGuard {
+    private static patterns;
+    static scan(content: string): {
+        safe: boolean;
+        found: string[];
+    };
+    static wrap(toolName: string, content: string): string;
+}
+
+declare class TokenBudget {
+    private config;
+    private model;
+    private used_input;
+    private used_output;
+    constructor(config: BudgetConfig, model: string);
+    add(input_tokens: number, output_tokens: number): void;
+    get total_tokens(): number;
+    get estimated_cost_usd(): number;
+    check(): "ok" | "warning" | "exceeded";
+    summary(): string;
+}
+
+/**
+ * Validate a loaded score config. Returns the config on success,
+ * throws a descriptive error on failure.
+ */
+declare function validateScore(config: unknown): void;
+
 interface AnthropicProviderOptions {
     api_key?: string;
 }
@@ -114,4 +226,4 @@ declare class GeminiProvider implements LLMProvider {
     chat(request: ChatRequest): Promise<ChatResponse>;
 }
 
-export { AgentRouter, AgentRunner, AnthropicProvider, type AnthropicProviderOptions, EventBus, GeminiProvider, type GeminiProviderOptions, InMemorySessionStore, OpenAIProvider, type OpenAIProviderOptions, ScoreLoader, TuttiRuntime, defineScore };
+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, defineScore, validateScore };