@titan-design/session-analytics 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -242,6 +242,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 +251,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 +324,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 +333,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 +661,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 +670,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 +1138,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 +1384,276 @@ 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;
+
+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 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, 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 ReviewerComparison, type RoleActions, type RouteFailureRow, type RouteMiss, type RouteMissKind, STANDING_PEER_MIN_ASSIGNMENTS, STANDING_PEER_MIN_HOURS, type SeatJournal, type SessionClass, type SessionClassification, type SessionFacts, type SessionOrigin, type SlotTick, type SpawnRecord, type StalePromptRow, TELEPORT_EVENT, TICK_HOLD_MAX_MIN, TOKEN_CLASSES, type TaskInitiative, type TeleportEvent, type TokenClass, 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, buildWakeEpisodes, cacheTtlReport, cacheTtlWhatIf, cacheTtlWhatIfSchema, classifyDeniedAction, classifyRequest, classifySession, contextBand, costPerRequest, costReport, costReportSchema, 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, roleFromProfile, routeFailureRows, routeMisses, scopeFilter, sessionInitiative, sessionRole, stalePromptRows, summarizeWakeEpisodes, sweepK, unreportedExitRows, wakeEpisodesSchema, workerRole, writeEpisodes };