@robiteame/dsh-pi-agent-session-tree 0.1.0

package/lib/typert.remote-client.d.ts

@@ -0,0 +1,2 @@
+declare const TYPERT_REMOTE: Record<string, unknown>
+export default TYPERT_REMOTE

package/lib/typert.remote-client.js

@@ -0,0 +1,247 @@
+/* Generated by @deepseek-ai/dsh-typert-generator from the Host FaceModel — do not edit. */
+import { z } from 'zod'
+
+const JsonValueRemoteCodec$schema = z.union([z.literal(null), z.string(), z.number(), z.literal(false), z.literal(true), z.array(z.lazy(() => JsonValueRemoteCodec$schema)), z.record(z.string(), z.lazy(() => JsonValueRemoteCodec$schema))])
+const _robiteame_dsh_pi_agent_session_tree_sessionTree_fork_parameter_0$schema = z.intersection(z.string(), z.unknown())
+const _robiteame_dsh_pi_agent_session_tree_sessionTree_fork_parameter_1$schema = z.string()
+const _robiteame_dsh_pi_agent_session_tree_sessionTree_fork_parameter_2$schema = z.string()
+const _robiteame_dsh_pi_agent_session_tree_sessionTree_fork_result$schema = z.object({
+  'cursor': z.string(),
+  'branch': z.string(),
+  'forkCount': z.number(),
+})
+const _robiteame_dsh_pi_agent_session_tree_sessionTree_jump_parameter_0$schema = z.intersection(z.string(), z.unknown())
+const _robiteame_dsh_pi_agent_session_tree_sessionTree_jump_parameter_1$schema = z.union([z.literal(null), z.string()])
+const _robiteame_dsh_pi_agent_session_tree_sessionTree_jump_result$schema = z.object({
+  'cursor': z.union([z.literal(null), z.string()]).readonly(),
+  'messages': z.array(z.object({
+  'role': z.union([z.literal("system"), z.literal("user"), z.literal("assistant"), z.literal("tool")]).readonly(),
+  'content': z.string().readonly(),
+  'name': z.string().readonly().optional(),
+  'toolCallId': z.string().readonly().optional(),
+})).readonly(),
+})
+const _robiteame_dsh_pi_agent_session_tree_sessionTree_list_parameter_0$schema = z.intersection(z.string(), z.unknown())
+const _robiteame_dsh_pi_agent_session_tree_sessionTree_list_result$schema = z.object({
+  'sessionId': z.intersection(z.string(), z.unknown()).readonly(),
+  'cursor': z.union([z.literal(null), z.string()]).readonly(),
+  'activeBranch': z.string().readonly(),
+  'selectedNodeId': z.union([z.literal(null), z.string()]).readonly().optional(),
+  'branchHeads': z.record(z.string(), z.string()).readonly().optional(),
+  'nodes': z.array(z.object({
+  'nodeId': z.string().readonly(),
+  'parentId': z.union([z.literal(null), z.string()]).readonly(),
+  'forkCount': z.number().readonly().optional(),
+  'type': z.union([z.literal("message"), z.literal("tool_call"), z.literal("tool_result"), z.literal("model_change"), z.literal("compaction"), z.literal("branch_summary"), z.literal("custom")]).readonly().optional(),
+  'branch': z.string().readonly(),
+  'summary': z.string().readonly(),
+  'createdAt': z.string().readonly(),
+  'message': z.object({
+  'role': z.union([z.literal("system"), z.literal("user"), z.literal("assistant"), z.literal("tool")]).readonly(),
+  'content': z.string().readonly(),
+  'name': z.string().readonly().optional(),
+  'toolCallId': z.string().readonly().optional(),
+}).readonly().optional(),
+  'content': z.array(z.union([z.object({
+  'type': z.literal("text").readonly(),
+  'text': z.string().readonly(),
+}), z.object({
+  'type': z.literal("tool_call").readonly(),
+  'id': z.string().readonly(),
+  'name': z.string().readonly(),
+  'arguments': z.union([z.literal(null), z.string(), z.number(), z.literal(false), z.literal(true), z.array(z.lazy(() => JsonValueRemoteCodec$schema)), z.record(z.string(), z.lazy(() => JsonValueRemoteCodec$schema))]).readonly(),
+}), z.object({
+  'type': z.literal("tool_result").readonly(),
+  'toolCallId': z.string().readonly(),
+  'content': z.string().readonly(),
+  'isError': z.boolean().readonly().optional(),
+}), z.object({
+  'type': z.literal("reasoning").readonly(),
+  'text': z.string().readonly(),
+})])).readonly().optional(),
+  'model': z.string().readonly().optional(),
+  'usage': z.record(z.string(), z.union([z.literal(null), z.string(), z.number(), z.literal(false), z.literal(true), z.array(z.lazy(() => JsonValueRemoteCodec$schema)), z.record(z.string(), z.lazy(() => JsonValueRemoteCodec$schema))])).readonly().optional(),
+  'cost': z.number().readonly().optional(),
+  'error': z.string().readonly().optional(),
+  'metadata': z.record(z.string(), z.union([z.literal(null), z.string(), z.number(), z.literal(false), z.literal(true), z.array(z.lazy(() => JsonValueRemoteCodec$schema)), z.record(z.string(), z.lazy(() => JsonValueRemoteCodec$schema))])).readonly().optional(),
+})).readonly(),
+  'branches': z.array(z.object({
+  'name': z.string().readonly(),
+  'headId': z.string().readonly(),
+  'nodeIds': z.array(z.string()).readonly(),
+})).readonly(),
+})
+const _robiteame_dsh_pi_agent_session_tree_sessionTree_session_parameter_0$schema = z.intersection(z.string(), z.unknown())
+const _robiteame_dsh_pi_agent_session_tree_sessionTree_session_result$schema = z.object({
+  'branchHeads': z.record(z.string(), z.string()).readonly().optional(),
+  'sessionId': z.intersection(z.string(), z.unknown()).readonly(),
+  'nodeCount': z.number().readonly(),
+  'messageCount': z.number().readonly(),
+  'branchCount': z.number().readonly(),
+  'cursor': z.union([z.literal(null), z.string()]).readonly(),
+  'activeBranch': z.string().readonly(),
+  'selectedNodeId': z.union([z.literal(null), z.string()]).readonly().optional(),
+  'currentPathLength': z.number().readonly(),
+  'usage': z.record(z.string(), z.number()).readonly().optional(),
+  'tokenCount': z.number().readonly().optional(),
+  'cost': z.number().readonly().optional(),
+  'snapshotVersion': z.literal(1).readonly(),
+})
+
+export const TYPERT_REMOTE = {
+  package: '@robiteame/dsh-pi-agent-session-tree',
+  descriptors: [
+    {
+      id: '@robiteame/dsh-pi-agent-session-tree#sessionTree/fork',
+      service: 'sessionTree',
+      namespace: 'sessionTree',
+      method: 'fork',
+      invocation: { kind: 'direct' },
+      scope: {
+        context: 'agent',
+        wire: 'agentId',
+      },
+      parameters: [
+        {
+          name: 'agent',
+          wire: 'agentId',
+          source: 'lookup',
+          lookup: 'agent',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
+            schema: _robiteame_dsh_pi_agent_session_tree_sessionTree_fork_parameter_0$schema,
+          },
+        },
+        {
+          name: 'nodeId',
+          wire: 'nodeId',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@robiteame/dsh-pi-agent-session-tree#sessionTree/fork:nodeId',
+            schema: _robiteame_dsh_pi_agent_session_tree_sessionTree_fork_parameter_1$schema,
+          },
+        },
+        {
+          name: 'branch',
+          wire: 'branch',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@robiteame/dsh-pi-agent-session-tree#sessionTree/fork:branch',
+            schema: _robiteame_dsh_pi_agent_session_tree_sessionTree_fork_parameter_2$schema,
+          },
+        },
+      ],
+      result: {
+        mode: 'strict',
+        typeSymbol: '@robiteame/dsh-pi-agent-session-tree#sessionTree/fork:result',
+        schema: _robiteame_dsh_pi_agent_session_tree_sessionTree_fork_result$schema,
+      },
+      sourceLocation: {"file":"packages/extensions/pi-agent-session-tree/src/index.ts","line":188,"column":3},
+    },
+    {
+      id: '@robiteame/dsh-pi-agent-session-tree#sessionTree/jump',
+      service: 'sessionTree',
+      namespace: 'sessionTree',
+      method: 'jump',
+      invocation: { kind: 'direct' },
+      scope: {
+        context: 'agent',
+        wire: 'agentId',
+      },
+      parameters: [
+        {
+          name: 'agent',
+          wire: 'agentId',
+          source: 'lookup',
+          lookup: 'agent',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
+            schema: _robiteame_dsh_pi_agent_session_tree_sessionTree_jump_parameter_0$schema,
+          },
+        },
+        {
+          name: 'nodeId',
+          wire: 'nodeId',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@robiteame/dsh-pi-agent-session-tree#sessionTree/jump:nodeId',
+            schema: _robiteame_dsh_pi_agent_session_tree_sessionTree_jump_parameter_1$schema,
+          },
+        },
+      ],
+      result: {
+        mode: 'strict',
+        typeSymbol: '@robiteame/dsh-pi-agent-session-tree/client#JumpView',
+        schema: _robiteame_dsh_pi_agent_session_tree_sessionTree_jump_result$schema,
+      },
+      sourceLocation: {"file":"packages/extensions/pi-agent-session-tree/src/index.ts","line":158,"column":3},
+    },
+    {
+      id: '@robiteame/dsh-pi-agent-session-tree#sessionTree/list',
+      service: 'sessionTree',
+      namespace: 'sessionTree',
+      method: 'list',
+      invocation: { kind: 'direct' },
+      scope: {
+        context: 'agent',
+        wire: 'agentId',
+      },
+      parameters: [
+        {
+          name: 'agent',
+          wire: 'agentId',
+          source: 'lookup',
+          lookup: 'agent',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
+            schema: _robiteame_dsh_pi_agent_session_tree_sessionTree_list_parameter_0$schema,
+          },
+        },
+      ],
+      result: {
+        mode: 'strict',
+        typeSymbol: '@robiteame/dsh-pi-agent-session-tree/client#SessionTreeView',
+        schema: _robiteame_dsh_pi_agent_session_tree_sessionTree_list_result$schema,
+      },
+      sourceLocation: {"file":"packages/extensions/pi-agent-session-tree/src/index.ts","line":132,"column":3},
+    },
+    {
+      id: '@robiteame/dsh-pi-agent-session-tree#sessionTree/session',
+      service: 'sessionTree',
+      namespace: 'sessionTree',
+      method: 'session',
+      invocation: { kind: 'direct' },
+      scope: {
+        context: 'agent',
+        wire: 'agentId',
+      },
+      parameters: [
+        {
+          name: 'agent',
+          wire: 'agentId',
+          source: 'lookup',
+          lookup: 'agent',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
+            schema: _robiteame_dsh_pi_agent_session_tree_sessionTree_session_parameter_0$schema,
+          },
+        },
+      ],
+      result: {
+        mode: 'strict',
+        typeSymbol: '@robiteame/dsh-pi-agent-session-tree/client#SessionTreeSessionInfo',
+        schema: _robiteame_dsh_pi_agent_session_tree_sessionTree_session_result$schema,
+      },
+      sourceLocation: {"file":"packages/extensions/pi-agent-session-tree/src/index.ts","line":211,"column":3},
+    },
+  ],
+}
+
+export default TYPERT_REMOTE

