@ironbee-ai/cli 0.6.2 → 0.7.0

package/dist/analytics/types.d.ts

@@ -0,0 +1,875 @@
+/**
+ * IronBee CLI — Analytics Types
+ *
+ * Type definitions for the analytics collection pipeline. The CLI projects
+ * the host transcript JSONL into a `SessionAnalytics` record (no content)
+ * and ships it to the IronBee collector as a `session_analytics` event.
+ *
+ * Privacy invariant: no field in any of these types ever holds raw
+ * user-prompt text or assistant-text content. Every field is structured
+ * metadata, count, label, byte size, or timestamp. The projection reads
+ * content locally for keyword matching / byte counting but emits only
+ * derived structural signals.
+ *
+ * Wire shape: top-level scalar fields are grouped into cohesive nested
+ * objects (`time`, `turns`, `classification`, `usage`, `tool_meta`,
+ * `code_changes`, `errors`, `user_activity`, `context_tokens`,
+ * `process_errors`, `user_messages`). Per-tool measurement is byte-based
+ * (`input_size`, `output_size`) plus a heuristic `approximated_*_tokens`;
+ * there is no per-tool token attribution and no `unattributed_*` residual.
+ */
+/**
+ * Current schema_version emitted on the wire. Kept at "1.0" by operator
+ * choice — the internal refactor (logical groups + byte-based ToolUsage)
+ * doesn't bump the wire-version; backend migrates to the new shape under
+ * the same `schema_version: "1.0"` label.
+ */
+export declare const SCHEMA_VERSION: string;
+/** Turn-bucket keys for context_tokens distribution. Bucketed by assistant message index. */
+export type ContextTurnBucket = "1-3" | "4-10" | "11-25" | "26-50" | "51-100" | "100+";
+/** Closed list of error categories derived from tool_result.content keyword match. */
+export type ToolErrorCategory = "command_failed" | "user_rejected" | "edit_failed" | "file_changed" | "file_too_large" | "file_not_found" | "other";
+export type TranscriptSource = "claude-code" | "cursor" | "missing";
+/**
+ * Per-turn category label assigned by the heuristic classifier in
+ * `src/analytics/classifier.ts`. Mirrors codeburn's taxonomy with extended
+ * pattern coverage (more runtimes / frameworks). Closed string union — add
+ * a new value here if the classifier introduces a new bucket.
+ */
+export type TurnCategory = "coding" | "debugging" | "feature" | "refactoring" | "testing" | "exploration" | "planning" | "delegation" | "git" | "build/deploy" | "conversation" | "brainstorming" | "general";
+/**
+ * Session-wide shape inferred from per-turn distribution + structural signals.
+ *
+ *   - `quick_question`: very short session, no edits, minimal turns.
+ *   - `exploration`: read-heavy with little/no editing.
+ *   - `iterative_refinement`: many edits to a small concentrated set of files.
+ *   - `multi_task`: ≥3 distinct human prompts (the user moved across tasks).
+ *   - `single_task`: focused; default when no other shape applies.
+ *   - `general`: not enough signal yet (e.g. fresh init, no human-user msg).
+ *
+ * Recomputed from `classification.category_breakdown` + bounds at every merge.
+ */
+export type SessionType = "quick_question" | "exploration" | "iterative_refinement" | "multi_task" | "single_task" | "general";
+/**
+ * Per-category aggregate stats emitted in `classification.category_breakdown`.
+ * Element-wise additive across deltas (per-key sum of every numeric field).
+ */
+export interface CategoryStats {
+    /** Number of turns classified into this category. */
+    turns: number;
+    /** Of those, how many had at least one Edit/Write tool call. */
+    turns_with_edit: number;
+    /** Of those, how many had at least one Edit→Bash→Edit retry chain. */
+    turns_with_retry: number;
+    /** Total Edit→Bash→Edit retry events across this category. */
+    total_retries: number;
+    /**
+     * Sum of `cost_usd` attributed to the assistant messages within this
+     * category's turns. Approximation — uses the per-message cost from
+     * `pricing.ts`.
+     */
+    cost_usd: number;
+}
+/**
+ * Time-bound aggregates: wall-clock duration, active vs. idle decomposition,
+ * hour-of-day for first / last activity.
+ *
+ *   active = wall-clock - idle (idle = sum of next-msg-is-user gaps)
+ *   start_hour, last_activity_hour are 0..23 local-time, derived from
+ *     start_time / last_activity_time at projection time.
+ */
+export interface TimeMetrics {
+    /** Wall-clock duration in minutes (`last_activity_time - start_time`). Includes idle. */
+    duration_minutes: number;
+    /** Active duration in minutes (`duration_minutes - idle_minutes`, clamped ≥ 0). */
+    active_minutes: number;
+    /** User-idle duration in minutes (sum of pre-user-msg gaps). */
+    idle_minutes: number;
+    /** Hour-of-day (0..23 local) of session start. */
+    start_hour: number;
+    /** Hour-of-day (0..23 local) of last activity. */
+    last_activity_hour: number;
+}
+/**
+ * Per-turn counters at session level. `with_retry` and `one_shot` are
+ * convenience rollups of `classification.category_breakdown[*].turns_with_retry`
+ * and the inverse — surfaced here so backend dashboards don't need to walk the
+ * category map.
+ */
+export interface TurnsMetrics {
+    /** User-typed prompts (count only — privacy fence). */
+    user_count: number;
+    /** Assistant messages emitted across the session. */
+    assistant_count: number;
+    /** Turns with at least one Edit→Bash→Edit retry chain. */
+    with_retry: number;
+    /** Turns with ≥1 edit AND zero retries — first try worked. */
+    one_shot: number;
+}
+/**
+ * Heuristic per-turn classification — distribution + session-wide shape.
+ * `category_breakdown` keys are members of `TurnCategory` typed as open
+ * string for compactness (zero-count categories omitted).
+ */
+export interface ClassificationMetrics {
+    category_breakdown: Record<string, CategoryStats>;
+    session_type: SessionType;
+}
+/**
+ * Anthropic-exact token / cost aggregates. Sourced from `usage.*` on
+ * assistant messages, msg_id deduped, computed via the pricing table in
+ * `src/analytics/pricing.ts`.
+ */
+export interface UsageMetrics {
+    /** Fresh (non-cached) input tokens. */
+    input_tokens: number;
+    output_tokens: number;
+    /** Tokens written into Anthropic prompt cache (1.25× rate). */
+    cache_creation_tokens: number;
+    /** Tokens served from prompt cache (0.1× rate). */
+    cache_read_tokens: number;
+    /** Total estimated USD cost — sum of per-message attributions. */
+    cost_usd: number;
+}
+/**
+ * Aggregate signal about user prompts — count + total bytes + heuristic
+ * token estimate. Privacy: only structured signal, never raw text.
+ *
+ *   `size`                  = sum of `JSON.stringify(message.content).length`
+ *                             for every human-typed user message.
+ *   `approximated_tokens`   = size / BYTES_PER_TOKEN.
+ */
+export interface UserMessagesMetrics {
+    count: number;
+    size: number;
+    approximated_tokens: number;
+}
+/**
+ * Bash-subcommand counts and session-wide tool boolean indicators. Per-tool
+ * breakdowns (tools / mcp_servers / skills / sub_agents / bash_binaries)
+ * remain top-level on the session — they each carry the full ToolUsage
+ * shape and have different keying semantics.
+ */
+export interface ToolMetaMetrics {
+    /** Optional argv[0..1] count map (e.g. `"git commit"` → N). */
+    bash_subcommands?: Record<string, number>;
+    /** Any `Task`/`Agent` tool_use seen — sub-agent invocation. */
+    uses_sub_agent: boolean;
+    /** Any `Skill` tool_use seen. */
+    uses_skill: boolean;
+    /** Any `mcp__<server>__<tool>` tool_use seen. */
+    uses_mcp: boolean;
+    uses_web_search: boolean;
+    uses_web_fetch: boolean;
+}
+/**
+ * File-edit aggregates — modified-file count, line deltas, hot files,
+ * per-language counts. `languages` lives here because it's derived from
+ * file extensions of edits.
+ */
+export interface CodeChangesMetrics {
+    /** Distinct file_paths edited across the session. */
+    files_modified: number;
+    lines_added: number;
+    lines_removed: number;
+    /** Top 5 by edit count. */
+    hot_files: Array<{
+        path: string;
+        change_count: number;
+    }>;
+    /** Per-language counts derived from edited file extensions. */
+    languages: Record<string, number>;
+}
+/**
+ * Tool-error totals + interrupt count. Categories are keyed by
+ * `ToolErrorCategory`; counts are session-wide.
+ */
+export interface ErrorsMetrics {
+    tool_errors_total: number;
+    tool_error_categories: Record<string, number>;
+    /** `[Request interrupted by user]` tool_results across the session. */
+    user_interruptions: number;
+}
+/**
+ * User-activity histograms — when did the user message? Privacy fence:
+ * histograms only, no per-message arrays.
+ *
+ *   `response_time_buckets` — `"2-10s"`, `"10-30s"`, `"30s-1m"`, `"1-2m"`,
+ *     `"2-5m"`, `"5-15m"`, `">15m"` (counter-map, additive)
+ *   `messages_by_hour`      — keys `"0".."23"` (local timezone)
+ *   `messages_by_date`      — keys `"YYYY-MM-DD"` (local timezone)
+ *   `messages_by_weekday`   — keys `"monday".."sunday"` (lowercase, local timezone)
+ */
+export interface UserActivityMetrics {
+    response_time_buckets: Record<string, number>;
+    messages_by_hour: Record<string, number>;
+    messages_by_date: Record<string, number>;
+    messages_by_weekday: Record<string, number>;
+}
+/**
+ * Context-window statistics. `latest` is the most recent assistant
+ * message's total context tokens (input + cache_creation + cache_read).
+ * `peak` is the max observed. `buckets` maps each `ContextTurnBucket` key
+ * to `{sum, count, avg}` where `avg = sum / count`.
+ */
+export interface ContextTokensMetrics {
+    latest: number;
+    peak: number;
+    buckets: Record<string, {
+        sum: number;
+        count: number;
+        avg: number;
+    }>;
+}
+/**
+ * Projection-time errors (parse / format / projector exceptions).
+ * `has` is the convenience boolean (`Object.keys(items).length > 0`).
+ */
+export interface ProcessErrorsMetrics {
+    has: boolean;
+    items: Record<string, ProcessError>;
+}
+/**
+ * The wire payload — fully-accumulated session analytics emitted to the
+ * collector at every Stop hook and SessionEnd. Backend retains the latest
+ * snapshot per session_id via (snapshot_at, offset) lexicographic LWW.
+ *
+ * Top-level scalar fields are grouped into logical objects (`time`,
+ * `turns`, `classification`, `usage`, `code_changes`, …). Identity /
+ * provenance, snapshot meta, and time bounds (ISO strings) stay flat.
+ * Per-tool maps (`tools`, `mcp_servers`, `skills`, `sub_agents`,
+ * `bash_binaries`) and `models` also stay top-level — each has different
+ * keying / merge semantics.
+ */
+export interface SessionAnalytics {
+    session_id: string;
+    /**
+     * Project name (basename of git root or project dir). Same convention as
+     * other IronBee events' `project_name` field — see `resolveProjectName`
+     * in `src/hooks/core/actions.ts`.
+     */
+    project_name: string;
+    /**
+     * Operator email read from per-session state.json (populated at
+     * session-start). Composed at emit time, NOT persisted in accumulated.
+     * Omitted from wire when unset.
+     */
+    user_email?: string;
+    /** semver-ish, e.g. "1.0". Bumped on any projection logic change. */
+    schema_version: string;
+    transcript_source: TranscriptSource;
+    is_final: boolean;
+    /** ISO; when this snapshot was projected. */
+    snapshot_at: string;
+    /** Byte offset in the host transcript JSONL that this snapshot covers up to. */
+    offset: number;
+    /** Only set when is_final and SessionEnd carried a reason. */
+    end_reason?: string;
+    /** ISO. */
+    start_time: string;
+    /** ISO; latest message timestamp seen. */
+    last_activity_time: string;
+    time: TimeMetrics;
+    turns: TurnsMetrics;
+    classification: ClassificationMetrics;
+    usage: UsageMetrics;
+    /**
+     * Per-model breakdown — `assistant.message.model` → usage + cost.
+     * Element-wise additive across deltas (per-key sum on every numeric
+     * field) — see merge.ts.
+     */
+    models: Record<string, ModelUsage>;
+    /** Aggregate user-prompt signal (count + size + approximated_tokens). */
+    user_messages: UserMessagesMetrics;
+    /** Per-tool — `tool_use.name` → ToolUsage. */
+    tools: Record<string, ToolUsage>;
+    /** Per-MCP-server — extracted prefix from `mcp__<server>__<tool>`. */
+    mcp_servers: Record<string, ToolUsage>;
+    /** Per-skill — keyed by `Skill` tool's `input.skill`. */
+    skills: Record<string, ToolUsage>;
+    /** Per-sub-agent — keyed by `Agent`/`Task` tool's `input.subagent_type`. */
+    sub_agents: Record<string, ToolUsage>;
+    /** Per-bash-binary — first token of every Bash command body. */
+    bash_binaries: Record<string, ToolUsage>;
+    tool_meta: ToolMetaMetrics;
+    code_changes: CodeChangesMetrics;
+    errors: ErrorsMetrics;
+    user_activity: UserActivityMetrics;
+    context_tokens: ContextTokensMetrics;
+    process_errors: ProcessErrorsMetrics;
+}
+/**
+ * Per-model usage breakdown. One entry per `assistant.message.model` seen
+ * in the session. Element-wise additive across deltas: matching keys sum
+ * every numeric field; new keys are added.
+ */
+export interface ModelUsage {
+    /** Number of assistant messages emitted by this model. */
+    count: number;
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_tokens: number;
+    cache_read_tokens: number;
+    /** Cost contribution of this model for this session, in USD. */
+    cost_usd: number;
+}
+/**
+ * Per-tool / per-MCP-server / per-skill / per-sub-agent / per-bash-binary
+ * usage breakdown. Byte-based measurement: `input_size` /
+ * `output_size` are exact byte counts; `approximated_*_tokens` is a
+ * single bytes/4 heuristic conversion. There is no per-tool token
+ * attribution — backend recomputes per-tool cost from session-level
+ * Anthropic-exact tokens × pricing rate when needed.
+ *
+ *   `input_size`                — sum of `JSON.stringify(tool_use.input).length`
+ *   `output_size`               — sum of `JSON.stringify(tool_result.content).length`
+ *   `approximated_input_tokens`  = input_size  / BYTES_PER_TOKEN
+ *   `approximated_output_tokens` = output_size / BYTES_PER_TOKEN
+ *
+ * Element-wise additive across deltas. `approximated_*_tokens` are
+ * recomputed from the summed sizes after merge to avoid drift.
+ */
+export interface ToolUsage {
+    count: number;
+    errors: number;
+    input_size: number;
+    output_size: number;
+    approximated_input_tokens: number;
+    approximated_output_tokens: number;
+}
+/**
+ * Captured projection-time error. Recorded into
+ * `accumulated.process_errors.items` (deduped by `errorSignature`) so
+ * analytics consumers can see when the client hit unexpected transcript
+ * shapes / format changes / projector bugs.
+ *
+ * Privacy: `error_message` and `stack_first_lines` are truncated and come
+ * from the JS engine / projector code path — not from user content.
+ */
+export interface ProcessError {
+    /** `Error.name` (e.g. "TypeError"). */
+    error_type: string;
+    /** `Error.message`, truncated to 200 chars. */
+    error_message: string;
+    /** First ~3 stack frames, joined by `\n`. Truncated to 800 chars. */
+    stack_first_lines: string;
+    /** How many times this signature was seen across the session. */
+    count: number;
+    /** ISO timestamp of the first occurrence. */
+    first_seen: string;
+    /** ISO timestamp of the most recent occurrence. */
+    last_seen: string;
+    /** Optional short label of where it happened. Truncated to 100 chars. */
+    sample_context?: string;
+}
+/**
+ * Pending tool_use lifecycle entry. Persisted in `state.internal` so a
+ * tool_use emitted in slice K can have its tool_result counted in slice
+ * K+N correctly. No per-tool token attribution — this carries only the
+ * identity needed to look up the tool's bucket when its tool_result
+ * eventually arrives.
+ */
+export interface PendingToolUse {
+    /** Full tool name (keeps `mcp__<server>__<tool>` prefix). */
+    tool_name: string;
+    /** Bash binary name (first non-env token) — set only when tool is Bash. */
+    bash_binary?: string;
+    /** Skill name from `Skill` tool's `input.skill`. */
+    skill_name?: string;
+    /** Sub-agent type from `Agent` / `Task` tool's `input.subagent_type`. */
+    sub_agent_type?: string;
+    /**
+     * `turn_index` of the turn that EMITTED this tool_use. Lets a
+     * late-arriving tool_result detect cross-turn cases.
+     */
+    originating_turn_index?: number;
+}
+/** Fields composed at emit time, never stored in `accumulated`. */
+export type PerTriggerFields = "is_final" | "snapshot_at" | "offset" | "end_reason" | "user_email";
+/**
+ * Accumulated subset of SessionAnalytics — only fields that carry forward
+ * across triggers. Per-trigger metadata is composed live from the trigger.
+ */
+export type AccumulatedAnalytics = Omit<SessionAnalytics, PerTriggerFields>;
+/**
+ * Per-session state file shape (stored at
+ * `<projectDir>/.ironbee/sessions/<session_id>/analytics/state.json`).
+ *
+ * Holds the read cursor + accumulated analytics + idempotency markers +
+ * transcript identity (for reset detection) + internal aggregation maps.
+ */
+export interface AnalyticsSessionState {
+    session_id: string;
+    transcript_path: string;
+    transcript_inode: number;
+    transcript_size_at_last_read: number;
+    transcript_first_kb_sha256: string;
+    /** Byte position to resume reading from (turn-safe — §4.8). */
+    offset: number;
+    /** ISO; touched on every persist for orphan-cleanup (§10.6). */
+    last_read_at: string;
+    last_emitted_offset: number;
+    last_emitted_is_final: boolean;
+    accumulated: AccumulatedAnalytics;
+    internal: {
+        /** Full path→count map; emit's `code_changes.hot_files` = top 5 of this. */
+        file_path_change_counts: Record<string, number>;
+        /** For `code_changes.files_modified` count integrity. Sorted on persist. */
+        distinct_file_paths_seen: string[];
+        /**
+         * ms-since-epoch of the most recent assistant message we've seen.
+         * Used to compute the user-msg gap to the FIRST human-text user
+         * message of the next slice.
+         */
+        last_assistant_ts_ms?: number;
+        /**
+         * Tool_use lifecycle tracking, keyed by `tool_use_id`. Carries an
+         * entry from the emitting assistant N1 until the tool_result arrives.
+         */
+        pending_tool_uses?: Record<string, PendingToolUse>;
+        /**
+         * Cumulative user-idle ms across all merged deltas. Stored at ms
+         * precision; the wire field `time.idle_minutes` is `Math.round(this / 60000)`.
+         */
+        idle_ms_total?: number;
+        /**
+         * In-flight per-turn classifier state. Persists across slice
+         * boundaries when a turn spans slices.
+         */
+        current_turn?: CurrentTurnState;
+        /**
+         * Next turn_index to assign when a fresh turn opens. Starts at 1.
+         */
+        next_turn_index?: number;
+        /**
+         * Built `SessionTurnAnalytics` records that have closed and are
+         * waiting for emit to drain to the collector.
+         */
+        pending_turn_events?: SessionTurnAnalytics[];
+        /**
+         * Built `SessionTurnStepAnalytics` records that have closed (their
+         * parent turn closed) and are waiting for emit to drain.
+         */
+        pending_step_events?: SessionTurnStepAnalytics[];
+        /**
+         * Built `APIRequestAnalytics` body-only records (one per assistant
+         * line in this and prior slices that haven't been drained yet).
+         * Emit drains these as `api_request` wire events alongside
+         * session_turn / session_turn_step.
+         */
+        pending_api_request_events?: APIRequestAnalytics[];
+        /**
+         * Anthropic API message ids already counted across all prior slices.
+         * Claude Code's transcript writer occasionally persists the same
+         * assistant API response on multiple JSONL lines; projection skips
+         * any assistant line whose `message.id` is in this set so a single
+         * API call counts once toward tokens / cost.
+         */
+        seen_assistant_message_ids?: string[];
+    };
+}
+/**
+ * In-flight signal accumulator for a single turn. Built by the projection
+ * walk and consumed by `classifyTurn` when the turn closes.
+ *
+ * Privacy: every field is a boolean / number — no raw content text.
+ *
+ * The per-turn aggregator carries the same logical structure as the wire
+ * `SessionTurnAnalytics` (groups: usage, tool_meta, code_changes, errors).
+ * Tokens / cost stay flat in the accumulator (`UsageMetrics`-shaped fields
+ * are folded into `usage` at delta-build time).
+ */
+export interface CurrentTurnState {
+    /** 1-based turn index within the session (assigned at openTurn). */
+    turn_index: number;
+    /** ISO timestamp of the opening human-user msg (this turn's start_time). */
+    start_time: string;
+    /**
+     * What opened this turn. Set at openTurn time based on whether the
+     * opening user msg carried `isMeta: true`.
+     */
+    triggered_by: "user_msg" | "host_inject";
+    /** Regex-match flags from the user prompt that opened this turn. */
+    kw_debug: boolean;
+    kw_feature: boolean;
+    kw_refactor: boolean;
+    kw_brainstorm: boolean;
+    kw_research: boolean;
+    kw_file_pattern: boolean;
+    kw_script_pattern: boolean;
+    kw_url: boolean;
+    /** Tool-bucket flags accumulated as assistant messages arrive. */
+    has_edit: boolean;
+    has_read: boolean;
+    has_bash: boolean;
+    has_task: boolean;
+    has_search: boolean;
+    has_mcp: boolean;
+    has_skill: boolean;
+    has_plan: boolean;
+    /** Bash command keyword flags accumulated across Bash tool_use bodies. */
+    bash_test: boolean;
+    bash_build: boolean;
+    bash_install: boolean;
+    bash_git: boolean;
+    /**
+     * Edit→Bash→Edit retry detection. `saw_edit_pending_bash` is true after
+     * an Edit until a Bash arrives; seeing the next Edit increments `retries`.
+     */
+    saw_edit_pending_bash: boolean;
+    saw_bash_after_edit: boolean;
+    retries: number;
+    /** Number of assistant messages observed in this turn. */
+    assistant_messages: number;
+    /** Total tool_use blocks observed in this turn. */
+    tool_calls: number;
+    /** Whether the turn was interrupted (tool_result with `[Request interrupted by user]`). */
+    was_interrupted: boolean;
+    /** Most recent message timestamp seen (drives end_time + duration). */
+    last_activity_time: string;
+    /** Tokens (this turn — Anthropic-exact). Folded into `usage` at delta build. */
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_tokens: number;
+    cache_read_tokens: number;
+    /** Sum of per-message cost_usd contributed by assistant messages in this turn. */
+    cost_usd: number;
+    /** Per-turn per-tool/server/binary/skill/sub-agent/model breakdowns. */
+    tools: Record<string, ToolUsage>;
+    mcp_servers: Record<string, ToolUsage>;
+    bash_binaries: Record<string, ToolUsage>;
+    bash_subcommands: Record<string, number>;
+    skills: Record<string, ToolUsage>;
+    sub_agents: Record<string, ToolUsage>;
+    models: Record<string, ModelUsage>;
+    /** Per-turn languages — derived from edited file extensions. Lives in CodeChanges group on wire. */
+    languages: Record<string, number>;
+    /** Per-turn parallels to the session-level `tool_meta.uses_*` booleans. */
+    uses_sub_agent: boolean;
+    uses_skill: boolean;
+    uses_mcp: boolean;
+    uses_web_search: boolean;
+    uses_web_fetch: boolean;
+    /** Files edited in this turn — path → change count. */
+    file_change_counts: Record<string, number>;
+    lines_added: number;
+    lines_removed: number;
+    /** Tool errors observed in this turn (tool_result with is_error=true). */
+    tool_errors: number;
+    tool_error_categories: Record<string, number>;
+    /** Context tokens at every assistant message in this turn. */
+    context_tokens_samples: number[];
+    context_tokens_latest: number;
+    context_tokens_peak: number;
+    /** Projection-time errors during this turn's lines, deduped by signature. */
+    process_errors: Record<string, ProcessError>;
+    /** In-flight per-step accumulator. */
+    current_step?: CurrentStepState;
+    /** Closed steps in this turn that are NOT yet ready to emit. */
+    completed_steps: CurrentStepState[];
+    /** Next `step_index` to assign when a fresh step opens within this turn. */
+    next_step_index: number;
+}
+/**
+ * In-flight signal accumulator for a single step within a turn. A step
+ * boundary = one assistant message + every tool_result that came back
+ * from its tool_uses.
+ *
+ * Privacy: same fence as CurrentTurnState — counts, labels, byte sizes,
+ * no raw text content.
+ */
+export interface CurrentStepState {
+    /** 1-based ordinal within the parent turn (resets per turn). */
+    step_index: number;
+    /** ISO timestamp of the opening assistant message. */
+    start_time: string;
+    /** ISO; updated to the latest tool_result timestamp in this step. */
+    last_activity_time: string;
+    tool_calls: number;
+    /** True if a `[Request interrupted by user]` tool_result landed in this step. */
+    was_interrupted: boolean;
+    /** Tokens / cost (this step only — Anthropic-exact). */
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_tokens: number;
+    cache_read_tokens: number;
+    cost_usd: number;
+    /** Per-step per-tool/server/binary/skill/sub-agent/model breakdowns. */
+    tools: Record<string, ToolUsage>;
+    mcp_servers: Record<string, ToolUsage>;
+    bash_binaries: Record<string, ToolUsage>;
+    bash_subcommands: Record<string, number>;
+    skills: Record<string, ToolUsage>;
+    sub_agents: Record<string, ToolUsage>;
+    models: Record<string, ModelUsage>;
+    languages: Record<string, number>;
+    /** Per-step parallels to the session/turn-level `tool_meta.uses_*` booleans. */
+    uses_sub_agent: boolean;
+    uses_skill: boolean;
+    uses_mcp: boolean;
+    uses_web_search: boolean;
+    uses_web_fetch: boolean;
+    /** Files edited in this step — path → change count. */
+    file_change_counts: Record<string, number>;
+    lines_added: number;
+    lines_removed: number;
+    /** Tool errors observed in this step. */
+    tool_errors: number;
+    tool_error_categories: Record<string, number>;
+    /** Context tokens at this step's assistant message (single sample per step). */
+    context_tokens?: number;
+    /** Projection-time errors during this step's lines. */
+    process_errors: Record<string, ProcessError>;
+}
+/**
+ * Why a turn closed.
+ *
+ * - `stop` — the Stop hook fired (agent finished its current task).
+ * - `session_end` — finalization with an open turn at SessionEnd.
+ * - `next_user_msg` — multiple human-user prompts arrived in a single slice.
+ * - `still_open` — reserved; not emitted in the Stop-closes-turn model.
+ */
+export type TurnEndReason = "stop" | "next_user_msg" | "session_end" | "still_open";
+/**
+ * Per-turn analytics record — one human-user prompt + the assistant
+ * messages and tool_results it triggered. Backend can reconstruct the
+ * session-level `SessionAnalytics` aggregate by merging N of these
+ * records (sum / max / OR per the rules in `merge.ts`).
+ *
+ * Same logical group structure as session, with these differences:
+ *   - `turns` group GONE (turn = 1 turn, redundant)
+ *   - `classification` collapses to single `category` field (not nested)
+ *   - `user_activity` GONE (session-level only)
+ *   - `context_tokens.buckets` GONE (turn has single sample range)
+ */
+export interface SessionTurnAnalytics {
+    session_id: string;
+    project_name: string;
+    user_email?: string;
+    schema_version: string;
+    transcript_source: TranscriptSource;
+    /** 1-based ordinal within the session. */
+    turn_index: number;
+    /**
+     * Deterministic identifier — `sha256(session_id|turn_index|start_time)`
+     * sliced to 16 hex chars. Idempotent across re-emits.
+     */
+    turn_id: string;
+    /**
+     * What opened this turn:
+     *   - `"user_msg"` — a real human-typed user prompt (no `isMeta` flag).
+     *   - `"host_inject"` — a host-injected user msg (`isMeta=true`) opened
+     *     the turn because no turn was open at the time.
+     */
+    triggered_by: "user_msg" | "host_inject";
+    /** ISO; opening human-user message timestamp. */
+    start_time: string;
+    /** ISO; closing event timestamp. */
+    end_time: string;
+    end_reason: TurnEndReason;
+    /** 0..23 derived from start_time (local timezone). */
+    start_hour: number;
+    /** 0..23 derived from end_time (local timezone). */
+    end_hour: number;
+    /** Wall-clock ms of the turn. */
+    duration: number;
+    category: TurnCategory;
+    /** Had at least one Edit/Write AND zero retries → first try worked. */
+    was_one_shot: boolean;
+    /** A `[Request interrupted by user]` tool_result was seen in this turn. */
+    was_interrupted: boolean;
+    assistant_messages: number;
+    tool_calls: number;
+    /** Edit→Bash→Edit retry chain count within this turn. */
+    retries: number;
+    usage: UsageMetrics;
+    tools: Record<string, ToolUsage>;
+    mcp_servers: Record<string, ToolUsage>;
+    bash_binaries: Record<string, ToolUsage>;
+    skills: Record<string, ToolUsage>;
+    sub_agents: Record<string, ToolUsage>;
+    models: Record<string, ModelUsage>;
+    tool_meta: ToolMetaMetrics;
+    code_changes: CodeChangesMetrics;
+    errors: ErrorsMetrics;
+    process_errors: ProcessErrorsMetrics;
+    /**
+     * Context tokens at each assistant message in this turn (in order).
+     * Lets backend reconstruct `context_tokens.buckets` at session level.
+     */
+    context_tokens_samples: number[];
+    /** Last assistant message's context tokens in this turn. */
+    context_tokens_latest: number;
+    /** Max across assistant messages in this turn. */
+    context_tokens_peak: number;
+}
+/**
+ * Per-step analytics record — one assistant message + the tool_results
+ * it received before the next assistant message in the same turn.
+ *
+ * Minimal subset of the group structure — `usage`, per-tool maps,
+ * `errors`, `process_errors`. `tool_meta` and `code_changes` are carried
+ * for reconstruction parity. `context_tokens` is a single optional scalar
+ * (no group wrapper, no buckets).
+ */
+export interface SessionTurnStepAnalytics {
+    session_id: string;
+    project_name: string;
+    user_email?: string;
+    schema_version: string;
+    transcript_source: TranscriptSource;
+    turn_id: string;
+    turn_index: number;
+    triggered_by: "user_msg" | "host_inject";
+    /** Deterministic — `sha256(turn_id|step_index|start_time)[:16]`. */
+    step_id: string;
+    /** 1-based ordinal within the parent turn (resets per turn). */
+    step_index: number;
+    start_time: string;
+    end_time: string;
+    /** 0..23 derived from start_time (local timezone). */
+    start_hour: number;
+    /** 0..23 derived from end_time. */
+    end_hour: number;
+    /** Wall-clock ms of the step. */
+    duration: number;
+    is_last_step: boolean;
+    turn_end_reason?: TurnEndReason;
+    turn_end_time?: string;
+    turn_duration?: number;
+    turn_category?: TurnCategory;
+    turn_was_one_shot?: boolean;
+    turn_was_interrupted?: boolean;
+    /** Always 1 — surfaced for reconstruction sums. */
+    assistant_messages: number;
+    tool_calls: number;
+    was_interrupted: boolean;
+    usage: UsageMetrics;
+    tools: Record<string, ToolUsage>;
+    mcp_servers: Record<string, ToolUsage>;
+    bash_binaries: Record<string, ToolUsage>;
+    skills: Record<string, ToolUsage>;
+    sub_agents: Record<string, ToolUsage>;
+    models: Record<string, ModelUsage>;
+    tool_meta: ToolMetaMetrics;
+    code_changes: CodeChangesMetrics;
+    errors: ErrorsMetrics;
+    process_errors: ProcessErrorsMetrics;
+    /** Context tokens at this step's assistant message (single sample). */
+    context_tokens?: number;
+}
+import { Event } from "../lib/event";
+/**
+ * Wire event format. Extends the generic `Event` base (see
+ * `src/lib/event.ts`) so the collector envelope shape stays uniform
+ * across every event type IronBee emits.
+ */
+export interface SessionAnalyticsEvent extends Event {
+    type: "session_analytics";
+    analytics: SessionAnalytics;
+}
+export interface SessionTurnEvent extends Event {
+    type: "session_turn_analytics";
+    turn: SessionTurnAnalytics;
+}
+export interface SessionTurnStepEvent extends Event {
+    type: "session_turn_step_analytics";
+    step: SessionTurnStepAnalytics;
+}
+/**
+ * Per-API-request body. Mirrors the Java `APIRequestEvent` shape (one
+ * record per assistant message line in the transcript). Stored in
+ * `internal.pending_api_request_events` as the body-only struct; emit
+ * wraps with the {@link Event} envelope at drain time.
+ *
+ * `id` carries the transcript line's top-level `uuid` (verified 100%
+ * presence on real transcripts, both success and failure lines). At
+ * drain time it becomes the wire `Event.id` — deterministic across re-
+ * projections so backend dedup on `(session_id, id)` is safe even when
+ * `request_id` is null (failure case).
+ *
+ * `timestamp_ms` is the line's parsed ISO timestamp, used as the wire
+ * `Event.timestamp` at drain time (semantically: when the API call
+ * completed, not when the wire envelope was constructed).
+ *
+ * Other fields are nullable where the transcript doesn't carry them:
+ *   - `request_id`: present on successful lines (top-level `requestId`);
+ *     ALWAYS absent on `isApiErrorMessage:true` failure lines → null.
+ *   - `error`: present on failure lines (top-level `error`); null on success.
+ *   - `status_code`: rare even on failure (transcript-side; only seen on
+ *     explicit HTTP errors like 429); always null on success.
+ *   - `speed`: usually present on successful lines; null on failures
+ *     (synthetic placeholder messages).
+ *   - `duration`: NEVER populated from transcript — Claude Code's transcript
+ *     does not carry per-API-call latency. Always null in transcript-derived
+ *     events. (Java consumers writing their own APIRequestEvents fill this.)
+ */
+export interface APIRequestAnalytics {
+    id: string;
+    timestamp_ms: number;
+    request_id: string | null;
+    success: boolean;
+    error: string | null;
+    status_code: number | null;
+    model: string;
+    speed: string | null;
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_tokens: number;
+    cache_creation_tokens: number;
+    cost_usd: number;
+    duration: number | null;
+}
+/**
+ * Wire event for a single API request. Flat field layout (no nested body
+ * object) — matches the Java `APIRequestEvent` shape exactly so the
+ * collector schema stays uniform across producers.
+ */
+export interface APIRequestEvent extends Event {
+    type: "api_request";
+    request_id: string | null;
+    success: boolean;
+    error: string | null;
+    status_code: number | null;
+    model: string;
+    speed: string | null;
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_tokens: number;
+    cache_creation_tokens: number;
+    cost_usd: number;
+    duration: number | null;
+}
+/**
+ * Delta produced by projecting a single slice of new transcript bytes.
+ * Same shape as AccumulatedAnalytics with delta-local signals (never
+ * emitted on the wire; merge consumes them and discards).
+ */
+export interface DeltaAnalytics extends AccumulatedAnalytics {
+    /** True if the delta consumed at least one assistant message with usage data. */
+    has_assistant_with_usage: boolean;
+    /**
+     * Tool_uses still in-flight at end of this slice. Merge copies verbatim
+     * into `state.internal.pending_tool_uses`.
+     */
+    closing_pending_tool_uses: Record<string, PendingToolUse>;
+    /** In-flight per-turn classifier state at slice end. `null` between turns. */
+    closing_current_turn: CurrentTurnState | null;
+    /** Turns that completed during this slice. */
+    completed_turns: SessionTurnAnalytics[];
+    /**
+     * Steps belonging to turns that completed during this slice — one entry
+     * per step, in `(turn_index, step_index)` order. Each turn's last step
+     * carries `is_last_step=true` + the turn-bookend fields.
+     */
+    completed_steps: SessionTurnStepAnalytics[];
+    /**
+     * Per-API-request records observed in this slice — one per non-duplicate
+     * assistant message line (success + failure). Body-only structs; emit
+     * wraps with the {@link Event} envelope at drain time. Backend dedup
+     * key: `(session_id, request_id)` for successes; failures carry no
+     * `request_id` so dedup is best-effort (id+timestamp fingerprint).
+     */
+    api_request_events: APIRequestAnalytics[];
+}
+//# sourceMappingURL=types.d.ts.map