@robota-sdk/agent-core 3.0.0-beta.5 → 3.0.0-beta.51

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @robota-sdk/agent-core
 
+## 3.0.0-beta.51
+
+## 3.0.0-beta.50
+
+## 3.0.0-beta.49
+
+## 3.0.0-beta.48
+
+## 3.0.0-beta.47
+
+## 3.0.0-beta.46
+
+## 3.0.0-beta.45
+
+## 3.0.0-beta.44
+
+### Patch Changes
+
+- feat: IHistoryEntry universal history architecture + test quality cleanup
+  - IHistoryEntry as universal history type across all 4 packages (core → sessions → sdk → cli)
+  - Tool summary stored as event entry in history (category: 'event', type: 'tool-summary')
+  - TuiStateManager pure TypeScript class for CLI rendering state
+  - MessageList renders IHistoryEntry[] with Tool:/System:/You:/Robota: labels
+  - Display order fixed: Tool → Robota (both streaming and abort)
+  - Remove 25 tautological, duplicate, and hardcoded tests
+
 ## 2.0.9
 
 ### Patch Changes

package/README.md

@@ -1,4 +1,4 @@
-# @robota-sdk/agent-core
+# Agent Core
 
 The foundation layer of the Robota SDK. Provides the `Robota` agent class, abstract base classes for providers/tools/plugins, the permission system, hook system, event services, and error hierarchy.
 
@@ -33,12 +33,18 @@ console.log(response);
 ## Key Features
 
 - **Robota class**: AI agent with conversation history, tool execution, and plugin support
+- **ConversationStore**: Append-only conversation history with streaming buffer (`beginAssistant`/`appendStreaming`/`commitAssistant`)
+- **IBaseMessage**: Every message has a unique `id` (UUID) and `state` (`'complete'` | `'interrupted'`)
 - **Multi-provider**: Register multiple providers, switch dynamically with `setModel()`
+- **AbstractAIProvider.streamWithAbort()**: Standard streaming wrapper for all providers — handles AbortSignal, returns partial content on abort
 - **Permission system**: Deterministic 3-step policy evaluation (`evaluatePermission`)
 - **Hook system**: Shell command-based lifecycle hooks (`runHooks`)
 - **Plugin system**: `AbstractPlugin` base class with lifecycle hooks (beforeRun, afterRun, onError, etc.)
 - **Event services**: Unified event emission with owner path tracking
 - **Error hierarchy**: Typed errors extending `RobotaError` (ProviderError, RateLimitError, etc.)
+- **Model definitions**: Central `CLAUDE_MODELS` registry with context windows, output limits, and human-readable names
+- **callProviderWithCache**: Accepts `Partial<IChatOptions>` overrides for per-call configuration
+- **AbortSignal propagation**: Signal flows through the entire execution chain (Session -> Robota -> Provider)
 - **Type safety**: Strict TypeScript, zero `any` in production code
 
 ## Robota API