package/lib/types/client.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Browser-safe type outlet: the pure payload vocabulary re-exported for the
+ * client half and consumed by the generated Remote declarations. Nothing here
+ * imports a host-only symbol; `dsh-session/types` is client-safe.
+ *
+ * @module @robiteame/dsh-pi-agent-session-tree/client
+ */
+export type * from './types.ts';

package/lib/types/index.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Session-tree domain service: the append-only multi-branch conversation
+ * tree, one per agent session, served to the browser through the generated
+ * `sessionTree` Remote namespace.
+ *
+ * Design notes
+ * - A process-wide store keeps every session's tree; the companion
+ *   `@robiteame/dsh-tool-session-tree` plugin shares the same store, so
+ *   anything the model appends is immediately visible to the browser panel
+ *   and vice versa.
+ * - Harness Session events are the durable source of truth; the process-wide
+ *   store is an incrementally synchronized projection, while explicit snapshots
+ *   remain available for export and full-tree restore.
+ * - Every operation answers `{ok, value}|{ok:false,error}` from the domain
+ *   layer; the Remote boundary adds its own transport envelope.
+ *
+ * @module @robiteame/dsh-pi-agent-session-tree
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { SessionEvent, SessionEventMap } from '@deepseek-ai/dsh-session/types';
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import { SessionTree } from './session-tree.ts';
+import type { JumpView, SessionTreeSessionInfo, SessionTreeView } from './types.ts';
+export { SessionTree, SessionTreeStore, sessionTreeStore } from './session-tree.ts';
+export type * from './types.ts';
+export { attachToolResult, sessionEventsToTreeNodes, toolResultOf, type ProjectedToolResult } from './session-event-adapter.ts';
+export { getSessionTreeSidecar, persistSessionTree, setSessionTreeSidecar, SessionTreeSidecar } from './session-tree-sidecar.ts';
+export { isSessionTreeRestoreEvent, sessionTreeMarkerOf, type SessionTreeRestoreMarker } from './session-tree-marker.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        sessionTree: SessionTreeService;
+    }
+}
+/** Selected-message-surface API added by the repository's optional dev/session-branch-surface.patch. */
+interface SelectedMessageSurfaceSession {
+    selectMessageSurface(nodes: readonly number[] | null): void;
+    messageSurfaceNodes(): readonly number[];
+}
+/**
+ * Whether a live Session exposes the selected-message-surface API shipped by
+ * this repository's `dev/session-branch-surface.patch`. A stock DeepSeek-Harness
+ * install (the target of `dsh plugin add`) has no such API: `deriveMessages()`
+ * always walks the canonical surface, and unknown `session-tree/*` events
+ * cannot be marked `ignorable` through the public append API, so a profile
+ * cannot persist them. The tree remains fully browsable and branchable inside
+ * the process store in that mode; only the in-place model-surface switch is
+ * unavailable.
+ */
+export declare function supportsSelectedMessageSurface(session: Session): session is Session & SelectedMessageSurfaceSession;
+/** How cursor movements reach the model-visible Session surface on this build. */
+export type SessionTreeSurfaceMode = 'native' | 'stock' | 'projection';
+/**
+ * The active surface mode for one session:
+ * - `native` — `dev/session-branch-surface.patch` (or an upstream merge)
+ *   provides `Session.selectMessageSurface()`; jump/fork switch the model
+ *   history directly.
+ * - `stock` — official Harness: the plugin emulates the switch with an official
+ *   empty `replace` surface event plus the durable sidecar.
+ * - `projection` — the live surface is not writable in this revision;
+ *   navigation updates the tree projection and panel only.
+ */
+export declare function sessionTreeSurfaceMode(session: Session): SessionTreeSurfaceMode;
+/**
+ * Whether the running Harness recognizes the durable `session-tree/*` event
+ * vocabulary. The event names are registered in the session known-event-types
+ * table by `dev/session-branch-surface.patch`; on stock packages an appended
+ * unknown event would make a resumed persisted log unreadable, so callers must
+ * skip those appends.
+ */
+export declare function supportsDurableSessionTreeEvents(session: Session): boolean;
+/** Durable SessionTree event types appended to the owning Session log. */
+export type SessionTreeEventType = 'session-tree/node' | 'session-tree/cursor' | 'session-tree/branch' | 'session-tree/selection' | 'session-tree/snapshot';
+/**
+ * Append one durable SessionTree marker when the runtime supports it, and
+ * return undefined on stock Harness so callers can skip sequence tracking.
+ */
+export declare function appendSessionTreeEvent(session: Session, type: SessionTreeEventType, data: SessionEventMap[SessionTreeEventType]): SessionEvent<SessionTreeEventType> | undefined;
+/** Materialize and incrementally synchronize native Harness history. */
+export declare function syncSessionTree(agent: Agent): SessionTree;
+/** Apply the selected tree path to Harness' actual model-visible Session surface. */
+export declare function applyTreeCursorToSession(agent: Agent, tree: SessionTree): void;
+/** Remote-only service backing the browser tree panel. */
+export declare class SessionTreeService extends TypertRemoteService {
+    /**
+     * Register the service under `sessionTree`.
+     * @param ctx - owning Cordis Context.
+     */
+    constructor(ctx: Context);
+    /**
+     * Read the current tree view (nodes, branches, cursor) for one agent.
+     * The tree is created on first read, so an empty panel is valid.
+     * @param agent - owning live agent.
+     * @returns the complete view for the panel.
+     */
+    list(agent: Agent): SessionTreeView;
+    /** Synchronize native history, falling back to the last committed tree when replay fails. */
+    private synced;
+    /**
+     * Move the SessionTree cursor to an existing node and return its root-to-node
+     * path through the context operation. This also selects the same path on
+     * Harness' model-visible Session surface, so the next turn genuinely branches
+     * from this leaf instead of merely changing the browser projection.
+     * @param agent - owning live agent.
+     * @param nodeId - target node, or null to reset before the first node.
+     * @returns the new cursor and reconstructed messages.
+     * @throws Error when the node does not exist (settles as the standard error envelope).
+     */
+    jump(agent: Agent, nodeId: string | null): JumpView;
+    /**
+     * Position a named branch at a historical node for the next append.
+     * @param agent - owning live agent.
+     * @param nodeId - historical node to branch from.
+     * @param branch - non-empty branch label.
+     * @returns the parked cursor, branch label, and direct-child fork count.
+     */
+    fork(agent: Agent, nodeId: string, branch: string): {
+        cursor: string;
+        branch: string;
+        forkCount: number;
+    };
+    /**
+     * Read compact status metadata for the current session tree.
+     * @param agent - owning live agent.
+     * @returns current tree counts, cursor, branches, and usage metadata.
+     */
+    session(agent: Agent): SessionTreeSessionInfo;
+}
+export default SessionTreeService;

