@everworker/oneringai 0.4.7 → 0.4.8

package/dist/{index-Blci0FEd.d.ts → index-13HQuxEB.d.ts}

@@ -98,6 +98,148 @@ interface ReasoningItem {
 type InputItem = Message | CompactionItem;
 type OutputItem = Message | CompactionItem | ReasoningItem;
 
+/**
+ * IHistoryJournal - Interface for append-only conversation history logging
+ *
+ * Provides a durable, append-only log of all conversation messages,
+ * independent of context compaction. While the agent's working window
+ * (_conversation) may be compacted to fit the LLM context, the journal
+ * preserves the full conversation history on disk/database.
+ *
+ * The journal is a companion capability of IContextStorage — storage
+ * implementations that support history logging expose it via the
+ * `journal` property. Consumers never configure the journal separately;
+ * it comes for free with the storage backend.
+ *
+ * Access patterns:
+ * - **Write**: append-only, per-message, fire-and-forget (non-blocking)
+ * - **Read**: on-demand, explicit (never loaded automatically)
+ *
+ * @example
+ * ```typescript
+ * // File storage → FileHistoryJournal (JSONL files)
+ * const storage = new FileContextStorage({ agentId: 'my-agent' });
+ * storage.journal.append('session-1', [entry]);
+ *
+ * // Mongo storage → MongoHistoryJournal (collection)
+ * const storage = new MongoContextStorage({ agentId: 'my-agent', db });
+ * storage.journal.append('session-1', [entry]);
+ *
+ * // Reading history (on-demand, explicit)
+ * const entries = await storage.journal.read('session-1', { limit: 50 });
+ * const total = await storage.journal.count('session-1');
+ * ```
+ */
+
+/**
+ * Type of history entry, derived from the message's role/purpose.
+ */
+type HistoryEntryType = 'user' | 'assistant' | 'tool_result' | 'system';
+/**
+ * A single entry in the history journal.
+ *
+ * Wraps an InputItem with metadata for ordering and filtering.
+ * The `item` field is the exact InputItem as it was added to the conversation,
+ * preserving full fidelity (including __images, tool_use_id, etc.).
+ */
+interface HistoryEntry {
+    /** When this entry was recorded (epoch ms) */
+    timestamp: number;
+    /** Entry type for filtering */
+    type: HistoryEntryType;
+    /** The actual conversation item (Message or CompactionItem) */
+    item: InputItem;
+    /**
+     * Monotonically increasing turn counter.
+     * A "turn" is one user message + one assistant response (+ any tool calls in between).
+     * Useful for grouping related messages and pagination.
+     */
+    turnIndex: number;
+}
+/**
+ * Options for reading history entries.
+ */
+interface HistoryReadOptions {
+    /** Skip this many entries from the start */
+    offset?: number;
+    /** Maximum number of entries to return */
+    limit?: number;
+    /** Filter by entry type(s) */
+    types?: HistoryEntryType[];
+    /** Only entries after this timestamp (epoch ms, inclusive) */
+    after?: number;
+    /** Only entries before this timestamp (epoch ms, inclusive) */
+    before?: number;
+    /** Only entries from this turn index onwards (inclusive) */
+    fromTurn?: number;
+    /** Only entries up to this turn index (inclusive) */
+    toTurn?: number;
+}
+/**
+ * Append-only history journal for conversation persistence.
+ *
+ * Implementations:
+ * - FileHistoryJournal: JSONL files at ~/.oneringai/agents/<agentId>/sessions/<sessionId>.history.jsonl
+ * - (Future) MongoHistoryJournal: MongoDB collection
+ * - (Future) RedisHistoryJournal: Redis Streams
+ */
+interface IHistoryJournal {
+    /**
+     * Append entries to the journal.
+     *
+     * This is the primary write operation, called on every addUserMessage(),
+     * addAssistantResponse(), and addToolResults(). Should be fast (append-only).
+     *
+     * @param sessionId - Session to append to
+     * @param entries - One or more history entries to append
+     */
+    append(sessionId: string, entries: HistoryEntry[]): Promise<void>;
+    /**
+     * Read history entries with optional filtering and pagination.
+     *
+     * Entries are returned in chronological order (oldest first).
+     *
+     * @param sessionId - Session to read from
+     * @param options - Filtering and pagination options
+     * @returns Array of history entries
+     */
+    read(sessionId: string, options?: HistoryReadOptions): Promise<HistoryEntry[]>;
+    /**
+     * Get the total number of entries in the journal.
+     *
+     * @param sessionId - Session to count
+     * @returns Number of entries (0 if session has no journal)
+     */
+    count(sessionId: string): Promise<number>;
+    /**
+     * Delete all history for a session.
+     *
+     * Called when a session is deleted via IContextStorage.delete().
+     *
+     * @param sessionId - Session to clear
+     */
+    clear(sessionId: string): Promise<void>;
+    /**
+     * Stream history entries for large histories.
+     *
+     * Optional — implementations may omit this if streaming isn't practical
+     * (e.g., in-memory storage). Callers should fall back to read() with
+     * pagination if stream() is not available.
+     *
+     * @param sessionId - Session to stream
+     * @param options - Same filtering options as read()
+     * @returns AsyncIterable of history entries in chronological order
+     */
+    stream?(sessionId: string, options?: HistoryReadOptions): AsyncIterable<HistoryEntry>;
+    /**
+     * Get a human-readable location string for debugging/display.
+     *
+     * @param sessionId - Session ID
+     * @returns Location string (file path, MongoDB URI, etc.)
+     */
+    getLocation?(sessionId: string): string;
+}
+
 /**
  * Memory entities for WorkingMemory
  *
@@ -723,6 +865,21 @@ interface IContextStorage {
      * Falls back to getPath() if not implemented.
      */
     getLocation?(): string;
+    /**
+     * History journal companion for full conversation logging.
+     *
+     * When present, AgentContextNextGen automatically appends every message
+     * to the journal (append-only, fire-and-forget). The journal is never
+     * affected by compaction, preserving full conversation history.
+     *
+     * Storage implementations create the appropriate journal for their backend:
+     * - FileContextStorage → FileHistoryJournal (JSONL files)
+     * - MongoContextStorage → MongoHistoryJournal (collection)
+     *
+     * Consumers never configure the journal separately — it comes for free
+     * with the storage backend.
+     */
+    readonly journal?: IHistoryJournal;
 }
 /**
  * Options for listing sessions
@@ -1055,12 +1212,6 @@ declare class ToolCatalogRegistry {
     static reset(): void;
 }
 
-/**
- * AgentContextNextGen - Type Definitions
- *
- * Clean, minimal type definitions for the next-generation context manager.
- */
-
 /**
  * A single auth identity: connector + optional account alias.
  *
@@ -1569,6 +1720,13 @@ interface AgentContextNextGenConfig {
      * Default: 0 (disabled - relies on each tool's own timeout)
      */
     toolExecutionTimeout?: number;
