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

package/lib/types/log-lane.d.ts

@@ -0,0 +1,198 @@
+import type { RequestConfig } from './types.ts';
+import { type StoredRequest } from './store.ts';
+import { type ScopeFingerprint } from './segmenter.ts';
+import { type CapturedMessage } from './messages.ts';
+/** The structural minimum of one decoded session-log row (untrusted JSON). */
+export interface SessionLogRow {
+    type: string;
+    seq?: number;
+    time?: number;
+    data?: unknown;
+    ignorable?: true;
+    surfaceOp?: 'append' | {
+        op: 'replace';
+        startSeq: number;
+        endSeq: number;
+    };
+    sourceEventSeqs?: number[];
+}
+/** What the lane asks of the host's persistence service (structural probe). */
+export interface SessionLogHandle {
+    read(offset?: number, length?: number): Promise<{
+        events: SessionLogRow[];
+    }>;
+    close(): Promise<void>;
+}
+/** The `sessionPersistence` service face this lane uses. */
+export interface SessionLogReader {
+    open(id: string, access: 'read'): Promise<SessionLogHandle>;
+}
+/** Structural check for the probed `sessionPersistence` service. */
+export declare function isSessionLogReader(value: unknown): value is SessionLogReader;
+/** A folded message plus its log position (fold order ≠ request membership). */
+interface FoldedMessage {
+    seq: number;
+    message: CapturedMessage;
+}
+/** One delegation call correlated across tool/call → subagent/catalog → tool/result. */
+export interface LogDelegation {
+    /** The host turn that ran the delegation, when the log scopes it. */
+    hostTurn?: number;
+    /** The delegating tool call; '' for a catalog-only child (an external agent no tool call started). */
+    callId: string;
+    name: string;
+    at: number;
+    /** The call arguments' description (the subagent_dsh convention). */
+    label?: string;
+    childId?: string;
+    catalogLabel?: string;
+    resultAt?: number;
+    isError?: boolean;
+    errorPreview?: string;
+}
+/** Incremental per-log fold state; survives across refreshes (child lane) or one shot (backfill). */
+export interface SessionLogCursor {
+    /** Events consumed so far (the next read's offset). */
+    consumed: number;
+    /** The log begins at its header/event zero, so request ordinals are anchored. */
+    numberedFromStart: boolean;
+    /** Model-visible messages folded so far, in log order. */
+    messages: FoldedMessage[];
+    compactions: Map<string, {
+        startedAt: number;
+        hostTurn?: number;
+        request?: BuiltLogRequest;
+    }>;
+    /** The latest step/start time — the next request's dispatch proxy. */
+    stepStartAt: number | undefined;
+    /**
+     * The log mirrors an external agent (its descriptor names a provider that
+     * runs in its own process). A mirror that writes a step only once its call
+     * is over writes step/start and the answer together; such a request
+     * starts when the log's previous event happened (`stepPrevAt`).
+     */
+    external?: boolean;
+    /** The latest event time that marks progress (not a live-stream checkpoint). */
+    lastEventAt?: number;
+    /** The progress event before the latest step/start. */
+    stepPrevAt?: number;
+    /**
+     * An external agent's step that reported no usage: a mirror writes one
+     * model call as several steps (one per item or content block) with the
+     * call's usage on its last, so the step waits to join the steps after it
+     * as one request. Its blocks accumulate in `deferredBlocks`.
+     */
+    deferred?: {
+        request: BuiltLogRequest;
+        hostTurn: number | undefined;
+        blocks: CapturedMessage['content'];
+    };
+    /** The latest request/header config, when the log carries any. */
+    config: RequestConfig | undefined;
+    /** The latest request/header tool list, when the log carries any. */
+    tools: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    }[] | undefined;
+    /** tool/call times by callId. */
+    callAt: Map<string, number>;
+    /** callId → tool name (tool-row labels). */
+    callNames: Map<string, string>;
+    /** callId → the built request whose response issued it (exec attribution). */
+    callOwners: Map<string, BuiltLogRequest>;
+    /** messageId → producing request's generation ms. */
+    messageDurations: Map<string, number>;
+    /** The previous request's diff baseline. */
+    previous: ScopeFingerprint | undefined;
+    /** Requests built so far (kept for late tool-exec closes). */
+    requests: BuiltLogRequest[];
+    /** The currently open host turn's number (turn/start … turn/end). */
+    turnHost: number | undefined;
+    /** Whether the current turn already contributed its query preview. */
+    turnQuerySeen: boolean;
+    /** Whether the current turn already named the non-human message that started it. */
+    turnTriggerSeen: boolean;
+    /** Delegation calls awaiting their catalog/result. */
+    pendingDelegations: Map<string, LogDelegation>;
+    /** Set once a read failed this cursor; the lane stops hammering a bad log. */
+    broken: string | undefined;
+    /**
+     * Whether a request of this host turn keeps its full segments. Every
+     * request carries its whole context, so materializing a long log at once
+     * grows with the square of its length; the backfill materializes only its
+     * window and records the rest as bodiless rows. Absent: materialize all.
+     */
+    materialize?: (hostTurn: number | undefined) => boolean;
+    /** The last request's messages when it was not materialized (the next full one diffs against them). */
+    previousMessages?: CapturedMessage[];
+    previousToolNames?: string[];
+}
+/** A request row built from the log, before the store assigns its sequence. */
+export type BuiltLogRequest = Omit<StoredRequest, 'seq' | 'sessionId' | 'scopeId' | 'turnSeq'>;
+/** Optional fold hooks beyond the request rows (the backfill driver uses them all). */
+export interface FoldSink {
+    turnStart?(hostTurn: number, at: number | undefined, seq?: number): void;
+    turnEnd?(hostTurn: number, reason: {
+        kind: string;
+        error?: {
+            message?: string;
+        };
+    }, at: number | undefined): void;
+    /** The turn's first human user message (the turn list's query preview). */
+    queryText?(hostTurn: number | undefined, text: string, at: number | undefined): void;
+    /** The turn's first message from a non-human producer (the turn's trigger when no human spoke). */
+    triggerText?(hostTurn: number | undefined, source: string, text: string): void;
+    /** Each committed assistant message id; the last one of a turn is its closing message. */
+    closingMessage?(hostTurn: number | undefined, messageId: string): void;
+    /** One completed request, tagged with its host turn when the log scopes it. */
+    request?(hostTurn: number | undefined, request: BuiltLogRequest): void;
+    /** One delegation run, emitted when its tool/result lands (or at fold flush). */
+    delegation?(delegation: LogDelegation): void;
+}
+/**
+ * Subagent providers that run inside this host, so their requests pass
+ * through the live capture. Every other provider (claude-local, codex-local,
+ * kimi-cli, dsh-cli, …) is its own process, mirrored into its log after the
+ * fact.
+ */
+export declare const IN_PROCESS_PROVIDERS: ReadonlySet<string>;
+/** A fresh cursor for one log. */
+export declare function openCursor(): SessionLogCursor;
+/**
+ * Fold new log rows into the cursor. Returns the requests completed by THIS
+ * batch (the child-scope driver's whole output); the sink receives those plus
+ * the turn/delegation structure (the backfill driver). Tool exec spans can
+ * open and close in later batches, so pairing data lives on the cursor.
+ */
+export declare function foldLogRows(cursor: SessionLogCursor, rows: readonly SessionLogRow[], sink?: FoldSink): BuiltLogRequest[];
+/**
+ * One-shot reconstruction of a whole session log into turns (the main-session
+ * backfill). Requests group by their host turn number (step-scoped events
+ * carry it; a torn bracket falls back to the fold's open-turn state). Turns
+ * never closed by a turn/end (a crash) come out with `endReasonKind` unset.
+ */
+export declare function reconstructSession(rows: readonly SessionLogRow[], materialize?: (hostTurn: number | undefined) => boolean): LogTurn[];
+/** One reconstructed turn (the store turns this into a TurnRecord). */
+export interface LogTurn {
+    hostTurn: number;
+    purpose?: string;
+    query: string;
+    /** First non-human message of the turn: who started it when no human did. */
+    trigger?: {
+        source: string;
+        text: string;
+    };
+    /** The `turn/start` row's seq (the chat's history-jump target). */
+    startSeq?: number;
+    startedAt: number;
+    endedAt?: number;
+    closingMessageId?: string;
+    /** The turn/end reason kind; absent when the log never closed the turn. */
+    endReasonKind?: string;
+    endError?: string;
+    requests: BuiltLogRequest[];
+    delegations: LogDelegation[];
+}
+export {};
+//# sourceMappingURL=log-lane.d.ts.map