package/lib/types/invariant.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Package-owned invariant companion for `@robiteame/dsh-pi-agent-session-tree`.
+ * @module @robiteame/dsh-pi-agent-session-tree/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "pi-agent-session-tree-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;

package/lib/types/session-event-adapter.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Pure projection between Harness SessionEvent logs and SessionTree nodes.
+ * This module does not subscribe to a live Session or persistence service: the
+ * host integration can feed it immutable `session.events` snapshots, while
+ * preserving the Session log as the durable source of truth.
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types';
+import type { TreeNode } from './types.ts';
+/**
+ * Compact result payload of one `tool/result` event: the call correlation,
+ * the flattened result text, and the failure identity when the call errored.
+ */
+export interface ProjectedToolResult {
+    callId: string;
+    text: string;
+    isError: boolean;
+    error?: string;
+}
+/** Extract the call correlation and outcome of one `tool/result` event. */
+export declare function toolResultOf(event: SessionEvent): ProjectedToolResult | undefined;
+/**
+ * Fold one projected tool result into its tool-call node so the call and its
+ * result read as a single tree entry (matching the model-visible pair). The
+ * function is pure and idempotent: an already-merged node is returned as-is.
+ */
+export declare function attachToolResult(node: TreeNode, result: ProjectedToolResult, resultEventSeq: number | undefined): TreeNode;
+/** Project the message-producing Harness events into an append-only tree. */
+export declare function sessionEventsToTreeNodes(events: readonly SessionEvent[], initialParentId?: string | null): TreeNode[];