+    /**
+     * Filter which message types are written to the history journal.
+     * When set, only entries matching these types are appended.
+     * Default: undefined (all types journaled).
+     * Example: ['user', 'assistant'] to exclude tool_result entries.
+     */
+    journalFilter?: HistoryEntryType[];
 }
 /**
  * Default configuration values
@@ -1809,6 +1967,7 @@ declare enum StreamEventType {
     REASONING_DELTA = "response.reasoning.delta",
     REASONING_DONE = "response.reasoning.done",
     RESPONSE_COMPLETE = "response.complete",
+    RETRY = "response.retry",
     ERROR = "response.error",
     AUDIO_CHUNK_READY = "response.audio_chunk.ready",
     AUDIO_CHUNK_ERROR = "response.audio_chunk.error",
@@ -1923,6 +2082,18 @@ interface ResponseCompleteEvent extends BaseStreamEvent {
     usage: TokenUsage;
     iterations: number;
     duration_ms?: number;
+    /** Raw provider stop reason for diagnostics (e.g., 'end_turn', 'max_tokens', 'SAFETY') */
+    stop_reason?: string;
+}
+/**
+ * Retry event - emitted when agent retries an empty/incomplete LLM response
+ */
+interface RetryEvent extends BaseStreamEvent {
+    type: StreamEventType.RETRY;
+    attempt: number;
+    max_attempts: number;
+    reason: string;
+    delay_ms: number;
 }
 /**
  * Reasoning/thinking delta - incremental reasoning output
@@ -1995,7 +2166,7 @@ interface AudioStreamCompleteEvent extends BaseStreamEvent {
  * Union type of all stream events
  * Discriminated by 'type' field for type narrowing
  */
-type StreamEvent = ResponseCreatedEvent | ResponseInProgressEvent | OutputTextDeltaEvent | OutputTextDoneEvent | ReasoningDeltaEvent | ReasoningDoneEvent | ToolCallStartEvent | ToolCallArgumentsDeltaEvent | ToolCallArgumentsDoneEvent | ToolExecutionStartEvent | ToolExecutionDoneEvent | IterationCompleteEvent$1 | ResponseCompleteEvent | ErrorEvent | AudioChunkReadyEvent | AudioChunkErrorEvent | AudioStreamCompleteEvent;
+type StreamEvent = ResponseCreatedEvent | ResponseInProgressEvent | OutputTextDeltaEvent | OutputTextDoneEvent | ReasoningDeltaEvent | ReasoningDoneEvent | ToolCallStartEvent | ToolCallArgumentsDeltaEvent | ToolCallArgumentsDoneEvent | ToolExecutionStartEvent | ToolExecutionDoneEvent | IterationCompleteEvent$1 | ResponseCompleteEvent | RetryEvent | ErrorEvent | AudioChunkReadyEvent | AudioChunkErrorEvent | AudioStreamCompleteEvent;
 /**
  * Type guard to check if event is a specific type
  */
@@ -2272,6 +2443,14 @@ interface ExecutionEmptyOutputEvent {
     duration: number;
     usage?: TokenUsage;
 }
