@khorsheed/dsh-context-lens 0.0.0-stage → 0.1.0

package/lib/types/store.d.ts

@@ -0,0 +1,424 @@
+import type { BackfillInfo, CapturedRequest, CapturedResponse, ListTurnsResult, SessionTrend, RequestConfig, RequestTiming, RequestUsage, ResponseSummary, ScopeFilter, ScopedRefusal, TurnOverview, TurnTiming } from './types.ts';
+import { type CapturedToolSchema, type ScopeFingerprint, type AssemblyRecord } from './segmenter.ts';
+import { type CapturedMessage } from './messages.ts';
+import type { LogTurn } from './log-lane.ts';
+import { type ReplacementFact } from './changes.ts';
+/** Retention knobs (InspectorConfig in the service mirrors these). */
+export interface StoreConfig {
+    /** Turns retained per session (oldest closed first, backfilled before live). Default 30. */
+    maxTurnsPerSession?: number;
+    /** Log-reconstructed main-scope requests retained per session. Default 500. */
+    maxBackfillRequestsPerSession?: number;
+    /**
+     * Global budget of stored segment text characters across all sessions — the
+     * real memory driver is the segments' `full` text (~200KB per request), not
+     * the row count. Default 150M chars (~150MB).
+     */
+    maxStoredCharsTotal?: number;
+}
+/** One streamed content block's open/closed time span. */
+export interface BlockSpan {
+    kind: string;
+    index: number;
+    start: number;
+    end?: number;
+    /** tool-call blocks: call id, name, and raw arguments (the response hint's source). */
+    callId?: string;
+    toolName?: string;
+    args?: string;
+    /**
+     * text/reasoning content: delta-accumulated while streaming, overwritten by
+     * the authoritative assembled block at block-end. This is what makes a
+     * cancelled mid-block response partially visible.
+     */
+    text?: string;
+}
+/** One tool execution interval attributed to the request that issued the call. */
+export interface ToolExecSpan {
+    callId: string;
+    name: string;
+    start: number;
+    end?: number;
+    isError?: boolean;
+    result?: string;
+}
+/** A request row as the store keeps it — the wire shapes assemble on query. */
+export interface StoredRequest {
+    requestNumber?: number;
+    /** The request's own session turn (log lane): a member child's run is one of these. */
+    hostTurn?: number;
+    seq: number;
+    sessionId: string;
+    scopeId: string;
+    turnSeq: number;
+    purpose?: string;
+    compaction?: CapturedRequest['compaction'];
+    startedAt: number;
+    status: 'streaming' | 'ok' | 'failed';
+    error?: string;
+    config: RequestConfig;
+    usage?: RequestUsage;
+    responseSummary: ResponseSummary;
+    segments: CapturedRequest['segments'];
+    totalChars: number;
+    /** The response's own char weight (counted in the store budget, not in 请求体 totalChars). */
+    responseChars?: number;
+    /** Execution result storage, excluded from request/input metrics. */
+    executionChars?: number;
+    /** The request's own response, set at settle (see CapturedRequest.response). */
+    response?: CapturedResponse;
+    firstChunkAt?: number;
+    settledAt?: number;
+    finishKind?: string;
+    blocks: BlockSpan[];
+    execs: ToolExecSpan[];
+    fingerprint: ScopeFingerprint;
+    /** Live capture preceded availability of its conversation-history baseline. */
+    needsHistoryBaseline?: boolean;
+}
+/** One scope row's internal record (exported via {@link TurnRecord}). */
+export interface ScopeRecord {
+    scopeId: string;
+    /** Per-session 1-based ordinal in scope-creation order (the chip's `#N`). */
+    scopeSeq: number;
+    kind: 'main' | 'subagent';
+    label?: string;
+    status: 'running' | 'ok' | 'failed';
+    error?: string;
+    config: RequestConfig;
+    requests: StoredRequest[];
+    startedAt: number;
+    endedAt?: number;
+    /** Fingerprint of the scope's latest request — the next request's diff baseline. */
+    previous?: ScopeFingerprint;
+    /** True once a live (in-process) request landed; the log lane then stays out. */
+    live: boolean;
+    /** True once the log lane reconstructed requests here; live capture then stays out. */
+    logFilled: boolean;
+    /** The delegation call this scope answers, when bound. */
+    callId?: string;
+    /** The child's `subagent/descriptor` provider (`dsh-cli`, `codex-local`, …), once seen. */
+    provider?: string;
+}
+/** One turn row's internal record (exported for the eviction hook's signature). */
+export interface TurnRecord {
+    /**
+     * The panel-facing address. Real turns key on the host's own turn number
+     * (the `turn/start` payload — a stable per-session ordinal shared with the
+     * log lane, so live-captured and log-reconstructed turns can never
+     * duplicate); purpose pseudo-turns take negative addresses from the
+     * session's bucket counter.
+     */
+    turnSeq: number;
+    /** The host's own turn number; absent on purpose pseudo-turns. */
+    hostTurn?: number;
+    /** Purpose key on pseudo-turns (`compaction`, `session-title`, …). */
+    purpose?: string;
+    /** True once any live (in-process) request or bracket landed here — backfill never merges into such a turn. */
+    liveContent: boolean;
+    /** Capture observed the turn opening, so this turn’s live request order is complete. */
+    liveStartObserved?: boolean;
+    query: string;
+    /** A room round: the dispatch's targets (see room.ts). */
+    room?: {
+        targets: string[];
+    };
+    /** First non-human message of the turn (see LogTurn.trigger). */
+    trigger?: {
+        source: string;
+        text: string;
+    };
+    /** The `turn/start` event's log seq. */
+    startSeq?: number;
+    startedAt: number;
+    endedAt?: number;
+    closingMessageId?: string;
+    scopes: Map<string, ScopeRecord>;
+}
+/** The eviction hook's view of a turn (the log lane drops child cursors on it). */
+export type EvictedTurn = TurnRecord;
+/** Snapshot one request needs at dispatch — the normalized GenerateOptions face. */
+export interface RequestSnapshot {
+    sessionId?: string;
+    purpose?: string;
+    config: RequestConfig;
+    messages: CapturedMessage[];
+    systemSlot?: string;
+    tools?: CapturedToolSchema[];
+}
+/** The clock and the eviction hook are injectable; everything else is internal. */
+export interface StoreDeps {
+    now?: () => number;
+    /** Turn-eviction notice (the log lane closes its per-child handles here). */
+    onTurnEvicted?: (sessionId: string, turn: TurnRecord) => void;
+    /** The instance epoch stamped on query results (restart invalidation); a mount-time id by default. */
+    generation?: string;
+}
+/**
+ * Whether one scope passes a read's allow-list: unfiltered when the filter
+ * carries no `scopes`, otherwise membership. Shared by the store's query
+ * methods and the service's child-log gate.
+ */
+export declare function scopeAuthorized(scopeId: string, filter?: ScopeFilter): boolean;
+/** The in-memory capture store. All mutation enters through the `note*`/`observe*` methods. */
+export declare class InspectorStore {
+    private readonly sessions;
+    private readonly childToParent;
+    /** A session opened on its own that its log header names as a child (`parentSession`). */
+    private readonly parents;
+    /** callId → the request whose response issued the call (exec attribution). */
+    private readonly callOwners;
+    private readonly callNames;
+    /** Recently observed rendered assemblies (system-section attribution). */
+    private readonly assemblies;
+    private readonly now;
+    private readonly onTurnEvicted;
+    private readonly maxTurnsPerSession;
+    private readonly maxBackfillRequestsPerSession;
+    private readonly maxStoredCharsTotal;
+    /** The instance epoch stamped on every query result (restart invalidation). */
+    private readonly generation;
+    private seqCounter;
+    /** Stored segment text characters across all sessions (the memory driver). */
+    private totalChars;
+    constructor(config?: StoreConfig, deps?: StoreDeps);
+    /** The shared assembly ring (service feeds it from the assemble waterfall). */
+    get assemblyRing(): AssemblyRecord[];
+    /** Whether `sessionId` is a known subagent child of some captured session. */
+    isChild(sessionId: string): boolean;
+    /** The root session one request/event belongs to (children resolve up). */
+    private rootOf;
+    private session;
+    /** Allocate one turn row; the caller sets the address (`turnSeq`) in `init`. */
+    private mintTurn;
+    private mainScope;
+    /** Observe durable compression boundaries without manufacturing model calls. */
+    noteCompaction(sessionId: string, type: string, data: Record<string, unknown>): void;
+    /** Preserve pruning metadata across later requests, with bounded observation state. */
+    notePruning(sessionId: string, messageId: string, beforeChars: number, afterChars: number): void;
+    /** Record one host surface replacement (live event or log backfill) for the change list. */
+    noteReplacement(sessionId: string, fact: ReplacementFact): void;
+    /**
+     * Begin one captured request: correlate session/turn/scope, split the
+     * segments against the scope's previous fingerprint, assign the sequence.
+     *
+     * @returns the stored row, or `undefined` when the request carries no
+     *   session identity the capture can place (a host call with no sessionId
+     *   and no purpose is out of the panel's scope).
+     */
+    beginRequest(snapshot: RequestSnapshot, startedAt: number): StoredRequest | undefined;
+    /** Attach a purpose-built (log-lane) request row to an existing child scope. */
+    appendLogRequest(rootSessionId: string, scopeId: string, built: Omit<StoredRequest, 'seq' | 'sessionId' | 'scopeId' | 'turnSeq'>): StoredRequest | undefined;
+    private findScope;
+    /** One stream chunk observed on a live request's tee. */
+    observeChunk(request: StoredRequest, chunk: {
+        type: string;
+        index?: number;
+        blockType?: string;
+        text?: string;
+        argumentsDelta?: string;
+        block?: {
+            type: string;
+            id?: string;
+            name?: string;
+            arguments?: string;
+            text?: string;
+        };
+        usage?: RequestUsage;
+        reason?: {
+            kind: string;
+            failure?: {
+                message: string;
+            };
+        };
+    }, at: number): void;
+    /** Settle one request: ok on a clean finish, failed on an error finish or a raised error. */
+    settleRequest(request: StoredRequest, at: number, thrown?: unknown): void;
+    /** Set the request's response and count its chars into the store budget. */
+    private attachResponse;
+    private accountExecutionResults;
+    /** Incremental child folds mutate shared execution spans after insertion. */
+    refreshExecutionResults(sessionId: string, scopeId: string): void;
+    /** turn/start on a root session (child sessions route their events to the parent instead). */
+    /** @param seq - the `turn/start` event's log seq (the chat's history-jump target). */
+    turnStart(sessionId: string, hostTurn: number, at: number, seq?: number): void;
+    /** turn/end: close the open turn, resolve its main scope, sweep abandoned streams. */
+    turnEnd(sessionId: string, hostTurn: number, reason: {
+        kind: string;
+        error?: {
+            message: string;
+        };
+    }, at: number): void;
+    /** A human message entering the turn — the turn list's query preview. */
+    noteUserMessage(sessionId: string, sourceKind: string, text: string): void;
+    /** The turn's closing assistant message id + generation-time backfill for history rows. */
+    noteAssistantMessage(sessionId: string, messageId: string): void;
+    /** tool/call: open the exec interval (when the issuing request is known) and queue delegation binding. */
+    toolCall(sessionId: string, callId: string, name: string, args: string, at: number): void;
+    /** Source turns belong to session events, not the immutable message payload. */
+    noteMessageTurn(sessionId: string, messageId: string, turn?: number): void;
+    /** tool/result: close the exec interval; resolve a delegation scope's outcome. */
+    toolResult(sessionId: string, callId: string, isError: boolean, result: string, at: number): void;
+    /** subagent/catalog: open the child scope on the current turn and bind the pending call. */
+    subagentCatalog(sessionId: string, childId: string, label: string | undefined, at: number): void;
+    /** Open one child scope on the session's current turn (or latest turn as a fallback). */
+    private openChildScope;
+    /** Every child scope of one session (the log lane iterates these). */
+    childScopes(sessionId: string): {
+        scopeId: string;
+        live: boolean;
+        status: string;
+    }[];
+    /** The session's backfill watermark (retryable until 'complete'). */
+    backfillState(sessionId: string): BackfillInfo['state'];
+    /** A durably unreadable log stops the backfill from retrying it on every query. */
+    markBackfillBroken(sessionId: string, reason: string): void;
+    /**
+     * Insert log-reconstructed turns (the pre-mount history), newest-first within
+     * budget: live-content turns win the budget outright, a host turn with any
+     * record is never merged into (the overlap rule), and one oversized turn is
+     * SKIPPED without aborting the older ones. Scope ordinals are renumbered
+     * afterwards so the chips' `#N` stay chronological across the live/backfill
+     * boundary (scopeSeq is a display anchor, not an address).
+     *
+     * The watermark is honest: 'complete' only when every candidate fit; a
+     * budget-dropped candidate keeps the state 'partial', and the service
+     * re-reads the log on later queries (eviction may have freed room). The
+     * insert itself never evicts a live turn: char pressure evicts the oldest
+     * BACKFILLED turns first.
+     *
+     * @returns the number of turns actually inserted.
+     */
+    insertLogTurns(sessionId: string, logTurns: readonly LogTurn[]): number;
+    /**
+     * The backfill window over a log's host turns: the newest
+     * `maxTurnsPerSession` at or before the window's end. At the latest, live
+     * turns the log does not hold yet take window slots too. The log lane
+     * materializes only these turns' requests.
+     */
+    windowHosts(sessionId: string, hosts: readonly number[]): Set<number>;
+    private windowOf;
+    /**
+     * Make room for `needed` chars by evicting other sessions' backfilled
+     * turns, least recently read session first, oldest turn first. Live
+     * content never yields. A session that lost backfill re-reads it when next
+     * read (its state drops back to partial).
+     */
+    private freeChars;
+    /**
+     * Move a session's backfill window: drop its backfilled turns (live turns
+     * stay) and let the next read refill the window ending at `end` (the
+     * latest turns when absent).
+     */
+    setWindow(sessionId: string, end: number | undefined): void;
+    /** A complete log can anchor live turns without retaining old request bodies. */
+    private reconcileRequestNumbers;
+    /** Retry numbering after a streaming turn’s first durable response becomes available. */
+    /**
+     * Make a session log-driven: an external agent's session opened on its own
+     * (a CLI in its own process, so no request passes through this host). Its
+     * turns come from its log only; the live turns opened so far held nothing
+     * and give way to the log's.
+     */
+    markLogDriven(sessionId: string): void;
+    /** Any live event of a log-driven session: the next read re-reads its log. */
+    noteLogActivity(sessionId: string): void;
+    /** Whether a read should re-read a log-driven session's log. */
+    needsLogRead(sessionId: string): boolean;
+    /** A log turn's end as the store records it: still open when it is a log-driven session's last turn. */
+    private logTurnEnd;
+    private logTurnOpen;
+    needsRequestNumbers(sessionId: string): boolean;
+    /** One reconstructed turn → one TurnRecord (main scope + delegation stubs). */
+    private insertLogTurn;
+    /** One reconstructed delegation → its child scope on `turn`. */
+    private addDelegationScope;
+    /** The hidden turn holding children started outside any turn (never listed; room rounds read it). */
+    private holderTurn;
+    /** Renumber one session's scope ordinals chronologically (turn order, then creation order). */
+    private renumberScopes;
+    /**
+     * Light turn list of one session plus its backfill watermark (sorted newest
+     * last). A {@link ScopeFilter} restricts every aggregate to the authorized
+     * scopes; the turn rows themselves (query preview, timestamps) are
+     * session-level metadata and stay listed.
+     */
+    listTurns(sessionId: string, filter?: ScopeFilter): ListTurnsResult;
+    /** The session's existing scopes that pass the filter (turn order, then creation order). */
+    private authorizedScopes;
+    private turnItem;
+    /** One turn's scope/request overview, without segments. */
+    getTurn(sessionId: string, turnSeq: number, filter?: ScopeFilter): TurnOverview | undefined;
+    /**
+     * The room's decision-model calls by the turn they happened in: each goes to
+     * the latest listed turn (main turn or room round) that started at or
+     * before it.
+     */
+    private decisionsByTurn;
+    /** Record one `room/*` event of a main session (log backfill or live). */
+    noteRoomEvent(sessionId: string, type: string, data: unknown, seq: number | undefined, at: number | undefined): void;
+    /** A listed turn or a room round, by its panel address. */
+    private findTurn;
+    /** Whether a moment falls inside some main turn (loaded or not). */
+    private insideMainTurn;
+    /**
+     * Every human room dispatch made outside a main turn, as a round: the
+     * dispatch's message, and per member run the child session's requests of
+     * that run (its recorded child turn, else the run's time span). Built on
+     * read from the room state and the children's scopes; nothing is stored.
+     */
+    private roomTurns;
+    /** The child session a run went to: named by the run, else the child catalogued closest to the run's start. */
+    private childOfRun;
+    /**
+     * One numbering for the whole session, by time: every main turn (loaded or
+     * not) and every room round. Keys: `h<hostTurn>` for main turns,
+     * `t<turnSeq>` for room rounds.
+     */
+    private ordinals;
+    /** Runs of main turns the log holds but the store has not loaded, in ordinals, with their host-turn ends. */
+    private unloadedRuns;
+    /** A compaction pseudo-turn's host turn: the one it started in, else the next turn to begin; undefined for any other turn. */
+    private attachedTurn;
+    /** Where the panel addresses a request: compaction requests live in their host turn's `compaction:` view. */
+    private addressOf;
+    private scopeOverview;
+    /** Record the child's provider from its `subagent/descriptor` (live child events or its log). */
+    noteChildProvider(childId: string, provider: string): void;
+    /** A session opened on its own that is some other session's child. */
+    noteParent(sessionId: string, parent: NonNullable<ListTurnsResult['parent']>): void;
+    /** Whether a child's parent link is already known (the service resolves it once). */
+    hasParent(sessionId: string): boolean;
+    /**
+     * One request's full four-segment breakdown. A request whose scope the
+     * filter excludes answers with a {@link ScopedRefusal} — distinguishable
+     * from `undefined` (no such seq on this instance).
+     */
+    getRequest(sessionId: string, seq: number, filter?: ScopeFilter): CapturedRequest | ScopedRefusal | undefined;
+    /** Resolve change entries to retained requests: the compaction call, and the request that still held un-pruned text. */
+    private withLinks;
+    private previousRequest;
+    private requestView;
+    /** One turn's whole-turn timing aggregation, filtered to the authorized scopes. */
+    getTurnTiming(sessionId: string, turnSeq: number, filter?: ScopeFilter): TurnTiming | undefined;
+    /** Session request headers only; excluded scopes contribute no rows or aggregates. */
+    getSessionTrend(sessionId: string, filter?: ScopeFilter): SessionTrend;
+    /** Release every session buffer (plugin dispose). */
+    dispose(): void;
+    /** @param counted - false for a window move or cross-session room, which the "collected then dropped" signal does not report. */
+    private evictTurn;
+    private turnIsLive;
+    /** The globally oldest closed backfilled turn (char-pressure eviction order). */
+    private oldestBackfilledTurn;
+    private enforceCaps;
+}
+/** The six-way timing split of one request, computed from its recorded spans. */
+export declare function requestTiming(request: StoredRequest): RequestTiming;
+/**
+ * Assemble a request's own response from its recorded block spans: the
+ * authoritative block-end content, falling back to delta-accumulated text for
+ * blocks a cancelled stream never closed. `undefined` when nothing was
+ * produced (a failure before any block — the `error` field covers that).
+ */
+export declare function responseFromSpans(blocks: readonly BlockSpan[]): CapturedResponse | undefined;
+//# sourceMappingURL=store.d.ts.map