@askdkc/dsh-cli 0.11.3

package/lib/types/dsh-adapter/scenes.js

@@ -0,0 +1,223 @@
+/** Provider-neutral full-screen scene registry for terminal front doors. */
+import { Service } from '@deepseek-ai/cordis';
+import { activationFiber, bindCallerEffect, compositionRoot, concreteService, requirePluginCaller } from './host-access.js';
+import { componentIdentityOf } from './component-identity.js';
+import { assertCapabilityShadowPolicy, } from '../adapter/kernel/runtime.js';
+import { adapterRuntimeFor } from '../adapter/kernel/runtime-context.js';
+export const name = 'dsh-tui-scenes';
+/**
+ * Small host-only registry; command execution remains owned by dsh-commands.
+ *
+ * A plugin registers a scene once (`ctx.tuiScenes.register(...)`, keep the
+ * dispose) and opens it from anywhere host-side — typically its own
+ * dsh-commands handler: `ctx.tuiScenes.open('my-scene')` plus a silent
+ * `success` result, so the conversation stays untouched while the scene
+ * takes the whole terminal the way the trajectory scene does.
+ */
+export class TuiSceneRuntime extends Service {
+    constructor(ctx) {
+        super(ctx, 'tuiScenes');
+        compositionRoot(ctx);
+        const runtime = this;
+        const state = {
+            scenes: new Map(),
+            owners: new Map(),
+            listeners: new Set(),
+            current: undefined,
+            host: undefined,
+            logger: ctx.logger,
+            runtime: adapterRuntimeFor(ctx),
+        };
+        state.host = Object.freeze({
+            get active() {
+                return sceneStateFor(runtime).current;
+            },
+            register(descriptor) {
+                const state = sceneStateFor(runtime);
+                const id = descriptor.id.trim().toLowerCase();
+                if (!/^[a-z][a-z0-9_-]*$/u.test(id))
+                    throw new TypeError(`invalid TUI scene id: ${descriptor.id}`);
+                if (state.scenes.has(id))
+                    throw new Error(`TUI scene "${id}" is already registered`);
+                const normalized = Object.freeze({ ...descriptor, id });
+                state.scenes.set(id, normalized);
+                return () => {
+                    if (state.scenes.get(id) !== normalized)
+                        return;
+                    state.scenes.delete(id);
+                    state.owners.delete(id);
+                    if (state.current === normalized) {
+                        state.current = undefined;
+                        notifyScenes(state);
+                    }
+                };
+            },
+            list() {
+                return [...sceneStateFor(runtime).scenes.values()];
+            },
+            open(id) {
+                return openScene(runtime, id);
+            },
+            close() {
+                closeScene(runtime);
+            },
+            subscribe(listener) {
+                return subscribeScenes(runtime, listener);
+            },
+        });
+        sceneStates.set(this, state);
+    }
+    /**
+     * Register a full-screen scene; returns the dispose function (caller
+     * scopes it with `ctx.effect`). The optional trailing `identity` (the
+     * plugin's own ctx) only feeds the effect ledger's pluginId — omitting it
+     * records `undeclared` (C-060).
+     */
+    register(descriptor, identity) {
+        assertCapabilityShadowPolicy('host.scenes.register', sceneStateFor(this).runtime.mode, sceneStateFor(this).runtime.slices);
+        const state = sceneStateFor(this);
+        const caller = requirePluginCaller(this.ctx, 'tuiScenes.register', this);
+        const activationOwner = activationFiber(caller);
+        if (activationOwner === undefined)
+            throw new Error('dsh-tui: tuiScenes.register requires a live activation');
+        const callerIdentity = componentIdentityOf(caller);
+        const suppliedIdentity = identity === undefined ? callerIdentity : componentIdentityOf(identity);
+        if (identity !== undefined && callerIdentity !== undefined && suppliedIdentity !== callerIdentity) {
+            throw new Error('dsh-tui: tuiScenes.register identity belongs to another activation');
+        }
+        const id = descriptor.id.trim().toLowerCase();
+        if (!/^[a-z][a-z0-9_-]*$/u.test(id))
+            throw new TypeError(`invalid TUI scene id: ${descriptor.id}`);
+        if (state.scenes.has(id)) {
+            caller.get('tuiEffectLedger')?.record({
+                operation: 'create',
+                resource: { kind: 'scene', id },
+                result: 'failed',
+                errorCode: 'DUPLICATE_CONTRIBUTION_ID',
+            }, identity);
+            throw new Error(`TUI scene "${id}" is already registered`);
+        }
+        const normalized = Object.freeze({ ...descriptor, id });
+        state.scenes.set(id, normalized);
+        state.owners.set(id, activationOwner);
+        caller.get('tuiEffectLedger')?.record({ operation: 'create', resource: { kind: 'scene', id }, result: 'applied' }, identity);
+        const dispose = () => {
+            if (state.scenes.get(id) !== normalized)
+                return;
+            state.scenes.delete(id);
+            state.owners.delete(id);
+            caller.get('tuiEffectLedger')?.record({ operation: 'release', resource: { kind: 'scene', id }, result: 'applied' }, identity);
+            // Disposing the open scene must not strand the user on a dead screen.
+            if (state.current === normalized) {
+                state.current = undefined;
+                notifyScenes(state, activationOwner);
+            }
+        };
+        bindCallerEffect(caller, dispose);
+        return dispose;
+    }
+    /**
+     * Swap the conversation for the named scene. Returns false (and warns)
+     * when no plugin registered that id — a mistyped id must fail visibly in
+     * the log, not silently do nothing in the UI.
+     */
+    open(id) {
+        assertCapabilityShadowPolicy('host.scenes.open', sceneStateFor(this).runtime.mode, sceneStateFor(this).runtime.slices);
+        const caller = requirePluginCaller(this.ctx, 'tuiScenes.open', this);
+        const owner = activationFiber(caller);
+        return owner === undefined ? false : openScene(this, id, caller, owner);
+    }
+    close() {
+        assertCapabilityShadowPolicy('host.scenes.close', sceneStateFor(this).runtime.mode, sceneStateFor(this).runtime.slices);
+        const caller = requirePluginCaller(this.ctx, 'tuiScenes.close', this);
+        const owner = activationFiber(caller);
+        if (owner !== undefined)
+            closeScene(this, caller, owner);
+    }
+    /** The scene currently replacing the conversation, if any. */
+    get active() {
+        assertCapabilityShadowPolicy('host.scenes.active', sceneStateFor(this).runtime.mode, sceneStateFor(this).runtime.slices);
+        const caller = requirePluginCaller(this.ctx, 'tuiScenes.active', this);
+        const owner = activationFiber(caller);
+        const state = sceneStateFor(this);
+        return owner !== undefined && state.current !== undefined && state.owners.get(state.current.id) === owner
+            ? state.current
+            : undefined;
+    }
+    /** UI-side change feed: fired after every open/close/dispose transition. */
+    subscribe(listener) {
+        assertCapabilityShadowPolicy('host.scenes.subscribe', sceneStateFor(this).runtime.mode, sceneStateFor(this).runtime.slices);
+        const caller = requirePluginCaller(this.ctx, 'tuiScenes.subscribe', this);
+        const owner = activationFiber(caller);
+        if (owner === undefined)
+            return () => { };
+        const dispose = subscribeScenes(this, listener, owner);
+        bindCallerEffect(caller, dispose);
+        return dispose;
+    }
+}
+const sceneStates = new WeakMap();
+function sceneStateFor(runtime) {
+    const state = sceneStates.get(concreteService(runtime));
+    if (state === undefined)
+        throw new Error('tuiScenes host state is unavailable');
+    return state;
+}
+function openScene(runtime, id, caller, owner) {
+    const state = sceneStateFor(runtime);
+    const scene = state.scenes.get(id.trim().toLowerCase());
+    if (scene === undefined) {
+        ;
+        (caller?.logger ?? state.logger).warn(`dsh-tui: no TUI scene registered as "${id}"`);
+        return false;
+    }
+    if (owner !== undefined && state.owners.get(scene.id) !== owner) {
+        caller?.logger.warn(`dsh-tui: scene "${scene.id}" belongs to another activation`);
+        return false;
+    }
+    if (scene === state.current)
+        return true;
+    const previousOwner = state.current === undefined ? undefined : state.owners.get(state.current.id);
+    state.current = scene;
+    notifyScenes(state, previousOwner);
+    return true;
+}
+function closeScene(runtime, caller, owner) {
+    const state = sceneStateFor(runtime);
+    if (state.current === undefined)
+        return;
+    if (owner !== undefined && state.owners.get(state.current.id) !== owner) {
+        caller?.logger.warn(`dsh-tui: scene "${state.current.id}" belongs to another activation`);
+        return;
+    }
+    const previousOwner = state.owners.get(state.current.id);
+    state.current = undefined;
+    notifyScenes(state, previousOwner);
+}
+function subscribeScenes(runtime, listener, owner) {
+    const state = sceneStateFor(runtime);
+    const entry = { owner, listener };
+    state.listeners.add(entry);
+    return () => {
+        state.listeners.delete(entry);
+    };
+}
+function notifyScenes(state, previousOwner) {
+    const currentOwner = state.current === undefined ? undefined : state.owners.get(state.current.id);
+    for (const entry of state.listeners) {
+        if (entry.owner !== undefined && entry.owner !== currentOwner && entry.owner !== previousOwner)
+            continue;
+        entry.listener();
+    }
+}
+export function getHostSceneRuntime(runtime) {
+    if (runtime === undefined)
+        return undefined;
+    try {
+        return sceneStateFor(runtime).host ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export default TuiSceneRuntime;

package/lib/types/dsh-adapter/session-mount-heartbeat.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Publishes this TUI process's mounted-session set to the cross-process
+ * ledger ({@link ../../sessionMounts.js}).
+ *
+ * A TUI terminal hosts several agent sessions at once — the attached one plus
+ * every parked background session — and two processes driving the same
+ * session log would interleave writes into one append-only transcript. The
+ * ledger is what lets another TUI see "this session is already mounted" and
+ * refuse it, so the published set has to cover EVERY live agent in this
+ * process, not just the attached one.
+ *
+ * Reading the agent registry is what makes that automatic, and the small timer
+ * is what keeps it honest: agents are created from more than seven paths
+ * (`/new`, `/resume`, `/bg`, fork, rewind, model switch, boot attach), so an
+ * announce-at-each-call-site design would silently drop a session the day
+ * someone adds an eighth. Deriving the set from the registry has exactly one
+ * place to be right.
+ *
+ * Publishing is NOT a liveness witness: {@link ../../sessionMounts.js} decides
+ * liveness from the owner's pid alone, so a late or missed publish cannot keep
+ * a dead process's claim alive and there is no timestamp here to expire. The
+ * timer's only job is to keep the published SET current, and it is deliberately
+ * unref'd: it must never be the reason a quitting TUI stays alive. Teardown
+ * removes the record outright so a clean exit frees its sessions immediately.
+ *
+ * Registered through the host's single teardown funnel by the caller, so both
+ * the interval and the ledger record are released exactly once.
+ *
+ * @module
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/**
+ * Collect the session ids this process currently has mounted: every live agent
+ * the registry knows about, minus sub-agent runs.
+ *
+ * Sub-agents are excluded because they are not independently mountable: they
+ * are a parent session's own work, they never appear as `/resume` rows, and
+ * claiming their ids would make the parent look occupied to a TUI that only
+ * wants to read the parent.
+ * @param ctx - The plugin context, for the agent registry.
+ * @returns Session ids as strings.
+ */
+export declare function mountedSessionIds(ctx: Context): string[];
+/**
+ * Start publishing this process's mounted sessions.
+ *
+ * The first publish runs synchronously so a session mounted during boot is
+ * claimed before the user can reach a second terminal.
+ * @param ctx - The plugin context, for the agent registry.
+ * @returns A disposer that stops publishing and releases the claim.
+ */
+export declare function startSessionMountHeartbeat(ctx: Context): () => void;
+//# sourceMappingURL=session-mount-heartbeat.d.ts.map

package/lib/types/dsh-adapter/session-mount-heartbeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-mount-heartbeat.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/session-mount-heartbeat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAelD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,EAAE,CASxD;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,IAAI,CA6BnE"}

package/lib/types/dsh-adapter/session-mount-heartbeat.js

@@ -0,0 +1,100 @@
+/**
+ * Publishes this TUI process's mounted-session set to the cross-process
+ * ledger ({@link ../../sessionMounts.js}).
+ *
+ * A TUI terminal hosts several agent sessions at once — the attached one plus
+ * every parked background session — and two processes driving the same
+ * session log would interleave writes into one append-only transcript. The
+ * ledger is what lets another TUI see "this session is already mounted" and
+ * refuse it, so the published set has to cover EVERY live agent in this
+ * process, not just the attached one.
+ *
+ * Reading the agent registry is what makes that automatic, and the small timer
+ * is what keeps it honest: agents are created from more than seven paths
+ * (`/new`, `/resume`, `/bg`, fork, rewind, model switch, boot attach), so an
+ * announce-at-each-call-site design would silently drop a session the day
+ * someone adds an eighth. Deriving the set from the registry has exactly one
+ * place to be right.
+ *
+ * Publishing is NOT a liveness witness: {@link ../../sessionMounts.js} decides
+ * liveness from the owner's pid alone, so a late or missed publish cannot keep
+ * a dead process's claim alive and there is no timestamp here to expire. The
+ * timer's only job is to keep the published SET current, and it is deliberately
+ * unref'd: it must never be the reason a quitting TUI stays alive. Teardown
+ * removes the record outright so a clean exit frees its sessions immediately.
+ *
+ * Registered through the host's single teardown funnel by the caller, so both
+ * the interval and the ledger record are released exactly once.
+ *
+ * @module
+ */
+import { clearOwnMounts, publishMounts } from '../sessionMounts.js';
+/**
+ * How often the mounted set is republished. One small file write, not tied to
+ * any render frame; it bounds how long a peer can read a set that predates a
+ * session this process just mounted.
+ */
+const PUBLISH_INTERVAL_MS = 15_000;
+/**
+ * Collect the session ids this process currently has mounted: every live agent
+ * the registry knows about, minus sub-agent runs.
+ *
+ * Sub-agents are excluded because they are not independently mountable: they
+ * are a parent session's own work, they never appear as `/resume` rows, and
+ * claiming their ids would make the parent look occupied to a TUI that only
+ * wants to read the parent.
+ * @param ctx - The plugin context, for the agent registry.
+ * @returns Session ids as strings.
+ */
+export function mountedSessionIds(ctx) {
+    const roster = ctx.get('agents');
+    const ids = [];
+    for (const agent of roster?.list?.() ?? []) {
+        if (agent.session.header.origin === 'subagent')
+            continue;
+        const id = String(agent.id);
+        if (id.length > 0)
+            ids.push(id);
+    }
+    return ids;
+}
+/**
+ * Start publishing this process's mounted sessions.
+ *
+ * The first publish runs synchronously so a session mounted during boot is
+ * claimed before the user can reach a second terminal.
+ * @param ctx - The plugin context, for the agent registry.
+ * @returns A disposer that stops publishing and releases the claim.
+ */
+export function startSessionMountHeartbeat(ctx) {
+    let stopped = false;
+    const beat = () => {
+        if (stopped)
+            return;
+        try {
+            publishMounts(mountedSessionIds(ctx));
+        }
+        catch {
+            // PUBLISHING is best-effort; DECIDING is not. A beat that cannot write
+            // costs announcement until the next one, and must not disturb this
+            // session — while the paths that grant a mount refuse outright when they
+            // cannot read the ledger, because that is the one error nothing can
+            // repair afterwards.
+        }
+    };
+    beat();
+    const timer = setInterval(beat, PUBLISH_INTERVAL_MS);
+    // Never let the publisher hold the process open: quitting the TUI must not
+    // wait for a timer that exists only to describe a process that is leaving.
+    timer.unref?.();
+    return () => {
+        stopped = true;
+        clearInterval(timer);
+        try {
+            clearOwnMounts();
+        }
+        catch {
+            // A leftover record is ignored once this pid is gone.
+        }
+    };
+}

package/lib/types/dsh-adapter/sessionTree.d.ts

@@ -0,0 +1,232 @@
+import type { SessionTreeData, TreeNode, TreeEntry } from '../adapter/ports/channel-session.js';
+export type { SessionTreeData, TreeNode, TreeEntry, TreeEntryKind, SessionTreeMeta, SessionRewindFacts, TurnRange } from '../adapter/ports/channel-session.js';
+/**
+ * Session family tree — the model behind the /tree screen
+ * (pi's Session Tree ported to DSH's cross-session fork model).
+ *
+ * DSH sessions are linear event logs; a rewind forks a NEW session whose
+ * header records `parentSession` + `seedLength` (the inherited prefix). The
+ * tree stitches the whole family back together: each session contributes its
+ * OWN entries (events at seq >= seedLength when the parent is known), a fork
+ * attaches at the parent's last entry with seq <= seedLength-1, and the
+ * parent's own tail past that point is the abandoned "main" branch.
+ *
+ * Pure module: no Ink, no channel state — channel.ts gathers the logs, this
+ * file shapes them. Rendering lives in screens/SessionTree.tsx.
+ *
+ * @module dsh-cli/sessionTree
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+/** Filter modes cycled in the tree screen (pi parity, minus labels). */
+export type TreeFilter = 'default' | 'no-tools' | 'user-only' | 'all';
+export declare const TREE_FILTERS: readonly TreeFilter[];
+/** One family member's log, as channel.buildSessionTree gathered it. */
+export interface FamilySession {
+    readonly id: string;
+    readonly createdAt: number;
+    readonly parentSession?: string;
+    readonly seedLength?: number;
+    /** This log's events (inherited seed prefix + own events), in log order.
+     *  A coverage-skipped read starts at the first seq no ancestor displays —
+     *  possibly mid-log — with only rare session/title events below the
+     *  cutoff. Never trust events[0].seq === 0. */
+    readonly events: readonly SessionEvent[];
+    /** True for the live session (events from memory, not persistence). */
+    readonly live: boolean;
+    /** True when the log could not be read — structure-only node, no entries. */
+    readonly unreadable?: boolean;
+    /** True when the log was never read because the tree's event/scan budget
+     *  was already spent — structure-only placeholder, distinct from
+     *  unreadable (the log is fine; the browse budget is not). */
+    readonly unloaded?: boolean;
+    /** True when `events` reaches the log's tip. Live memory logs always
+     *  qualify (the tail window trims the HEAD only); bounded reads of dead
+     *  branches slice the tail off when the event budget runs out. The
+     *  branch-adopt target (tipBoundary) and the drop-turn confirm warning are
+     *  only safe to derive when this holds — otherwise the unseen tail could
+     *  hold content the UX claims does not exist. */
+    readonly tailComplete?: boolean;
+}
+/** What dropping a user-message pick's turn removes (the confirm warning). */
+export interface DropTurnInfo {
+    /** Own entries of the session inside the dropped turn. */
+    readonly droppedEntries: number;
+    /** Every own entry of the session sits inside the dropped turn, and the
+     *  loaded log reaches the tip — so the fork will show NONE of this
+     *  branch's own content. (The user's "click the branch message → lose the
+     *  whole branch" trap: a branch whose own content is one turn.) */
+    readonly coversBranch: boolean;
+}
+/**
+ * Confirm-time preview for a USER-message pick: how much of its branch the
+ * drop removes. Undefined for non-user entries (they keep through their
+ * step) and whenever the turn cannot be located in the loaded events.
+ */
+export declare function droppedTurnInfo(data: SessionTreeData, entry: TreeEntry): DropTurnInfo | undefined;
+/** One flattened, render-ready row with its tree-drawing geometry. */
+export interface FlatNode {
+    readonly node: TreeNode;
+    /** Tree-parent node id (null for roots) — cursor preservation walks this.
+     *  Set by flattenTree and NEVER rewritten by filterTree (rows are shared
+     *  across filter passes; a rewritten hop would skip ancestors). */
+    readonly parentId: string | null;
+    /** Indentation level (each level = 3 chars), pi's rules. */
+    indent: number;
+    /** Whether to draw a connector (├─/└─) — parent has multiple children. */
+    showConnector: boolean;
+    /** Under a connector: true = last sibling (└─). */
+    isLast: boolean;
+    /** Ancestor branch points: position (indent level) + whether │ continues. */
+    gutters: readonly GutterInfo[];
+    /** Root under a virtual branching root (multiple roots). */
+    isVirtualRootChild: boolean;
+    /** True when this pass produced multiple roots (screen shifts display). */
+    multipleRoots: boolean;
+}
+export interface GutterInfo {
+    position: number;
+    show: boolean;
+}
+/**
+ * Coalesce runs of same-type assistant/chunk deltas into single synthetic
+ * events for REPLAY only. A streamed pre-V3 turn logs one event per token
+ * (~100k events in long sessions); replaying them one at a time costs
+ * per-chunk string growth on every row (quadratic in the turn's length).
+ * Merging is outcome-identical: ensureStreaming/ensureReasoning only read
+ * chunk.type and the concatenated text, and the row's seq comes from the
+ * run's FIRST chunk (the fork boundary rewindToNode derives from it). Parts
+ * join once — no quadratic concat. Live events never go through this.
+ *
+ * Pre-V3 durable logs only: 0.1.5 removed `assistant/chunk` from the event
+ * union (V3 embeds the compacted stream in `assistant/message.stream`), so
+ * the merger works on the widened structural shape — runtime payloads from
+ * raw pre-V3 logs remain typed as SessionEvent by the reader.
+ *
+ * (Moved from channel.ts: the transcript replay and the tree extraction
+ * share it.)
+ */
+export declare function coalesceReplayEvents(events: readonly SessionEvent[]): SessionEvent[];
+/**
+ * Fork boundary for rewinding to the entry at `seq`: the seq just before its
+ * enclosing turn/start (DSH logs `turn/start → user/message → … → turn/end`,
+ * so a message's own seq sits inside an open turn and fork would reject it).
+ * This is the DROP-THE-TURN boundary — used for user messages (the turn is
+ * dropped, its prompt returns to the input) and as the fallback for entries
+ * of a still-open turn. Falls back to `seq` itself when no enclosing
+ * turn/start exists (bookkeeping between turns).
+ */
+export declare function turnBoundary(events: readonly SessionEvent[], seq: number): number;
+/** Where rewinding to a tree entry lands — see rewindTarget. */
+export interface RewindTarget {
+    /** Inclusive seed boundary (a seq into the FULL contiguous log). */
+    readonly boundary: number;
+    /**
+     * Set when the boundary cuts a turn in the middle: the fork must append a
+     * synthetic turn/end for this turn number (the exact shape a real user
+     * cancellation writes). Undefined when the seed already ends turn-closed.
+     */
+    readonly closeTurn?: number;
+}
+/**
+ * Rewind target for a tree entry — pi's navigateTree semantics mapped onto
+ * DSH's turn-closed fork constraint (the seed must not end inside an open
+ * turn). Callers must pass the FULL session log (seq === array index).
+ *
+ *  - user message → DROP its turn: the seq just before the enclosing
+ *    turn/start (turnBoundary); the turn's prompt returns to the input for
+ *    re-editing. -1 when that turn is the log's own first turn.
+ *  - any other entry inside a CLOSED turn (assistant/tool/notice/interrupt)
+ *    → KEEP through the entry's enclosing STEP: the boundary is that step's
+ *    step/end, with closeTurn set. DSH agentic turns are marathons (one
+ *    prompt → N steps → thousands of events), so turn-granular keeping is
+ *    useless mid-turn — picking a bash call of step 2 in a 6-step turn must
+ *    not retain steps 3-6. The step is the finest SAFE cut: a step closes
+ *    with every tool call answered, so the replayed context never dangles a
+ *    tool_call the API would reject. When no step/end follows the entry
+ *    inside its turn (no-step turns, or the entry sits past the last step),
+ *    the boundary is the turn/end as before (no closeTurn).
+ *  - entry between turns (a compact checkpoint) → its own seq.
+ *  - entry inside the still-OPEN last turn → a closed step ahead of it is
+ *    still a valid mid-turn cut (closeTurn set; the open tail drops); with no
+ *    step/end ahead the turn cannot be kept at all, so it falls back to
+ *    dropping the turn (turnBoundary) and restoring its prompt.
+ */
+export declare function rewindTarget(events: readonly SessionEvent[], seq: number): RewindTarget;
+/**
+ * Fork target for a tree entry — pi's `/fork` semantics: the picked entry is
+ * KEPT (a fork branches the conversation; it does not re-edit the past).
+ *
+ *  - user message → keep THROUGH the message itself: the boundary is the
+ *    entry's own seq and the turn's reply drops. The cut ends inside the
+ *    still-open turn, so closeTurn carries the enclosing turn's number for
+ *    the synthetic turn/end (the same shape a real interrupt writes). A
+ *    between-turns plugin message (a compact checkpoint) is already
+ *    turn-closed — no closer.
+ *  - any other entry → identical to rewindTarget (keep through the
+ *    entry's enclosing step / turn end).
+ *
+ * Unlike a rewind pick, a turn-0 user message forks fine (boundary = its own
+ * seq, never -1), and nothing returns to the input for re-editing.
+ */
+export declare function forkTarget(events: readonly SessionEvent[], seq: number): RewindTarget;
+/**
+ * Tail window of an over-budget LIVE session's events, aligned to whole
+ * turns. Recent turns are the likely rewind targets, so the budget keeps
+ * the tail — but a slice can open mid-turn, and entries of a partial turn
+ * make broken rows: when that partial turn is the log's OWN first turn its
+ * rewind boundary is -1 ("cannot rewind to the very first message"), yet
+ * the slice hides the turn/start@0 that firstTurn marking keys on — the
+ * row would confirm and then fail inside rewindToNode. So: align to the
+ * first whole turn inside the window. When the window holds no turn/start
+ * at all, the log's LAST turn alone overflows the budget — retry over the
+ * log before that turn: its earlier complete turns are perfectly good
+ * rewind targets and must not vanish behind one giant turn. Only when the
+ * oversized turn IS the log's own first turn does the window drop to empty
+ * — no complete turn in view means no safe rewind target to show. Entries
+ * dropped here stay rewindable through the real session; the slice only
+ * narrows what the tree displays.
+ */
+export declare function liveTailWindow(events: readonly SessionEvent[], remaining: number): readonly SessionEvent[];
+/** The turn's first human-typed text (the prompt rewind restores for editing). */
+export declare function turnUserText(events: readonly SessionEvent[], seq: number): string;
+/**
+ * One session's displayable entries, in seq order. Mirrors renderEvent's
+ * choices (channel.ts): human user messages only, compaction checkpoints as
+ * compact rows, assistant text (chunk-only text from aborted turns kept with
+ * an `aborted` label), tool cards minus ask_user_question, interrupts and
+ * failed turns. Bookkeeping events (turn/step markers, titles, requests,
+ * `session/end-seed`, activity frames…) never become entries.
+ */
+export declare function extractEntries(sessionId: string, events: readonly SessionEvent[]): TreeEntry[];
+/**
+ * Assemble the family tree. Roots are sessions with no parentSession (or a
+ * parent missing from the family — a deleted log; the orphan's self-contained
+ * prefix keeps its history whole). Fork chains attach at the last entry with
+ * seq <= seedLength-1, walking UP the ancestor chain when the direct parent
+ * no longer displays that entry (seed-prefix trimming — the fork point lives
+ * in the shared prefix an ancestor shows); the anchored session's own tail
+ * past the anchor stays the first (main) branch. Sessions with no own
+ * entries get one placeholder node so the fork structure stays visible.
+ */
+export declare function buildSessionTree(sessions: readonly FamilySession[], liveSessionId: string, truncated?: boolean): SessionTreeData;
+/**
+ * Flatten the tree into render rows, pi-style: the subtree containing the
+ * active leaf sorts first at every branch point; single-child chains keep
+ * their indent, branch points indent +1 (plus the first generation after a
+ * branch); gutters record where ancestor │ lines continue.
+ */
+export declare function flattenTree(roots: readonly TreeNode[], activeLeafId: string | null): FlatNode[];
+/**
+ * Filter + search the flattened tree, then recompute the tree drawing over
+ * the visible rows (each visible node re-hangs under its nearest visible
+ * ancestor, so hidden intermediates don't drift the indent). The active leaf
+ * always survives filtering (pi keeps the current position visible).
+ */
+export declare function filterTree(flat: readonly FlatNode[], activeLeafId: string | null, filter: TreeFilter, query: string): FlatNode[];
+/**
+ * Index of `targetId` in `visible`, walking the FULL list's parent chain when
+ * the exact node was filtered out; falls back to the last visible row
+ * (pi's findNearestVisibleIndex).
+ */
+export declare function nearestVisibleIndex(visible: readonly FlatNode[], full: readonly FlatNode[], targetId: string | null): number;
+//# sourceMappingURL=sessionTree.d.ts.map

package/lib/types/dsh-adapter/sessionTree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionTree.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/sessionTree.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,SAAS,EAAiE,MAAM,qCAAqC,CAAA;AAC9J,YAAY,EAAE,eAAe,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,EAAE,eAAe,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAA;AAC9J;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAG5D,wEAAwE;AACxE,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,KAAK,CAAA;AACrE,eAAO,MAAM,YAAY,EAAE,SAAS,UAAU,EAAgD,CAAA;AAE9F,wEAAwE;AACxE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B;;;mDAG+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAA;IACxC,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAA;IAC7B;;kEAE8D;IAC9D,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAC3B;;;;;qDAKiD;IACjD,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAChC;AAED,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B;;;uEAGmE;IACnE,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;CAC/B;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,SAAS,GAAG,YAAY,GAAG,SAAS,CAUjG;AAED,sEAAsE;AACtE,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB;;uEAEmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAA;IACd,0EAA0E;IAC1E,aAAa,EAAE,OAAO,CAAA;IACtB,mDAAmD;IACnD,MAAM,EAAE,OAAO,CAAA;IACf,6EAA6E;IAC7E,OAAO,EAAE,SAAS,UAAU,EAAE,CAAA;IAC9B,4DAA4D;IAC5D,kBAAkB,EAAE,OAAO,CAAA;IAC3B,2EAA2E;IAC3E,aAAa,EAAE,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,OAAO,CAAA;CACd;AA2BD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,YAAY,EAAE,CAoCpF;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAUjF;AAED,gEAAgE;AAChE,MAAM,WAAW,YAAY;IAC3B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,CA0BvF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,CAkBrF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,SAAS,YAAY,EAAE,EAC/B,SAAS,EAAE,MAAM,GAChB,SAAS,YAAY,EAAE,CAyBzB;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAgBjF;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,SAAS,EAAE,CAqK9F;AAcD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,SAAS,aAAa,EAAE,EAClC,aAAa,EAAE,MAAM,EACrB,SAAS,UAAQ,GAChB,eAAe,CAoQjB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,QAAQ,EAAE,CA0F/F;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,SAAS,QAAQ,EAAE,EACzB,YAAY,EAAE,MAAM,GAAG,IAAI,EAC3B,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,MAAM,GACZ,QAAQ,EAAE,CA+FZ;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,SAAS,QAAQ,EAAE,EAC5B,IAAI,EAAE,SAAS,QAAQ,EAAE,EACzB,QAAQ,EAAE,MAAM,GAAG,IAAI,GACtB,MAAM,CAaR"}