+interface ExecutionRetryEvent {
+    executionId: string;
+    attempt: number;
+    maxAttempts: number;
+    reason: string;
+    delayMs: number;
+    timestamp: Date;
+}
 interface ExecutionMaxIterationsEvent {
     executionId: string;
     iteration: number;
@@ -2390,6 +2569,7 @@ interface AgenticLoopEvents {
     'tool:timeout': ToolTimeoutEvent;
     'hook:error': HookErrorEvent;
     'execution:empty_output': ExecutionEmptyOutputEvent;
+    'execution:retry': ExecutionRetryEvent;
     'circuit:opened': CircuitOpenedEvent;
     'circuit:half-open': CircuitHalfOpenEvent;
     'circuit:closed': CircuitClosedEvent;
@@ -2607,6 +2787,10 @@ declare class HookManager {
      * Clear all hooks and reset error tracking
      */
     clear(): void;
+    /**
+     * Destroy the hook manager and release all references
+     */
+    destroy(): void;
     /**
      * Re-enable a disabled hook
      */
@@ -2617,4 +2801,4 @@ declare class HookManager {
     getDisabledHooks(): string[];
 }
 
-export { type TokenUsage as $, type AgentContextNextGenConfig as A, type BeforeCompactionCallback as B, type ContextFeatures as C, type HookName as D, ExecutionContext as E, type FunctionToolDefinition as F, type ITokenEstimator as G, type HookConfig as H, type IContextStorage as I, type ToolCategoryScope as J, type CompactionContext as K, type LLMResponse as L, type MemoryEntry as M, type CompactionResult as N, type OutputItem as O, type PriorityCalculator as P, type AudioChunkReadyEvent as Q, type StaleEntryInfo as R, type SerializedContextState as S, type Tool as T, type PriorityContext as U, type MemoryIndex as V, type WorkingMemoryConfig as W, type TaskStatusForMemory as X, type WorkingMemoryAccess as Y, type ContextStorageListOptions as Z, type ContextSessionSummary as _, type MemoryScope as a, defaultDescribeCall as a$, StreamEventType as a0, type TextGenerateOptions as a1, type ModelCapabilities as a2, MessageRole as a3, type AfterToolContext as a4, type AgentEventName as a5, type AgenticLoopEventName as a6, type AgenticLoopEvents as a7, type ApprovalResult as a8, type ApproveToolContext as a9, type OutputTextContent as aA, type OutputTextDeltaEvent as aB, type OutputTextDoneEvent as aC, type OversizedInputResult as aD, type PluginConfigs as aE, type ReasoningDeltaEvent as aF, type ReasoningDoneEvent as aG, type ReasoningItem as aH, type ResponseCompleteEvent as aI, type ResponseCreatedEvent as aJ, type ResponseInProgressEvent as aK, type SimpleScope as aL, type TaskAwareScope as aM, type ThinkingContent as aN, type ToolCallArgumentsDeltaEvent as aO, type ToolCallArgumentsDoneEvent as aP, type ToolCallStartEvent as aQ, ToolCallState as aR, ToolCatalogRegistry as aS, type ToolCategoryDefinition as aT, type ToolExecutionContext as aU, type ToolExecutionDoneEvent as aV, type ToolExecutionStartEvent as aW, type ToolModification as aX, type ToolResultContent as aY, type ToolUseContent as aZ, calculateEntrySize as a_, type AudioChunkErrorEvent as aa, type AudioStreamCompleteEvent as ab, type BeforeToolContext as ac, type BuiltInTool as ad, CONTEXT_SESSION_FORMAT_VERSION as ae, type ToolRegistryEntry as af, type CatalogToolEntry as ag, type CompactionItem as ah, type ConnectorCategoryInfo as ai, ContentType as aj, DEFAULT_CONFIG as ak, DEFAULT_FEATURES as al, DEFAULT_MEMORY_CONFIG as am, type ErrorEvent as an, type ExecutionConfig as ao, type Hook as ap, HookManager as aq, type InputImageContent as ar, type InputTextContent as as, type IterationCompleteEvent$1 as at, type JSONSchema as au, MEMORY_PRIORITY_VALUES as av, type MemoryEntryInput as aw, type MemoryIndexEntry as ax, type Message as ay, type ModifyingHook as az, type ToolFunction as b, forPlan as b0, forTasks as b1, getToolCallDescription as b2, isAudioChunkError as b3, isAudioChunkReady as b4, isAudioStreamComplete as b5, isErrorEvent as b6, isOutputTextDelta as b7, isReasoningDelta as b8, isReasoningDone as b9, isResponseComplete as ba, isSimpleScope as bb, isStreamEvent as bc, isTaskAwareScope as bd, isTerminalMemoryStatus as be, isToolCallArgumentsDelta as bf, isToolCallArgumentsDone as bg, isToolCallStart as bh, scopeEquals as bi, scopeMatches as bj, type ExecutionCompleteEvent as bk, type ExecutionStartEvent as bl, type LLMRequestEvent as bm, type LLMResponseEvent as bn, type ToolCompleteEvent as bo, type ToolStartEvent as bp, type ToolContext as c, type ToolPermissionConfig as d, type ContextBudget as e, type ToolCall as f, type IContextPluginNextGen as g, type MemoryPriority as h, type MemoryTier as i, type ContextEvents as j, type AuthIdentity as k, type ICompactionStrategy as l, type InputItem as m, type Content as n, type PreparedContext as o, type ToolResult as p, type ConsolidationResult as q, type StoredContextSession as r, type ITextProvider as s, type ContextSessionMetadata as t, type StreamEvent as u, type HistoryMode as v, type AgentEvents as w, type AgentResponse as x, type ExecutionMetrics as y, type AuditEntry as z };
+export { type MemoryIndex as $, type AgentContextNextGenConfig as A, type BeforeCompactionCallback as B, type ContextFeatures as C, type AuditEntry as D, ExecutionContext as E, type FunctionToolDefinition as F, type HookName as G, type HookConfig as H, type IContextStorage as I, type ITokenEstimator as J, type ToolCategoryScope as K, type LLMResponse as L, type MemoryEntry as M, type CompactionContext as N, type OutputItem as O, type PriorityCalculator as P, type CompactionResult as Q, type AudioChunkReadyEvent as R, type SerializedContextState as S, type Tool as T, type ContextStorageListOptions as U, type ContextSessionSummary as V, type WorkingMemoryConfig as W, type HistoryEntry as X, type HistoryReadOptions as Y, type StaleEntryInfo as Z, type PriorityContext as _, type MemoryScope as a, type ToolModification as a$, type TaskStatusForMemory as a0, type WorkingMemoryAccess as a1, type TokenUsage as a2, StreamEventType as a3, type TextGenerateOptions as a4, type ModelCapabilities as a5, MessageRole as a6, type AfterToolContext as a7, type AgentEventName as a8, type AgenticLoopEventName as a9, type MemoryEntryInput as aA, type MemoryIndexEntry as aB, type Message as aC, type ModifyingHook as aD, type OutputTextContent as aE, type OutputTextDeltaEvent as aF, type OutputTextDoneEvent as aG, type OversizedInputResult as aH, type PluginConfigs as aI, type ReasoningDeltaEvent as aJ, type ReasoningDoneEvent as aK, type ReasoningItem as aL, type ResponseCompleteEvent as aM, type ResponseCreatedEvent as aN, type ResponseInProgressEvent as aO, type SimpleScope as aP, type TaskAwareScope as aQ, type ThinkingContent as aR, type ToolCallArgumentsDeltaEvent as aS, type ToolCallArgumentsDoneEvent as aT, type ToolCallStartEvent as aU, ToolCallState as aV, ToolCatalogRegistry as aW, type ToolCategoryDefinition as aX, type ToolExecutionContext as aY, type ToolExecutionDoneEvent as aZ, type ToolExecutionStartEvent as a_, type AgenticLoopEvents as aa, type ApprovalResult as ab, type ApproveToolContext as ac, type AudioChunkErrorEvent as ad, type AudioStreamCompleteEvent as ae, type BeforeToolContext as af, type BuiltInTool as ag, CONTEXT_SESSION_FORMAT_VERSION as ah, type ToolRegistryEntry as ai, type CatalogToolEntry as aj, type CompactionItem as ak, type ConnectorCategoryInfo as al, ContentType as am, DEFAULT_CONFIG as an, DEFAULT_FEATURES as ao, DEFAULT_MEMORY_CONFIG as ap, type ErrorEvent as aq, type ExecutionConfig as ar, type HistoryEntryType as as, type Hook as at, HookManager as au, type InputImageContent as av, type InputTextContent as aw, type IterationCompleteEvent$1 as ax, type JSONSchema as ay, MEMORY_PRIORITY_VALUES as az, type ToolFunction as b, type ToolResultContent as b0, type ToolUseContent as b1, calculateEntrySize as b2, defaultDescribeCall as b3, forPlan as b4, forTasks as b5, getToolCallDescription as b6, isAudioChunkError as b7, isAudioChunkReady as b8, isAudioStreamComplete as b9, isErrorEvent as ba, isOutputTextDelta as bb, isReasoningDelta as bc, isReasoningDone as bd, isResponseComplete as be, isSimpleScope as bf, isStreamEvent as bg, isTaskAwareScope as bh, isTerminalMemoryStatus as bi, isToolCallArgumentsDelta as bj, isToolCallArgumentsDone as bk, isToolCallStart as bl, scopeEquals as bm, scopeMatches as bn, type ExecutionCompleteEvent as bo, type ExecutionStartEvent as bp, type LLMRequestEvent as bq, type LLMResponseEvent as br, type ToolCompleteEvent as bs, type ToolStartEvent as bt, type ToolContext as c, type ToolPermissionConfig as d, type ContextBudget as e, type ToolCall as f, type IContextPluginNextGen as g, type MemoryPriority as h, type MemoryTier as i, type ContextEvents as j, type AuthIdentity as k, type ICompactionStrategy as l, type InputItem as m, type Content as n, type PreparedContext as o, type ToolResult as p, type IHistoryJournal as q, type ConsolidationResult as r, type StoredContextSession as s, type ITextProvider as t, type ContextSessionMetadata as u, type StreamEvent as v, type HistoryMode as w, type AgentEvents as x, type AgentResponse as y, type ExecutionMetrics as z };

package/dist/{index-D8RCwpK9.d.cts → index-Cbd5vY_8.d.cts}

@@ -98,6 +98,148 @@ interface ReasoningItem {
 type InputItem = Message | CompactionItem;
 type OutputItem = Message | CompactionItem | ReasoningItem;
 
+/**
+ * IHistoryJournal - Interface for append-only conversation history logging
+ *
+ * Provides a durable, append-only log of all conversation messages,
+ * independent of context compaction. While the agent's working window
+ * (_conversation) may be compacted to fit the LLM context, the journal
+ * preserves the full conversation history on disk/database.
+ *
+ * The journal is a companion capability of IContextStorage — storage
+ * implementations that support history logging expose it via the
+ * `journal` property. Consumers never configure the journal separately;
+ * it comes for free with the storage backend.
+ *
+ * Access patterns:
+ * - **Write**: append-only, per-message, fire-and-forget (non-blocking)
+ * - **Read**: on-demand, explicit (never loaded automatically)
+ *
+ * @example
+ * ```typescript
+ * // File storage → FileHistoryJournal (JSONL files)
+ * const storage = new FileContextStorage({ agentId: 'my-agent' });
+ * storage.journal.append('session-1', [entry]);
+ *
+ * // Mongo storage → MongoHistoryJournal (collection)
+ * const storage = new MongoContextStorage({ agentId: 'my-agent', db });
+ * storage.journal.append('session-1', [entry]);
+ *
+ * // Reading history (on-demand, explicit)
+ * const entries = await storage.journal.read('session-1', { limit: 50 });
+ * const total = await storage.journal.count('session-1');
+ * ```
+ */
+
+/**
+ * Type of history entry, derived from the message's role/purpose.
+ */
+type HistoryEntryType = 'user' | 'assistant' | 'tool_result' | 'system';
+/**
+ * A single entry in the history journal.
+ *
+ * Wraps an InputItem with metadata for ordering and filtering.
+ * The `item` field is the exact InputItem as it was added to the conversation,
+ * preserving full fidelity (including __images, tool_use_id, etc.).
+ */
+interface HistoryEntry {
+    /** When this entry was recorded (epoch ms) */
+    timestamp: number;
+    /** Entry type for filtering */
+    type: HistoryEntryType;
+    /** The actual conversation item (Message or CompactionItem) */
+    item: InputItem;
+    /**
+     * Monotonically increasing turn counter.
+     * A "turn" is one user message + one assistant response (+ any tool calls in between).
+     * Useful for grouping related messages and pagination.
+     */
+    turnIndex: number;
+}
+/**
+ * Options for reading history entries.
+ */
+interface HistoryReadOptions {
+    /** Skip this many entries from the start */
+    offset?: number;
+    /** Maximum number of entries to return */
+    limit?: number;
+    /** Filter by entry type(s) */
+    types?: HistoryEntryType[];
+    /** Only entries after this timestamp (epoch ms, inclusive) */
+    after?: number;
+    /** Only entries before this timestamp (epoch ms, inclusive) */
+    before?: number;
+    /** Only entries from this turn index onwards (inclusive) */
+    fromTurn?: number;
+    /** Only entries up to this turn index (inclusive) */
+    toTurn?: number;
+}
+/**
+ * Append-only history journal for conversation persistence.
+ *
+ * Implementations:
+ * - FileHistoryJournal: JSONL files at ~/.oneringai/agents/<agentId>/sessions/<sessionId>.history.jsonl
+ * - (Future) MongoHistoryJournal: MongoDB collection
+ * - (Future) RedisHistoryJournal: Redis Streams
+ */
+interface IHistoryJournal {
+    /**
+     * Append entries to the journal.
+     *
+     * This is the primary write operation, called on every addUserMessage(),
+     * addAssistantResponse(), and addToolResults(). Should be fast (append-only).
+     *
+     * @param sessionId - Session to append to
+     * @param entries - One or more history entries to append
+     */
+    append(sessionId: string, entries: HistoryEntry[]): Promise<void>;
+    /**
+     * Read history entries with optional filtering and pagination.
+     *
+     * Entries are returned in chronological order (oldest first).
+     *
+     * @param sessionId - Session to read from
+     * @param options - Filtering and pagination options
+     * @returns Array of history entries
+     */
+    read(sessionId: string, options?: HistoryReadOptions): Promise<HistoryEntry[]>;
+    /**
+     * Get the total number of entries in the journal.
+     *
+     * @param sessionId - Session to count
+     * @returns Number of entries (0 if session has no journal)
+     */
+    count(sessionId: string): Promise<number>;
+    /**
+     * Delete all history for a session.
+     *
+     * Called when a session is deleted via IContextStorage.delete().
+     *
+     * @param sessionId - Session to clear
+     */
+    clear(sessionId: string): Promise<void>;
+    /**
+     * Stream history entries for large histories.
+     *
+     * Optional — implementations may omit this if streaming isn't practical
+     * (e.g., in-memory storage). Callers should fall back to read() with
+     * pagination if stream() is not available.
+     *
+     * @param sessionId - Session to stream
+     * @param options - Same filtering options as read()
+     * @returns AsyncIterable of history entries in chronological order
+     */
+    stream?(sessionId: string, options?: HistoryReadOptions): AsyncIterable<HistoryEntry>;
+    /**
+     * Get a human-readable location string for debugging/display.
+     *
+     * @param sessionId - Session ID
+     * @returns Location string (file path, MongoDB URI, etc.)
+     */
+    getLocation?(sessionId: string): string;
+}
+
 /**
  * Memory entities for WorkingMemory
  *
@@ -723,6 +865,21 @@ interface IContextStorage {
      * Falls back to getPath() if not implemented.
      */
     getLocation?(): string;
+    /**
+     * History journal companion for full conversation logging.
+     *
+     * When present, AgentContextNextGen automatically appends every message
+     * to the journal (append-only, fire-and-forget). The journal is never
+     * affected by compaction, preserving full conversation history.
+     *
+     * Storage implementations create the appropriate journal for their backend:
+     * - FileContextStorage → FileHistoryJournal (JSONL files)
+     * - MongoContextStorage → MongoHistoryJournal (collection)
+     *
+     * Consumers never configure the journal separately — it comes for free
+     * with the storage backend.
+     */
+    readonly journal?: IHistoryJournal;
 }
 /**
  * Options for listing sessions
@@ -1055,12 +1212,6 @@ declare class ToolCatalogRegistry {
     static reset(): void;
 }
 
-/**
- * AgentContextNextGen - Type Definitions
- *
- * Clean, minimal type definitions for the next-generation context manager.
- */
-
 /**
  * A single auth identity: connector + optional account alias.
  *
@@ -1569,6 +1720,13 @@ interface AgentContextNextGenConfig {
      * Default: 0 (disabled - relies on each tool's own timeout)
      */
     toolExecutionTimeout?: number;
+    /**
+     * Filter which message types are written to the history journal.
+     * When set, only entries matching these types are appended.
+     * Default: undefined (all types journaled).
+     * Example: ['user', 'assistant'] to exclude tool_result entries.
+     */
+    journalFilter?: HistoryEntryType[];
 }
 /**
  * Default configuration values
@@ -1809,6 +1967,7 @@ declare enum StreamEventType {
     REASONING_DELTA = "response.reasoning.delta",
     REASONING_DONE = "response.reasoning.done",
     RESPONSE_COMPLETE = "response.complete",
+    RETRY = "response.retry",
     ERROR = "response.error",
     AUDIO_CHUNK_READY = "response.audio_chunk.ready",
     AUDIO_CHUNK_ERROR = "response.audio_chunk.error",
@@ -1923,6 +2082,18 @@ interface ResponseCompleteEvent extends BaseStreamEvent {
     usage: TokenUsage;
     iterations: number;
     duration_ms?: number;
+    /** Raw provider stop reason for diagnostics (e.g., 'end_turn', 'max_tokens', 'SAFETY') */
+    stop_reason?: string;
+}
+/**
+ * Retry event - emitted when agent retries an empty/incomplete LLM response
+ */
+interface RetryEvent extends BaseStreamEvent {
+    type: StreamEventType.RETRY;
+    attempt: number;
+    max_attempts: number;
+    reason: string;
+    delay_ms: number;
 }
 /**
  * Reasoning/thinking delta - incremental reasoning output
@@ -1995,7 +2166,7 @@ interface AudioStreamCompleteEvent extends BaseStreamEvent {
  * Union type of all stream events
  * Discriminated by 'type' field for type narrowing
  */
-type StreamEvent = ResponseCreatedEvent | ResponseInProgressEvent | OutputTextDeltaEvent | OutputTextDoneEvent | ReasoningDeltaEvent | ReasoningDoneEvent | ToolCallStartEvent | ToolCallArgumentsDeltaEvent | ToolCallArgumentsDoneEvent | ToolExecutionStartEvent | ToolExecutionDoneEvent | IterationCompleteEvent$1 | ResponseCompleteEvent | ErrorEvent | AudioChunkReadyEvent | AudioChunkErrorEvent | AudioStreamCompleteEvent;
+type StreamEvent = ResponseCreatedEvent | ResponseInProgressEvent | OutputTextDeltaEvent | OutputTextDoneEvent | ReasoningDeltaEvent | ReasoningDoneEvent | ToolCallStartEvent | ToolCallArgumentsDeltaEvent | ToolCallArgumentsDoneEvent | ToolExecutionStartEvent | ToolExecutionDoneEvent | IterationCompleteEvent$1 | ResponseCompleteEvent | RetryEvent | ErrorEvent | AudioChunkReadyEvent | AudioChunkErrorEvent | AudioStreamCompleteEvent;
 /**
  * Type guard to check if event is a specific type
  */
@@ -2272,6 +2443,14 @@ interface ExecutionEmptyOutputEvent {
     duration: number;
     usage?: TokenUsage;
 }
+interface ExecutionRetryEvent {
+    executionId: string;
+    attempt: number;
+    maxAttempts: number;
+    reason: string;
+    delayMs: number;
+    timestamp: Date;
+}
 interface ExecutionMaxIterationsEvent {
     executionId: string;
     iteration: number;
@@ -2390,6 +2569,7 @@ interface AgenticLoopEvents {
     'tool:timeout': ToolTimeoutEvent;
     'hook:error': HookErrorEvent;
     'execution:empty_output': ExecutionEmptyOutputEvent;
+    'execution:retry': ExecutionRetryEvent;
     'circuit:opened': CircuitOpenedEvent;
     'circuit:half-open': CircuitHalfOpenEvent;
     'circuit:closed': CircuitClosedEvent;
@@ -2607,6 +2787,10 @@ declare class HookManager {
      * Clear all hooks and reset error tracking
      */
     clear(): void;
+    /**
+     * Destroy the hook manager and release all references
+     */
+    destroy(): void;
     /**
      * Re-enable a disabled hook
      */
@@ -2617,4 +2801,4 @@ declare class HookManager {
     getDisabledHooks(): string[];
 }
 
-export { type TokenUsage as $, type AgentContextNextGenConfig as A, type BeforeCompactionCallback as B, type ContextFeatures as C, type HookName as D, ExecutionContext as E, type FunctionToolDefinition as F, type ITokenEstimator as G, type HookConfig as H, type IContextStorage as I, type ToolCategoryScope as J, type CompactionContext as K, type LLMResponse as L, type MemoryEntry as M, type CompactionResult as N, type OutputItem as O, type PriorityCalculator as P, type AudioChunkReadyEvent as Q, type StaleEntryInfo as R, type SerializedContextState as S, type Tool as T, type PriorityContext as U, type MemoryIndex as V, type WorkingMemoryConfig as W, type TaskStatusForMemory as X, type WorkingMemoryAccess as Y, type ContextStorageListOptions as Z, type ContextSessionSummary as _, type MemoryScope as a, defaultDescribeCall as a$, StreamEventType as a0, type TextGenerateOptions as a1, type ModelCapabilities as a2, MessageRole as a3, type AfterToolContext as a4, type AgentEventName as a5, type AgenticLoopEventName as a6, type AgenticLoopEvents as a7, type ApprovalResult as a8, type ApproveToolContext as a9, type OutputTextContent as aA, type OutputTextDeltaEvent as aB, type OutputTextDoneEvent as aC, type OversizedInputResult as aD, type PluginConfigs as aE, type ReasoningDeltaEvent as aF, type ReasoningDoneEvent as aG, type ReasoningItem as aH, type ResponseCompleteEvent as aI, type ResponseCreatedEvent as aJ, type ResponseInProgressEvent as aK, type SimpleScope as aL, type TaskAwareScope as aM, type ThinkingContent as aN, type ToolCallArgumentsDeltaEvent as aO, type ToolCallArgumentsDoneEvent as aP, type ToolCallStartEvent as aQ, ToolCallState as aR, ToolCatalogRegistry as aS, type ToolCategoryDefinition as aT, type ToolExecutionContext as aU, type ToolExecutionDoneEvent as aV, type ToolExecutionStartEvent as aW, type ToolModification as aX, type ToolResultContent as aY, type ToolUseContent as aZ, calculateEntrySize as a_, type AudioChunkErrorEvent as aa, type AudioStreamCompleteEvent as ab, type BeforeToolContext as ac, type BuiltInTool as ad, CONTEXT_SESSION_FORMAT_VERSION as ae, type ToolRegistryEntry as af, type CatalogToolEntry as ag, type CompactionItem as ah, type ConnectorCategoryInfo as ai, ContentType as aj, DEFAULT_CONFIG as ak, DEFAULT_FEATURES as al, DEFAULT_MEMORY_CONFIG as am, type ErrorEvent as an, type ExecutionConfig as ao, type Hook as ap, HookManager as aq, type InputImageContent as ar, type InputTextContent as as, type IterationCompleteEvent$1 as at, type JSONSchema as au, MEMORY_PRIORITY_VALUES as av, type MemoryEntryInput as aw, type MemoryIndexEntry as ax, type Message as ay, type ModifyingHook as az, type ToolFunction as b, forPlan as b0, forTasks as b1, getToolCallDescription as b2, isAudioChunkError as b3, isAudioChunkReady as b4, isAudioStreamComplete as b5, isErrorEvent as b6, isOutputTextDelta as b7, isReasoningDelta as b8, isReasoningDone as b9, isResponseComplete as ba, isSimpleScope as bb, isStreamEvent as bc, isTaskAwareScope as bd, isTerminalMemoryStatus as be, isToolCallArgumentsDelta as bf, isToolCallArgumentsDone as bg, isToolCallStart as bh, scopeEquals as bi, scopeMatches as bj, type ExecutionCompleteEvent as bk, type ExecutionStartEvent as bl, type LLMRequestEvent as bm, type LLMResponseEvent as bn, type ToolCompleteEvent as bo, type ToolStartEvent as bp, type ToolContext as c, type ToolPermissionConfig as d, type ContextBudget as e, type ToolCall as f, type IContextPluginNextGen as g, type MemoryPriority as h, type MemoryTier as i, type ContextEvents as j, type AuthIdentity as k, type ICompactionStrategy as l, type InputItem as m, type Content as n, type PreparedContext as o, type ToolResult as p, type ConsolidationResult as q, type StoredContextSession as r, type ITextProvider as s, type ContextSessionMetadata as t, type StreamEvent as u, type HistoryMode as v, type AgentEvents as w, type AgentResponse as x, type ExecutionMetrics as y, type AuditEntry as z };
+export { type MemoryIndex as $, type AgentContextNextGenConfig as A, type BeforeCompactionCallback as B, type ContextFeatures as C, type AuditEntry as D, ExecutionContext as E, type FunctionToolDefinition as F, type HookName as G, type HookConfig as H, type IContextStorage as I, type ITokenEstimator as J, type ToolCategoryScope as K, type LLMResponse as L, type MemoryEntry as M, type CompactionContext as N, type OutputItem as O, type PriorityCalculator as P, type CompactionResult as Q, type AudioChunkReadyEvent as R, type SerializedContextState as S, type Tool as T, type ContextStorageListOptions as U, type ContextSessionSummary as V, type WorkingMemoryConfig as W, type HistoryEntry as X, type HistoryReadOptions as Y, type StaleEntryInfo as Z, type PriorityContext as _, type MemoryScope as a, type ToolModification as a$, type TaskStatusForMemory as a0, type WorkingMemoryAccess as a1, type TokenUsage as a2, StreamEventType as a3, type TextGenerateOptions as a4, type ModelCapabilities as a5, MessageRole as a6, type AfterToolContext as a7, type AgentEventName as a8, type AgenticLoopEventName as a9, type MemoryEntryInput as aA, type MemoryIndexEntry as aB, type Message as aC, type ModifyingHook as aD, type OutputTextContent as aE, type OutputTextDeltaEvent as aF, type OutputTextDoneEvent as aG, type OversizedInputResult as aH, type PluginConfigs as aI, type ReasoningDeltaEvent as aJ, type ReasoningDoneEvent as aK, type ReasoningItem as aL, type ResponseCompleteEvent as aM, type ResponseCreatedEvent as aN, type ResponseInProgressEvent as aO, type SimpleScope as aP, type TaskAwareScope as aQ, type ThinkingContent as aR, type ToolCallArgumentsDeltaEvent as aS, type ToolCallArgumentsDoneEvent as aT, type ToolCallStartEvent as aU, ToolCallState as aV, ToolCatalogRegistry as aW, type ToolCategoryDefinition as aX, type ToolExecutionContext as aY, type ToolExecutionDoneEvent as aZ, type ToolExecutionStartEvent as a_, type AgenticLoopEvents as aa, type ApprovalResult as ab, type ApproveToolContext as ac, type AudioChunkErrorEvent as ad, type AudioStreamCompleteEvent as ae, type BeforeToolContext as af, type BuiltInTool as ag, CONTEXT_SESSION_FORMAT_VERSION as ah, type ToolRegistryEntry as ai, type CatalogToolEntry as aj, type CompactionItem as ak, type ConnectorCategoryInfo as al, ContentType as am, DEFAULT_CONFIG as an, DEFAULT_FEATURES as ao, DEFAULT_MEMORY_CONFIG as ap, type ErrorEvent as aq, type ExecutionConfig as ar, type HistoryEntryType as as, type Hook as at, HookManager as au, type InputImageContent as av, type InputTextContent as aw, type IterationCompleteEvent$1 as ax, type JSONSchema as ay, MEMORY_PRIORITY_VALUES as az, type ToolFunction as b, type ToolResultContent as b0, type ToolUseContent as b1, calculateEntrySize as b2, defaultDescribeCall as b3, forPlan as b4, forTasks as b5, getToolCallDescription as b6, isAudioChunkError as b7, isAudioChunkReady as b8, isAudioStreamComplete as b9, isErrorEvent as ba, isOutputTextDelta as bb, isReasoningDelta as bc, isReasoningDone as bd, isResponseComplete as be, isSimpleScope as bf, isStreamEvent as bg, isTaskAwareScope as bh, isTerminalMemoryStatus as bi, isToolCallArgumentsDelta as bj, isToolCallArgumentsDone as bk, isToolCallStart as bl, scopeEquals as bm, scopeMatches as bn, type ExecutionCompleteEvent as bo, type ExecutionStartEvent as bp, type LLMRequestEvent as bq, type LLMResponseEvent as br, type ToolCompleteEvent as bs, type ToolStartEvent as bt, type ToolContext as c, type ToolPermissionConfig as d, type ContextBudget as e, type ToolCall as f, type IContextPluginNextGen as g, type MemoryPriority as h, type MemoryTier as i, type ContextEvents as j, type AuthIdentity as k, type ICompactionStrategy as l, type InputItem as m, type Content as n, type PreparedContext as o, type ToolResult as p, type IHistoryJournal as q, type ConsolidationResult as r, type StoredContextSession as s, type ITextProvider as t, type ContextSessionMetadata as u, type StreamEvent as v, type HistoryMode as w, type AgentEvents as x, type AgentResponse as y, type ExecutionMetrics as z };