@titan-design/session-analytics 0.5.0 → 0.8.0

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 import { Db } from '@titan-design/store-sqlite';
 import { z } from 'zod';
 import { EpisodeRow, SessionGraph } from '@titan-design/session-graph';
+import { ToolFamily, NormalizedSessionObservation } from '@titan-design/session-read';
+export { ToolFamily } from '@titan-design/session-read';
 
 /** USD per million tokens. Fitted against 392 `cost-state` rows in the 2026-09-20 audit. */
 interface PriceRow {
@@ -242,6 +244,7 @@ declare const reviewerSchema: z.ZodObject<{
         sessions: z.ZodNumber;
         requestsPerPr: z.ZodNumber;
         requestsFrom: z.ZodString;
+        requestsFromSessions: z.ZodNumber;
         costUsd: z.ZodNumber;
     }, z.core.$strip>>;
     standing: z.ZodArray<z.ZodObject<{
@@ -250,6 +253,7 @@ declare const reviewerSchema: z.ZodObject<{
         sessions: z.ZodNumber;
         requestsPerPr: z.ZodNumber;
         requestsFrom: z.ZodString;
+        requestsFromSessions: z.ZodNumber;
         costUsd: z.ZodNumber;
     }, z.core.$strip>>;
 }, z.core.$strip>;
@@ -322,6 +326,7 @@ declare const handoffThresholdSchema: z.ZodObject<{
             sessions: z.ZodNumber;
             requestsPerPr: z.ZodNumber;
             requestsFrom: z.ZodString;
+            requestsFromSessions: z.ZodNumber;
             costUsd: z.ZodNumber;
         }, z.core.$strip>>;
         standing: z.ZodArray<z.ZodObject<{
@@ -330,6 +335,7 @@ declare const handoffThresholdSchema: z.ZodObject<{
             sessions: z.ZodNumber;
             requestsPerPr: z.ZodNumber;
             requestsFrom: z.ZodString;
+            requestsFromSessions: z.ZodNumber;
             costUsd: z.ZodNumber;
         }, z.core.$strip>>;
     }, z.core.$strip>;
@@ -657,6 +663,7 @@ declare const costReportSchema: z.ZodObject<{
                 sessions: z.ZodNumber;
                 requestsPerPr: z.ZodNumber;
                 requestsFrom: z.ZodString;
+                requestsFromSessions: z.ZodNumber;
                 costUsd: z.ZodNumber;
             }, z.core.$strip>>;
             standing: z.ZodArray<z.ZodObject<{
@@ -665,6 +672,7 @@ declare const costReportSchema: z.ZodObject<{
                 sessions: z.ZodNumber;
                 requestsPerPr: z.ZodNumber;
                 requestsFrom: z.ZodString;
+                requestsFromSessions: z.ZodNumber;
                 costUsd: z.ZodNumber;
             }, z.core.$strip>>;
         }, z.core.$strip>;
@@ -1132,11 +1140,15 @@ interface DenialRecord {
     /** What the refused call was doing, from its tool input; the reason label alone is loose. */
     action: string;
     tool: string;
+    /** The refused call's id; a forked or resumed transcript repeats it, so it is counted once. */
+    toolUseId?: string;
 }
 /** Classifies a refused call by what it did; MCP tools keep their own short name. */
 declare function classifyDeniedAction(tool: string, input: unknown): string;
 /** Scans transcript JSONL for classifier refusals and joins each to the tool call it refused. */
 declare function parseDenials(lines: Iterable<string>, seat: string): DenialRecord[];
+/** One denial per refused call; a record without a tool_use_id cannot be matched and is kept. */
+declare function dedupeDenials(denials: readonly DenialRecord[]): DenialRecord[];
 
 /** A seat journal line that states its implementer slot count, and why it did not fill a free slot. */
 interface SlotTick {
@@ -1374,4 +1386,544 @@ declare function blockedFlowReport(input: BlockedFlowInput): BlockedFlowReport;
 /** Each table's title names the JSON field its numbers come from; the sources close the report. */
 declare function renderBlockedFlowText(report: BlockedFlowReport): string;
 
-export { ACTION_CLASSES, AGENT_LIFECYCLE, ALL_REPOS, type ActionCall, type ActionClass, type ActionRule, type AgentNameRow, BLOCKED_FLOW_SOURCES, BOOT_TOOL, type Band, type BlockedFlowInput, type BlockedFlowReport, type BlockedFlowSource, CHANNEL_CLUSTER_MS, CONTEXT_BANDS, CONTEXT_RESET_TOKENS, COORDINATOR_MERGE_DEDUPE_REQUESTS, COORDINATOR_MIN_EPISODE_REQUESTS, COORDINATOR_WAVE_QUIET_REQUESTS, COST_REPORT_SECTIONS, type CacheTtlBucket, type CacheTtlWhatIf, type CostBucket, type CostReport, type CostReportOptions, type CostReportSection, type CycleParams, DEFAULT_ACTION_RULES, DEFAULT_CONFIGURED_K, DEFAULT_EPISODE_ROLES, DEFAULT_K_SWEEP, DEFAULT_MECHANICAL_CLASSES, DEFAULT_NO_ACTION_CLASSES, DEFAULT_REVIEWER_PRS, DEFAULT_REVIEWER_ROLE, DEFAULT_STANDING_ROLE, type DenialRecord, type EpisodeInbound, type EpisodeInput, type EpisodeNames, type EpisodeRequest, type EpisodeRequestRow, type EpisodeSignal, GAP_BANDS, HEURISTIC_VERSIONS, type HandoffCohort, type HandoffOptions, type HandoffRequestRow, type HandoffSession, type HandoffTeleport, type HandoffThreshold, type Heuristic, type HumanRole, IDLE_GAP_MS, type IdleSlotRow, type KSweep, LIST_PRICE_CAVEAT, type LatencyRow, type LatencyStats, type MechanicalShare, type MergeOutcome, type MergeStatus, POOLED_REVIEWERS, PRICE_TABLE, PRICE_TABLE_VERSION, PROFILE_ROLES, type ParsedVerdict, type PriceRow, type PricedRequest, type PullState, REBUILD_GAP_BANDS, type ReportScope, type ReportWindow, type RequestTokens, type ReviewerComparison, type RoleActions, STANDING_PEER_MIN_ASSIGNMENTS, STANDING_PEER_MIN_HOURS, type SeatJournal, type SessionClass, type SessionClassification, type SessionFacts, type SessionOrigin, type SlotTick, TELEPORT_EVENT, TICK_HOLD_MAX_MIN, TOKEN_CLASSES, type TaskInitiative, type TeleportEvent, type TokenClass, type TtlRequestRow, UNSTATED_REASON, type VerdictRecord, WAKE_FROM_KINDS, type WakeCauseBucket, type WakeCauseEpisodes, type WakeEpisode, type WakeEpisodes, type WakeEventRow, type WakeFromKind, type WakeGapCell, type WakePair, type WorkerFacts, type WorkerRole, type WrittenEpisodes, assignmentCount, bandOf, blockedFlowReport, blockedFlowSchema, buildEpisodes, buildWakeEpisodes, cacheTtlReport, cacheTtlWhatIf, cacheTtlWhatIfSchema, classifyDeniedAction, classifyRequest, classifySession, contextBand, costPerRequest, costReport, costReportSchema, episodeNames, findPrice, gapBand, handoffThreshold, handoffThresholdSchema, heuristicFor, idleSlotMinutes, initiativeFromCwd, isBootAction, latencyStats, latencyStatsSchema, mergeOutcomes, parseDenials, parseSeatJournal, parseTeleportEvents, parseVerdict, prKey, priceRequest, readEpisodeInput, readRequestToolCalls, readTtlRows, renderBlockedFlowText, renderCacheTtlText, renderCostReportSections, renderCostReportText, roleFromProfile, scopeFilter, sessionInitiative, sessionRole, summarizeWakeEpisodes, sweepK, wakeEpisodesSchema, workerRole, writeEpisodes };
+/** One agent-chat broker.log entry and the 1-based line it came from, so each finding can cite it. */
+interface BrokerEntry {
+    line: number;
+    ts: string;
+    event: string;
+    fields: Record<string, unknown>;
+}
+/** Broker log lines to entries; a line that is not a JSON object with `ts` and `event` is skipped but still counted. */
+declare function parseBrokerLog(lines: Iterable<string>): BrokerEntry[];
+
+/**
+ * How a route missed a recipient: `failed` is a `delivered:false` the broker dropped, `partial` reached
+ * others but not this name, and `queued` is a `delivered:false` the broker kept for later delivery.
+ */
+type RouteMissKind = "failed" | "partial" | "queued";
+/** One recipient a routed message did not reach when it was sent. */
+interface RouteMiss {
+    line: number;
+    at: string;
+    recipient: string;
+    from: string;
+    kind: string;
+    miss: RouteMissKind;
+}
+interface RouteFailureRow {
+    recipient: string;
+    failed: number;
+    partial: number;
+    queued: number;
+    first: string;
+    last: string;
+    lines: number[];
+}
+/** Each recipient named in `to` that a route did not reach. */
+declare function routeMisses(entries: readonly BrokerEntry[]): RouteMiss[];
+/** Misses grouped by recipient, most first. */
+declare function routeFailureRows(misses: readonly RouteMiss[]): RouteFailureRow[];
+declare function countMisses(misses: readonly RouteMiss[]): Record<RouteMissKind, number>;
+
+/** A seat off the broker for longer than this is dark; a teleport hand-off takes seconds. */
+declare const DARK_MIN = 5;
+/** A name deregistered from the broker until it registered again, or until asOf if it never did, without exiting in between. */
+interface DarkGap {
+    seat: string;
+    from: string;
+    to: string | null;
+    minutes: number;
+    /** A teleport of this name started after its last registration and before the gap closed. */
+    teleport: boolean;
+    /** Routes to the seat during the gap logged `delivered:false` and dropped. */
+    failedRoutes: number;
+    /** Routes during the gap that reached other recipients but not the seat. */
+    partialRoutes: number;
+    /** Routes the broker held or queued in the seat's inbox for delivery when it returned. */
+    queuedRoutes: number;
+    /** The deregistered and registered lines, then any teleport lines. */
+    lines: number[];
+    routeLines: number[];
+}
+/** Gaps longer than DARK_MIN, skipping a clean exit and later resume; one still open at asOf counts only if a route missed the seat in it. */
+declare function darkGaps(entries: readonly BrokerEntry[], misses: readonly RouteMiss[], asOf: string): DarkGap[];
+
+/** An `agent_spawned` row of agent-chat's events table: the agent id and the profile it ran under. */
+interface SpawnRecord {
+    eventId: number;
+    agentId: string;
+    name: string;
+    profile: string | null;
+}
+/** An agent the broker saw exit without reporting to its spawner. */
+interface UnreportedExit {
+    at: string;
+    line: number;
+    agentId: string;
+    name: string;
+    spawner: string;
+    lastAction: string;
+    /** The `agent_spawned` row the profile came from, or null when none matched the agent id. */
+    spawnEventId: number | null;
+}
+interface UnreportedExitRow {
+    profile: string;
+    count: number;
+    exits: UnreportedExit[];
+}
+declare const UNKNOWN_PROFILE = "unknown";
+/** Broker `unreported-exit` lines grouped by the profile the agent was spawned with, most first. */
+declare function unreportedExitRows(entries: readonly BrokerEntry[], spawns: readonly SpawnRecord[]): UnreportedExitRow[];
+
+/** A prompt this old with nothing after it from the agent is a hang, not a pause for the owner. */
+declare const PROMPT_STALE_MIN = 10;
+/** The newest events-table row an actor wrote before asOf. */
+interface LastEventRecord {
+    eventId: number;
+    at: string;
+    actor: string;
+    kind: string;
+    /** `meta.tool_name` of an approval request. */
+    tool: string | null;
+    /** A `resolution` row whose `ref` is this request's msg_id, written before asOf. */
+    resolutionEventId: number | null;
+    /** An `agent_exited` or `agent_retired` row for this actor after the request and before asOf. */
+    endEventId: number | null;
+}
+interface StalePromptRow {
+    agent: string;
+    at: string;
+    ageMin: number;
+    tool: string | null;
+    eventId: number;
+    resolutionEventId: number | null;
+}
+/** Live agents whose last event is an approval request older than PROMPT_STALE_MIN, oldest first; resolved ones included. */
+declare function stalePromptRows(lastEvents: readonly LastEventRecord[], broker: readonly BrokerEntry[], asOf: string): StalePromptRow[];
+
+/** Where each section's findings come from: the command that re-reads them and the field it reads. */
+declare const LIVENESS_SOURCES: {
+    readonly registrations: {
+        readonly command: "grep -nE '\"event\":\"(registered|deregistered|agent_exited|teleport_started|teleport_completed|teleport_failed|teleport_aborted)\"' <broker.log>";
+        readonly field: "ts, event, name; cited as broker.log line numbers; a gap with a clean agent_exited (code 0, not inferred) and no teleport is a resume";
+    };
+    readonly routes: {
+        readonly command: "grep -n '\"event\":\"route\"' <broker.log>";
+        readonly field: "to, delivered, recipients";
+    };
+    readonly exits: {
+        readonly command: "grep -n '\"event\":\"unreported-exit\"' <broker.log>";
+        readonly field: "agentId, name, spawner, lastAction";
+    };
+    readonly spawns: {
+        readonly command: "sqlite3 -readonly <events.db> \"SELECT id, msg_id, target, json_extract(meta,'$.profile') FROM events WHERE kind='agent_spawned'\"";
+        readonly field: "events.msg_id (agent id), events.meta.profile";
+    };
+    readonly prompts: {
+        readonly command: "sqlite3 -readonly <events.db> \"SELECT e.* FROM events e JOIN (SELECT actor, max(id) id FROM events WHERE ts < <asOf> AND kind != 'resolution' GROUP BY actor) l ON e.id = l.id WHERE e.kind='approval_request'\"";
+        readonly field: "events.ts, events.actor, events.meta.tool_name; a resolution row's events.ref; skipped after the actor's agent_exited or agent_retired, or a broker_started it never re-registered after";
+    };
+};
+type LivenessSource = keyof typeof LIVENESS_SOURCES;
+interface LivenessInput {
+    broker: readonly BrokerEntry[];
+    spawns: readonly SpawnRecord[];
+    lastEvents: readonly LastEventRecord[];
+    /** Gaps still open and prompt ages are measured to here; later entries are ignored. */
+    asOf: string;
+    /** A finding is kept when it starts inside the window; a prompt from a live agent still unanswered at asOf is kept however old. */
+    window?: {
+        since?: string;
+        until?: string;
+    };
+    /** Keeps only findings about these names: the dark seat, route recipient, exiting agent or its spawner, prompting agent. */
+    seats?: readonly string[];
+}
+declare const livenessSchema: z.ZodObject<{
+    asOf: z.ZodString;
+    window: z.ZodObject<{
+        since: z.ZodOptional<z.ZodString>;
+        until: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    thresholds: z.ZodObject<{
+        darkMin: z.ZodNumber;
+        promptStaleMin: z.ZodNumber;
+    }, z.core.$strip>;
+    sources: z.ZodRecord<z.ZodEnum<{
+        exits: "exits";
+        registrations: "registrations";
+        routes: "routes";
+        spawns: "spawns";
+        prompts: "prompts";
+    }>, z.ZodObject<{
+        command: z.ZodString;
+        field: z.ZodString;
+    }, z.core.$strip>>;
+    darkSeats: z.ZodObject<{
+        cites: z.ZodArray<z.ZodEnum<{
+            exits: "exits";
+            registrations: "registrations";
+            routes: "routes";
+            spawns: "spawns";
+            prompts: "prompts";
+        }>>;
+        withTeleport: z.ZodNumber;
+        withoutTeleport: z.ZodNumber;
+        rows: z.ZodArray<z.ZodObject<{
+            seat: z.ZodString;
+            from: z.ZodString;
+            to: z.ZodNullable<z.ZodString>;
+            minutes: z.ZodNumber;
+            teleport: z.ZodBoolean;
+            failedRoutes: z.ZodNumber;
+            partialRoutes: z.ZodNumber;
+            queuedRoutes: z.ZodNumber;
+            lines: z.ZodArray<z.ZodNumber>;
+            routeLines: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    routeFailures: z.ZodObject<{
+        cites: z.ZodArray<z.ZodEnum<{
+            exits: "exits";
+            registrations: "registrations";
+            routes: "routes";
+            spawns: "spawns";
+            prompts: "prompts";
+        }>>;
+        failed: z.ZodNumber;
+        partial: z.ZodNumber;
+        queued: z.ZodNumber;
+        rows: z.ZodArray<z.ZodObject<{
+            recipient: z.ZodString;
+            failed: z.ZodNumber;
+            partial: z.ZodNumber;
+            queued: z.ZodNumber;
+            first: z.ZodString;
+            last: z.ZodString;
+            lines: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    unreportedExits: z.ZodObject<{
+        cites: z.ZodArray<z.ZodEnum<{
+            exits: "exits";
+            registrations: "registrations";
+            routes: "routes";
+            spawns: "spawns";
+            prompts: "prompts";
+        }>>;
+        total: z.ZodNumber;
+        rows: z.ZodArray<z.ZodObject<{
+            profile: z.ZodString;
+            count: z.ZodNumber;
+            exits: z.ZodArray<z.ZodObject<{
+                at: z.ZodString;
+                line: z.ZodNumber;
+                agentId: z.ZodString;
+                name: z.ZodString;
+                spawner: z.ZodString;
+                lastAction: z.ZodString;
+                spawnEventId: z.ZodNullable<z.ZodNumber>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    stalePrompts: z.ZodObject<{
+        cites: z.ZodArray<z.ZodEnum<{
+            exits: "exits";
+            registrations: "registrations";
+            routes: "routes";
+            spawns: "spawns";
+            prompts: "prompts";
+        }>>;
+        rows: z.ZodArray<z.ZodObject<{
+            agent: z.ZodString;
+            at: z.ZodString;
+            ageMin: z.ZodNumber;
+            tool: z.ZodNullable<z.ZodString>;
+            eventId: z.ZodNumber;
+            resolutionEventId: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>>;
+        resolvedRows: z.ZodArray<z.ZodObject<{
+            agent: z.ZodString;
+            at: z.ZodString;
+            ageMin: z.ZodNumber;
+            tool: z.ZodNullable<z.ZodString>;
+            eventId: z.ZodNumber;
+            resolutionEventId: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type LivenessReport = z.infer<typeof livenessSchema>;
+/** Seats dark past DARK_MIN, routes that missed their recipient, unreported exits and agents stuck on a prompt. */
+declare function livenessReport(input: LivenessInput): LivenessReport;
+/** Each table's title names the JSON field its rows come from; the sources and the shared caveat close the report. */
+declare function renderLivenessText(report: LivenessReport): string;
+
+/** Bump when a field is removed or changes meaning. Adding a field keeps the version. */
+declare const SESSION_TIMELINE_VERSION = 1;
+/** Idle time between two events that counts as a gap. */
+declare const TIMELINE_GAP_MIN_MS: number;
+/** Default cap on each message text. The byte offset still points at the full record. */
+declare const TIMELINE_TEXT_CAP = 4000;
+/** `prompt` is typed or sent text, `injected` is a harness block, `compaction` is a continuation summary, `none` is activity before any user message. */
+type TimelineTurnOrigin = "prompt" | "injected" | "compaction" | "none";
+/** `unknown` is a result whose source did not report an error state; `pending` has no result yet. */
+type TimelineToolOutcome = "success" | "error" | "unknown" | "pending";
+interface TimelineMessage {
+    role: "user" | "assistant";
+    /** Source order across the whole session; sort a turn's messages and tool calls by it to interleave them. */
+    seq: number;
+    atMs: number | null;
+    text: string;
+    /** True when `text` was cut at the cap. */
+    truncated: boolean;
+    /** Offset of the transcript line, for reading the full record. */
+    byteOffset: number;
+}
+interface TimelineToolCall {
+    /** The harness's own call id, unique within the session. */
+    id: string;
+    seq: number;
+    turnIndex: number;
+    name: string;
+    family: ToolFamily;
+    atMs: number | null;
+    /** When the result arrived; null while pending. */
+    endMs: number | null;
+    /** Observed call-to-result span, not harness execution time. */
+    durationMs: number | null;
+    outcome: TimelineToolOutcome;
+    errorMessage: string | null;
+    /** One line naming what the call acted on: a path, a command, a pattern or a description. */
+    inputSummary: string;
+    filePath: string | null;
+    sidechain: boolean;
+    byteOffset: number;
+}
+/** Prompt-side counts are disjoint: `input` excludes cache reads and cache writes. */
+interface TimelineTokens {
+    input: number;
+    cacheRead: number;
+    /** All cache writes, `cacheWrite5m + cacheWrite1h`. */
+    cacheWrite: number;
+    /** Writes at the 5m rate, including a total the source reported without a split. */
+    cacheWrite5m: number;
+    /** Writes at the 1h rate. */
+    cacheWrite1h: number;
+    output: number;
+}
+interface TimelineTurn {
+    index: number;
+    origin: TimelineTurnOrigin;
+    /** The session-read injected-marker name when `origin` is `injected` or `compaction`. */
+    injectedMarker: string | null;
+    startMs: number | null;
+    endMs: number | null;
+    /** Idle time before this turn when it is `TIMELINE_GAP_MIN_MS` or more, else null. */
+    gapBeforeMs: number | null;
+    /** The message that opened the turn; null when `origin` is `none`. */
+    user: TimelineMessage | null;
+    assistant: TimelineMessage[];
+    toolCalls: TimelineToolCall[];
+    errorCount: number;
+    tokens: TimelineTokens;
+    costUsd: number;
+}
+/** One UTC clock minute that held activity. Minutes with none are omitted. */
+interface TimelineMinuteBucket {
+    /** Start of the minute. */
+    minuteMs: number;
+    /** Messages, tool calls and tool results. */
+    events: number;
+    messages: number;
+    toolCalls: number;
+    errors: number;
+    outputTokens: number;
+    costUsd: number;
+    /** Set on the first bucket after a gap. */
+    gapBeforeMs: number | null;
+}
+/** An idle stretch. Time spent waiting on a tool call that later returned is not idle, so it is never a gap. */
+interface TimelineGap {
+    startMs: number;
+    endMs: number;
+    durationMs: number;
+}
+/** One API request. Points are in source order and cumulative fields run over that order. */
+interface TimelineTokenPoint {
+    atMs: number;
+    turnIndex: number | null;
+    model: string | null;
+    /** The prompt size of this request: input plus cache read plus cache write. Null when the source omitted a count. */
+    contextTokens: number | null;
+    outputTokens: number;
+    cumulativeOutputTokens: number;
+    costUsd: number;
+    cumulativeCostUsd: number;
+    /** False when no price row covers the model; `costUsd` is then 0. */
+    priced: boolean;
+    /** True on the first request after a compaction. */
+    afterCompaction: boolean;
+}
+interface CompactionMark {
+    atMs: number | null;
+    turnIndex: number | null;
+    byteOffset: number;
+    summary: string | null;
+    summaryTruncated: boolean;
+}
+interface ModelRequests {
+    model: string;
+    requests: number;
+}
+interface TokenTimeline {
+    /** `delta` has per-request points. A `snapshot` source reports running totals only: `points` is empty and nothing is priced, so every `costUsd` is 0. */
+    basis: "delta" | "snapshot" | "unreported";
+    points: TimelineTokenPoint[];
+    compactions: CompactionMark[];
+    /** Most requests first. */
+    models: ModelRequests[];
+}
+interface ToolNameCount {
+    name: string;
+    family: ToolFamily;
+    calls: number;
+    errors: number;
+    durationMs: number;
+}
+interface ToolFamilyCount {
+    family: ToolFamily;
+    calls: number;
+    errors: number;
+    /** Call start times, ascending, for `countAtOrBefore`. */
+    atMs: number[];
+}
+interface TimelineToolBreakdown {
+    /** Most calls first. */
+    byName: ToolNameCount[];
+    byFamily: ToolFamilyCount[];
+    /** Every call start time, ascending. */
+    atMs: number[];
+}
+interface TimelineFileTouch {
+    path: string;
+    access: "read" | "write";
+    /** First touch of this path with this access. */
+    atMs: number | null;
+    calls: number;
+}
+interface TimelineFileBreakdown {
+    /** One row per path and access, ordered by first touch. */
+    touches: TimelineFileTouch[];
+    readCount: number;
+    writeCount: number;
+}
+interface TimelineError {
+    callId: string;
+    toolName: string;
+    turnIndex: number;
+    /** When the failing result arrived. */
+    atMs: number | null;
+    message: string;
+    sidechain: boolean;
+}
+interface TimelineErrorBreakdown {
+    /** Failed calls over all calls; 0 with no calls. */
+    rate: number;
+    items: TimelineError[];
+    atMs: number[];
+}
+/** A subagent dispatch, from its tool call to that call's result. */
+interface TimelineAgentSpan {
+    callId: string;
+    label: string;
+    startMs: number | null;
+    endMs: number | null;
+    outcome: TimelineToolOutcome;
+}
+interface TimelineTotals {
+    turns: number;
+    userMessages: number;
+    assistantMessages: number;
+    toolCalls: number;
+    errors: number;
+    compactions: number;
+    /** API requests with usage. Null on a `snapshot` basis, which cannot count them. */
+    requests: number | null;
+    unpricedRequests: number;
+    tokens: TimelineTokens;
+    /** 0 on a `snapshot` basis, which has no per-request usage to price. */
+    costUsd: number;
+}
+/**
+ * Everything a session view reads, as plain JSON. Every `*Ms` field is epoch milliseconds,
+ * so the model holds no time zone and a renderer picks one.
+ */
+interface SessionTimeline {
+    version: typeof SESSION_TIMELINE_VERSION;
+    sessionId: string | null;
+    harness: string | null;
+    startMs: number | null;
+    endMs: number | null;
+    durationMs: number;
+    totals: TimelineTotals;
+    turns: TimelineTurn[];
+    buckets: TimelineMinuteBucket[];
+    gaps: TimelineGap[];
+    tokens: TokenTimeline;
+    tools: TimelineToolBreakdown;
+    files: TimelineFileBreakdown;
+    errors: TimelineErrorBreakdown;
+    agents: TimelineAgentSpan[];
+}
+
+interface SessionTimelineOptions {
+    /** Idle time that counts as a gap. Defaults to `TIMELINE_GAP_MIN_MS`. */
+    gapMinMs?: number;
+    /** Cap on each message and compaction summary. Defaults to `TIMELINE_TEXT_CAP`. */
+    maxTextChars?: number;
+    /** Price rows for the cost series. Defaults to `PRICE_TABLE`. */
+    prices?: readonly PriceRow[];
+}
+/** Storage-free fold for a streamed read: `add` each observation, then `result`, which returns a fresh copy each time. */
+declare class SessionTimelineAccumulator {
+    private readonly turns;
+    private readonly tokens;
+    private readonly gapMinMs;
+    private conversation;
+    private startMs;
+    private endMs;
+    constructor(options?: SessionTimelineOptions);
+    add(observation: NormalizedSessionObservation): void;
+    result(): SessionTimeline;
+    private claim;
+    /** A record with no usable timestamp takes the latest one seen, so it still lands in order. */
+    private clock;
+}
+/** The read model behind every session view: turns, minute buckets, the token and cost series, and tool, file and error breakdowns. */
+declare function buildSessionTimeline(observations: Iterable<NormalizedSessionObservation>, options?: SessionTimelineOptions): SessionTimeline;
+
+/** How many of the ascending `sortedMs` are at or before `targetMs`, by binary search. */
+declare function countAtOrBefore(sortedMs: readonly number[], targetMs: number): number;
+
+declare const reviewFillSchema: z.ZodObject<{
+    window: z.ZodObject<{
+        since: z.ZodNullable<z.ZodString>;
+        until: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    unfilled: z.ZodNumber;
+    unresolved: z.ZodNumber;
+    rows: z.ZodArray<z.ZodObject<{
+        band: z.ZodString;
+        model: z.ZodString;
+        verdicts: z.ZodNumber;
+        changesRequested: z.ZodNumber;
+        changesRate: z.ZodNullable<z.ZodNumber>;
+        verdictErrors: z.ZodNumber;
+        errorRate: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type ReviewFillReport = z.infer<typeof reviewFillSchema>;
+/** Review verdicts in the window by the reviewer's context fill when it issued them, and how often an approve was contradicted. */
+declare function reviewFillReport(db: Db, window: ReportWindow): ReviewFillReport;
+
+export { ACTION_CLASSES, AGENT_LIFECYCLE, ALL_REPOS, type ActionCall, type ActionClass, type ActionRule, type AgentNameRow, BLOCKED_FLOW_SOURCES, BOOT_TOOL, type Band, type BlockedFlowInput, type BlockedFlowReport, type BlockedFlowSource, type BrokerEntry, CHANNEL_CLUSTER_MS, CONTEXT_BANDS, CONTEXT_RESET_TOKENS, COORDINATOR_MERGE_DEDUPE_REQUESTS, COORDINATOR_MIN_EPISODE_REQUESTS, COORDINATOR_WAVE_QUIET_REQUESTS, COST_REPORT_SECTIONS, type CacheTtlBucket, type CacheTtlWhatIf, type CompactionMark, type CostBucket, type CostReport, type CostReportOptions, type CostReportSection, type CycleParams, DARK_MIN, DEFAULT_ACTION_RULES, DEFAULT_CONFIGURED_K, DEFAULT_EPISODE_ROLES, DEFAULT_K_SWEEP, DEFAULT_MECHANICAL_CLASSES, DEFAULT_NO_ACTION_CLASSES, DEFAULT_REVIEWER_PRS, DEFAULT_REVIEWER_ROLE, DEFAULT_STANDING_ROLE, type DarkGap, type DenialRecord, type EpisodeInbound, type EpisodeInput, type EpisodeNames, type EpisodeRequest, type EpisodeRequestRow, type EpisodeSignal, GAP_BANDS, HEURISTIC_VERSIONS, type HandoffCohort, type HandoffOptions, type HandoffRequestRow, type HandoffSession, type HandoffTeleport, type HandoffThreshold, type Heuristic, type HumanRole, IDLE_GAP_MS, type IdleSlotRow, type KSweep, LIST_PRICE_CAVEAT, LIVENESS_SOURCES, type LastEventRecord, type LatencyRow, type LatencyStats, type LivenessInput, type LivenessReport, type LivenessSource, type MechanicalShare, type MergeOutcome, type MergeStatus, type ModelRequests, POOLED_REVIEWERS, PRICE_TABLE, PRICE_TABLE_VERSION, PROFILE_ROLES, PROMPT_STALE_MIN, type ParsedVerdict, type PriceRow, type PricedRequest, type PullState, REBUILD_GAP_BANDS, type ReportScope, type ReportWindow, type RequestTokens, type ReviewFillReport, type ReviewerComparison, type RoleActions, type RouteFailureRow, type RouteMiss, type RouteMissKind, SESSION_TIMELINE_VERSION, STANDING_PEER_MIN_ASSIGNMENTS, STANDING_PEER_MIN_HOURS, type SeatJournal, type SessionClass, type SessionClassification, type SessionFacts, type SessionOrigin, type SessionTimeline, SessionTimelineAccumulator, type SessionTimelineOptions, type SlotTick, type SpawnRecord, type StalePromptRow, TELEPORT_EVENT, TICK_HOLD_MAX_MIN, TIMELINE_GAP_MIN_MS, TIMELINE_TEXT_CAP, TOKEN_CLASSES, type TaskInitiative, type TeleportEvent, type TimelineAgentSpan, type TimelineError, type TimelineErrorBreakdown, type TimelineFileBreakdown, type TimelineFileTouch, type TimelineGap, type TimelineMessage, type TimelineMinuteBucket, type TimelineTokenPoint, type TimelineTokens, type TimelineToolBreakdown, type TimelineToolCall, type TimelineToolOutcome, type TimelineTotals, type TimelineTurn, type TimelineTurnOrigin, type TokenClass, type TokenTimeline, type ToolFamilyCount, type ToolNameCount, type TtlRequestRow, UNKNOWN_PROFILE, UNSTATED_REASON, type UnreportedExit, type UnreportedExitRow, type VerdictRecord, WAKE_FROM_KINDS, type WakeCauseBucket, type WakeCauseEpisodes, type WakeEpisode, type WakeEpisodes, type WakeEventRow, type WakeFromKind, type WakeGapCell, type WakePair, type WorkerFacts, type WorkerRole, type WrittenEpisodes, assignmentCount, bandOf, blockedFlowReport, blockedFlowSchema, buildEpisodes, buildSessionTimeline, buildWakeEpisodes, cacheTtlReport, cacheTtlWhatIf, cacheTtlWhatIfSchema, classifyDeniedAction, classifyRequest, classifySession, contextBand, costPerRequest, costReport, costReportSchema, countAtOrBefore, countMisses, darkGaps, dedupeDenials, episodeNames, findPrice, gapBand, handoffThreshold, handoffThresholdSchema, heuristicFor, idleSlotMinutes, initiativeFromCwd, isBootAction, latencyStats, latencyStatsSchema, livenessReport, livenessSchema, mergeOutcomes, parseBrokerLog, parseDenials, parseSeatJournal, parseTeleportEvents, parseVerdict, prKey, priceRequest, readEpisodeInput, readRequestToolCalls, readTtlRows, renderBlockedFlowText, renderCacheTtlText, renderCostReportSections, renderCostReportText, renderLivenessText, reviewFillReport, reviewFillSchema, roleFromProfile, routeFailureRows, routeMisses, scopeFilter, sessionInitiative, sessionRole, stalePromptRows, summarizeWakeEpisodes, sweepK, unreportedExitRows, wakeEpisodesSchema, workerRole, writeEpisodes };