@falai/agent 1.1.3 → 1.2.0

package/dist/types/compaction.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Context compaction types for managing conversation history size
+ */
+import type { AiProvider } from "./ai";
+import type { HistoryItem } from "./history";
+/**
+ * Configuration for the compaction engine.
+ *
+ * Validation constraints:
+ * - `compactionThreshold` must be between 0.5 and 0.95
+ * - `preserveRecentCount` must be >= 2
+ * - `maxToolResultChars` must be > 0
+ */
+export interface CompactionOptions {
+    /** Maximum token budget for the conversation */
+    maxTokens: number;
+    /**
+     * Threshold ratio (0–1) at which to trigger compaction.
+     * Must be between 0.5 and 0.95.
+     */
+    compactionThreshold: number;
+    /**
+     * Number of recent messages to always preserve unchanged.
+     * Must be >= 2.
+     */
+    preserveRecentCount: number;
+    /**
+     * Maximum characters per tool result before truncation.
+     * Must be > 0.
+     */
+    maxToolResultChars: number;
+    /** Provider to use for LLM summarization during auto-compact */
+    provider: AiProvider;
+}
+/**
+ * Result of a compaction operation
+ */
+export interface CompactionResult {
+    /** The compacted history */
+    history: HistoryItem[];
+    /** Strategy that was applied */
+    strategy: 'none' | 'tool_result_budget' | 'micro_compact' | 'auto_compact';
+    /** Estimated tokens after compaction */
+    estimatedTokens: number;
+    /** Number of messages removed/compacted */
+    messagesCompacted: number;
+    /** Summary text (if auto-compact was used) */
+    summary?: string;
+}
+//# sourceMappingURL=compaction.d.ts.map

package/dist/types/compaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.d.ts","sourceRoot":"","sources":["../../src/types/compaction.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAC9B,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,mBAAmB,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,mBAAmB,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gEAAgE;IAChE,QAAQ,EAAE,UAAU,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC7B,4BAA4B;IAC5B,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,gCAAgC;IAChC,QAAQ,EAAE,MAAM,GAAG,oBAAoB,GAAG,eAAe,GAAG,cAAc,CAAC;IAC3E,wCAAwC;IACxC,eAAe,EAAE,MAAM,CAAC;IACxB,2CAA2C;IAC3C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB"}

package/dist/types/compaction.js

@@ -0,0 +1,5 @@
+/**
+ * Context compaction types for managing conversation history size
+ */
+export {};
+//# sourceMappingURL=compaction.js.map

package/dist/types/compaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.js","sourceRoot":"","sources":["../../src/types/compaction.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/types/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * Central type definitions export
  */
-export type { AgentOptions, Term, Guideline, GuidelineMatch, AgentResponseStreamChunk, AgentResponse, ContextLifecycleHooks, ContextProvider, ValidationError, ValidationResult, } from "./agent";
+export type { AgentOptions, AgentCompactionConfig, Term, Guideline, GuidelineMatch, AgentResponseStreamChunk, AgentResponse, ContextLifecycleHooks, ContextProvider, ValidationError, ValidationResult, } from "./agent";
 export { CompositionMode } from "./agent";
 export type { Event, EmittedEvent, MessageEventData, ToolEventData, StatusEventData, Participant, ToolResult as EventToolResult, ToolCall, HistoryMessage, Role, HistoryItem, History, UserHistoryItem, AssistantHistoryItem, SystemHistoryItem, ToolHistoryItem, } from "./history";
 export { EventKind, MessageRole } from "./history";
@@ -9,8 +9,10 @@ export * from "./history";
 export type { RouteOptions, RouteRef, StepRef, StepOptions, BranchSpec, StepResult, BranchResult, RouteCompletionHandler, RouteTransitionConfig, RouteLifecycleHooks, } from "./route";
 export * from "./route";
 export type { SessionState, PendingTransition } from "./session";
-export type { Tool, ToolContext, ToolResult, ToolHandler, ToolExecutionResult, DataEnrichmentConfig, ValidationConfig, ApiCallConfig, ComputationConfig } from "./tool";
+export type { Tool, ToolContext, ToolResult, ToolHandler, ToolExecutionResult, EnhancedTool, ToolValidationResult, ToolPermissionResult, ToolCallRequest, ToolExecutionUpdate, TrackedTool, ToolStatus, DataEnrichmentConfig, ValidationConfig, ApiCallConfig, ComputationConfig } from "./tool";
 export { ToolScope } from "./tool";
