@cuylabs/agent-core 0.4.0 → 0.5.0

package/dist/runtime/index.d.ts

@@ -0,0 +1,357 @@
+import { A as AgentEvent } from '../runner-C7aMP_x3.js';
+import { T as TokenUsage, M as Message } from '../messages-BYWGn8TY.js';
+import { n as AgentTurnStepCommitSnapshot, t as CreateAgentTurnStepCommitBatchOptions, f as AgentTurnCommitBatch, K as PrepareModelStepOptions, M as PreparedAgentModelStep, U as RunModelStepOptions, a as ProcessorOutput, V as RunToolBatchOptions, W as RunToolBatchResult, C as CommitOutputOptions, r as CommitStepOptions, l as AgentTurnState, p as AgentTurnStepCommitToolResult, o as AgentTurnStepCommitToolCall } from '../types-MM1JoX5T.js';
+export { b as AgentTurnActiveToolCall, c as AgentTurnBoundaryMetadata, d as AgentTurnBoundarySnapshot, e as AgentTurnCommitApplier, g as AgentTurnCommitOptions, h as AgentTurnEngine, i as AgentTurnEngineOptions, j as AgentTurnPhase, k as AgentTurnResolvedToolCall, m as AgentTurnStateAdvanceOptions, q as AgentTurnStepRuntimeConfig, s as CreateAgentTurnStateOptions, a2 as advanceAgentTurnState, a4 as createAgentTurnEngine, a5 as createAgentTurnState, a8 as failAgentTurnState } from '../types-MM1JoX5T.js';
+import { ModelMessage } from 'ai';
+import '../tool-pFAnJc5Y.js';
+import 'zod';
+import '../tool-DYp6-cC3.js';
+import '../types-CQaXbRsS.js';
+
+declare function createAgentTurnStepCommitBatch(step: number, snapshot: AgentTurnStepCommitSnapshot, options?: CreateAgentTurnStepCommitBatchOptions): AgentTurnCommitBatch | undefined;
+
+/**
+ * Prepare the next model step from the current committed messages.
+ */
+declare function prepareModelStep(options: PrepareModelStepOptions): PreparedAgentModelStep;
+
+/**
+ * Execute exactly one model/tool step and stream its events.
+ */
+declare function runModelStep(options: RunModelStepOptions): AsyncGenerator<AgentEvent, ProcessorOutput>;
+
+/**
+ * Execute planned tool calls outside the AI SDK loop.
+ */
+declare function runToolBatch(options: RunToolBatchOptions): Promise<RunToolBatchResult>;
+
+/**
+ * Persist the assistant tool-call message and tool-result messages for a step.
+ */
+declare function commitStep(options: CommitStepOptions): AsyncGenerator<AgentEvent, boolean>;
+/**
+ * Persist the final assistant output for a turn.
+ */
+declare function commitOutput(options: CommitOutputOptions): AsyncGenerator<AgentEvent, boolean>;
+
+interface AgentTaskPayload {
+    /** Prompt/message passed to the agent. */
+    message: string;
+    /** Optional explicit session id. If omitted, a runtime session id is generated. */
+    sessionId?: string;
+    /** Optional per-run system override forwarded to agent.chat(). */
+    system?: string;
+}
+interface AgentTaskExecutionContext {
+    /** Abort signal propagated to agent.chat(). */
+    signal?: AbortSignal;
+    /** Optional trigger descriptor from caller (for logging/routing). */
+    trigger?: string;
+    /**
+     * Optional stable key used when auto-generating session ids.
+     * For scheduled jobs, a job ID is a good candidate.
+     */
+    fallbackSessionKey?: string;
+}
+interface AgentTaskResult {
+    response: string;
+    sessionId: string;
+    usage: TokenUsage;
+    toolCalls: Array<{
+        name: string;
+        result: unknown;
+    }>;
+}
+type AgentTaskRunner<TPayload extends AgentTaskPayload = AgentTaskPayload> = (payload: TPayload, context?: AgentTaskExecutionContext) => Promise<AgentTaskResult>;
+/**
+ * Minimal chat surface required by `createAgentTaskRunner(...)`.
+ *
+ * The concrete `Agent` class already satisfies this contract. Keeping the
+ * requirement this small makes runtime integration easier to test and reuse.
+ */
+interface AgentTaskChatAdapter {
+    chat(sessionId: string, message: string, options?: {
+        abort?: AbortSignal;
+        system?: string;
+    }): AsyncIterable<AgentEvent>;
+}
+
+type AgentTaskCheckpointReason = "task-start" | "input-commit-start" | "input-commit-finish" | "intervention-commit-start" | "intervention-commit-finish" | "step-finish" | "step-commit-start" | "step-commit-finish" | "tool-result" | "tool-error" | "output-commit-start" | "output-commit-finish" | "task-complete" | "task-error";
+interface AgentTaskExecutionRun<TPayload extends AgentTaskPayload = AgentTaskPayload> {
+    payload: Readonly<TPayload>;
+    context: Readonly<AgentTaskExecutionContext>;
+    sessionId: string;
+    startedAt: string;
+}
+interface AgentTaskExecutionSnapshot {
+    sessionId: string;
+    response: string;
+    usage: TokenUsage;
+    toolCalls: Array<{
+        name: string;
+        result: unknown;
+    }>;
+    eventCount: number;
+    activeStep?: number;
+    lastEvent?: AgentEvent;
+    error?: string;
+    startedAt: string;
+    updatedAt: string;
+    turnState: AgentTurnState;
+}
+interface AgentTaskExecutionCheckpoint<TPayload extends AgentTaskPayload = AgentTaskPayload> {
+    run: AgentTaskExecutionRun<TPayload>;
+    reason: AgentTaskCheckpointReason;
+    snapshot: AgentTaskExecutionSnapshot;
+    event?: AgentEvent;
+    createdAt: string;
+}
+interface AgentTaskObserver<TPayload extends AgentTaskPayload = AgentTaskPayload> {
+    onTaskStart?(run: AgentTaskExecutionRun<TPayload>, snapshot: AgentTaskExecutionSnapshot): void | Promise<void>;
+    onTaskEvent?(run: AgentTaskExecutionRun<TPayload>, event: AgentEvent, snapshot: AgentTaskExecutionSnapshot): void | Promise<void>;
+    onCheckpoint?(checkpoint: AgentTaskExecutionCheckpoint<TPayload>): void | Promise<void>;
+    onTaskComplete?(run: AgentTaskExecutionRun<TPayload>, result: AgentTaskResult, snapshot: AgentTaskExecutionSnapshot): void | Promise<void>;
+    onTaskError?(run: AgentTaskExecutionRun<TPayload>, error: Error, snapshot: AgentTaskExecutionSnapshot): void | Promise<void>;
+    /**
+     * Get the active OTel context for a session.
+     *
+     * Used for trace context propagation between layers — e.g. the
+     * workflow bridge retrieves the observer's span context and injects
+     * it into activities so child spans (AI SDK, tool calls) are
+     * correlated under the observer's root span.
+     */
+    getOtelContext?(sessionId: string): unknown;
+    /**
+     * Activate the OTel context for a session around a function call.
+     *
+     * Used by the task runner to ensure child spans (from middleware,
+     * AI SDK) are parented under the observer's root span in direct
+     * execution mode. The observer wraps `fn` in `context.with()` so
+     * that `context.active()` returns the session's trace context.
+     */
+    activateContext?<T>(sessionId: string, fn: () => T): T;
+}
+interface AgentTaskCheckpointStrategyInput<TPayload extends AgentTaskPayload = AgentTaskPayload> {
+    run: AgentTaskExecutionRun<TPayload>;
+    event: AgentEvent;
+    snapshot: AgentTaskExecutionSnapshot;
+}
+type AgentTaskCheckpointStrategy<TPayload extends AgentTaskPayload = AgentTaskPayload> = (input: AgentTaskCheckpointStrategyInput<TPayload>) => AgentTaskCheckpointReason | undefined;
+/**
+ * Default checkpoint strategy for runtime integrations.
+ *
+ * This intentionally checkpoints at coarse-grained boundaries that are useful
+ * for external runtimes and durable adapters without creating excessive churn:
+ * - step completion
+ * - tool results/errors
+ * - task completion
+ */
+declare function defaultAgentTaskCheckpointStrategy<TPayload extends AgentTaskPayload = AgentTaskPayload>(input: AgentTaskCheckpointStrategyInput<TPayload>): AgentTaskCheckpointReason | undefined;
+
+interface AgentTaskRunnerOptions<TPayload extends AgentTaskPayload = AgentTaskPayload> {
+    /** Prefix used for generated runtime session IDs. Defaults to "runtime". */
+    sessionPrefix?: string;
+    /**
+     * Optional callback for resolving session IDs from payload/context.
+     * Ignored when payload.sessionId is provided.
+     */
+    resolveSessionId?: (payload: TPayload, context: AgentTaskExecutionContext) => string | undefined;
+    /**
+     * Optional execution observers. These are generic lifecycle hooks that can be
+     * consumed by runtime adapters (in-memory, Dapr, queues, etc.) without
+     * introducing infrastructure dependencies into `@cuylabs/agent-core`.
+     */
+    observers?: AgentTaskObserver<TPayload>[];
+    /**
+     * Optional checkpoint strategy for converting streamed agent events into
+     * coarse-grained execution checkpoints. Defaults to
+     * `defaultAgentTaskCheckpointStrategy(...)`.
+     */
+    checkpointStrategy?: AgentTaskCheckpointStrategy<TPayload>;
+}
+/**
+ * Create a reusable task runner that maps generic task payloads to `agent.chat()`.
+ *
+ * This helper is intentionally infrastructure-agnostic. It can be used by any
+ * runtime/orchestration package (in-memory, Dapr, queues, cron, etc.) without
+ * introducing infrastructure dependencies into `@cuylabs/agent-core`.
+ *
+ * The runner also exposes a neutral execution observer/checkpoint surface so
+ * external runtimes can persist progress, react to lifecycle events, or map
+ * streamed execution milestones into their own durability layer.
+ */
+declare function createAgentTaskRunner<TPayload extends AgentTaskPayload = AgentTaskPayload>(agent: AgentTaskChatAdapter, options?: AgentTaskRunnerOptions<TPayload>): AgentTaskRunner<TPayload>;
+
+interface AgentWorkflowToolCallSnapshot {
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+}
+interface AgentWorkflowUserMessageSnapshot {
+    id: string;
+    role: "user";
+    createdAt: string;
+    content: string;
+    system?: string;
+}
+interface AgentWorkflowAssistantMessageSnapshot {
+    id: string;
+    role: "assistant";
+    createdAt: string;
+    content: string;
+    finish?: "stop" | "length" | "tool-calls" | "content-filter" | "error" | "unknown";
+    tokens?: TokenUsage;
+    cost?: number;
+    error?: {
+        name: string;
+        message: string;
+        code?: string;
+        status?: number;
+    };
+    toolCalls?: AgentWorkflowToolCallSnapshot[];
+}
+interface AgentWorkflowToolMessageSnapshot {
+    id: string;
+    role: "tool";
+    createdAt: string;
+    content: string;
+    toolCallId: string;
+    toolName: string;
+    result: unknown;
+    compactedAt?: number;
+}
+interface AgentWorkflowSystemMessageSnapshot {
+    id: string;
+    role: "system";
+    createdAt: string;
+    content: string;
+}
+type AgentWorkflowMessageSnapshot = AgentWorkflowUserMessageSnapshot | AgentWorkflowAssistantMessageSnapshot | AgentWorkflowToolMessageSnapshot | AgentWorkflowSystemMessageSnapshot;
+type AgentWorkflowTurnPhase = "model-step" | "tool-batch" | "step-commit" | "output-commit" | "completed" | "failed";
+interface AgentWorkflowReplayDecision {
+    toolCallId: string;
+    toolName: string;
+    action: "replay" | "skip";
+    source: "policy" | "runtime" | "operator";
+    decidedAt: string;
+    reason?: string;
+}
+interface AgentWorkflowModelStepResult {
+    text: string;
+    usage?: TokenUsage;
+    finishReason?: string;
+    turnState: AgentTurnState;
+    stepCommit?: AgentTurnStepCommitSnapshot;
+}
+interface AgentWorkflowCommitResult {
+    messages: AgentWorkflowMessageSnapshot[];
+}
+interface AgentWorkflowToolBatchResult {
+    stepCommit: AgentTurnStepCommitSnapshot;
+    turnState?: AgentTurnState;
+}
+interface AgentWorkflowToolCallResult {
+    toolResult: AgentTurnStepCommitToolResult;
+    turnState?: AgentTurnState;
+}
+interface AgentWorkflowTurnState {
+    sessionId: string;
+    systemPrompts: string[];
+    messages: AgentWorkflowMessageSnapshot[];
+    phase: AgentWorkflowTurnPhase;
+    step: number;
+    maxSteps: number;
+    usage?: TokenUsage;
+    turnState?: AgentTurnState;
+    lastModelStep?: AgentWorkflowModelStepResult;
+    replayDecisions: Record<string, AgentWorkflowReplayDecision>;
+    finalResponse?: string;
+    error?: string;
+    startedAt: string;
+    updatedAt: string;
+}
+interface CreateAgentWorkflowTurnStateOptions {
+    sessionId: string;
+    startedAt: string;
+    maxSteps: number;
+    systemPrompts?: string[];
+    initialMessages?: AgentWorkflowMessageSnapshot[];
+    initialStep?: number;
+}
+declare function snapshotAgentWorkflowMessage(message: Message): AgentWorkflowMessageSnapshot;
+declare function snapshotAgentWorkflowMessages(messages: Message[]): AgentWorkflowMessageSnapshot[];
+declare function restoreAgentWorkflowMessage(snapshot: AgentWorkflowMessageSnapshot): Message;
+declare function restoreAgentWorkflowMessages(snapshots: AgentWorkflowMessageSnapshot[]): Message[];
+declare function createAgentWorkflowTurnState(options: CreateAgentWorkflowTurnStateOptions): AgentWorkflowTurnState;
+declare function cloneAgentWorkflowTurnState(state: AgentWorkflowTurnState): AgentWorkflowTurnState;
+
+interface AgentWorkflowModelStepPlan {
+    kind: "model-step";
+    sessionId: string;
+    step: number;
+    maxSteps: number;
+    systemPrompts: string[];
+    messages: AgentWorkflowMessageSnapshot[];
+}
+interface AgentWorkflowStepCommitPlan {
+    kind: "step-commit";
+    sessionId: string;
+    step: number;
+    snapshot: AgentTurnStepCommitSnapshot;
+}
+interface AgentWorkflowToolCallPlan {
+    kind: "tool-call";
+    step: number;
+    sessionId: string;
+    toolCall: AgentTurnStepCommitToolCall;
+    turnState: AgentWorkflowTurnState["turnState"];
+    replayDecision?: AgentWorkflowReplayDecision;
+}
+interface AgentWorkflowOutputCommitPlan {
+    kind: "output-commit";
+    sessionId: string;
+    text: string;
+    usage?: TokenUsage;
+}
+type AgentWorkflowOperationPlan = AgentWorkflowModelStepPlan | AgentWorkflowToolCallPlan | AgentWorkflowStepCommitPlan | AgentWorkflowOutputCommitPlan;
+
+/**
+ * Decide which deterministic workflow operation should run next.
+ */
+declare function planNextAgentWorkflowOperation(state: AgentWorkflowTurnState): AgentWorkflowOperationPlan | undefined;
+
+/**
+ * Advance serializable workflow state after the model-step activity completes.
+ */
+declare function applyAgentWorkflowModelStepResult(state: AgentWorkflowTurnState, result: AgentWorkflowModelStepResult, updatedAt: string): AgentWorkflowTurnState;
+/**
+ * Advance serializable workflow state after a separate tool-batch activity.
+ */
+declare function applyAgentWorkflowToolBatchResult(state: AgentWorkflowTurnState, result: AgentWorkflowToolBatchResult, updatedAt: string): AgentWorkflowTurnState;
+/**
+ * Advance serializable workflow state after a single tool-call activity.
+ */
+declare function applyAgentWorkflowToolCallResult(state: AgentWorkflowTurnState, result: AgentWorkflowToolCallResult, updatedAt: string): AgentWorkflowTurnState;
+/**
+ * Advance serializable workflow state after a commit activity persists messages.
+ */
+declare function applyAgentWorkflowCommitResult(state: AgentWorkflowTurnState, result: AgentWorkflowCommitResult, updatedAt: string): AgentWorkflowTurnState;
+/**
+ * Record a concrete replay decision chosen by a runtime or operator.
+ */
+declare function recordAgentWorkflowReplayDecision(state: AgentWorkflowTurnState, decision: AgentWorkflowReplayDecision, updatedAt: string): AgentWorkflowTurnState;
+/**
+ * Mark the workflow-side turn state as failed.
+ */
+declare function failAgentWorkflowTurnState(state: AgentWorkflowTurnState, error: Error, updatedAt: string): AgentWorkflowTurnState;
+
+/**
+ * Convert framework messages into Vercel AI SDK model messages.
+ *
+ * This keeps the message translation logic reusable for workflow activities
+ * and other runtime integrations without forcing those integrations to reach
+ * into `Agent` internals.
+ */
+declare function convertAgentMessagesToModelMessages(messages: Message[]): ModelMessage[];
+
+export { type AgentTaskChatAdapter, type AgentTaskCheckpointReason, type AgentTaskCheckpointStrategy, type AgentTaskCheckpointStrategyInput, type AgentTaskExecutionCheckpoint, type AgentTaskExecutionContext, type AgentTaskExecutionRun, type AgentTaskExecutionSnapshot, type AgentTaskObserver, type AgentTaskPayload, type AgentTaskResult, type AgentTaskRunner, type AgentTaskRunnerOptions, AgentTurnCommitBatch, AgentTurnState, AgentTurnStepCommitSnapshot, AgentTurnStepCommitToolCall, AgentTurnStepCommitToolResult, type AgentWorkflowAssistantMessageSnapshot, type AgentWorkflowCommitResult, type AgentWorkflowMessageSnapshot, type AgentWorkflowModelStepPlan, type AgentWorkflowModelStepResult, type AgentWorkflowOperationPlan, type AgentWorkflowOutputCommitPlan, type AgentWorkflowReplayDecision, type AgentWorkflowStepCommitPlan, type AgentWorkflowSystemMessageSnapshot, type AgentWorkflowToolBatchResult, type AgentWorkflowToolCallPlan, type AgentWorkflowToolCallResult, type AgentWorkflowToolCallSnapshot, type AgentWorkflowToolMessageSnapshot, type AgentWorkflowTurnPhase, type AgentWorkflowTurnState, type AgentWorkflowUserMessageSnapshot, CommitOutputOptions, CommitStepOptions, CreateAgentTurnStepCommitBatchOptions, type CreateAgentWorkflowTurnStateOptions, PrepareModelStepOptions, PreparedAgentModelStep, RunModelStepOptions, RunToolBatchOptions, RunToolBatchResult, applyAgentWorkflowCommitResult, applyAgentWorkflowModelStepResult, applyAgentWorkflowToolBatchResult, applyAgentWorkflowToolCallResult, cloneAgentWorkflowTurnState, commitOutput, commitStep, convertAgentMessagesToModelMessages, createAgentTaskRunner, createAgentTurnStepCommitBatch, createAgentWorkflowTurnState, defaultAgentTaskCheckpointStrategy, failAgentWorkflowTurnState, planNextAgentWorkflowOperation, prepareModelStep, recordAgentWorkflowReplayDecision, restoreAgentWorkflowMessage, restoreAgentWorkflowMessages, runModelStep, runToolBatch, snapshotAgentWorkflowMessage, snapshotAgentWorkflowMessages };