package/lib/types/session-tree-marker.d.ts

@@ -0,0 +1,13 @@
+/** Marker carried by official surface events written by stock-mode tree jumps. */
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types';
+export interface SessionTreeRestoreMarker {
+    readonly kind: 'cursor';
+    readonly nodeId: string | null;
+}
+/**
+ * Read the plugin marker from an event's JSON data. Native Harness events
+ * never carry this key, so its presence is unambiguous.
+ */
+export declare function sessionTreeMarkerOf(event: SessionEvent): SessionTreeRestoreMarker | undefined;
+/** Whether one event is a synthetic cursor rewrite rather than conversation content. */
+export declare function isSessionTreeRestoreEvent(event: SessionEvent): boolean;

package/lib/types/session-tree-sidecar.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Plugin-owned durable sidecar for SessionTree projections.
+ *
+ * The stock DeepSeek-Harness session log does not recognize `session-tree/*`
+ * events, so branch names, cursor, selection, and explicit snapshot state
+ * cannot live inside `session.jsonl.zstd` without patching the harness. This
+ * module keeps one small JSON artifact per session under the DSH home instead
+ * and replays only native events after the stored watermark on resume.
+ */
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import { SessionTree } from './session-tree.ts';
+/** Synchronous sidecar store used by host-only session-tree plugins. */
+export declare class SessionTreeSidecar {
+    readonly root: string;
+    constructor(root?: string);
+    /** Read and validate the latest snapshot for one session. */
+    load(sessionId: SessionId): SessionTree | undefined;
+    /**
+     * Atomically persist one tree. I/O errors are deliberately contained:
+     * the native Session log remains the source of truth and can rebuild a
+     * linear projection even when the sidecar directory is unavailable.
+     */
+    save(sessionId: SessionId, tree: SessionTree): boolean;
+}
+export declare function getSessionTreeSidecar(): SessionTreeSidecar;
+/** Replace the active sidecar, primarily for isolated tests. */
+export declare function setSessionTreeSidecar(sidecar: SessionTreeSidecar): void;
+/** Persist one tree without coupling callers to the active store selection. */
+export declare function persistSessionTree(tree: SessionTree): boolean;

