@robota-sdk/agent-core 3.0.0-beta.6 → 3.0.0-beta.61

package/dist/node/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.
  *
@@ -155,6 +202,42 @@ interface IPluginContext {
     error?: Error;
     executionContext?: TContextData;
 }
+/**
+ * Type utility functions for safe type checking and validation
+ * @internal
+ */
+declare const TypeUtils: {
+    isPrimitive: (value: TUniversalValue) => value is TPrimitiveValue;
+    isArray: (value: TUniversalValue) => value is TUniversalArrayValue;
+    isObject: (value: TUniversalValue) => value is IUniversalObjectValue;
+    isUniversalValue: (value: TUniversalValue) => value is TUniversalValue;
+};
+
+interface IProviderFunctionCallingCapability {
+    supported: boolean;
+    reason?: string;
+}
+interface IProviderNativeWebToolCapability {
+    supported: boolean;
+    enabled: boolean;
+    source?: string;
+    reason?: string;
+}
+interface IProviderNativeWebToolCapabilities {
+    webSearch: IProviderNativeWebToolCapability;
+    webFetch: IProviderNativeWebToolCapability;
+}
+interface IProviderCapabilities {
+    functionCalling: IProviderFunctionCallingCapability;
+    nativeWebTools: IProviderNativeWebToolCapabilities;
+}
+interface IProviderNativeWebToolRequest {
+    webSearch?: boolean;
+    webFetch?: boolean;
+}
+declare function createDefaultProviderCapabilities(functionCallingSupported: boolean): IProviderCapabilities;
+declare function getProviderCapabilities(provider: IAIProvider): IProviderCapabilities;
+declare function assertProviderNativeWebToolsAvailable(providerName: string, capabilities: IProviderCapabilities, request: IProviderNativeWebToolRequest | undefined): void;
 
 /**
  * Reusable type definitions for provider layer
@@ -187,6 +270,7 @@ interface IToolSchema {
         type: 'object';
         properties: Record<string, IParameterSchema>;
         required?: string[];
+        additionalProperties?: boolean | IParameterSchema;
     };
 }
 /**
@@ -283,6 +367,17 @@ interface IProviderSpecificOptions {
  * Called for each text chunk as the model generates output.
  */
 type TTextDeltaCallback = (delta: string) => void;
+type TProviderNativeRawPayloadKind = 'request' | 'response' | 'stream_event';
+type TProviderNativeRawPayload = string | number | boolean | object | null | undefined;
+interface IProviderNativeRawPayloadEvent {
+    provider: string;
+    apiSurface?: string;
+    payloadKind: TProviderNativeRawPayloadKind;
+    payload: TProviderNativeRawPayload;
+    sequence?: number;
+    metadata?: Record<string, TProviderConfigValue>;
+}
+type TProviderNativeRawPayloadCallback = (event: IProviderNativeRawPayloadEvent) => void;
 /**
  * Options for AI provider chat requests
  */
@@ -299,6 +394,12 @@ interface IChatOptions extends IProviderSpecificOptions {
      *  should use streaming internally and call this for each text chunk,
      *  while still returning the complete assembled message. */
     onTextDelta?: TTextDeltaCallback;
+    /** Callback for provider-owned native SDK request/response/stream payload capture. */
+    onProviderNativeRawPayload?: TProviderNativeRawPayloadCallback;
+    /** AbortSignal for cancelling the provider call */
+    signal?: AbortSignal;
+    /** Provider-native hosted web tools requested for this call */
+    nativeWebTools?: IProviderNativeWebToolRequest;
 }
 /**
  * Provider-agnostic AI Provider interface
@@ -340,6 +441,15 @@ interface IAIProvider {
      * @returns true if tool calling is supported
      */
     supportsTools(): boolean;
+    /**
+     * Report provider-neutral capability state.
+     * Providers without native web support can omit this and use default capability helpers.
+     */
+    getCapabilities?(): IProviderCapabilities;
+    /**
+     * Optional generic hook for enabling provider-native hosted web behavior.
+     */
+    configureNativeWebTools?(request: IProviderNativeWebToolRequest): IProviderCapabilities;
     /**
      * Validate provider configuration
      * @returns true if configuration is valid
@@ -481,6 +591,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
@@ -593,57 +775,6 @@ interface IParameterValidationResult {
  * Generic tool executor function
  */
 type TToolExecutor<TParams = TToolParameters, TResult = TUniversalValue> = (parameters: TParams, context?: IToolExecutionContext) => Promise<TResult>;
