@everworker/oneringai 0.4.6 → 0.4.8

package/dist/{index-oBtp-8Qn.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,7 +1967,11 @@ declare enum StreamEventType {
     REASONING_DELTA = "response.reasoning.delta",
     REASONING_DONE = "response.reasoning.done",
     RESPONSE_COMPLETE = "response.complete",
-    ERROR = "response.error"
+    RETRY = "response.retry",
+    ERROR = "response.error",
+    AUDIO_CHUNK_READY = "response.audio_chunk.ready",
+    AUDIO_CHUNK_ERROR = "response.audio_chunk.error",
+    AUDIO_STREAM_COMPLETE = "response.audio_stream.complete"
 }
 /**
  * Base interface for all stream events
@@ -1920,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
@@ -1950,11 +2124,49 @@ interface ErrorEvent extends BaseStreamEvent {
     };
     recoverable: boolean;
 }
+/**
+ * Audio chunk ready - TTS synthesis complete for a text chunk
+ */
+interface AudioChunkReadyEvent extends BaseStreamEvent {
+    type: StreamEventType.AUDIO_CHUNK_READY;
+    /** Sequential index for ordered playback */
+    chunk_index: number;
+    /** Sub-chunk index within a chunk (for streaming TTS mode) */
+    sub_index?: number;
+    /** Source text that was synthesized */
+    text: string;
+    /** Audio data as base64 string (survives JSON/IPC serialization) */
+    audio_base64: string;
+    /** Audio format */
+    format: string;
+    /** Duration in seconds (if available from TTS provider) */
+    duration_seconds?: number;
+    /** Characters used for this chunk */
+    characters_used?: number;
+}
+/**
+ * Audio chunk error - TTS synthesis failed for a text chunk
+ */
+interface AudioChunkErrorEvent extends BaseStreamEvent {
+    type: StreamEventType.AUDIO_CHUNK_ERROR;
+    chunk_index: number;
+    text: string;
+    error: string;
+}
+/**
+ * Audio stream complete - all TTS chunks have been processed
+ */
+interface AudioStreamCompleteEvent extends BaseStreamEvent {
+    type: StreamEventType.AUDIO_STREAM_COMPLETE;
+    total_chunks: number;
+    total_characters: number;
+    total_duration_seconds?: number;
+}
 /**
  * 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;
+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
  */
@@ -1970,6 +2182,9 @@ declare function isReasoningDelta(event: StreamEvent): event is ReasoningDeltaEv
 declare function isReasoningDone(event: StreamEvent): event is ReasoningDoneEvent;
 declare function isResponseComplete(event: StreamEvent): event is ResponseCompleteEvent;
 declare function isErrorEvent(event: StreamEvent): event is ErrorEvent;
+declare function isAudioChunkReady(event: StreamEvent): event is AudioChunkReadyEvent;
+declare function isAudioChunkError(event: StreamEvent): event is AudioChunkErrorEvent;
+declare function isAudioStreamComplete(event: StreamEvent): event is AudioStreamCompleteEvent;
 
 /**
  * Text generation provider interface
@@ -2228,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;
@@ -2346,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;
@@ -2563,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
      */
@@ -2573,4 +2801,4 @@ declare class HookManager {
     getDisabledHooks(): string[];
 }
 
-export { StreamEventType 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 StaleEntryInfo as Q, type PriorityContext as R, type SerializedContextState as S, type Tool as T, type MemoryIndex as U, type TaskStatusForMemory as V, type WorkingMemoryConfig as W, type WorkingMemoryAccess as X, type ContextStorageListOptions as Y, type ContextSessionSummary as Z, type TokenUsage as _, type MemoryScope as a, getToolCallDescription as a$, type TextGenerateOptions as a0, type ModelCapabilities as a1, MessageRole as a2, type AfterToolContext as a3, type AgentEventName as a4, type AgenticLoopEventName as a5, type AgenticLoopEvents as a6, type ApprovalResult as a7, type ApproveToolContext as a8, type BeforeToolContext as a9, type OversizedInputResult as aA, type PluginConfigs as aB, type ReasoningDeltaEvent as aC, type ReasoningDoneEvent as aD, type ReasoningItem as aE, type ResponseCompleteEvent as aF, type ResponseCreatedEvent as aG, type ResponseInProgressEvent as aH, type SimpleScope as aI, type TaskAwareScope as aJ, type ThinkingContent as aK, type ToolCallArgumentsDeltaEvent as aL, type ToolCallArgumentsDoneEvent as aM, type ToolCallStartEvent as aN, ToolCallState as aO, ToolCatalogRegistry as aP, type ToolCategoryDefinition as aQ, type ToolExecutionContext as aR, type ToolExecutionDoneEvent as aS, type ToolExecutionStartEvent as aT, type ToolModification as aU, type ToolResultContent as aV, type ToolUseContent as aW, calculateEntrySize as aX, defaultDescribeCall as aY, forPlan as aZ, forTasks as a_, type BuiltInTool as aa, CONTEXT_SESSION_FORMAT_VERSION as ab, type ToolRegistryEntry as ac, type CatalogToolEntry as ad, type CompactionItem as ae, type ConnectorCategoryInfo as af, ContentType as ag, DEFAULT_CONFIG as ah, DEFAULT_FEATURES as ai, DEFAULT_MEMORY_CONFIG as aj, type ErrorEvent as ak, type ExecutionConfig as al, type Hook as am, HookManager as an, type InputImageContent as ao, type InputTextContent as ap, type IterationCompleteEvent$1 as aq, type JSONSchema as ar, MEMORY_PRIORITY_VALUES as as, type MemoryEntryInput as at, type MemoryIndexEntry as au, type Message as av, type ModifyingHook as aw, type OutputTextContent as ax, type OutputTextDeltaEvent as ay, type OutputTextDoneEvent as az, type ToolFunction as b, isErrorEvent as b0, isOutputTextDelta as b1, isReasoningDelta as b2, isReasoningDone as b3, isResponseComplete as b4, isSimpleScope as b5, isStreamEvent as b6, isTaskAwareScope as b7, isTerminalMemoryStatus as b8, isToolCallArgumentsDelta as b9, isToolCallArgumentsDone as ba, isToolCallStart as bb, scopeEquals as bc, scopeMatches as bd, type ExecutionCompleteEvent as be, type ExecutionStartEvent as bf, type LLMRequestEvent as bg, type LLMResponseEvent as bh, type ToolCompleteEvent as bi, type ToolStartEvent as bj, 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 };