package/dist/runtime/index.js

@@ -0,0 +1,64 @@
+import {
+  AgentTurnEngine,
+  advanceAgentTurnState,
+  applyAgentWorkflowCommitResult,
+  applyAgentWorkflowModelStepResult,
+  applyAgentWorkflowToolBatchResult,
+  applyAgentWorkflowToolCallResult,
+  cloneAgentWorkflowTurnState,
+  commitOutput,
+  commitStep,
+  convertAgentMessagesToModelMessages,
+  createAgentTaskRunner,
+  createAgentTurnEngine,
+  createAgentTurnState,
+  createAgentTurnStepCommitBatch,
+  createAgentWorkflowTurnState,
+  defaultAgentTaskCheckpointStrategy,
+  failAgentTurnState,
+  failAgentWorkflowTurnState,
+  planNextAgentWorkflowOperation,
+  prepareModelStep,
+  recordAgentWorkflowReplayDecision,
+  restoreAgentWorkflowMessage,
+  restoreAgentWorkflowMessages,
+  runModelStep,
+  runToolBatch,
+  snapshotAgentWorkflowMessage,
+  snapshotAgentWorkflowMessages
+} from "../chunk-IMGQOTU2.js";
+import "../chunk-FG4MD5MU.js";
+import "../chunk-VEKUXUVF.js";
+import "../chunk-QAQADS4X.js";
+import "../chunk-X635CM2F.js";
+import "../chunk-QWFMX226.js";
+import "../chunk-DWYX7ASF.js";
+export {
+  AgentTurnEngine,
+  advanceAgentTurnState,
+  applyAgentWorkflowCommitResult,
+  applyAgentWorkflowModelStepResult,
+  applyAgentWorkflowToolBatchResult,
+  applyAgentWorkflowToolCallResult,
+  cloneAgentWorkflowTurnState,
+  commitOutput,
+  commitStep,
+  convertAgentMessagesToModelMessages,
+  createAgentTaskRunner,
+  createAgentTurnEngine,
+  createAgentTurnState,
+  createAgentTurnStepCommitBatch,
+  createAgentWorkflowTurnState,
+  defaultAgentTaskCheckpointStrategy,
+  failAgentTurnState,
+  failAgentWorkflowTurnState,
+  planNextAgentWorkflowOperation,
+  prepareModelStep,
+  recordAgentWorkflowReplayDecision,
+  restoreAgentWorkflowMessage,
+  restoreAgentWorkflowMessages,
+  runModelStep,
+  runToolBatch,
+  snapshotAgentWorkflowMessage,
+  snapshotAgentWorkflowMessages
+};