-/**
- * OpenAPI specification configuration
- */
-interface IOpenAPIToolConfig {
-    /** OpenAPI 3.0 specification */
-    spec: {
-        openapi: string;
-        info: {
-            title: string;
-            version: string;
-            description?: string;
-        };
-        servers?: Array<{
-            url: string;
-            description?: string;
-        }>;
-        paths: Record<string, Record<string, string | number | boolean | Record<string, string | number | boolean>>>;
-        components?: Record<string, Record<string, string | number | boolean>>;
-    };
-    /** Operation ID from the OpenAPI spec */
-    operationId: string;
-    /** Base URL for API calls */
-    baseURL: string;
-    /** Authentication configuration */
-    auth?: {
-        type: 'bearer' | 'apiKey' | 'basic';
-        token?: string;
-        apiKey?: string;
-        header?: string;
-        username?: string;
-        password?: string;
-    };
-}
-/**
- * MCP (Model Context Protocol) configuration
- */
-interface IMCPToolConfig {
-    /** MCP server endpoint */
-    endpoint: string;
-    /** Protocol version */
-    version?: string;
-    /** Authentication configuration */
-    auth?: {
-        type: 'bearer' | 'apiKey';
-        token: string;
-    };
-    /** Tool-specific configuration */
-    toolConfig?: Record<string, string | number | boolean>;
-    /** Timeout in milliseconds */
-    timeout?: number;
-}
 /**
  * Base tool interface
  */
@@ -707,23 +838,6 @@ interface IToolRegistry {
      */
     clear(): void;
 }