@@ -84,16 +90,18 @@ agent-sdk         ← Assembly layer
 agent-cli         ← Terminal UI
 ```
 
-## What This Package Provides
-
-| Category        | Exports                                                                                                                |
-| --------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| **Core**        | `Robota`, `AbstractAgent`, `AbstractAIProvider`, `AbstractPlugin`, `AbstractTool`, `AbstractExecutor`, `LocalExecutor` |
-| **Permissions** | `evaluatePermission`, `MODE_POLICY`, `TRUST_TO_MODE`, `TPermissionMode`, `TToolArgs`                                   |
-| **Hooks**       | `runHooks`, `THookEvent` (PreToolUse, PostToolUse, PreCompact, PostCompact, SessionStart, Stop)                        |
-| **Events**      | `AbstractEventService`, `DefaultEventService`, `StructuredEventService`, `EventEmitterPlugin`                          |
-| **Types**       | `TUniversalMessage`, `IAgentConfig`, `IAIProvider`, `IToolSchema`, `IContextWindowState`                               |
-| **Errors**      | `RobotaError`, `ProviderError`, `RateLimitError`, `AuthenticationError`, `ToolExecutionError`, etc.                    |
+## Public API Surface
+
+| Category        | Exports                                                                                                                                                                                   |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Core**        | `Robota`, `ConversationStore`, `AbstractAgent`, `AbstractAIProvider` (+ `streamWithAbort`), `AbstractPlugin`, `AbstractTool`, `AbstractExecutor`, `LocalExecutor`                         |
+| **Permissions** | `evaluatePermission`, `MODE_POLICY`, `TRUST_TO_MODE`, `UNKNOWN_TOOL_FALLBACK`, `TPermissionMode`, `TTrustLevel`, `TPermissionDecision`, `TToolArgs`, `IPermissionLists`, `TKnownToolName` |
+| **Hooks**       | `runHooks`, `CommandExecutor`, `HttpExecutor`, `IHookTypeExecutor`, `THookEvent`, `THooksConfig`, `IHookGroup`, `IHookDefinition`, `IHookInput`, `IHookResult`                            |
+| **Events**      | `EventEmitterPlugin`, `IEventService`, `IOwnerPathSegment`                                                                                                                                |
+| **Models**      | `CLAUDE_MODELS`, `DEFAULT_CONTEXT_WINDOW`, `DEFAULT_MAX_OUTPUT`, `getModelContextWindow()`, `getModelMaxOutput()`, `getModelName()`, `formatTokenCount()`, `IModelDefinition`             |
+| **Types**       | `TUniversalMessage`, `IBaseMessage` (`id`, `state`), `TMessageState`, `IAgentConfig`, `IAIProvider`, `IToolSchema`, `IContextWindowState`, `IContextTokenUsage`, `TTextDeltaCallback`     |
+| **Errors**      | `RobotaError`, `ProviderError`, `RateLimitError`, `AuthenticationError`, `ToolExecutionError`, etc.                                                                                       |
+| **Managers**    | `AgentFactory`, `AgentTemplates`, `ConversationHistory`, `EventHistoryModule`                                                                                                             |
 
 ## What Moved Out in v3
 

package/dist/browser/index.d.ts

@@ -44,12 +44,18 @@ interface IToolCall {
         arguments: string;
     };
 }
+/** State of a message in conversation history */
+type TMessageState = 'complete' | 'interrupted';
 /**
  * Base message contract shared by all message variants.
  */
 interface IBaseMessage {
+    /** Unique message identifier */
+    id: string;
     /** Message creation timestamp */
     timestamp: Date;
+    /** Whether this message is complete or was interrupted */
+    state: TMessageState;
     /** Additional metadata */
     metadata?: TUniversalMessageMetadata;
 }
@@ -81,8 +87,49 @@ interface IToolMessage extends IBaseMessage {
 }
 /**
  * Universal message union used across the SDK as the canonical contract.
+ * Used for AI provider communication. Extracted from IHistoryEntry[] via filtering.
  */
 type TUniversalMessage = IUserMessage | IAssistantMessage | ISystemMessage | IToolMessage;
+/**
+ * Universal history entry — the base type for all records in conversation history.
+ *
+ * History is a universal timeline that records everything: AI chat messages,
+ * system events, skill invocations, permission decisions, etc.
+ * AI provider receives only chat entries (filtered and converted to TUniversalMessage).
+ * TUI can render any range of entries.
+ *
+ * - append-only, read-only
+ * - category + type for classification (free-form strings, no pre-defined enum)
+ * - data holds type-specific structured content
+ */
+interface IHistoryEntry<T = unknown> {
+    /** Unique entry identifier */
+    id: string;
+    /** Entry creation timestamp */
+    timestamp: Date;
+    /** Top-level classification: 'chat', 'event', etc. */
+    category: string;
+    /** Sub-classification within category. Free-form, not pre-defined. */
+    type: string;
+    /** Type-specific structured data */
+    data?: T;
+}
+/** Check if a history entry is a chat message (for AI provider filtering). */
+declare function isChatEntry(entry: IHistoryEntry): boolean;
+/**
+ * Convert a chat history entry to TUniversalMessage for AI provider consumption.
+ * Only call on entries where isChatEntry() returns true.
+ */
+declare function chatEntryToMessage(entry: IHistoryEntry): TUniversalMessage;
+/**
+ * Convert a TUniversalMessage to an IHistoryEntry for storage.
+ */
+declare function messageToHistoryEntry(message: TUniversalMessage): IHistoryEntry;
+/**
+ * Filter history entries and convert chat entries to TUniversalMessage[].
+ * Used when passing conversation to AI provider.
+ */
+declare function getMessagesForAPI(history: IHistoryEntry[]): TUniversalMessage[];
 /**
  * Type guards for the canonical TUniversalMessage union.
  *
@@ -299,6 +346,8 @@ interface IChatOptions extends IProviderSpecificOptions {
      *  should use streaming internally and call this for each text chunk,
      *  while still returning the complete assembled message. */
     onTextDelta?: TTextDeltaCallback;
+    /** AbortSignal for cancelling the provider call */
+    signal?: AbortSignal;
 }
 /**
  * Provider-agnostic AI Provider interface
@@ -481,6 +530,78 @@ interface IEventServiceOwnerBinding {
     ownerPath: IOwnerPathSegment[];
 }
 
+/**
+ * Abstract base for event services.
+ * Concrete implementations decide how events are delivered.
+ */
+declare abstract class AbstractEventService implements IEventService {
+    private listeners;
+    abstract emit(eventType: string, data: IBaseEventData, context?: IEventContext): void;
+    subscribe(listener: TEventListener): void;
+    unsubscribe(listener: TEventListener): void;
+    protected notifyListeners(eventType: string, data: IBaseEventData, context?: IEventContext): void;
+}
+/**
+ * Default no-op event service (production-safe).
+ * When injected, emit() intentionally does nothing.
+ */
+declare class DefaultEventService extends AbstractEventService {
+    emit(_eventType: string, _data: IBaseEventData, _context?: IEventContext): void;
+}
+/**
+ * Singleton default event service instance.
+ */
+declare const DEFAULT_ABSTRACT_EVENT_SERVICE: IEventService;
+/**
+ * Check if a given service is the default no-op implementation.
+ */
+declare function isDefaultEventService(service: IEventService): boolean;
+/**
+ * Compose a full event name from owner prefix and local name.
+ * Local names must not contain dots.
+ */
+declare function composeEventName(ownerType: string, localName: string): string;
+/**
+ * A scoped event service that always emits with an owner binding applied.
+ */
+declare class StructuredEventService extends AbstractEventService {
+    private readonly base;
+    private readonly binding;
+    constructor(base: IEventService, binding: IEventServiceOwnerBinding);
+    emit(eventType: string, data: IBaseEventData, context?: IEventContext): void;
+    subscribe(listener: TEventListener): void;
+    unsubscribe(listener: TEventListener): void;
+}
+/**
+ * Bind an EventService to an explicit owner path.
+ * This is the standard entry point for scoped emission (path-only architecture).
+ */
+declare function bindWithOwnerPath(base: IEventService, binding: IEventServiceOwnerBinding): IEventService;
+/**
+ * Alias for bindWithOwnerPath for historical call sites.
+ * Intentionally forwards to the single authoritative implementation.
+ */
+declare function bindEventServiceOwner(base: IEventService, binding: IEventServiceOwnerBinding): IEventService;
+/**
+ * Observable EventService that notifies subscribed listeners.
+ */
+declare class ObservableEventService extends AbstractEventService {
+    emit(eventType: string, data: IBaseEventData, context?: IEventContext): void;
+}
+
+declare const TASK_EVENTS: {
+    readonly ASSIGNED: "assigned";
+    readonly COMPLETED: "completed";
+};
+declare const TASK_EVENT_PREFIX: "task";
+
+declare const USER_EVENTS: {
+    readonly MESSAGE: "message";
+    readonly INPUT: "input";
+};
+declare const USER_EVENT_PREFIX: "user";
+type TUserEvent = (typeof USER_EVENTS)[keyof typeof USER_EVENTS];
+
 type TToolContextExtensionValue = TUniversalValue | Date | Error | TLoggerData | TContextData | TToolParameters | TToolMetadata;
 /**
  * Tool metadata structure - specific type definition
@@ -1549,6 +1670,8 @@ interface IRunOptions {
     sessionId?: string;
     userId?: string;
     metadata?: TMetadata;
+    /** AbortSignal for cancelling execution */
+    signal?: AbortSignal;
 }
 /**
  * Generic agent interface with type parameters for enhanced type safety
@@ -2470,6 +2593,15 @@ declare abstract class AbstractAIProvider<TConfig = IProviderConfig> implements
      * @returns Promise resolving to a response
      */
     abstract chat(messages: TUniversalMessage[], options?: IChatOptions): Promise<TUniversalMessage>;
+    /**
+     * Wrap an async iterable to yield to the macrotask queue periodically.
+     * Providers MUST use this when iterating over streaming events to ensure
+     * the main thread event loop stays responsive (ESC abort, Ctrl+C, etc.).
+     *
+     * Usage in provider:
+     *   for await (const event of this.streamWithAbort(stream, signal)) { ... }
+     */
+    protected streamWithAbort<T>(source: AsyncIterable<T>, signal?: AbortSignal): AsyncGenerator<T>;
     /**
      * Each provider must implement streaming chat using their own native SDK types internally
      * @param messages - Array of messages from conversation history
@@ -2919,6 +3051,131 @@ declare function stopPeriodicTask(timer: TTimerId | undefined): void;
  */
 type TTimerId = ReturnType<typeof setTimeout>;
 
+/** Create a user message. */
+declare function createUserMessage(content: string, options?: {
+    name?: string;
+    metadata?: TUniversalMessageMetadata;
+    parts?: TUniversalMessagePart[];
+}): IUserMessage;
+/** Create an assistant message. */
+declare function createAssistantMessage(content: string | null, options?: {
+    toolCalls?: IToolCall[];
+    metadata?: TUniversalMessageMetadata;
+    parts?: TUniversalMessagePart[];
+    state?: TMessageState;
+}): IAssistantMessage;
+/** Create a system message. */
+declare function createSystemMessage(content: string, options?: {
+    name?: string;
+    metadata?: TUniversalMessageMetadata;
+    parts?: TUniversalMessagePart[];
+}): ISystemMessage;
+/** Create a tool message. */
+declare function createToolMessage(content: string, options: {
+    toolCallId: string;
+    name?: string;
+    metadata?: TUniversalMessageMetadata;
+    parts?: TUniversalMessagePart[];
+}): IToolMessage;
+
+/** API message format for provider consumption */
+interface IProviderApiMessage {
+    role: string;
+    content: string | null;
+    tool_calls?: Array<{
+        id: string;
+        type: 'function';
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+    tool_call_id?: string;
+}
+/**
+ * Conversation store with duplicate prevention and API format conversion.
+ * @public
+ */
+declare class ConversationStore implements IConversationHistory {
+    private history;
+    private toolCallIds;
+    private pendingAssistant;
+    constructor(maxMessages?: number);
+    addMessage(message: TUniversalMessage): void;
+    addUserMessage(content: string, metadata?: TUniversalMessageMetadata, parts?: TUniversalMessagePart[]): void;
+    addAssistantMessage(content: string | null, toolCalls?: IToolCall[], metadata?: TUniversalMessageMetadata, parts?: TUniversalMessagePart[]): void;
+    addSystemMessage(content: string, metadata?: TUniversalMessageMetadata, parts?: TUniversalMessagePart[]): void;
+    addToolMessage(content: string, toolCallId: string, toolName?: string, metadata?: TUniversalMessageMetadata, parts?: TUniversalMessagePart[]): void;
+    addToolMessageWithId(content: string, toolCallId: string, toolName: string, metadata?: TUniversalMessageMetadata, parts?: TUniversalMessagePart[]): void;
+    /** Add a raw history entry (events, etc.) */
+    addEntry(entry: IHistoryEntry): void;
+    /** Get all history entries (universal timeline) */
+    getHistory(): IHistoryEntry[];
+    getMessages(): TUniversalMessage[];
+    getMessagesByRole(role: TUniversalMessageRole): TUniversalMessage[];
+    getRecentMessages(count: number): TUniversalMessage[];
+    getMessageCount(): number;
+    /** Begin a new assistant response. Must be called before provider call.
+     *  Ensures pendingAssistant exists so commitAssistant always has data to save. */
+    beginAssistant(): void;
+    /** Append streaming text delta to pending assistant response */
+    appendStreaming(delta: string): void;
+    /** Append a tool call to pending assistant response (deduplicates by id) */
+    appendToolCall(toolCall: IToolCall): void;
+    /**
+     * Commit pending assistant response to history.
+     * Precondition: beginAssistant() must have been called before the provider call.
+     * History is append-only — this always adds a message.
+     */
+    commitAssistant(state: TMessageState, metadata?: TUniversalMessageMetadata): void;
+    /** Discard pending assistant response without saving */
+    discardPending(): void;
+    /** Returns true if there is accumulated pending assistant state (streaming or tool calls) */
+    hasPendingAssistant(): boolean;
+    /** Get pending assistant content (empty string if no content streamed yet) */
+    getPendingContent(): string;
+    getMessagesForAPI(): IProviderApiMessage[];
+    clear(): void;
+}
+
+/** Interface for managing conversation history. @public */
+interface IConversationHistory {
+    addMessage(message: TUniversalMessage): void;
+    addUserMessage(content: string, metadata?: TUniversalMessageMetadata, parts?: TUniversalMessagePart[]): void;
+    addAssistantMessage(content: string | null, toolCalls?: IToolCall[], metadata?: TUniversalMessageMetadata, parts?: TUniversalMessagePart[]): void;
+    addSystemMessage(content: string, metadata?: TUniversalMessageMetadata, parts?: TUniversalMessagePart[]): void;
+    addToolMessageWithId(content: string, toolCallId: string, toolName: string, metadata?: TUniversalMessageMetadata, parts?: TUniversalMessagePart[]): void;
+    addEntry(entry: IHistoryEntry): void;
+    getHistory(): IHistoryEntry[];
+    getMessages(): TUniversalMessage[];
+    getMessagesByRole(role: TUniversalMessageRole): TUniversalMessage[];
+    getRecentMessages(count: number): TUniversalMessage[];
+    clear(): void;
+    getMessageCount(): number;
+}
+/** Configuration options for ConversationHistory manager */
+interface IConversationHistoryOptions {
+    maxMessagesPerConversation?: number;
+    maxConversations?: number;
+}
+/** Multi-session conversation history manager. @public */
+declare class ConversationHistory {
+    private conversations;
+    private logger;
+    private readonly maxMessagesPerConversation;
+    private readonly maxConversations;
+    constructor(options?: IConversationHistoryOptions);
+    getConversationStore(conversationId: string): ConversationStore;
+    hasConversation(conversationId: string): boolean;
+    removeConversation(conversationId: string): boolean;
+    clearAll(): void;
+    getStats(): {
+        totalConversations: number;
+        conversationIds: string[];
+        totalMessages: number;
+    };
+}
+
 /**
  * Local executor that directly delegates to AI provider instances
  *
@@ -3150,7 +3407,25 @@ declare class Robota extends AbstractAgent<IAgentConfig, IRunOptions, TUniversal
     runStream(input: string, options?: IRunOptions): AsyncGenerator<string, void, undefined>;
     private executionDeps;
     getHistory(): TUniversalMessage[];
+    /** Get full history timeline (IHistoryEntry[]) including events */
+    getFullHistory(): Array<{
+        id: string;
+        timestamp: Date;
+        category: string;
+        type: string;
+        data?: unknown;
+    }>;
+    /** Add an event entry to history */
+    addHistoryEntry(entry: {
+        id: string;
+        timestamp: Date;
+        category: string;
+        type: string;
+        data?: unknown;
+    }): void;
     clearHistory(): void;
+    /** Inject a message into conversation history without triggering execution. */
+    injectMessage(role: 'user' | 'assistant' | 'system', content: string): void;
     updateTools(next: Array<IToolWithEventService>): Promise<{
         version: number;
     }>;
@@ -3443,84 +3718,6 @@ declare class AgentFactory {
     private updateCreationStats;
 }
 
-/**
- * Conversation session implementations.
- *
- * Extracted from conversation-history-manager.ts.
- */
-
-/** API message format for provider consumption */
-interface IProviderApiMessage {
-    role: string;
-    content: string | null;
-    tool_calls?: Array<{
-        id: string;
-        type: 'function';
-        function: {
-            name: string;
-            arguments: string;
-        };
-    }>;
-    tool_call_id?: string;
-}
-/**
- * Conversation session with duplicate prevention and API format conversion.
- * @public
- */
-declare class ConversationSession implements IConversationHistory {
-    private history;
-    private toolCallIds;
-    constructor(maxMessages?: number);
-    addMessage(message: TUniversalMessage): void;
-    addUserMessage(content: string, metadata?: TUniversalMessageMetadata, parts?: TUniversalMessagePart[]): void;
-    addAssistantMessage(content: string | null, toolCalls?: IToolCall[], metadata?: TUniversalMessageMetadata, parts?: TUniversalMessagePart[]): void;
-    addSystemMessage(content: string, metadata?: TUniversalMessageMetadata, parts?: TUniversalMessagePart[]): void;
-    addToolMessage(content: string, toolCallId: string, toolName?: string, metadata?: TUniversalMessageMetadata, parts?: TUniversalMessagePart[]): void;
-    addToolMessageWithId(content: string, toolCallId: string, toolName: string, metadata?: TUniversalMessageMetadata, parts?: TUniversalMessagePart[]): void;
-    getMessages(): TUniversalMessage[];
-    getMessagesByRole(role: TUniversalMessageRole): TUniversalMessage[];
-    getRecentMessages(count: number): TUniversalMessage[];
-    getMessageCount(): number;
-    getMessagesForAPI(): IProviderApiMessage[];
-    clear(): void;
-}
-
-/** Interface for managing conversation history. @public */
-interface IConversationHistory {
-    addMessage(message: TUniversalMessage): void;
-    addUserMessage(content: string, metadata?: TUniversalMessageMetadata, parts?: TUniversalMessagePart[]): void;
-    addAssistantMessage(content: string | null, toolCalls?: IToolCall[], metadata?: TUniversalMessageMetadata, parts?: TUniversalMessagePart[]): void;
-    addSystemMessage(content: string, metadata?: TUniversalMessageMetadata, parts?: TUniversalMessagePart[]): void;
-    addToolMessageWithId(content: string, toolCallId: string, toolName: string, metadata?: TUniversalMessageMetadata, parts?: TUniversalMessagePart[]): void;
-    getMessages(): TUniversalMessage[];
-    getMessagesByRole(role: TUniversalMessageRole): TUniversalMessage[];
-    getRecentMessages(count: number): TUniversalMessage[];
-    clear(): void;
-    getMessageCount(): number;
-}
-/** Configuration options for ConversationHistory manager */
-interface IConversationHistoryOptions {
-    maxMessagesPerConversation?: number;
-    maxConversations?: number;
-}
-/** Multi-session conversation history manager. @public */
-declare class ConversationHistory {
-    private conversations;
-    private logger;
-    private readonly maxMessagesPerConversation;
-    private readonly maxConversations;
-    constructor(options?: IConversationHistoryOptions);
-    getConversationSession(conversationId: string): ConversationSession;
-    hasConversation(conversationId: string): boolean;
-    removeConversation(conversationId: string): boolean;
-    clearAll(): void;
-    getStats(): {
-        totalConversations: number;
-        conversationIds: string[];
-        totalMessages: number;
-    };
-}
-
 declare class EventHistoryModule implements IEventHistoryModule {
     private readonly store;
     private readonly listener;
@@ -4175,22 +4372,76 @@ interface IContextWindowState {
     remainingPercentage: number;
 }
 
+/**
+ * Claude model definitions — SSOT for model metadata.
+ * Source: https://platform.claude.com/docs/en/about-claude/models/overview
+ */
+interface IModelDefinition {
+    /** Human-readable model name */
+    name: string;
+    /** API model identifier */
+    id: string;
+    /** Context window size in tokens */
+    contextWindow: number;
+    /** Maximum output tokens */
+    maxOutput: number;
+}
+/**
+ * Known Claude models (4.5+).
+ * Keyed by API model ID for fast lookup.
+ */
+declare const CLAUDE_MODELS: Record<string, IModelDefinition>;
+declare const DEFAULT_CONTEXT_WINDOW = 200000;
+/** Get context window size for a model ID. Falls back to DEFAULT_CONTEXT_WINDOW. */
+declare function getModelContextWindow(modelId: string): number;
+declare const DEFAULT_MAX_OUTPUT = 16384;
+/** Get max output tokens for a model ID. Falls back to DEFAULT_MAX_OUTPUT. */
+declare function getModelMaxOutput(modelId: string): number;
+/** Get human-readable model name for a model ID. Falls back to the ID itself. */
+declare function getModelName(modelId: string): string;
+/** Format token count as human-readable (e.g., 200K, 1M, 1.2M). Minimum unit is K. */
+declare function formatTokenCount(tokens: number): string;
+
 /**
  * Hook system types — Claude Code compatible event/hook model.
  */
 /** Hook lifecycle events */
-type THookEvent = 'PreToolUse' | 'PostToolUse' | 'SessionStart' | 'Stop' | 'PreCompact' | 'PostCompact';
-/** A single hook definition */
-interface IHookDefinition {
-    /** Shell command to execute */
+type THookEvent = 'PreToolUse' | 'PostToolUse' | 'SessionStart' | 'Stop' | 'PreCompact' | 'PostCompact' | 'UserPromptSubmit' | 'Notification';
+/** Command hook — executes a shell command */
+interface ICommandHookDefinition {
     type: 'command';
     command: string;
+    timeout?: number;
 }
+/** HTTP hook — sends an HTTP request */
+interface IHttpHookDefinition {
+    type: 'http';
+    url: string;
+    headers?: Record<string, string>;
+    timeout?: number;
+}
+/** Prompt hook — evaluates a prompt via an AI model */
+interface IPromptHookDefinition {
+    type: 'prompt';
+    prompt: string;
+    model?: string;
+}
+/** Agent hook — delegates to a sub-agent */
+interface IAgentHookDefinition {
+    type: 'agent';
+    agent: string;
+    maxTurns?: number;
+    timeout?: number;
+}
+/** Discriminated union of all hook definition types */
+type IHookDefinition = ICommandHookDefinition | IHttpHookDefinition | IPromptHookDefinition | IAgentHookDefinition;
 /** A hook group — matcher + array of hook definitions */
 interface IHookGroup {
     /** Regex pattern to match tool name (empty string = match all) */
     matcher: string;
     hooks: IHookDefinition[];
+    /** Environment variables injected into hook child processes for this group */
+    env?: Record<string, string>;
 }
 /** Complete hooks configuration: event → array of hook groups */
 type THooksConfig = Partial<Record<THookEvent, IHookGroup[]>>;
@@ -4206,6 +4457,14 @@ interface IHookInput {
     trigger?: 'auto' | 'manual';
     /** Compaction summary text (PostCompact only) */
     compact_summary?: string;
+    /** User message text (UserPromptSubmit only) */
+    user_message?: string;
+    /** User prompt text — Claude Code compatible alias for user_message (UserPromptSubmit only) */
+    prompt?: string;
+    /** Assistant response text (Stop only) */
+    response?: string;
+    /** Additional environment variables to pass to hook child processes */
+    env?: Record<string, string>;
 }
 /** Hook execution result */
 interface IHookResult {
@@ -4214,11 +4473,21 @@ interface IHookResult {
     stdout: string;
     stderr: string;
 }
+/** Strategy interface for hook type executors */
+interface IHookTypeExecutor {
+    /** The hook type this executor handles */
+    type: IHookDefinition['type'];
+    /** Execute a hook definition with the given input */
+    execute(definition: IHookDefinition, input: IHookInput): Promise<IHookResult>;
+}
 
 /**
- * Hook runner — executes shell command hooks for lifecycle events.
+ * Hook runner — executes hooks for lifecycle events using the strategy pattern.
+ *
+ * Dispatches to registered IHookTypeExecutor implementations by definition type.
+ * Default executors: CommandExecutor (shell), HttpExecutor (HTTP POST).
  *
- * Hooks receive JSON input on stdin and communicate results via exit codes:
+ * Exit code semantics:
  * - 0: allow/proceed
  * - 2: block/deny (stderr contains reason)
  * - other: proceed (logged as warning)
@@ -4229,10 +4498,19 @@ interface IHookResult {
  *
  * For PreToolUse: if any hook returns exit code 2, the tool call is blocked.
  * Returns { blocked: true, reason: string } if blocked, { blocked: false } otherwise.
+ *
+ * @param config - Hooks configuration mapping events to hook groups
+ * @param event - The lifecycle event being fired
+ * @param input - Hook input data passed to executors
+ * @param executors - Optional array of hook type executors (defaults to command + http)
  */
-declare function runHooks(config: THooksConfig | undefined, event: THookEvent, input: IHookInput): Promise<{
+/** Result of running hooks for an event. */
+interface IRunHooksResult {
     blocked: boolean;
     reason?: string;
-}>;
+    /** Collected stdout from all successful hooks (exit code 0). */
+    stdout: string;
+}
+declare function runHooks(config: THooksConfig | undefined, event: THookEvent, input: IHookInput, executors?: IHookTypeExecutor[]): Promise<IRunHooksResult>;
 
-export { AGENT_EVENTS, AGENT_EVENT_PREFIX, AbstractAIProvider, AbstractAgent, AbstractExecutor, AbstractManager, AbstractPlugin, AbstractTool, AgentFactory, AgentTemplates, AuthenticationError, CacheIntegrityError, CircuitBreakerOpenError, ConfigurationError, ConversationHistory, ConversationSession, EVENT_EMITTER_EVENTS, EXECUTION_EVENTS, EXECUTION_EVENT_PREFIX, ErrorUtils, EventEmitterPlugin, EventHistoryModule, ExecutionProxy, type IAIProvider, type IAIProviderInstance, type IAIProviderManager, type IAbstractTool, type IAbstractToolOptions, type IAgent, type IAgentConfig, type IAgentCreationOptions, type IAgentCreationStats, type IAgentEventData, type IAgentFactory, type IAgentFactoryOptions, type IAgentLifecycleEvents, type IAgentTemplate, type IAssistantMessage, type IBaseEventData, type IBaseMessage, type ICacheEntry, type ICacheKey, type ICacheOptions, type ICacheStats, type ICacheStorage, type IChatExecutionRequest, type IChatOptions, type IConfigValidationResult, type IContextOptions, type IContextTokenUsage, type IContextWindowState, type IConversationContext, type IConversationResponse, type IConversationService, type IConversationServiceOptions, type IEventContext, type IEventEmitterEventData, type IEventEmitterHierarchicalEventData, type IEventEmitterMetrics, type IEventEmitterMetricsSnapshot, type IEventEmitterPlugin, type IEventEmitterPluginOptions, type IEventHistoryModule, type IEventHistoryRecord, type IEventHistorySnapshot, type IEventService, type IEventServiceOwnerBinding, type IExecutionEventData, type IExecutionService, type IExecutionServiceOptions, type IExecutor, type IExecutorAwareProviderConfig, type IFunctionTool, type IHookDefinition, type IHookGroup, type IHookInput, type IHookResult, type IImageComposeRequest, type IImageEditRequest, type IImageGenerationProvider, type IImageGenerationRequest, type IImageGenerationResult, type IInlineImageInputSource, type IInlineImageMessagePart, type ILocalExecutorConfig, type ILogger, type IMCPToolConfig, type IMediaOutputRef, type IOpenAPIToolConfig, type IOwnerPathSegment, type IParameterSchema, type IParameterValidationResult, type IPermissionLists, type IPlugin, type IPluginConfig, type IPluginContext, type IPluginContract, type IPluginData, type IPluginErrorContext, type IPluginExecutionContext, type IPluginExecutionResult, type IPluginHooks, type IPluginOptions, type IPluginStats, type IProgressReportingTool, type IProviderConfig, type IProviderMediaError, type IProviderOptions, type IProviderRequest, type IProviderSpecificOptions, type IRawProviderResponse, type IRemoteExecutorConfig, type IRunOptions, type ISimpleValidationResult, type IStreamExecutionRequest, type IStreamingChunk, type ISystemMessage, type ITemplateApplicationResult, type ITextMessagePart, type ITokenUsage, type ITool, type IToolCall, type IToolContract, type IToolEventData, type IToolExecutionContext, type IToolExecutionRequest, type IToolExecutionResult, type IToolExecutionService, type IToolExecutionStep, type IToolFactory, type IToolManager, type IToolMessage, type IToolRegistry, type IToolResult, type IToolSchema, type IToolWithEventService, type IUniversalObjectValue, type IUriImageInputSource, type IUriImageMessagePart, type IUserMessage, type IUtilLogEntry, type IValidationIssue, type IValidationOptions, type IValidationResult, type IVideoGenerationProvider, type IVideoGenerationRequest, type IVideoJobAccepted, type IVideoJobSnapshot, type IWorkflowConfig, type IWorkflowConversionOptions, type IWorkflowConversionResult, type IWorkflowConverter, type IWorkflowData, type IWorkflowMetadata, type IWorkflowValidator, InMemoryEventEmitterMetrics, LocalExecutor, MODE_POLICY, MessageConverter, ModelNotAvailableError, NetworkError, PluginCategory, PluginError, PluginPriority, ProviderError, RateLimitError, Robota, RobotaError, SilentLogger, StorageError, type TAgentCreationMetadata, type TComplexConfigValue, type TConfigData, type TConfigValue, type TContextData, type TConversationContextMetadata, type TErrorContextData, type TErrorExternalInput, type TEventEmitterListener, type TEventListener, type TEventName, type TExecutionEventName, type TExecutionMetadata, type THookEvent, type THooksConfig, type TImageInputSource, type TJSONSchemaEnum, type TJSONSchemaKind, type TKnownToolName, type TLoggerData, type TManagerToolParameters, type TMetadata, type TMetadataValue, TOOL_EVENTS, TOOL_EVENT_PREFIX, type TParameterDefaultValue, type TPermissionDecision, type TPermissionMode, type TPrimitiveValue, type TProviderConfigValue, type TProviderLoggingData, type TProviderMediaResult, type TProviderOptionValueBase, TRUST_TO_MODE, type TResponseMetadata, type TTextDeltaCallback, type TTimerId, type TToolArgs, type TToolExecutionFunction, type TToolExecutionParameters, type TToolExecutor, type TToolMetadata, type TToolParameters, type TToolProgressCallback, type TTrustLevel, type TUniversalArrayValue, type TUniversalMessage, type TUniversalMessageMetadata, type TUniversalMessagePart, type TUniversalMessageRole, type TUniversalValue, type TUtilLogLevel, ToolExecutionError, UNKNOWN_TOOL_FALLBACK, ValidationError, ValidationSeverity, Validator, createExecutionProxy, createLogger, evaluatePermission, getGlobalLogLevel, getToolEstimatedDuration, getToolExecutionSteps, isAssistantMessage, isImageGenerationProvider, isProgressReportingTool, isSystemMessage, isToolMessage, isUserMessage, isVideoGenerationProvider, logger, runHooks, setGlobalLogLevel, setToolProgressCallback, startPeriodicTask, stopPeriodicTask, validateAgentConfig, validateApiKey, validateModelName, validateProviderName, validateUserInput, withEventEmission };
+export { AGENT_EVENTS, AGENT_EVENT_PREFIX, AbstractAIProvider, AbstractAgent, AbstractEventService, AbstractExecutor, AbstractManager, AbstractPlugin, AbstractTool, AgentFactory, AgentTemplates, AuthenticationError, CLAUDE_MODELS, CacheIntegrityError, CircuitBreakerOpenError, ConfigurationError, ConversationHistory, ConversationStore, DEFAULT_ABSTRACT_EVENT_SERVICE, DEFAULT_CONTEXT_WINDOW, DEFAULT_MAX_OUTPUT, DefaultEventService, EVENT_EMITTER_EVENTS, EXECUTION_EVENTS, EXECUTION_EVENT_PREFIX, ErrorUtils, EventEmitterPlugin, EventHistoryModule, ExecutionProxy, type IAIProvider, type IAIProviderInstance, type IAIProviderManager, type IAbstractTool, type IAbstractToolOptions, type IAgent, type IAgentConfig, type IAgentCreationOptions, type IAgentCreationStats, type IAgentEventData, type IAgentFactory, type IAgentFactoryOptions, type IAgentHookDefinition, type IAgentLifecycleEvents, type IAgentTemplate, type IAssistantMessage, type IBaseEventData, type IBaseMessage, type ICacheEntry, type ICacheKey, type ICacheOptions, type ICacheStats, type ICacheStorage, type IChatExecutionRequest, type IChatOptions, type ICommandHookDefinition, type IConfigValidationResult, type IContextOptions, type IContextTokenUsage, type IContextWindowState, type IConversationContext, type IConversationResponse, type IConversationService, type IConversationServiceOptions, type IEventContext, type IEventEmitterEventData, type IEventEmitterHierarchicalEventData, type IEventEmitterMetrics, type IEventEmitterMetricsSnapshot, type IEventEmitterPlugin, type IEventEmitterPluginOptions, type IEventHistoryModule, type IEventHistoryRecord, type IEventHistorySnapshot, type IEventObjectValue, type IEventService, type IEventServiceOwnerBinding, type IExecutionEventData, type IExecutionService, type IExecutionServiceOptions, type IExecutor, type IExecutorAwareProviderConfig, type IFunctionTool, type IHistoryEntry, type IHookDefinition, type IHookGroup, type IHookInput, type IHookResult, type IHookTypeExecutor, type IHttpHookDefinition, type IImageComposeRequest, type IImageEditRequest, type IImageGenerationProvider, type IImageGenerationRequest, type IImageGenerationResult, type IInlineImageInputSource, type IInlineImageMessagePart, type ILocalExecutorConfig, type ILogger, type IMCPToolConfig, type IMediaOutputRef, type IModelDefinition, type IOpenAPIToolConfig, type IOwnerPathSegment, type IParameterSchema, type IParameterValidationResult, type IPermissionLists, type IPlugin, type IPluginConfig, type IPluginContext, type IPluginContract, type IPluginData, type IPluginErrorContext, type IPluginExecutionContext, type IPluginExecutionResult, type IPluginHooks, type IPluginOptions, type IPluginStats, type IProgressReportingTool, type IPromptHookDefinition, type IProviderConfig, type IProviderMediaError, type IProviderOptions, type IProviderRequest, type IProviderSpecificOptions, type IRawProviderResponse, type IRemoteExecutorConfig, type IRunOptions, type ISimpleValidationResult, type IStreamExecutionRequest, type IStreamingChunk, type ISystemMessage, type ITemplateApplicationResult, type ITextMessagePart, type ITokenUsage, type ITool, type IToolCall, type IToolContract, type IToolEventData, type IToolExecutionContext, type IToolExecutionRequest, type IToolExecutionResult, type IToolExecutionService, type IToolExecutionStep, type IToolFactory, type IToolManager, type IToolMessage, type IToolRegistry, type IToolResult, type IToolSchema, type IToolWithEventService, type IUniversalObjectValue, type IUriImageInputSource, type IUriImageMessagePart, type IUserMessage, type IUtilLogEntry, type IValidationIssue, type IValidationOptions, type IValidationResult, type IVideoGenerationProvider, type IVideoGenerationRequest, type IVideoJobAccepted, type IVideoJobSnapshot, type IWorkflowConfig, type IWorkflowConversionOptions, type IWorkflowConversionResult, type IWorkflowConverter, type IWorkflowData, type IWorkflowMetadata, type IWorkflowValidator, InMemoryEventEmitterMetrics, LocalExecutor, MODE_POLICY, MessageConverter, ModelNotAvailableError, NetworkError, ObservableEventService, PluginCategory, PluginError, PluginPriority, ProviderError, RateLimitError, Robota, RobotaError, SilentLogger, StorageError, StructuredEventService, TASK_EVENTS, TASK_EVENT_PREFIX, type TAgentCreationMetadata, type TComplexConfigValue, type TConfigData, type TConfigValue, type TContextData, type TConversationContextMetadata, type TErrorContextData, type TErrorExternalInput, type TEventEmitterListener, type TEventExtensionValue, type TEventListener, type TEventLoggerData, type TEventName, type TEventUniversalValue, type TExecutionEventName, type TExecutionMetadata, type THookEvent, type THooksConfig, type TImageInputSource, type TJSONSchemaEnum, type TJSONSchemaKind, type TKnownToolName, type TLoggerData, type TManagerToolParameters, type TMessageState, type TMetadata, type TMetadataValue, TOOL_EVENTS, TOOL_EVENT_PREFIX, type TParameterDefaultValue, type TPermissionDecision, type TPermissionMode, type TPrimitiveValue, type TProviderConfigValue, type TProviderLoggingData, type TProviderMediaResult, type TProviderOptionValueBase, TRUST_TO_MODE, type TResponseMetadata, type TTextDeltaCallback, type TTimerId, type TToolArgs, type TToolExecutionFunction, type TToolExecutionParameters, type TToolExecutor, type TToolMetadata, type TToolParameters, type TToolProgressCallback, type TTrustLevel, type TUniversalArrayValue, type TUniversalMessage, type TUniversalMessageMetadata, type TUniversalMessagePart, type TUniversalMessageRole, type TUniversalValue, type TUserEvent, type TUtilLogLevel, ToolExecutionError, UNKNOWN_TOOL_FALLBACK, USER_EVENTS, USER_EVENT_PREFIX, ValidationError, ValidationSeverity, Validator, bindEventServiceOwner, bindWithOwnerPath, chatEntryToMessage, composeEventName, createAssistantMessage, createExecutionProxy, createLogger, createSystemMessage, createToolMessage, createUserMessage, evaluatePermission, formatTokenCount, getGlobalLogLevel, getMessagesForAPI, getModelContextWindow, getModelMaxOutput, getModelName, getToolEstimatedDuration, getToolExecutionSteps, isAssistantMessage, isChatEntry, isDefaultEventService, isImageGenerationProvider, isProgressReportingTool, isSystemMessage, isToolMessage, isUserMessage, isVideoGenerationProvider, logger, messageToHistoryEntry, runHooks, setGlobalLogLevel, setToolProgressCallback, startPeriodicTask, stopPeriodicTask, validateAgentConfig, validateApiKey, validateModelName, validateProviderName, validateUserInput, withEventEmission };