@code-yeongyu/senpi-agent-core 2026.9.12-3 → 2026.9.12

package/dist/harness/session/types.d.ts

@@ -1,512 +1,352 @@
-import type { JsonValue } from "@earendil-works/chord";
-import type { AssistantMessage, StopReason, Usage } from "@earendil-works/pi-ai";
-import type { AgentMessage, QueueMode, ThinkingLevel } from "../../types.ts";
-import type { BranchPreparation } from "../compaction/branch-summarization.ts";
-import type { CompactionPreparation, CompactionSettings } from "../compaction/compaction.ts";
-import type { Context } from "../context.ts";
-import type { AgentHarnessStreamOptions } from "../types.ts";
-import type { ListElement, ListReadOptions, ListWrite, StoredValue, Value, ValueList, ValueWrite } from "./values.ts";
-export type { JsonValue } from "@earendil-works/chord";
-export type SettledAssistantMessage = AssistantMessage & {
-    stopReason: Exclude<StopReason, "pending">;
+import type { StopReason, Usage } from "@earendil-works/pi-ai";
+import "../messages.ts";
+import type { AgentMessage } from "../../types.ts";
+import type { Session } from "./session.ts";
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
 };
-export type EntryType = "message" | "compaction" | "branch_summary" | "custom";
+export type SessionStopReason = Exclude<StopReason, "pending"> | "deferred";
+export interface IdGenerator {
+    next(): string;
+}
 export interface EntryBase {
+    type: string;
     id: string;
-    parentId: string | null;
     seq: number;
+    parentId: string | null;
     timestamp: number;
-    type: EntryType;
-    customType?: string;
 }
 export interface MessageEntry extends EntryBase {
     type: "message";
     message: AgentMessage;
     terminate?: true;
 }
+export interface ModelChangeEntry extends EntryBase {
+    type: "model_change";
+    provider: string;
+    modelId: string;
+}
+export interface ThinkingLevelEntry extends EntryBase {
+    type: "thinking_level_change";
+    thinkingLevel: string;
+}
+export interface ConfigurationUpdateEntry extends EntryBase {
+    type: "configuration_update";
+    reasoning: {
+        effort: string;
+    };
+}
+export interface ActiveToolsEntry extends EntryBase {
+    type: "active_tools_change";
+    activeToolNames: string[];
+}
 export interface CompactionEntry extends EntryBase {
     type: "compaction";
     summary: string;
     retainedTail: AgentMessage[];
     tokensBefore: number;
-    details?: JsonValue;
+    details?: unknown;
     usage?: Usage;
-    fromHook: boolean;
 }
 export interface BranchSummaryEntry extends EntryBase {
     type: "branch_summary";
-    fromId: string | null;
+    fromId: string;
     summary: string;
-    details?: JsonValue;
+    details?: unknown;
     usage?: Usage;
-    fromHook: boolean;
 }
 export interface CustomEntry extends EntryBase {
     type: "custom";
     customType: string;
-    data?: JsonValue;
-}
-/** Convert an application-defined custom entry into model context. */
-export type EntryProjector = (entry: CustomEntry, context: Context) => AgentMessage[] | undefined | Promise<AgentMessage[] | undefined>;
-export type Entry = MessageEntry | CompactionEntry | BranchSummaryEntry | CustomEntry;
-/** Entry supplied to a transaction before storage assigns sequence and timestamp. */
-export type NewEntry<TEntry extends Entry = Entry> = TEntry extends Entry ? Omit<TEntry, "seq" | "timestamp"> : never;
-export interface LaneConfiguration {
-    model: {
-        provider: string;
-        modelId: string;
-    };
-    thinkingLevel: ThinkingLevel;
-    activeToolNames: string[];
+    data?: unknown;
 }