-/**
- * Tool factory interface
- */
-interface IToolFactory {
-    /**
-     * Create function tool from schema and function
-     */
-    createFunctionTool(schema: IToolSchema, fn: TToolExecutor): IFunctionTool;
-    /**
-     * Create tool from OpenAPI specification
-     */
-    createOpenAPITool(config: IOpenAPIToolConfig): ITool;
-    /**
-     * Create MCP tool
-     */
-    createMCPTool(config: IMCPToolConfig): ITool;
-}
 
 declare const EXECUTION_EVENT_NAMES: {
     readonly START: "execution.start";
@@ -864,6 +978,24 @@ interface ILogger {
  * - Inject a real logger explicitly if you want output.
  */
 declare const SilentLogger: ILogger;
+/**
+ * Console logger implementation
+ * @internal
+ */
+declare class ConsoleLogger implements ILogger {
+    private level?;
+    private packageName;
+    private sinkLogger;
+    constructor(packageName: string, logger?: ILogger);
+    debug(...args: Array<TUniversalValue | TLoggerData | Error>): void;
+    info(...args: Array<TUniversalValue | TLoggerData | Error>): void;
+    warn(...args: Array<TUniversalValue | TLoggerData | Error>): void;
+    error(...args: Array<TUniversalValue | TLoggerData | Error>): void;
+    log(...args: Array<TUniversalValue | TLoggerData | Error>): void;
+    private getLevel;
+    private shouldLog;
+    private forward;
+}
 /**
  * Create a named logger instance for a package or module.
  * Use this to create loggers with a specific name prefix for easy log filtering.
@@ -1513,6 +1645,7 @@ interface IAgentConfig {
     responseFormat?: IResponseFormatConfig;
     safetySettings?: ISafetySetting[];
     timeout?: number;
+    maxExecutionRounds?: number;
     retryAttempts?: number;
     rateLimiting?: {
         enabled?: boolean;
@@ -1549,7 +1682,20 @@ interface IRunOptions {
     sessionId?: string;
     userId?: string;
     metadata?: TMetadata;
+    /** AbortSignal for cancelling execution */
+    signal?: AbortSignal;
+    /** Per-run streaming text callback. Prefer this over mutating provider callback state. */
+    onTextDelta?: TTextDeltaCallback;
+    /** Per-run replay event callback for provider/tool execution boundaries. */
+    onExecutionEvent?: TExecutionEventCallback;
+    /**
+     * Maximum model/tool rounds for this run.
+     * Use 0 for no core round cap.
+     */
+    maxExecutionRounds?: number;
 }
+type TExecutionEventData = Record<string, unknown>;
+type TExecutionEventCallback = (event: string, data: TExecutionEventData) => void;
 /**
  * Generic agent interface with type parameters for enhanced type safety
  *
@@ -1595,6 +1741,97 @@ interface ISafetySetting {
     [key: string]: TConfigValue;
 }
 
+interface IProviderConfig$1 {
+    name: string;
+    model: string;
+    apiKey?: string;
+    baseURL?: string;
+    timeout?: number;
+    options?: Record<string, TUniversalValue>;
+}
+interface IProviderProfileDefaults {
+    model?: string;
+    apiKey?: string;
+    baseURL?: string;
+    timeout?: number;
+    options?: Record<string, TUniversalValue>;
+}
+interface IProviderProfileConfig {
+    type?: string;
+    model?: string;
+    apiKey?: string;
+    baseURL?: string;
+    timeout?: number;
+    options?: Record<string, TUniversalValue>;
+}
+interface IProviderProbeResult {
+    ok: boolean;
+    message: string;
+    models?: string[];
+}
+type TProviderCredentialField = 'apiKey';
+type TProviderSetupField = 'baseURL' | 'model' | TProviderCredentialField;
+type TProviderSetupHelpLinkKind = 'api-key' | 'console' | 'official';
+interface IProviderCredentialRequirement {
+    anyOf: readonly TProviderCredentialField[];
+}
+interface IProviderSetupHelpLink {
+    kind: TProviderSetupHelpLinkKind;
+    label: string;
+    url: string;
+    sourceUrl?: string;
+    lastVerifiedAt?: string;
+}
+type TProviderModelCatalogStatus = 'live' | 'generated' | 'fallback' | 'unavailable';
+type TProviderModelLifecycle = 'active' | 'preview' | 'deprecated' | 'unavailable';
+type TProviderModelCapability = 'tools' | 'vision' | 'json_schema' | 'reasoning' | 'native_web' | 'streaming';
+interface IProviderModelCatalogEntry {
+    id: string;
+    displayName: string;
+    aliases?: readonly string[];
+    contextWindow?: number;
+    capabilities?: readonly TProviderModelCapability[];
+    lifecycle?: TProviderModelLifecycle;
+    lastVerifiedAt?: string;
+    sourceUrl?: string;
+}
+interface IProviderModelCatalog {
+    status: TProviderModelCatalogStatus;
+    entries?: readonly IProviderModelCatalogEntry[];
+    lastVerifiedAt?: string;
+    sourceUrl?: string;
+    message?: string;
+}
+interface IProviderModelCatalogRefreshOptions {
+    profile: IProviderProfileConfig;
+}
+type TProviderModelCatalogRefresh = (options: IProviderModelCatalogRefreshOptions) => Promise<IProviderModelCatalog>;
+interface IProviderSetupStepDefinition {
+    key: TProviderSetupField;
+    title: string;
+    defaultValue?: string;
+    required?: boolean;
+    masked?: boolean;
+}
+interface IProviderDefinition {
+    type: string;
+    aliases?: readonly string[];
+    displayName?: string;
+    description?: string;
+    defaults?: IProviderProfileDefaults;
+    modelCatalog?: IProviderModelCatalog;
+    refreshModelCatalog?: TProviderModelCatalogRefresh;
+    setupHelpLinks?: readonly IProviderSetupHelpLink[];
+    setupSteps?: readonly IProviderSetupStepDefinition[];
+    credentialRequirement?: IProviderCredentialRequirement;
+    requiresApiKey?: boolean;
+    createProvider: (config: IProviderConfig$1) => IAIProvider;
+    probeProfile?: (profile: IProviderProfileConfig) => Promise<IProviderProbeResult>;
+}
+declare function findProviderDefinition(definitions: readonly IProviderDefinition[], type: string): IProviderDefinition | undefined;
+declare function formatSupportedProviderTypes(definitions: readonly IProviderDefinition[]): string;
+declare function getProviderCredentialRequirement(definition: IProviderDefinition | undefined): IProviderCredentialRequirement | undefined;
+
 /**
  * Provider-agnostic media output reference.
  * Providers must not return raw binary payloads in this contract.
@@ -1818,6 +2055,75 @@ interface IAgentFactory {
     mergeConfig(base: IAgentConfig, override: Partial<IAgentConfig>): IAgentConfig;
 }
 
+/**
+ * OpenAPI specification configuration
+ */
+interface IOpenAPIToolConfig {
+    /** OpenAPI 3.0 specification */
+    spec: {
+        openapi: string;
+        info: {
+            title: string;
+            version: string;
+            description?: string;
+        };
+        servers?: Array<{
+            url: string;
+            description?: string;
+        }>;
+        paths: Record<string, Record<string, string | number | boolean | Record<string, string | number | boolean>>>;
+        components?: Record<string, Record<string, string | number | boolean>>;
+    };
+    /** Operation ID from the OpenAPI spec */
+    operationId: string;
+    /** Base URL for API calls */
+    baseURL: string;
+    /** Authentication configuration */
+    auth?: {
+        type: 'bearer' | 'apiKey' | 'basic';
+        token?: string;
+        apiKey?: string;
+        header?: string;
+        username?: string;
+        password?: string;
+    };
+}
+/**
+ * MCP (Model Context Protocol) configuration
+ */
+interface IMCPToolConfig {
+    /** MCP server endpoint */
+    endpoint: string;
+    /** Protocol version */
+    version?: string;
+    /** Authentication configuration */
+    auth?: {
+        type: 'bearer' | 'apiKey';
+        token: string;
+    };
+    /** Tool-specific configuration */
+    toolConfig?: Record<string, string | number | boolean>;
+    /** Timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Tool factory interface
+ */
+interface IToolFactory {
+    /**
+     * Create function tool from schema and function
+     */
+    createFunctionTool(schema: IToolSchema, fn: TToolExecutor): IFunctionTool;
+    /**
+     * Create tool from OpenAPI specification
+     */
+    createOpenAPITool(config: IOpenAPIToolConfig): ITool;
+    /**
+     * Create MCP tool
+     */
+    createMCPTool(config: IMCPToolConfig): ITool;
+}
+
 /**
  * Execution step definition for tools that support step-by-step progress reporting
  */
@@ -2384,72 +2690,13 @@ interface IExecutorAwareProviderConfig {
     [key: string]: string | number | boolean | IExecutor | undefined;
 }
 /**
- * Base AI provider implementation with proper type constraints
- * All AI providers should extend this class
- *
- * ========================================
- * CRITICAL IMPLEMENTATION GUIDELINES
- * ========================================
- *
- * ALL AI PROVIDER IMPLEMENTATIONS (OpenAI, Anthropic, Google, etc.) MUST:
- *
- * 1. EXTEND THIS CLASS:
- *    ```typescript
- *    export class OpenAIProvider extends AbstractAIProvider {
- *        override readonly name = 'openai';
- *        override readonly version = '1.0.0';
- *    ```
- *
- * 2. USE IMPORTS FROM @robota-sdk/agent-core:
- *    ```typescript
- *    import { AbstractAIProvider } from '@robota-sdk/agent-core';
- *    import type {
- *        TUniversalMessage,
- *        ChatOptions,
- *        IToolCall,
- *        ToolSchema,
- *        AssistantMessage
- *    } from '@robota-sdk/agent-core';
- *    ```
- *
- * 3. USE OVERRIDE KEYWORD FOR ALL INHERITED METHODS:
- *    - override async chat(...)
- *    - override async *chatStream(...)
- *    - override supportsTools()
- *    - override validateConfig()
- *    - override async dispose()
- *
- * 4. DO NOT REDEFINE TYPES THAT EXIST IN @robota-sdk/agent-core:
- *    - TUniversalMessage
- *    - ChatOptions
- *    - IToolCall
- *    - ToolSchema
- *    - AssistantMessage
- *    - SystemMessage
- *    - UserMessage
- *    - ToolMessage
+ * Base AI provider implementation with proper type constraints.
+ * All AI providers should extend this class.
  *
- * 5. HANDLE MESSAGE CONTENT PROPERLY:
- *    - For tool calls: content should be null (not empty string)
- *    - For regular messages: content can be string or null
- *    - Always preserve null values from API responses
+ * Subclasses MUST: extend this class, use override keyword, call super() in constructor,
+ * not redefine types that exist in agent-core, handle null message content correctly.
  *
- * 6. CALL SUPER() IN CONSTRUCTOR:
- *    ```typescript
- *    constructor(options: IProviderOptions) {
- *        super();
- *        // provider-specific initialization
- *    }
- *    ```
- *
- * This ensures ExecutionService can properly identify providers
- * and prevents type conflicts across the codebase.
- *
- * ========================================
- *
- * @template TConfig - Provider configuration type (defaults to IProviderConfig for type safety)
- * @template TUniversalMessage - Message type (defaults to TUniversalMessage for backward compatibility)
- * @template TResponse - Response type (defaults to TUniversalMessage for backward compatibility)
+ * @template TConfig - Provider configuration type
  */
 declare abstract class AbstractAIProvider<TConfig = IProviderConfig> implements IAIProvider {
     abstract readonly name: string;
@@ -2470,6 +2717,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
@@ -2496,30 +2752,24 @@ declare abstract class AbstractAIProvider<TConfig = IProviderConfig> implements
      * @returns true if tool calling is supported
      */
     supportsTools(): boolean;
+    getCapabilities(): IProviderCapabilities;
     /**
      * Default implementation - providers can override for specific validation
      * @returns true if configuration is valid
      */
     validateConfig(): boolean;
-    /**
-     * Utility method for validating TUniversalMessage array
-     * @param messages - Messages to validate
-     */
+    /** Validate that messages is a non-empty array with valid roles. */
     protected validateMessages(messages: TUniversalMessage[]): void;
-    /**
-     * Utility method for validating tool schemas
-     * @param tools - Tool schemas to validate
-     */
+    /** Validate tool schemas. No-ops if tools is undefined. */
     protected validateTools(tools?: IToolSchema[]): void;
+    protected validateNativeWebTools(request?: IProviderNativeWebToolRequest): void;
     /**
      * Execute chat via executor.
-     *
      * Subclasses should call this only when an executor is configured.
      */
     protected executeViaExecutorOrDirect(messages: TUniversalMessage[], options?: IChatOptions): Promise<TUniversalMessage>;
     /**
      * Execute streaming chat via executor.
-     *
      * Subclasses should call this only when an executor is configured.
      */
     protected executeStreamViaExecutorOrDirect(messages: TUniversalMessage[], options?: IChatOptions): AsyncIterable<TUniversalMessage>;
@@ -2636,55 +2886,26 @@ declare abstract class AbstractExecutor implements IExecutor {
     protected validateResponse(response: TUniversalMessage): void;
 }
 
-interface IOpenAIMessage {
-    role: 'system' | 'user' | 'assistant' | 'tool';
-    content: string | null;
-    tool_calls?: {
-        id: string;
-        type: 'function';
-        function: {
-            name: string;
-            arguments: string;
-        };
-    }[];
-    tool_call_id?: string;
-    name?: string;
-}
-interface IAnthropicProviderMessage {
-    role: 'user' | 'assistant';
-    content: string;
-}
-interface IGoogleProviderMessage {
-    role: 'user' | 'model';
-    parts: {
-        text: string;
-    }[];
-}
 /**
- * Provider message format union type
+ * Provider message format type.
+ *
+ * Provider packages own concrete message shapes. Core only carries the generic
+ * conversion hook and never branches on provider names.
  */
-type TProviderMessage = IOpenAIMessage | IAnthropicProviderMessage | IGoogleProviderMessage | TUniversalMessage;
+type TProviderMessage = TUniversalMessage | IUniversalObjectValue;
+type TMessageFormatConverter<TMessage extends TProviderMessage = TProviderMessage> = (messages: readonly TUniversalMessage[]) => TMessage[];
+type TMessageConverterRegistry = Readonly<Record<string, TMessageFormatConverter>>;
 /**
  * Universal message converter utility
- * Handles message format conversion between different providers
+ *
+ * The converter is registry-based so provider-specific message conversion is
+ * injected by provider packages or callers instead of being hardcoded in core.
  */
 declare class MessageConverter {
     /**
-     * Convert messages to provider-specific format
-     */
-    static toProviderFormat(messages: TUniversalMessage[], providerName: string): TProviderMessage[];
-    /**
-     * Convert to OpenAI format
-     */
-    private static toOpenAIFormat;
-    /**
-     * Convert to Anthropic format
-     */
-    private static toAnthropicFormat;
-    /**
-     * Convert to Google format
+     * Convert messages using an injected converter or converter registry.
      */
-    private static toGoogleFormat;
+    static toProviderFormat(messages: TUniversalMessage[], converter?: TMessageFormatConverter | string, registry?: TMessageConverterRegistry): TProviderMessage[];
     /**
      * Convert to universal format (no conversion)
      */
@@ -2730,7 +2951,7 @@ declare class Validator {
     /**
      * Validate API key format (basic check)
      */
-    static validateApiKey(apiKey: string, provider?: string): ISimpleValidationResult;
+    static validateApiKey(apiKey: string): ISimpleValidationResult;
 }
 declare const validateAgentConfig: typeof Validator.validateAgentConfig;
 declare const validateUserInput: typeof Validator.validateUserInput;
@@ -2919,6 +3140,132 @@ 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 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;
+    };
+    /** @internal */
+    private cleanupOldConversations;
+}
+
 /**
  * Local executor that directly delegates to AI provider instances
  *
@@ -3047,7 +3394,6 @@ interface IEventEmitterHierarchicalEventData extends IEventEmitterEventData {
         actualResult?: IToolResult;
     };
 }
-
 /** Event emitter configuration */
 interface IEventEmitterPluginOptions extends IPluginOptions {
     events?: TEventName[];
@@ -3104,17 +3450,49 @@ declare class EventEmitterPlugin extends AbstractPlugin<IEventEmitterPluginOptio
     off(eventType: TEventName, handlerIdOrListener: string | TEventEmitterListener): boolean;
     emit(eventType: TEventName, eventData?: Partial<IEventEmitterEventData>): Promise<void>;
     private processEvent;
-    private executeHandler;
     flushBuffer(): Promise<void>;
     getStats(): IEventEmitterPluginStats;
     clearAllListeners(): void;
     destroy(): Promise<void>;
-    private validateOptions;
 }
 
+/**
+ * Configuration and tool management delegate for the Robota agent.
+ *
+ * Extracted from robota.ts to keep the main class under 300 lines.
+ */
+
 /** Agent statistics metadata type */
 type TAgentStatsMetadata = Record<string, string | number | boolean | Date | string[]>;
 
+/** Shared model configuration shape used in setModel / getModel. */
+type TModelConfig = {
+    provider: string;
+    model: string;
+    temperature?: number;
+    maxTokens?: number;
+    topP?: number;
+    systemMessage?: string;
+};
+/** Return shape of getConfiguration(). */
+type TConfigurationSnapshot = {
+    version: number;
+    tools: Array<{
+        name: string;
+        parameters?: string[];
+    }>;
+    updatedAt: number;
+};
+/** Return shape of getModuleStats(). */
+type TModuleStats = {
+    totalExecutions: number;
+    successfulExecutions: number;
+    failedExecutions: number;
+    averageExecutionTime: number;
+    lastExecutionTime?: Date;
+} | undefined;
+/** Shorthand for the plugin contract type used throughout this class. */
+type TPlugin = IPluginContract<IPluginOptions, IPluginStats> & IPluginHooks;
 /**
  * Core AI agent integrating multiple AI providers, tools, and plugins
  * into a unified conversational interface.
@@ -3144,50 +3522,33 @@ declare class Robota extends AbstractAgent<IAgentConfig, IRunOptions, TUniversal
     private pluginManager;
     private configManager;
     constructor(config: IAgentConfig);
-    private initDelegates;
-    private emitCreatedEvent;
     run(input: string, options?: IRunOptions): Promise<string>;
     runStream(input: string, options?: IRunOptions): AsyncGenerator<string, void, undefined>;
     private executionDeps;
     getHistory(): TUniversalMessage[];
+    getFullHistory(): IHistoryEntry[];
+    addHistoryEntry(entry: IHistoryEntry): void;
     clearHistory(): void;
+    injectMessage(role: 'user' | 'assistant' | 'system' | 'tool', content: string, options?: {
+        toolCallId?: string;
+        name?: string;
+    }): void;
     updateTools(next: Array<IToolWithEventService>): Promise<{
         version: number;
     }>;
     updateConfiguration(patch: Partial<IAgentConfig>): Promise<{
         version: number;
     }>;
-    getConfiguration(): Promise<{
-        version: number;
-        tools: Array<{
-            name: string;
-            parameters?: string[];
-        }>;
-        updatedAt: number;
-    }>;
-    setModel(mc: {
-        provider: string;
-        model: string;
-        temperature?: number;
-        maxTokens?: number;
-        topP?: number;
-        systemMessage?: string;
-    }): void;
-    getModel(): {
-        provider: string;
-        model: string;
-        temperature?: number;
-        maxTokens?: number;
-        topP?: number;
-        systemMessage?: string;
-    };
+    getConfiguration(): Promise<TConfigurationSnapshot>;
+    setModel(mc: TModelConfig): void;
+    getModel(): TModelConfig;
     registerTool(tool: AbstractTool): void;
     unregisterTool(toolName: string): void;
     getConfig(): IAgentConfig;
-    addPlugin(plugin: IPluginContract<IPluginOptions, IPluginStats> & IPluginHooks): void;
+    addPlugin(plugin: TPlugin): void;
     removePlugin(pluginName: string): boolean;
-    getPlugin(pluginName: string): (IPluginContract<IPluginOptions, IPluginStats> & IPluginHooks) | undefined;
-    getPlugins(): Array<IPluginContract<IPluginOptions, IPluginStats> & IPluginHooks>;
+    getPlugin(pluginName: string): TPlugin | undefined;
+    getPlugins(): TPlugin[];
     getPluginNames(): string[];
     registerModule(module: IModule, options?: {
         autoInitialize?: boolean;
@@ -3210,13 +3571,7 @@ declare class Robota extends AbstractAgent<IAgentConfig, IRunOptions, TUniversal
         error?: Error;
         duration?: number;
     }>;
-    getModuleStats(moduleName: string): {
-        totalExecutions: number;
-        successfulExecutions: number;
-        failedExecutions: number;
-        averageExecutionTime: number;
-        lastExecutionTime?: Date;
-    } | undefined;
+    getModuleStats(moduleName: string): TModuleStats;
     getStats(): {
         name: string;
         version: string;
@@ -3235,7 +3590,6 @@ declare class Robota extends AbstractAgent<IAgentConfig, IRunOptions, TUniversal
     private ensureFullyInitialized;
     private doAsyncInit;
     private emitAgentEvent;
-    private buildOwnerPath;
 }
 
 /**
@@ -3356,6 +3710,7 @@ interface IAgentLifecycleEvents {
     /** Called when agent is destroyed */
     onDestroy?: (agentId: string) => Promise<void> | void;
 }
+
 /**
  * Agent Factory for creating and managing agents
  * Instance-based for isolated agent factory management
@@ -3429,97 +3784,18 @@ declare class AgentFactory {
         isValid: boolean;
         errors: string[];
     };
-    /**
-     * Apply default configuration values
-     */
-    private applyDefaults;
-    /**
-     * Generate unique agent ID
-     */
-    private generateAgentId;
-    /**
-     * Update creation statistics
-     */
-    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;
+interface IAssistantUsageMetadata {
+    inputTokens: number;
+    outputTokens: number;
+    usage: {
+        totalTokens: number;
+        inputTokens: number;
+        outputTokens: number;
     };
 }
+declare function collectAssistantUsageMetadata(message: TUniversalMessage): IAssistantUsageMetadata | undefined;
 
 declare class EventHistoryModule implements IEventHistoryModule {
     private readonly store;
@@ -3997,11 +4273,13 @@ interface IExecutionProxyConfig {
         task?: boolean;
     };
 }
+/** Internal target shape for proxy interception */
+type TExecutionProxyTarget = Record<string, TUniversalValue>;
+/** Internal args shape for proxy interception */
+type TExecutionProxyArgs = TUniversalValue[];
 /**
  * Metadata extractor function type
  */
-type TExecutionProxyTarget = Record<string, TUniversalValue>;
-type TExecutionProxyArgs = TUniversalValue[];
 type TMetadataExtractor = (target: TExecutionProxyTarget, methodName: string, args: TExecutionProxyArgs) => Record<string, TUniversalValue>;
 /**
  * Method configuration for proxy
@@ -4013,6 +4291,7 @@ interface IMethodConfig {
     extractMetadata?: TMetadataExtractor;
     extractResult?: (result: TUniversalValue) => Record<string, TUniversalValue>;
 }
+
 /**
  * ExecutionProxy - Automatic event emission using Proxy pattern
  *
@@ -4129,7 +4408,7 @@ declare function evaluatePermission(toolName: string, toolArgs: TToolArgs, mode:
  * Permission mode definitions for Robota CLI
  *
  * Matches Claude Code-compatible permission modes:
- * - plan: read-only tools only (Read, Glob, Grep auto; Write, Edit, Bash denied)
+ * - plan: read-only tools only (Read, Glob, Grep, WebFetch, WebSearch auto; Write, Edit, Bash denied)
  * - default: safe reads auto, writes and bash need approval
  * - acceptEdits: reads + writes auto, bash needs approval
  * - bypassPermissions: all tools auto
@@ -4138,7 +4417,7 @@ declare function evaluatePermission(toolName: string, toolArgs: TToolArgs, mode:
 /**
  * Tool names known to the permission system
  */
-type TKnownToolName = 'Bash' | 'Read' | 'Write' | 'Edit' | 'Glob' | 'Grep';
+type TKnownToolName = 'Bash' | 'Read' | 'Write' | 'Edit' | 'Glob' | 'Grep' | 'WebFetch' | 'WebSearch';
 /**
  * Permission mode → tool policy matrix
  * Maps each mode to a decision for each known tool.
@@ -4175,22 +4454,100 @@ interface IContextWindowState {
     remainingPercentage: number;
 }
 
+declare const CONTEXT_ESTIMATE_CHARS_PER_TOKEN = 4;
+interface IContextTokenEstimateOptions {
+    readonly usageFloorTokens?: number;
+}
+interface IContextTokenEstimate {
+    readonly usedTokens: number;
+    readonly serializedTokens: number;
+    readonly providerTokens?: number;
+    readonly usageFloorTokens?: number;
+}
+declare function estimateSerializedContextTokens(messages: readonly TUniversalMessage[]): number;
+declare function estimateContextTokensFromMessages(messages: readonly TUniversalMessage[], options?: IContextTokenEstimateOptions): IContextTokenEstimate;
+
+interface IMessageTokenUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly totalTokens?: number;
+}
+/** Read normalized provider usage from a universal message when present. */
+declare function readTokenUsageFromMessage(message: TUniversalMessage): IMessageTokenUsage | undefined;
+declare function readTokenUsageFromMetadata(metadata: TUniversalMessageMetadata | undefined): IMessageTokenUsage | undefined;
+
+/**
+ * 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' | 'SessionEnd' | 'Stop' | 'StopFailure' | 'PreCompact' | 'PostCompact' | 'UserPromptSubmit' | 'SubagentStart' | 'SubagentStop' | 'WorktreeCreate' | 'WorktreeRemove';
+/** Claude Code compatible session end reasons. */
+type TSessionEndReason = 'clear' | 'resume' | 'logout' | 'prompt_input_exit' | 'bypass_permissions_disabled' | 'other';
+/** 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 +4563,28 @@ 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;
+    /** Last assistant message text (StopFailure only) */
+    last_assistant_message?: string;
+    /** Stop hook recursion guard (Stop/StopFailure only) */
+    stop_hook_active?: boolean;
+    /** Session end reason (SessionEnd only) */
+    reason?: TSessionEndReason | string;
+    /** Session transcript path when available (SessionEnd/SubagentStop only) */
+    transcript_path?: string;
+    /** Subagent identifier (SubagentStart/SubagentStop only) */
+    agent_id?: string;
+    /** Subagent type/name (SubagentStart/SubagentStop only) */
+    agent_type?: string;
+    /** Subagent transcript path when available (SubagentStop only) */
+    agent_transcript_path?: string;
+    /** Additional environment variables to pass to hook child processes */
+    env?: Record<string, string>;
 }
 /** Hook execution result */
 interface IHookResult {
@@ -4214,11 +4593,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 +4618,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, CONTEXT_ESTIMATE_CHARS_PER_TOKEN, CacheIntegrityError, CircuitBreakerOpenError, ConfigurationError, ConsoleLogger, 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 IAssistantUsageMetadata, 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 IContextTokenEstimate, type IContextTokenEstimateOptions, 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 IMessageTokenUsage, 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 IProviderCapabilities, type IProviderConfig$1 as IProviderConfig, type IProviderCredentialRequirement, type IProviderDefinition, type IProviderFunctionCallingCapability, type IProviderMediaError, type IProviderModelCatalog, type IProviderModelCatalogEntry, type IProviderModelCatalogRefreshOptions, type IProviderNativeRawPayloadEvent, type IProviderNativeWebToolCapabilities, type IProviderNativeWebToolCapability, type IProviderNativeWebToolRequest, type IProviderOptions, type IProviderProbeResult, type IProviderProfileConfig, type IProviderProfileDefaults, type IProviderRequest, type IProviderSetupHelpLink, type IProviderSetupStepDefinition, 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 TExecutionEventCallback, type TExecutionEventData, type TExecutionEventName, type TExecutionMetadata, type THookEvent, type THooksConfig, type TImageInputSource, type TJSONSchemaEnum, type TJSONSchemaKind, type TKnownToolName, type TLoggerData, type TManagerToolParameters, type TMessageConverterRegistry, type TMessageFormatConverter, type TMessageState, type TMetadata, type TMetadataValue, TOOL_EVENTS, TOOL_EVENT_PREFIX, type TParameterDefaultValue, type TPermissionDecision, type TPermissionMode, type TPrimitiveValue, type TProviderConfigValue, type TProviderCredentialField, type TProviderLoggingData, type TProviderMediaResult, type TProviderMessage, type TProviderModelCapability, type TProviderModelCatalogRefresh, type TProviderModelCatalogStatus, type TProviderModelLifecycle, type TProviderNativeRawPayload, type TProviderNativeRawPayloadCallback, type TProviderNativeRawPayloadKind, type TProviderOptionValueBase, type TProviderSetupField, type TProviderSetupHelpLinkKind, TRUST_TO_MODE, type TResponseMetadata, type TSessionEndReason, 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, TypeUtils, UNKNOWN_TOOL_FALLBACK, USER_EVENTS, USER_EVENT_PREFIX, ValidationError, ValidationSeverity, Validator, assertProviderNativeWebToolsAvailable, bindEventServiceOwner, bindWithOwnerPath, chatEntryToMessage, collectAssistantUsageMetadata, composeEventName, createAssistantMessage, createDefaultProviderCapabilities, createExecutionProxy, createLogger, createSystemMessage, createToolMessage, createUserMessage, estimateContextTokensFromMessages, estimateSerializedContextTokens, evaluatePermission, findProviderDefinition, formatSupportedProviderTypes, formatTokenCount, getGlobalLogLevel, getMessagesForAPI, getModelContextWindow, getModelMaxOutput, getModelName, getProviderCapabilities, getProviderCredentialRequirement, getToolEstimatedDuration, getToolExecutionSteps, isAssistantMessage, isChatEntry, isDefaultEventService, isImageGenerationProvider, isProgressReportingTool, isSystemMessage, isToolMessage, isUserMessage, isVideoGenerationProvider, logger, messageToHistoryEntry, readTokenUsageFromMessage, readTokenUsageFromMetadata, runHooks, setGlobalLogLevel, setToolProgressCallback, startPeriodicTask, stopPeriodicTask, validateAgentConfig, validateApiKey, validateModelName, validateProviderName, validateUserInput, withEventEmission };