package/lib/types/session-tree.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Append-only multi-branch session tree. One tree owns one sessionId; the
+ * store holds many trees side by side. All mutations are additions: a node
+ * is never edited or removed after creation, and navigation only moves the
+ * cursor, so every history branch survives (PI-Agent SessionTree semantics:
+ * append-only entries, leaf-pointer branching, root-to-leaf message paths).
+ *
+ * @module @robiteame/dsh-pi-agent-session-tree/session-tree
+ */
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { BranchView, JsonValue, JumpView, ContentPart, LlmMessage, SessionTreeSessionInfo, SessionTreeSnapshot, SessionTreeView, TreeEntryType, TreeNode, SessionTreeLogEntry, TreeResult } from './types.ts';
+/** One stored node plus the internal cursor bookkeeping. */
+export declare class SessionTree {
+    readonly sessionId: SessionId;
+    private readonly nodesById;
+    private cursorId;
+    private selectedNodeId;
+    private activeBranchName;
+    private readonly branchHeads;
+    private syncedSessionEventSeq;
+    /**
+     * Create an empty tree, or restore one from a versioned snapshot.
+     * @param sessionId - owning session identity.
+     * @param snapshot - optional durable snapshot to restore.
+     * @throws Error when the snapshot is malformed (version, ownership, cursor).
+     */
+    constructor(sessionId: SessionId, snapshot?: unknown);
+    /** Mint a node id guaranteed absent from this tree (collision-safe). */
+    private mintNodeId;
+    /** @returns the current cursor node id, or null before the first append. */
+    get cursor(): string | null;
+    /** Explicit node bound to context-aware UI commands. */
+    get selectedNode(): string | null;
+    /** Bind /fork and /clone to an existing node without changing cursor semantics. */
+    select(nodeId: string): TreeResult<{
+        nodeId: string;
+    }>;
+    /** @returns the branch label the next append joins. */
+    get activeBranch(): string;
+    /**
+     * Append one new node as a child of the cursor. The cursor's parent chain
+     * is never touched; the new node joins the active branch unless one is
+     * named. Historical nodes stay byte-identical.
+     * @param message - standard LLM message to carry.
+     * @param options - optional branch override, summary, and JSON extras.
+     * @returns the created node, or a standard error for invalid input.
+     */
+    /** Capture mutable projection state so an external durable write can commit atomically. */
+    checkpoint(): SessionTreeSnapshot;
+    /** Roll back to a previously captured checkpoint after a durable append fails. */
+    rollback(snapshot: SessionTreeSnapshot): TreeResult<void>;
+    append(message: LlmMessage, options?: {
+        branch?: string;
+        summary?: string;
+        content?: readonly ContentPart[];
+        model?: string;
+        usage?: Record<string, JsonValue>;
+        cost?: number;
+        error?: string;
+        metadata?: Record<string, JsonValue>;
+    }): TreeResult<TreeNode>;
+    /**
+     * Move the cursor to an existing node (root-to-node path replay). Old
+     * branches remain intact; the next append forks from the target.
+     * @param target - target node id, or null to reset before any node.
+     * @returns the new cursor and the reconstructed root-to-cursor messages.
+     */
+    jump(target: string | null): TreeResult<JumpView>;
+    /**
+     * Fork the active cursor from a historical node. This is the Pi `/fork`
+     * primitive: old nodes remain intact and the next tree append becomes a child.
+     * The owning service selects the matching Harness model surface path.
+     */
+    fork(target: string, branch?: string): TreeResult<{
+        cursor: string;
+        branch: string;
+        forkCount: number;
+    }>;
+    /**
+     * Set the branch label the next append joins and park the cursor at the
+     * chosen node, without appending anything.
+     * @param target - node to branch from (must exist).
+     * @param branch - new branch label (non-empty).
+     * @returns the new cursor and branch.
+     */
+    branch(target: string, branch: string): TreeResult<{
+        cursor: string;
+        branch: string;
+    }>;
+    /**
+     * Branch with a summary of the abandoned path: park the cursor at `target`
+     * (like {@link branch}), then append a summary node whose parent is the
+     * target. The abandoned branch's nodes stay untouched.
+     * @param target - node to branch from.
+     * @param summary - summary text stored on the new node.
+     * @returns the created summary node.
+     */
+    branchWithSummary(target: string, summary: string): TreeResult<TreeNode>;
+    /**
+     * Reconstruct the standard LLM messages array for the path root→node
+     * (defaults to the cursor). System/user/assistant/tool messages keep their
+     * roles; branch-summary nodes carry no message and stay out of the array.
+     * @param from - target node id, or null for the empty path.
+     * @returns messages in conversation order (root first).
+     */
+    messages(from?: string | null): LlmMessage[];
+    /**
+     * @returns all nodes in creation order (defensive copies).
+     */
+    log(fromSeq?: number): SessionTreeLogEntry[];
+    replay(records: readonly SessionTreeLogEntry[]): TreeResult<{
+        applied: number;
+    }>;
+    list(): TreeNode[];
+    /**
+     * @returns named branch pointers and their reachable nodes. Branch identity
+     * comes from the session-level head map; node.branch is display metadata only.
+     */
+    branches(): BranchView[];
+    /** Return a compact Pi-style session status projection. */
+    info(): SessionTreeSessionInfo;
+    /** @returns the full read view served to the browser panel. */
+    view(): SessionTreeView;
+    /** @returns a versioned durable snapshot (defensive copy). */
+    snapshot(): SessionTreeSnapshot;
+    /** Return the current leaf's root-to-leaf node path. */
+    currentPath(from?: string | null): TreeNode[];
+    /** Return the greatest native Session event seq already projected into this tree. */
+    lastSessionEventSeq(): number;
+    /** Advance the native Session event watermark after a successful sync/write. */
+    markSessionEventSeq(seq: number): void;
+    /** Rewind the watermark when a persisted native tail is shorter than the sidecar expected. */
+    limitSessionEventSeq(seq: number): void;
+    /** @returns true when a node with this id exists. */
+    has(nodeId: string): boolean;
+    /**
+     * Find the dedicated tool-call node carrying this call id. Assistant
+     * message nodes may echo the same tool-call block in their content, but a
+     * tool result must never fold into them: only `type === 'tool_call'` nodes
+     * represent the interaction entry the panel renders.
+     */
+    findToolCallNode(callId: string): TreeNode | undefined;
+    /**
+     * Replace a projected tool-call node with its result-merged form, so one
+     * call and its result stay one tree entry even when the result arrives in a
+     * later sync batch than the call. The tree is a deterministic projection of
+     * the durable Session log, so this derived update never rewrites history in
+     * the log itself and replays identically from scratch.
+     */
+    attachToolResult(callId: string, merged: TreeNode): TreeResult<TreeNode>;
+    /** @returns direct child ids, used to expose the derived fork count. */
+    private directChildren;
+    private messagesFrom;
+}
+/** Keyed store: many independent trees coexist, one per session. */
+export declare class SessionTreeStore {
+    private readonly trees;
+    /** Look up a tree without creating one. */
+    get(sessionId: SessionId): SessionTree | undefined;
+    /** Look up a tree, or return the standard SESSION_NOT_FOUND error. */
+    require(sessionId: SessionId): TreeResult<SessionTree>;
+    /** Create a new tree session. Existing ids are never silently reset. */
+    create(sessionId: SessionId): SessionTree;
+    /** Clone the active branch into an independent session with fresh node ids. */
+    clone(sourceSessionId: SessionId, targetSessionId: SessionId): TreeResult<{
+        sessionId: string;
+    }>;
+    /** Replace one session's tree from a previously validated candidate. */
+    replace(sessionId: SessionId, tree: SessionTree): void;
+    /** Replace one session's tree from a snapshot. */
+    load(snapshot: SessionTreeSnapshot): TreeResult<{
+        sessionId: string;
+    }>;
+    /** @returns all session ids with a live tree, in creation order. */
+    list(): string[];
+}
+export type { BranchView, ContentPart, JumpView, LlmMessage, SessionTreeLogEntry, SessionTreeSessionInfo, SessionTreeSnapshot, SessionTreeView, TreeEntryType, TreeNode, TreeResult };
+/**
+ * Process-wide store shared by the domain service and the tool/command
+ * companion, so model appends and browser jumps read the same trees.
+ */
+export declare const sessionTreeStore: SessionTreeStore;