+export type { CompactionOptions, CompactionResult, } from "./compaction";
+export type { PromptSectionType, PromptCacheConfig, SectionCompute, } from "../core/PromptSectionCache";
 export type { AiProvider, GenerateMessageInput, GenerateMessageOutput, AgentStructuredResponse, ReasoningConfig, GenerateMessageStreamChunk, } from "./ai";
 export type { StructuredSchema } from "./schema";
 export type { RoutingDecision } from "./routing";

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,YAAY,EACV,YAAY,EACZ,IAAI,EACJ,SAAS,EACT,cAAc,EACd,wBAAwB,EACxB,aAAa,EACb,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,gBAAgB,GACjB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAG1C,YAAY,EACV,KAAK,EACL,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,WAAW,EACX,UAAU,IAAI,eAAe,EAC7B,QAAQ,EACR,cAAc,EACd,IAAI,EACJ,WAAW,EACX,OAAO,EACP,eAAe,EACf,oBAAoB,EACpB,iBAAiB,EACjB,eAAe,GAChB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,cAAc,WAAW,CAAC;AAG1B,YAAY,EACV,YAAY,EACZ,QAAQ,EACR,OAAO,EACP,WAAW,EACX,UAAU,EACV,UAAU,EACV,YAAY,EACZ,sBAAsB,EACtB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,SAAS,CAAC;AACjB,cAAc,SAAS,CAAC;AAGxB,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAGjE,YAAY,EACV,IAAI,EACJ,WAAW,EACX,UAAU,EACV,WAAW,EACX,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EAClB,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAGnC,YAAY,EACV,UAAU,EACV,oBAAoB,EACpB,qBAAqB,EACrB,uBAAuB,EACvB,eAAe,EACf,0BAA0B,GAC3B,MAAM,MAAM,CAAC;AAGd,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAGjD,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,cAAc,WAAW,CAAC;AAG1B,YAAY,EACV,WAAW,EACX,WAAW,EACX,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,cAAc,eAAe,CAAC;AAG9B,YAAY,EACV,QAAQ,EACR,eAAe,EACf,iBAAiB,EACjB,yBAAyB,EAC1B,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,kBAAkB,EAClB,wBAAwB,EACxB,uBAAuB,EACvB,yBAAyB,EAC1B,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,YAAY,EACV,YAAY,EACZ,qBAAqB,EACrB,IAAI,EACJ,SAAS,EACT,cAAc,EACd,wBAAwB,EACxB,aAAa,EACb,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,gBAAgB,GACjB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAG1C,YAAY,EACV,KAAK,EACL,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,WAAW,EACX,UAAU,IAAI,eAAe,EAC7B,QAAQ,EACR,cAAc,EACd,IAAI,EACJ,WAAW,EACX,OAAO,EACP,eAAe,EACf,oBAAoB,EACpB,iBAAiB,EACjB,eAAe,GAChB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,cAAc,WAAW,CAAC;AAG1B,YAAY,EACV,YAAY,EACZ,QAAQ,EACR,OAAO,EACP,WAAW,EACX,UAAU,EACV,UAAU,EACV,YAAY,EACZ,sBAAsB,EACtB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,SAAS,CAAC;AACjB,cAAc,SAAS,CAAC;AAGxB,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAGjE,YAAY,EACV,IAAI,EACJ,WAAW,EACX,UAAU,EACV,WAAW,EACX,mBAAmB,EACnB,YAAY,EACZ,oBAAoB,EACpB,oBAAoB,EACpB,eAAe,EACf,mBAAmB,EACnB,WAAW,EACX,UAAU,EACV,oBAAoB,EACpB,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EAClB,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAGnC,YAAY,EACV,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAGtB,YAAY,EACV,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,GACf,MAAM,4BAA4B,CAAC;AAGpC,YAAY,EACV,UAAU,EACV,oBAAoB,EACpB,qBAAqB,EACrB,uBAAuB,EACvB,eAAe,EACf,0BAA0B,GAC3B,MAAM,MAAM,CAAC;AAGd,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAGjD,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,cAAc,WAAW,CAAC;AAG1B,YAAY,EACV,WAAW,EACX,WAAW,EACX,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,cAAc,eAAe,CAAC;AAG9B,YAAY,EACV,QAAQ,EACR,eAAe,EACf,iBAAiB,EACjB,yBAAyB,EAC1B,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,kBAAkB,EAClB,wBAAwB,EACxB,uBAAuB,EACvB,yBAAyB,EAC1B,MAAM,oBAAoB,CAAC"}