-export interface OperationMeta {
-    operationId: string;
+export type Entry = MessageEntry | ModelChangeEntry | ThinkingLevelEntry | ConfigurationUpdateEntry | ActiveToolsEntry | CompactionEntry | BranchSummaryEntry | CustomEntry;
+export type ProvisionedEntry<TEntry extends Entry = Entry> = TEntry extends Entry ? Omit<TEntry, "parentId" | "seq" | "timestamp"> : never;
+export interface RecordBase {
+    id: string;
+    seq: number;
     lane: string;
-    sourceTipId: string | null;
-    startedAt: number;
+    timestamp: number;
+}
+export interface OperationStartedRecord extends RecordBase {
+    type: "operation_started";
+    sourceLeafId: string | null;
     intent: {
         kind: "run";
-        promptEntryIds: string[];
+        /** Normalized caller input before before_run; kept for suspended operations and before_resume. */
+        originalPrompt: AgentMessage[];
+        /** Captured nextRun items, then the prompt, then before_run injections. */
+        initialMessages: ProvisionedEntry[];
+        systemPromptOverride?: string;
+        resumeData?: {
+            [extensionId: string]: JsonValue;
+        };
     } | {
         kind: "compaction";
         customInstructions?: string;
+        resultEntryId: string;
     } | {
         kind: "navigation";
         targetId: string | null;
         summarize: boolean;
-        label?: string;
         customInstructions?: string;
+        label?: string;
+        summaryEntryId?: string;
     };
 }
-export type Control = {
-    status: "running";
-} | {
-    status: "cancel_requested";
-    requestedAt: number;
-};
-export interface OperationError {
-    code: string;
-    message: string;
-    details?: JsonValue;
-}
-export type TerminalStatus = "completed" | "declined" | "aborted" | "failed";
-/** Immutable lane-lived observation record written by one terminal transaction. */
-export interface OperationResultRecord {
-    operationId: string;
-    kind: OperationMeta["intent"]["kind"];
-    status: TerminalStatus;
-    error?: OperationError;
-    fromTipId: string | null;
-    tipId: string | null;
-    startedAt: number;
-    endedAt: number;
-}
-export type Continuation = {
-    kind: "need_assistant";
-    overflowRecoveryUsed: boolean;
-} | {
-    kind: "may_finish";
-    includeFinalAssistant: boolean;
-};
-/** Checkpoint payload; the flat leaf literal replaces the old nested phase tag. */
-export interface CheckpointData {
-    continuation: Continuation;
-    triggerEntryId: string;
-}
-export type InboxItemKind = "steer" | "followUp" | "nextRun" | "write";
-export interface InboxItem {
-    entryId: string;
-    kind: InboxItemKind;
-}
-export interface NormalizedRetryPolicy {
-    maxAttempts: number;
-    baseDelayMs: number;
-    maxAgentDelayMs: number;
-}
-export interface GenerationContext {
-    stepId: string;
-    triggerEntryId: string;
-    configuration: LaneConfiguration;
-    streamOptions: AgentHarnessStreamOptions;
-    retryPolicy: NormalizedRetryPolicy;
-    overflowRecoveryUsed: boolean;
+export interface AbortRequestedRecord extends RecordBase {
+    type: "abort_requested";
+    runId: string;
+}
+export interface OperationFinishedRecord extends RecordBase {
+    type: "operation_finished";
+    runId: string;
+    outcome: "completed" | "aborted" | "failed" | "declined";
+    error?: {
+        code: string;
+        message: string;
+    };
 }
-interface ToolCallSource {
-    /** Zero-based index in the assistant message's complete content array, not a filtered tool-call ordinal. */
-    sourceIndex: number;
+export type CompactionReason = "manual" | "threshold" | "overflow";
+export type StepAttemptRecord = RecordBase & ({
+    type: "step_attempt";
+    runId: string;
+    step: "assistant" | "branch_summary";
+    attempt: number;
     resultEntryId: string;
-}
-export type ToolCall = ToolCallSource & ({
-    status: "planned";
-} | {
-    status: "effect_pending";
-    replay: "never" | "safe";
-} | {
-    status: "outcome_ready";
-    terminate: boolean;
+    compactionReason?: never;
 } | {
-    status: "completed";
-    terminate: boolean;
+    type: "step_attempt";
+    runId: string;
+    step: "compaction";
+    attempt: number;
+    resultEntryId: string;
+    /** Persists why compaction summary generation started so recovery resumes the same work. */
+    compactionReason: CompactionReason;
 });
-export interface ToolBatch {
+export interface ToolStartedRecord extends RecordBase {
+    type: "tool_started";
+    runId: string;
     assistantEntryId: string;
-    configuration: LaneConfiguration;
-    turnId: string;
-    calls: ToolCall[];
-}
-export interface SummaryContext {
+    toolIndex: number;
+    toolCallId: string;
+    toolName: string;
+    effectiveArgs: {
+        [key: string]: unknown;
+    };
     resultEntryId: string;
-    configuration: LaneConfiguration;
-    streamOptions: AgentHarnessStreamOptions;
-    retryPolicy: NormalizedRetryPolicy;
-}
-export interface Cancellable {
-    control: Control;
-}
-export interface RunSettings {
-    compaction: CompactionSettings;
-    steeringMode: QueueMode;
-    followUpMode: QueueMode;
-    toolExecution: "sequential" | "parallel";
-}
-/** Uniform scope carried by every operation leaf. */
-export interface OperationScope extends Cancellable {
-    settings: RunSettings;
-    latestAssistantEntryId: string | null;
-}
-/** Shared backoff data for every retry-wait leaf. */
-export interface RetryWait {
-    nextAttempt: number;
-    notBefore: number;
-    errorMessage: string;
-}
-export interface AssistantGenerationScope {
-    generationContext: GenerationContext;
+    replay: "never" | "safe";
 }
-export type ResultBoundary = {
-    kind: "resume_checkpoint";
-    resumeAfter: CheckpointData;
+export type QueueEnqueuedRecord = RecordBase & ({
+    type: "queue_enqueued";
+    queue: "steer" | "followUp";
+    runId: string;
+    target: ProvisionedEntry;
 } | {
-    kind: "finish";
-} | {
-    kind: "commit_navigation";
-    targetId: string;
-    label?: string;
-};
-export interface SummaryTask {
-    taskId: string;
-    reason?: "manual" | "threshold" | "overflow";
-    customInstructions?: string;
-    boundary: ResultBoundary;
-}
-export interface SummaryGenerationScope {
-    task: SummaryTask;
-    summaryContext: SummaryContext;
-}
-export interface SummaryGenerationReady extends SummaryGenerationScope {
-    nextAttempt: number;
-}
-export interface SummaryGenerationEffectPending extends SummaryGenerationScope {
-    attempt: number;
-    request?: {
-        index: number;
-        usageId: string;
-    };
-    usageIds: string[];
-}
-export interface SummaryGenerationRetryWait extends SummaryGenerationScope, RetryWait {
-}
-export interface DeferredScope extends OperationScope {
-    stepId: string;
-    sourceEntryId: string;
-    poll: number;
-    configuration: LaneConfiguration;
-    streamOptions: AgentHarnessStreamOptions;
-}
-export interface StartingOperation extends OperationScope {
-    at: "starting";
-}
-export interface CheckpointOperation extends OperationScope, CheckpointData {
-    at: "checkpoint";
+    type: "queue_enqueued";
+    queue: "nextRun";
+    runId?: never;
+    target: ProvisionedEntry;
+});
+export interface QueueCancelledRecord extends RecordBase {
+    type: "queue_cancelled";
+    runId?: string;
+    entryId: string;
 }
-export interface AssistantReadyOperation extends OperationScope, AssistantGenerationScope {
-    at: "assistant.ready";
-    nextAttempt: number;
+export interface WriteDeferredRecord extends RecordBase {
+    type: "write_deferred";
+    runId: string;
+    target: ProvisionedEntry;
 }
-export interface AssistantEffectPendingOperation extends OperationScope, AssistantGenerationScope {
-    at: "assistant.effect_pending";
+export type UsageRecord = RecordBase & {
+    type: "usage";
+    usage: Usage;
+} & ({
+    cause: "assistant" | "compaction" | "branch_summary" | "deferred_fetch";
+    runId: string;
+    entryId: string;
     attempt: number;
-    responseEntryId: string;
-    usageId: string;
-    intendedOutputLimit: number;
-    contextWindow: number;
-}
-export interface AssistantRetryWaitOperation extends OperationScope, AssistantGenerationScope, RetryWait {
-    at: "assistant.retry_wait";
-}
-export interface ToolsOperation extends OperationScope {
-    at: "tools";
-    batch: ToolBatch;
-}
-export interface DeferredSuspendedOperation extends DeferredScope {
-    at: "deferred.suspended";
-}
-export interface DeferredEffectPendingOperation extends DeferredScope {
-    at: "deferred.effect_pending";
-    responseEntryId: string;
-    usageId: string;
-}
-export interface SummaryDecidingOperation extends OperationScope {
-    at: "summary.deciding";
-    task: SummaryTask;
-}
-export interface SummaryReadyOperation extends OperationScope, SummaryGenerationReady {
-    at: "summary.ready";
-}
-export interface SummaryEffectPendingOperation extends OperationScope, SummaryGenerationEffectPending {
-    at: "summary.effect_pending";
-}
-export interface SummaryRetryWaitOperation extends OperationScope, SummaryGenerationRetryWait {
-    at: "summary.retry_wait";
-}
-export interface NavigationReadyToCommitOperation extends OperationScope {
-    at: "navigation.ready_to_commit";
-    /** Unsummarized navigation may target the branch root (null). */
-    targetId: string | null;
-    label?: string;
-}
-/** Flat durable operation state: exactly 13 family-neutral dispatcher leaves. */
-export type OperationState = StartingOperation | CheckpointOperation | AssistantReadyOperation | AssistantEffectPendingOperation | AssistantRetryWaitOperation | ToolsOperation | DeferredSuspendedOperation | DeferredEffectPendingOperation | SummaryDecidingOperation | SummaryReadyOperation | SummaryEffectPendingOperation | SummaryRetryWaitOperation | NavigationReadyToCommitOperation;
-export type OperationAt = OperationState["at"];
-/** Copy only the uniform operation scope when constructing a successor leaf. */
-export declare function operationScopeOf(state: OperationState): OperationScope;
-export type Operation = {
-    meta: OperationMeta;
-    state: OperationState;
-};
-export interface LaneState {
-    currentOperationId: string | null;
-    lastOperationId: string | null;
-    inbox: InboxItem[];
-}
-export type PendingEntry = {
-    type: "message";
-    payload: AgentMessage;
+    stopReason: SessionStopReason;
 } | {
-    type: "custom";
-    customType: string;
-    payload?: JsonValue;
-};
-export interface DurableFileOperations {
-    read: string[];
-    written: string[];
-    edited: string[];
-}
-export type DurableStructuralPreparation = {
-    kind: "compaction";
-    messagesToSummarize: CompactionPreparation["messagesToSummarize"];
-    turnPrefixMessages: CompactionPreparation["turnPrefixMessages"];
-    retainedTail: CompactionPreparation["retainedTail"];
-    isSplitTurn: boolean;
-    tokensBefore: number;
-    previousSummary?: string;
-    fileOps: DurableFileOperations;
-    settings: CompactionSettings;
+    cause: "tool";
+    runId: string;
+    entryId: string;
+    toolCallId: string;
 } | {
-    kind: "branch_summary";
-    messages: BranchPreparation["messages"];
-    fileOps: DurableFileOperations;
-    totalTokens: number;
-};
-export interface UsageRow {
-    id: string;
-    seq: number;
-    usage: Usage;
+    cause: "hook";
+    runId: string;
+    entryId: string;
+} | {
+    cause: "adjustment";
+    runId?: string;
     entryId?: string;
-    adjustment: boolean;
     details?: JsonValue;
-}
-export interface EntryWrite {
-    kind: "entry";
-    entry: NewEntry;
-}
-export interface UsageWrite {
-    kind: "usage";
-    row: Omit<UsageRow, "seq">;
-}
-export type Write = EntryWrite | UsageWrite | ValueWrite | ListWrite;
-export interface CommitResult {
-    firstSeq: number;
-    seqs: number[];
-    timestamp: number;
-    /** Session totals immediately after this commit was applied. */
-    stats: SessionStats;
-}
-export interface EntryStructure {
-    id: string;
-    parentId: string | null;
-    seq: number;
-    timestamp: number;
-    type: EntryType;
-    customType?: string;
-}
+});
+export type LaneRecord = OperationStartedRecord | AbortRequestedRecord | OperationFinishedRecord | StepAttemptRecord | ToolStartedRecord | QueueEnqueuedRecord | QueueCancelledRecord | WriteDeferredRecord | UsageRecord;
+export type NewRecord<TRecord extends LaneRecord = LaneRecord> = TRecord extends LaneRecord ? Omit<TRecord, "seq" | "timestamp"> : never;
+export type EntryOrder = "newestFirst" | "oldestFirst";
 export interface EntryCursor {
-    seq: number;
+    afterSeq: number;
 }
-export interface BranchScan {
-    start?: string;
-    stopAtType?: EntryType;
-    stopAtId?: string;
-    type?: EntryType;
+export interface EntryQuery {
+    type?: Entry["type"];
     customType?: string;
-    order?: "newestFirst" | "oldestFirst";
+    order?: EntryOrder;
     limit?: number;
     cursor?: EntryCursor;
 }
-export type StorageBranchScan = BranchScan & {
-    start: string;
-};
-export interface EntryScan {
-    type?: EntryType;
-    customType?: string;
-    fromSeq?: number;
-    toSeq?: number;
-    order?: "asc" | "desc";
-    limit?: number;
+/** Bounds of a branch scan. Default: the whole path, leaf to root. */
+export interface BranchBounds {
+    start?: string;
+    stopAtType?: Entry["type"];
+    stopAtId?: string;
 }
-export interface UsageScan {
-    fromSeq?: number;
-    toSeq?: number;
-    order?: "asc" | "desc";
+export interface RecordQuery {
+    /** Exact lane match. Omit to query every lane. */
+    lane?: string;
+    /** Exact record discriminant match. Omit to query every record type. */
+    type?: LaneRecord["type"];
+    /**
+     * Operation identity. Matches OperationStartedRecord.id and the runId
+     * property of operation-owned records. Records without an operation
+     * identity do not match.
+     */
+    runId?: string;
+    /** Exact operation intent kind. Valid only with type "operation_started". */
+    operationKind?: OperationStartedRecord["intent"]["kind"];
+    /** Exclusive chronological lower bound: seq > afterSeq, regardless of order. */
+    afterSeq?: number;
+    /** Sequence order. Default: "newestFirst". */
+    order?: EntryOrder;
+    /** Positive maximum number of matching records. */
     limit?: number;
 }
-export interface SessionStats {
-    messageCount: number;
-    usage: Usage;
-}
-export interface Storage {
-    commit(writes: Write[], context: Context): Promise<CommitResult>;
-    getEntries(ids: string[], context: Context): Promise<Map<string, Entry>>;
-    getValue<T>(address: Value<T>, context: Context): Promise<StoredValue<T> | undefined>;
-    scanValues<T>(prefix: Value<T>, context: Context): Promise<StoredValue<T>[]>;
-    readList<T>(address: ValueList<T>, options: ListReadOptions | undefined, context: Context): Promise<ListElement<T>[]>;
-    scanBranch(query: StorageBranchScan, context: Context): Promise<Entry[]>;
-    scanBranchStructure(query: StorageBranchScan, context: Context): Promise<EntryStructure[]>;
-    scanEntries(query: EntryScan, context: Context): Promise<Entry[]>;
-    scanUsage(query: UsageScan, context: Context): Promise<UsageRow[]>;
-    getStats(context: Context): Promise<SessionStats>;
-    close(context: Context): Promise<void>;
-}
 export interface SessionMetadata {
     id: string;
     createdAt: number;
-    storageVersion: number;
-    cwd?: string;
     parentSessionId?: string;
-    legacyParentSessionPath?: string;
-}
-export interface IdGenerator {
-    next(timestampMs?: number): string;
-}
-export interface EntryQuery {
-    type?: EntryType;
-    customType?: string;
-    order?: "asc" | "desc";
-    limit?: number;
-    cursor?: EntryCursor;
 }
-export interface SessionReader {
-    getEntries(ids: string[], context: Context): Promise<Map<string, Entry>>;
-    getStats(context: Context): Promise<SessionStats>;
-    getValue<T>(address: Value<T>, context: Context): Promise<StoredValue<T> | undefined>;
-    scanValues<T>(prefix: Value<T>, context: Context): Promise<StoredValue<T>[]>;
-    readList<T>(address: ValueList<T>, options: ListReadOptions | undefined, context: Context): Promise<ListElement<T>[]>;
-    /** Scan a branch from an explicit entry while this reader capability remains valid. */
-    scanBranch(query: StorageBranchScan, context: Context): Promise<Entry[]>;
+export interface SessionStats {
+    messageCount: number;
+    cachedTokens: number;
+    uncachedTokens: number;
+    totalTokens: number;
+    costTotal: number;
 }
-/** Exclusive keyless mutation barrier for one Session. */
-export interface SessionMutation extends SessionReader {
-    /** Exactly zero or one commit attempt. A second attempt rejects. */
-    commit(writes: Write[], context: Context): Promise<CommitResult>;
-    /** Wait for any commit attempt, invalidate the capability, and release the barrier. */
-    end(context: Context): Promise<void>;
+export interface LanePointer {
+    lane: string;
+    leafId: string | null;
 }
-/** Callback-scoped mutation capability without authority to release its Session barrier. */
-export type SessionMutator = Omit<SessionMutation, "end">;
-export type SessionMutationCallback<T> = (mutator: SessionMutator, context: Context) => T | Promise<T>;
-export interface Branch {
-    readonly name: string;
-    getTipId(context: Context): Promise<string | null>;
-    findEntries(query: BranchScan | undefined, context: Context): Promise<Entry[]>;
-    findEntry(query: BranchScan | undefined, context: Context): Promise<Entry | undefined>;
-    appendMessage(message: AgentMessage, context: Context): Promise<string>;
-    appendCustomEntry(customType: string, data: JsonValue | undefined, context: Context): Promise<string>;
+export type LogItem = {
+    kind: "entry";
+    seq: number;
+    entry: Entry;
+} | {
+    kind: "record";
+    seq: number;
+    record: LaneRecord;
+} | {
+    kind: "lane";
+    seq: number;
+    lane: string;
+    leafId: string | null;
+} | {
+    kind: "fact";
+    seq: number;
+    fact: "name";
+    name: string | undefined;
+} | {
+    kind: "fact";
+    seq: number;
+    fact: "label";
+    targetId: string;
+    label: string | undefined;
+};
+export interface LogOptions {
+    afterSeq?: number;
+    limit?: number;
 }
-export interface Session<TMetadata extends SessionMetadata = SessionMetadata> extends SessionReader {
-    readonly metadata: TMetadata;
-    readonly idGenerator: IdGenerator;
-    getEntry(id: string, context: Context): Promise<Entry | undefined>;
-    getStats(context: Context): Promise<SessionStats>;
-    getName(context: Context): Promise<string | undefined>;
-    getLabel(targetId: string, context: Context): Promise<string | undefined>;
-    findEntries(query: EntryQuery | undefined, context: Context): Promise<Entry[]>;
-    findEntry(query: EntryQuery | undefined, context: Context): Promise<Entry | undefined>;
-    branch(name: string, context: Context): Promise<Branch | undefined>;
-    createBranch(name: string, at: string | null, context: Context): Promise<Branch>;
-    beginMutation(context: Context): Promise<SessionMutation>;
+export interface SessionStorage<TMetadata extends SessionMetadata = SessionMetadata> {
+    getMetadata(): Promise<TMetadata>;
+    getLanes(): Promise<{
+        lane: string;
+        leafId: string | null;
+    }[]>;
+    createLane(lane: string, at: string | null): Promise<void>;
+    moveLane(lane: string, to: string | null): Promise<void>;
+    appendEntry<TEntry extends Entry>(entry: ProvisionedEntry<TEntry>, lane: string): Promise<TEntry>;
+    appendRecord<TRecord extends LaneRecord>(record: NewRecord<TRecord>): Promise<TRecord>;
+    getEntry(id: string): Promise<Entry | undefined>;
+    findEntries(query?: EntryQuery): Promise<Entry[]>;
+    /** start is mandatory here (as opposed to SessionTree's findEntriesOnBranch); defaulting to a lane's leaf is view sugar. */
+    findEntriesOnBranch(query: EntryQuery & BranchBounds & {
+        start: string;
+    }): Promise<Entry[]>;
+    findRecords<K extends LaneRecord["type"]>(query: RecordQuery & {
+        type: K;
+    }): Promise<Extract<LaneRecord, {
+        type: K;
+    }>[]>;
+    findRecords(query?: RecordQuery): Promise<LaneRecord[]>;
     /**
-     * Trusted exclusive callback over the Session mutation line. Calling a public Session writer from
-     * this callback queues it behind the callback; awaiting that nested writer therefore deadlocks.
-     * Use the supplied mutator for the callback's sole commit.
+     * Returns unfinished operation starts newest first. Recovery uses `limit: 2`:
+     * zero results mean the lane is idle, one means it is suspended, and two
+     * mean at least two operations are open, which is corruption. Further
+     * results provide no additional recovery state.
      */
-    mutate<T>(mutation: SessionMutationCallback<T>, context: Context): Promise<T>;
-    setValue<T>(address: Value<T>, next: NoInfer<T>, context: Context): Promise<void>;
-    deleteValue<T>(address: Value<T>, context: Context): Promise<void>;
-    appendList<T>(address: ValueList<T>, element: NoInfer<T>, context: Context): Promise<void>;
-    deleteList<T>(address: ValueList<T>, context: Context): Promise<void>;
-    setName(name: string | undefined, context: Context): Promise<void>;
-    setLabel(targetId: string, label: string | undefined, context: Context): Promise<void>;
-    close(context: Context): Promise<void>;
+    findOpenOperations(lane: string, options?: {
+        limit?: number;
+    }): Promise<OperationStartedRecord[]>;
+    getLog(options?: {
+        afterSeq?: number;
+        limit?: number;
+    }): Promise<LogItem[]>;
+    getName(): Promise<string | undefined>;
+    setName(name: string | undefined): Promise<void>;
+    getLabel(id: string): Promise<string | undefined>;
+    setLabel(id: string, label: string | undefined): Promise<void>;
+    getStats(): Promise<SessionStats>;
+}
+export interface SessionTree {
+    getLeafId(): Promise<string | null>;
+    getEntry(id: string): Promise<Entry | undefined>;
+    getStats(): Promise<SessionStats>;
+    getName(): Promise<string | undefined>;
+    setName(name: string | undefined): Promise<void>;
+    getLabel(targetId: string): Promise<string | undefined>;
+    setLabel(targetId: string, label: string | undefined): Promise<void>;
+    /** Session-wide, all branches, sequence order. */
+    findEntries(query?: EntryQuery): Promise<Entry[]>;
+    findEntry(query?: EntryQuery): Promise<Entry | undefined>;
+    /** Branch-scoped: the path from start toward root. */
+    findEntriesOnBranch(query?: EntryQuery & BranchBounds): Promise<Entry[]>;
+    findEntryOnBranch(query?: EntryQuery & BranchBounds): Promise<Entry | undefined>;
+    appendMessage(message: AgentMessage): Promise<string>;
+    appendCustomEntry(customType: string, data?: unknown): Promise<string>;
 }
 export interface SessionCreateOptions {
     id?: string;
     parentSessionId?: string;
 }
 export type ForkOptions = {
-    /**
-     * Copy one path from a complete configured source AgentLane under the same
-     * Branch name, with copied configuration and fresh idle lane state.
-     */
-    scope: "branch";
-    /** Source Branch to copy. */
-    branch: string;
-    /** Entry on the source Branch's current tip ancestry. Defaults to the current tip. */
+    scope?: "branch";
     entryId?: string;
-    /**
-     * Whether the fork includes the selected entry or stops at its parent.
-     * Defaults to including the selected entry.
-     */
     position?: "before" | "at";
-    /** Optional destination session id. */
-    id?: string;
 } | {
-    /**
-     * Copy the whole conversation tree and every Branch tip. Each configured
-     * AgentLane copies configuration plus fresh idle state; data-only Branches
-     * remain data-only. Operation/pending/result/usage state is excluded.
-     */
     scope: "tree";
-    /** Optional destination session id. */
-    id?: string;
 };
-export interface SessionRepo<TMetadata extends SessionMetadata = SessionMetadata, TCreateOptions extends {
-    id?: string;
-    parentSessionId?: string;
-} = SessionCreateOptions, TListOptions = void> {
-    create(options: TCreateOptions, context: Context): Promise<Session<TMetadata>>;
-    open(metadata: TMetadata, context: Context): Promise<Session<TMetadata>>;
-    list(options: TListOptions | undefined, context: Context): Promise<TMetadata[]>;
-    delete(metadata: TMetadata, context: Context): Promise<void>;
-    fork(source: TMetadata, options: ForkOptions, context: Context): Promise<Session<TMetadata>>;
+export interface SessionRepo<TMetadata extends SessionMetadata = SessionMetadata, TCreateOptions extends SessionCreateOptions = SessionCreateOptions, TListOptions = void> {
+    create(options: TCreateOptions): Promise<Session<TMetadata>>;
+    /** Opens the session for writing and acquires any backend writer claim. */
+    open(metadata: TMetadata): Promise<Session<TMetadata>>;
+    /** Lists session metadata without opening sessions or acquiring writer claims. */
+    list(options?: TListOptions): Promise<TMetadata[]>;
+    delete(metadata: TMetadata): Promise<void>;
+    fork(source: TMetadata, options: ForkOptions & TCreateOptions): Promise<Session<TMetadata>>;
+}
+export type SessionErrorCode = "not_found" | "already_exists" | "invalid_entry" | "invalid_payload" | "invalid_lane" | "invalid_query" | "invalid_fork_target" | "storage";
+export declare class SessionError extends Error {
+    readonly code: SessionErrorCode;
+    constructor(code: SessionErrorCode, message: string, cause?: Error);
 }
 //# sourceMappingURL=types.d.ts.map