@robota-sdk/agent-core 3.0.0-beta.3 → 3.0.0-beta.30

package/dist/browser/index.d.ts

@@ -14,7 +14,7 @@ type TUniversalMessageRole = 'user' | 'assistant' | 'system' | 'tool';
 /**
  * Message metadata used across conversation history and provider adapters.
  */
-type TUniversalMessageMetadata = Record<string, string | number | boolean | Date | string[] | number[]>;
+type TUniversalMessageMetadata = Record<string, string | number | boolean | Date | string[] | number[] | Record<string, number>>;
 /**
  * Universal multimodal message part contracts.
  */
@@ -3151,6 +3151,8 @@ declare class Robota extends AbstractAgent<IAgentConfig, IRunOptions, TUniversal
     private executionDeps;
     getHistory(): TUniversalMessage[];
     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;
     }>;
@@ -4175,22 +4177,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 +4262,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 +4278,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 +4303,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, AbstractExecutor, AbstractManager, AbstractPlugin, AbstractTool, AgentFactory, AgentTemplates, AuthenticationError, CLAUDE_MODELS, CacheIntegrityError, CircuitBreakerOpenError, ConfigurationError, ConversationHistory, ConversationSession, DEFAULT_CONTEXT_WINDOW, DEFAULT_MAX_OUTPUT, 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 IEventService, type IEventServiceOwnerBinding, type IExecutionEventData, type IExecutionService, type IExecutionServiceOptions, type IExecutor, type IExecutorAwareProviderConfig, type IFunctionTool, 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, 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, formatTokenCount, getGlobalLogLevel, getModelContextWindow, getModelMaxOutput, getModelName, getToolEstimatedDuration, getToolExecutionSteps, isAssistantMessage, isImageGenerationProvider, isProgressReportingTool, isSystemMessage, isToolMessage, isUserMessage, isVideoGenerationProvider, logger, runHooks, setGlobalLogLevel, setToolProgressCallback, startPeriodicTask, stopPeriodicTask, validateAgentConfig, validateApiKey, validateModelName, validateProviderName, validateUserInput, withEventEmission };