package/dist/types/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAeH,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAqB1C,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,cAAc,WAAW,CAAC;AAe1B,cAAc,SAAS,CAAC;AAiBxB,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAiBnC,cAAc,WAAW,CAAC;AAgB1B,cAAc,eAAe,CAAC;AAS9B,OAAO,EACL,kBAAkB,EAClB,wBAAwB,EACxB,uBAAuB,EACvB,yBAAyB,EAC1B,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAgBH,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAqB1C,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,cAAc,WAAW,CAAC;AAe1B,cAAc,SAAS,CAAC;AAwBxB,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AA8BnC,cAAc,WAAW,CAAC;AAgB1B,cAAc,eAAe,CAAC;AAS9B,OAAO,EACL,kBAAkB,EAClB,wBAAwB,EACxB,uBAAuB,EACvB,yBAAyB,EAC1B,MAAM,oBAAoB,CAAC"}

package/dist/types/tool.d.ts

@@ -84,6 +84,90 @@ export declare enum ToolScope {
     REGISTERED = "registered",
     ALL = "all"
 }
+/**
+ * Result of input validation on a tool call
+ */
+export interface ToolValidationResult {
+    valid: boolean;
+    error?: string;
+    /** Suggested corrected input */
+    correctedInput?: Record<string, unknown>;
+}
+/**
+ * Result of a permission check on a tool call
+ */
+export interface ToolPermissionResult {
+    allowed: boolean;
+    reason?: string;
+    /** If not allowed, can the user override? */
+    canOverride?: boolean;
+}
+/**
+ * A single tool invocation request from the LLM
+ */
+export interface ToolCallRequest {
+    /** Unique ID for this tool call instance */
+    id: string;
+    /** Tool name/ID to execute */
+    toolName: string;
+    /** Arguments passed to the tool */
+    arguments: Record<string, unknown>;
+}
+/**
+ * Result or progress update from a tool execution
+ */
+export interface ToolExecutionUpdate<TData = unknown> {
+    /** The tool call this update relates to */
+    toolCallId: string;
+    /** Result message (undefined for progress updates) */
+    result?: ToolExecutionResult;
+    /** Progress message for long-running tools */
+    progress?: string;
+    /** Updated context after tool execution */
+    contextUpdate?: Record<string, unknown>;
+    /** Updated data after tool execution */
+    dataUpdate?: Partial<TData>;
+}
+/**
+ * Internal status of a tracked tool in the executor queue
+ */
+export type ToolStatus = 'queued' | 'executing' | 'completed' | 'yielded';
+/**
+ * Internal type tracking the state of a queued or executing tool
+ */
+export interface TrackedTool<TContext = unknown, TData = unknown> {
+    id: string;
+    toolCall: ToolCallRequest;
+    tool: EnhancedTool<TContext, TData>;
+    status: ToolStatus;
+    isConcurrencySafe: boolean;
+    promise?: Promise<void>;
+    results: ToolExecutionResult[];
+    pendingProgress: string[];
+}
+/**
+ * Extended tool interface with rich metadata for concurrency control,
+ * permission gating, input validation, and result size management.
+ *
+ * All additional methods/properties are optional — plain `Tool` objects
+ * remain fully compatible.
+ */
+export interface EnhancedTool<TContext = any, TData = any, TResult = any> extends Tool<TContext, TData, TResult> {
+    /** Whether this tool is safe to run concurrently with other concurrent-safe tools */
+    isConcurrencySafe?(input?: Record<string, unknown>): boolean;
+    /** Whether this tool only reads data without side effects */
+    isReadOnly?(input?: Record<string, unknown>): boolean;
+    /** Whether this tool performs destructive/irreversible operations */
+    isDestructive?(input?: Record<string, unknown>): boolean;
+    /** How the tool responds to abort signals: 'cancel' = immediate abort, 'block' = allow completion */
+    interruptBehavior?(): 'cancel' | 'block';
+    /** Maximum characters for the tool result before truncation */
+    maxResultSizeChars?: number;
+    /** Validate input before execution */
+    validateInput?(input: Record<string, unknown>, context: ToolContext<TContext, TData>): Promise<ToolValidationResult> | ToolValidationResult;
+    /** Check permissions before execution */
+    checkPermissions?(input: Record<string, unknown>, context: ToolContext<TContext, TData>): Promise<ToolPermissionResult> | ToolPermissionResult;
+}
 /**
  * Configuration for data enrichment tools
  */

