@tuttiai/types 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -50,15 +50,8 @@ interface TokenUsage {
 interface StreamChunk {
     type: "text" | "tool_use" | "usage";
     text?: string;
-    tool?: {
-        id: string;
-        name: string;
-        input: unknown;
-    };
-    usage?: {
-        input_tokens: number;
-        output_tokens: number;
-    };
+    tool?: Omit<ToolUseBlock, "type">;
+    usage?: TokenUsage;
     stop_reason?: StopReason;
 }
 interface LLMProvider {
@@ -109,6 +102,38 @@ interface Voice {
     teardown?(): Promise<void>;
 }
 
+/** Lifecycle hooks for agent runs, LLM calls, and tool executions. */
+
+/** Context passed to every hook invocation. */
+interface HookContext {
+    agent_name: string;
+    session_id: string;
+    turn: number;
+    metadata: Record<string, unknown>;
+}
+/**
+ * Lifecycle hooks for customizing agent behavior.
+ *
+ * Set on `ScoreConfig.hooks` (global) or `AgentConfig.hooks` (per-agent).
+ * Agent-level hooks merge with global hooks — both fire, agent-level first.
+ *
+ * Hook errors are caught and logged — they never crash the agent.
+ */
+interface TuttiHooks {
+    /** Called before each LLM call. Return a modified request to alter it. */
+    beforeLLMCall?: (ctx: HookContext, request: ChatRequest) => Promise<ChatRequest>;
+    /** Called after each LLM response. */
+    afterLLMCall?: (ctx: HookContext, response: ChatResponse) => Promise<void>;
+    /** Called before each tool execution. Return false to block the call, or modified input. */
+    beforeToolCall?: (ctx: HookContext, tool: string, input: unknown) => Promise<boolean | unknown>;
+    /** Called after each tool execution. Return a modified result. */
+    afterToolCall?: (ctx: HookContext, tool: string, result: ToolResult) => Promise<ToolResult>;
+    /** Called when an agent run starts (before the first turn). */
+    beforeAgentRun?: (ctx: HookContext) => Promise<void>;
+    /** Called when an agent run finishes (after the last turn). */
+    afterAgentRun?: (ctx: HookContext, result: AgentResult) => Promise<void>;
+}
+
 /** Agent configuration and result types. */
 
 interface BudgetConfig {
@@ -140,10 +165,14 @@ interface AgentConfig {
     semantic_memory?: AgentMemoryConfig;
     /** Enable token-by-token streaming (default: false). */
     streaming?: boolean;
+    /** Allow the agent to pause and ask the human for input (default: false). */
+    allow_human_input?: boolean;
     /** Agent IDs this agent can delegate to via the orchestrator. */
     delegates?: string[];
     /** Role in the orchestration — orchestrator receives input first. */
     role?: "orchestrator" | "specialist";
+    /** Agent-level lifecycle hooks — merged with global hooks from ScoreConfig. */
+    hooks?: TuttiHooks;
 }
 interface AgentResult {
     session_id: string;
@@ -179,6 +208,8 @@ interface ScoreConfig {
     memory?: MemoryConfig;
     /** OpenTelemetry tracing configuration. */
     telemetry?: TelemetryConfig;
+    /** Global lifecycle hooks — apply to all agents. */
+    hooks?: TuttiHooks;
 }
 
 /** Session types for conversation state management. */
@@ -268,10 +299,25 @@ type TuttiEvent = {
     type: "token:stream";
     agent_name: string;
     text: string;
+} | {
+    type: "hitl:requested";
+    agent_name: string;
+    session_id: string;
+    question: string;
+    options?: string[];
+} | {
+    type: "hitl:answered";
+    agent_name: string;
+    session_id: string;
+    answer: string;
+} | {
+    type: "hitl:timeout";
+    agent_name: string;
+    session_id: string;
 };
 type TuttiEventType = TuttiEvent["type"];
 type TuttiEventHandler<T extends TuttiEventType = TuttiEventType> = (event: Extract<TuttiEvent, {
     type: T;
 }>) => void;
 
-export type { 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 };
+export type { 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tuttiai/types",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Type definitions for the Tutti multi-agent orchestration framework",
   "type": "module",
   "exports": {