package/dist/session-manager-Uawm2Le7.d.ts

@@ -0,0 +1,274 @@
+import { M as Message } from './messages-BYWGn8TY.js';
+
+/**
+ * Storage Types
+ *
+ * Core types for session storage with tree structure support.
+ * Designed for append-only event sourcing with branching.
+ */
+/**
+ * Base interface for all session entries
+ * Supports tree structure via id/parentId
+ */
+interface EntryBase {
+    /** Unique entry ID (8-char hex) */
+    id: string;
+    /** Parent entry ID (null for first entry after header) */
+    parentId: string | null;
+    /** ISO timestamp */
+    timestamp: string;
+}
+/**
+ * Session header - always first entry in file
+ */
+interface SessionHeader {
+    type: "header";
+    /** Storage format version */
+    version: number;
+    /** Session ID */
+    id: string;
+    /** Working directory */
+    cwd: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Parent session ID (if forked) */
+    parentSessionId?: string;
+    /** Session title */
+    title?: string;
+}
+/**
+ * Serialized message (dates as ISO strings)
+ */
+interface SerializedMessage {
+    id: string;
+    role: "user" | "assistant" | "tool" | "system";
+    content: string;
+    createdAt: string;
+    system?: string;
+    finish?: string;
+    tokens?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+    };
+    cost?: number;
+    error?: {
+        name: string;
+        message: string;
+        code?: string;
+    };
+    /** Tool calls for assistant messages with finish=tool-calls */
+    toolCalls?: Array<{
+        toolCallId: string;
+        toolName: string;
+        args: unknown;
+    }>;
+    toolCallId?: string;
+    toolName?: string;
+    result?: unknown;
+}
+/**
+ * Message entry
+ */
+interface MessageEntry extends EntryBase {
+    type: "message";
+    message: SerializedMessage;
+}
+/**
+ * Compaction/summarization entry
+ * Replaces old messages with a summary
+ */
+interface CompactionEntry extends EntryBase {
+    type: "compaction";
+    /** Summary of compacted messages */
+    summary: string;
+    /** ID of first entry that was kept (not compacted) */
+    firstKeptEntryId: string;
+    /** Token count before compaction */
+    tokensBefore: number;
+    /** Token count after compaction */
+    tokensAfter: number;
+    /** Files that were read during compacted messages */
+    readFiles?: string[];
+    /** Files that were modified during compacted messages */
+    modifiedFiles?: string[];
+}
+/**
+ * Session info/metadata update
+ */
+interface MetadataEntry extends EntryBase {
+    type: "metadata";
+    /** Updated title */
+    title?: string;
+    /** User-defined name */
+    name?: string;
+}
+/**
+ * Branch marker - indicates a branch point
+ */
+interface BranchEntry extends EntryBase {
+    type: "branch";
+    /** ID of the entry we're branching from */
+    branchFromId: string;
+    /** Optional summary of the branch */
+    summary?: string;
+}
+/**
+ * Model/config change entry
+ */
+interface ConfigChangeEntry extends EntryBase {
+    type: "config_change";
+    /** What changed */
+    change: "model" | "reasoning_level" | "temperature" | "other";
+    /** Previous value */
+    from?: string;
+    /** New value */
+    to: string;
+}
+/**
+ * All entry types (excluding header)
+ */
+type SessionEntry = MessageEntry | CompactionEntry | MetadataEntry | BranchEntry | ConfigChangeEntry;
+/**
+ * All file entries (including header)
+ */
+type FileEntry = SessionHeader | SessionEntry;
+/**
+ * Session summary info (lightweight, for listing)
+ */
+interface SessionInfo {
+    /** Session ID */
+    id: string;
+    /** File path */
+    path: string;
+    /** Working directory */
+    cwd: string;
+    /** Session title */
+    title?: string;
+    /** User-defined name */
+    name?: string;
+    /** Parent session ID (if forked) */
+    parentSessionId?: string;
+    /** Creation time */
+    createdAt: Date;
+    /** Last modified time */
+    updatedAt: Date;
+    /** Number of message entries */
+    messageCount: number;
+    /** First user message (preview) */
+    firstMessage?: string;
+}
+/**
+ * Session storage interface
+ * Pluggable backend for session persistence
+ */
+interface SessionStorage {
+    /**
+     * Create a new session
+     */
+    create(header: SessionHeader): Promise<void>;
+    /**
+     * Append an entry to a session
+     */
+    append(sessionId: string, entry: SessionEntry): Promise<void>;
+    /**
+     * Append multiple entries atomically
+     */
+    appendBatch(sessionId: string, entries: SessionEntry[]): Promise<void>;
+    /**
+     * Read all entries from a session
+     */
+    read(sessionId: string): Promise<FileEntry[]>;
+    /**
+     * Delete a session
+     */
+    delete(sessionId: string): Promise<boolean>;
+    /**
+     * Check if session exists
+     */
+    exists(sessionId: string): Promise<boolean>;
+    /**
+     * List all sessions (lightweight info only)
+     */
+    list(): Promise<SessionInfo[]>;
+    /**
+     * Clear all sessions
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Current storage format version
+ */
+declare const STORAGE_VERSION = 1;
+
+/**
+ * Options for creating a new session.
+ */
+interface CreateSessionOptions {
+    /** Custom session ID (auto-generated if not provided) */
+    id?: string;
+    /** Working directory */
+    cwd: string;
+    /** Session title */
+    title?: string;
+    /** Parent session ID (if forking) */
+    parentSessionId?: string;
+}
+/**
+ * Session context for LLM calls.
+ */
+interface SessionContext {
+    /** Messages for LLM context */
+    messages: Message[];
+    /** Current leaf entry ID */
+    leafId: string | null;
+    /** Session metadata */
+    metadata: {
+        id: string;
+        cwd: string;
+        title?: string;
+        name?: string;
+    };
+}
+
+/**
+ * Manages session lifecycle with tree-structured entries.
+ */
+declare class SessionManager {
+    private storage;
+    private currentSessionId;
+    private currentLeafId;
+    private entriesCache;
+    private idsCache;
+    constructor(storage?: SessionStorage);
+    create(options: CreateSessionOptions): Promise<string>;
+    load(sessionId: string): Promise<void>;
+    getSessionId(): string | null;
+    getLeafId(): string | null;
+    addMessage(message: Message): Promise<string>;
+    addMessages(messages: Message[]): Promise<string[]>;
+    getMessages(leafId?: string): Message[];
+    addCompaction(options: {
+        summary: string;
+        firstKeptEntryId: string;
+        tokensBefore: number;
+        tokensAfter: number;
+        readFiles?: string[];
+        modifiedFiles?: string[];
+    }): Promise<string>;
+    branch(fromEntryId: string, summary?: string): Promise<string>;
+    switchToLeaf(leafId: string): void;
+    updateMetadata(updates: {
+        title?: string;
+        name?: string;
+    }): Promise<void>;
+    getContext(): SessionContext;
+    getEntries(): FileEntry[];
+    getHeader(): SessionHeader | null;
+    listSessions(): Promise<SessionInfo[]>;
+    deleteSession(sessionId: string): Promise<boolean>;
+    sessionExists(sessionId: string): Promise<boolean>;
+    getStorage(): SessionStorage;
+}
+
+export { type BranchEntry as B, type CompactionEntry as C, type EntryBase as E, type FileEntry as F, type MessageEntry as M, STORAGE_VERSION as S, type CreateSessionOptions as a, type MetadataEntry as b, type SessionContext as c, type SessionEntry as d, type SessionHeader as e, type SessionInfo as f, SessionManager as g, type SessionStorage as h, type SerializedMessage as i, type ConfigChangeEntry as j };