package/dist/types/tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/types/tool.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/types/tool.ts"],"names":[],"mappings":"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"}

package/docs/api/overview.md

@@ -12,10 +12,14 @@ Complete API documentation for `@falai/agent`. This framework provides a strongl
   - [RoutingEngine](#routingengine)
   - [ResponseEngine](#responseengine)
   - [PromptComposer](#promptcomposer)
+  - [StreamingToolExecutor](#streamingtoolexecutor)
+  - [CompactionEngine](#compactionengine)
+  - [PromptSectionCache](#promptsectioncache)
 
 - [AI Providers](#ai-providers)
 - [Persistence Adapters](#persistence-adapters)
 - [Types & Interfaces](#types--interfaces)
+  - [EnhancedTool](#enhancedtool)
 - [Utilities](#utilities)
 
 ---
@@ -602,6 +606,119 @@ build(): Promise<string>
 
 
 
+---
+
+### StreamingToolExecutor
+
+Executes tools as they arrive from the LLM stream with concurrency control, abort handling, and ordered result yielding.
+
+#### Constructor
+
+```typescript
+new StreamingToolExecutor<TContext, TData>(
+  toolContext: ToolContext<TContext, TData>,
+  options?: {
+    maxParallel?: number;   // default: 10
+    signal?: AbortSignal;
+  }
+)
+```
+
+#### Methods
+
+```typescript
+addTool(toolCall: ToolCallRequest, tool: EnhancedTool<TContext, TData>): void
+```
+
+Queue a tool for execution. Concurrency safety is evaluated once at queue time.
+
+```typescript
+getCompletedResults(): Generator<ToolExecutionUpdate<TData>>
+```
+
+Synchronous generator yielding available results in request order.
+
+```typescript
+getRemainingResults(): AsyncGenerator<ToolExecutionUpdate<TData>>
+```
+
+Async generator yielding all results, waiting for pending tools.
+
+```typescript
+discard(): void
+getUpdatedContext(): TContext
+hasUnfinishedTools(): boolean
+```
+
+See [Streaming Execution Guide](../core/tools/streaming-execution.md) for detailed usage.
+
+---
+
+### CompactionEngine
+
+Manages conversation history size through multi-layered compaction strategies.
+
+#### Static Methods
+
+```typescript
+CompactionEngine.estimateTokens(history: HistoryItem[]): number
+CompactionEngine.applyToolResultBudget(history: HistoryItem[], maxCharsPerResult: number): HistoryItem[]
+CompactionEngine.validateOptions(options: CompactionOptions): void
+CompactionEngine.checkAndCompact(history: HistoryItem[], options: CompactionOptions): Promise<CompactionResult>
+```
+
+See [Context Compaction Guide](../guides/context-compaction.md) for detailed usage.
+
+---
+
+### PromptSectionCache
+
+Memoizes static prompt sections across turns, recomputing only dynamic sections per-turn. Integrates with `PromptComposer` for optimized prompt generation.
+
+#### Constructor
+
+```typescript
+new PromptSectionCache(config?: PromptCacheConfig)
+```
+
+#### Configuration
+
+```typescript
+interface PromptCacheConfig {
+  enabled?: boolean;       // default: true
+  volatileKeys?: string[]; // keys that always recompute
+}
+```
+
+#### Methods
+
+```typescript
+register(key: string, type: PromptSectionType, compute: () => string | null | Promise<string | null>): void
+```
+
+Register a section as `'static'` (cached) or `'dynamic'` (recomputed every turn).
+
+```typescript
+get(key: string): Promise<string | null>
+```
+
+Get a section's value, using cache for static sections.
+
+```typescript
+resolveAll(): Promise<(string | null)[]>
+```
+
+Resolve all sections in registration order.
+
+```typescript
+invalidate(key: string): void
+invalidateAll(): void
+```
+
+Invalidate a specific section or all sections.
+
+See [Prompt Optimization Guide](../guides/prompt-optimization.md) for detailed usage.
+
 ---
 
 ## AI Providers
@@ -1077,6 +1194,29 @@ type ToolHandler<TContext, TArgs extends unknown[], TResult, TData> = (
 }>;
 ```
 
+### EnhancedTool
+
+Extends `Tool` with optional metadata for concurrency, permissions, validation, and result budgeting. See [EnhancedTool Reference](../core/tools/enhanced-tool.md) for full documentation.
+
+```typescript
+interface EnhancedTool<TContext, TData, TResult> extends Tool<TContext, TData, TResult> {
+  isConcurrencySafe?(input?: Record<string, unknown>): boolean;
+  isReadOnly?(input?: Record<string, unknown>): boolean;
+  isDestructive?(input?: Record<string, unknown>): boolean;
+  interruptBehavior?(): 'cancel' | 'block';
+  maxResultSizeChars?: number;
+  validateInput?(input: Record<string, unknown>, context: ToolContext<TContext, TData>): Promise<ToolValidationResult> | ToolValidationResult;
+  checkPermissions?(input: Record<string, unknown>, context: ToolContext<TContext, TData>): Promise<ToolPermissionResult> | ToolPermissionResult;
+}
+
+interface ToolValidationResult { valid: boolean; error?: string; correctedInput?: Record<string, unknown>; }
+interface ToolPermissionResult { allowed: boolean; reason?: string; canOverride?: boolean; }
+interface ToolCallRequest { id: string; toolName: string; arguments: Record<string, unknown>; }
+interface ToolExecutionUpdate<TData> { toolCallId: string; result?: ToolExecutionResult; progress?: string; contextUpdate?: Record<string, unknown>; dataUpdate?: Partial<TData>; }
+interface CompactionOptions { maxTokens: number; compactionThreshold: number; preserveRecentCount: number; maxToolResultChars: number; provider: AiProvider; }
+interface CompactionResult<TData> { history: HistoryItem[]; strategy: 'none' | 'tool_result_budget' | 'micro_compact' | 'auto_compact'; estimatedTokens: number; messagesCompacted: number; summary?: string; }
+```
+
 ### AI Provider Types
 
 ```typescript

package/docs/core/tools/enhanced-tool.md

@@ -0,0 +1,186 @@
+# EnhancedTool Interface
+
+`EnhancedTool` extends the existing `Tool` interface with optional metadata for concurrency control, permission gating, input validation, and result size management. All additional methods are optional — plain `Tool` objects remain fully compatible.
+
+## Interface
+
+```typescript
+interface EnhancedTool<TContext = any, TData = any, TResult = any>
+  extends Tool<TContext, TData, TResult> {
+
+  // Concurrency & safety
+  isConcurrencySafe?(input?: Record<string, unknown>): boolean;
+  isReadOnly?(input?: Record<string, unknown>): boolean;
+  isDestructive?(input?: Record<string, unknown>): boolean;
+
+  // Execution control
+  interruptBehavior?(): 'cancel' | 'block';
+  maxResultSizeChars?: number;
+
+  // Validation & permissions
+  validateInput?(
+    input: Record<string, unknown>,
+    context: ToolContext<TContext, TData>
+  ): Promise<ToolValidationResult> | ToolValidationResult;
+
+  checkPermissions?(
+    input: Record<string, unknown>,
+    context: ToolContext<TContext, TData>
+  ): Promise<ToolPermissionResult> | ToolPermissionResult;
+}
+```
+
+## Methods & Properties
+
+### isConcurrencySafe
+
+Returns `true` if this tool can safely run in parallel with other concurrency-safe tools. The `StreamingToolExecutor` evaluates this once at queue time and caches the result.
+
+Default (when absent): `false` — the tool runs serially.
+
+```typescript
+const listFiles: EnhancedTool = {
+  id: "list-files",
+  name: "list_files",
+  description: "List files in a directory",
+  handler: async (ctx, args) => { /* ... */ },
+  isConcurrencySafe: () => true,
+};
+```
+
+The method receives the tool's input arguments, so concurrency safety can be input-dependent:
+
+```typescript
+isConcurrencySafe: (input) => {
+  // Safe for read paths, not safe for write paths
+  return input?.mode === "read";
+},
+```
+
+### isReadOnly / isDestructive
+
+Informational metadata. `isReadOnly` indicates the tool has no side effects; `isDestructive` indicates irreversible operations. Both default to `false` when absent.
+
+```typescript
+isReadOnly: () => true,
+isDestructive: () => false,
+```
+
+### interruptBehavior
+
+Controls how the tool responds to abort signals (sibling failure or parent cancellation):
+
+- `'cancel'` — immediately abort the tool
+- `'block'` — allow the tool to finish (default when absent)
+
+```typescript
+interruptBehavior: () => "cancel",
+```
+
+### maxResultSizeChars
+
+Maximum characters for the tool result. Results exceeding this limit are truncated with a notice like `[Truncated: 12000 chars total, showing first 5000]`.
+
+```typescript
+maxResultSizeChars: 50_000,
+```
+
+### validateInput
+
+Called before the tool handler. If it returns `{ valid: false }`, the handler is never invoked and a validation error is returned instead.
+
+```typescript
+validateInput: async (input, ctx) => {
+  if (!input.resourceId || typeof input.resourceId !== "string") {
+    return { valid: false, error: "resourceId must be a non-empty string" };
+  }
+  return { valid: true };
+},
+```
+
+The return type:
+
+```typescript
+interface ToolValidationResult {
+  valid: boolean;
+  error?: string;
+  correctedInput?: Record<string, unknown>;
+}
+```
+
+### checkPermissions
+
+Called before the tool handler (after validation). If it returns `{ allowed: false }`, the handler is never invoked and a permission error is returned.
+
+```typescript
+checkPermissions: async (input, ctx) => {
+  const role = (ctx.context as any)?.userRole;
+  if (role !== "admin") {
+    return { allowed: false, reason: "Only admins can delete resources", canOverride: false };
+  }
+  return { allowed: true };
+},
+```
+
+The return type:
+
+```typescript
+interface ToolPermissionResult {
+  allowed: boolean;
+  reason?: string;
+  canOverride?: boolean;
+}
+```
+
+## Full Example
+
+```typescript
+const deleteTool: EnhancedTool = {
+  id: "delete-resource",
+  name: "delete_resource",
+  description: "Delete a resource permanently",
+  parameters: {
+    type: "object",
+    properties: { resourceId: { type: "string" } },
+    required: ["resourceId"],
+  },
+  handler: async (ctx, args) => {
+    await deleteResource(args?.resourceId as string);
+    return { success: true };
+  },
+
+  isConcurrencySafe: () => false,
+  isReadOnly: () => false,
+  isDestructive: () => true,
+  interruptBehavior: () => "block",
+  maxResultSizeChars: 500,
+
+  validateInput: async (input) => {
+    if (!input.resourceId || typeof input.resourceId !== "string") {
+      return { valid: false, error: "resourceId must be a non-empty string" };
+    }
+    return { valid: true };
+  },
+
+  checkPermissions: async (input, ctx) => {
+    const role = (ctx.context as any)?.userRole;
+    if (role !== "admin") {
+      return { allowed: false, reason: "Only admins can delete resources" };
+    }
+    return { allowed: true };
+  },
+};
+```
+
+## Backward Compatibility
+
+Plain `Tool` objects without any `EnhancedTool` methods work exactly as before. The framework applies these defaults:
+
+| Property | Default |
+|---|---|
+| `isConcurrencySafe` | `false` |
+| `isReadOnly` | `false` |
+| `isDestructive` | `false` |
+| `interruptBehavior` | `'block'` |
+| `validateInput` | skipped |
+| `checkPermissions` | skipped |