agent-session-analytics 0.1.0__py3-none-any.whl

agent_session_analytics/_query.py

@@ -0,0 +1,59 @@
+"""Run one read-only query against the session database."""
+
+from __future__ import annotations
+
+import os
+
+from agent_session_analytics._db import (
+    DB_PATH,
+    SCHEMA_VERSION,
+    DatabaseError,
+    IngestError,
+    QueryError,
+    db_is_fresh,
+    db_is_stamped,
+    query_rows,
+    require_duckdb,
+)
+from agent_session_analytics._ingest import build_database
+
+
+def _refresh_default_database() -> None:
+    """Rebuild an old, absent, or wrong-version default database before the query."""
+    if db_is_fresh():
+        return
+    try:
+        _ = build_database()
+    except DatabaseError as error:
+        outcome = (
+            "refusing to query stale data"
+            if os.path.exists(DB_PATH)
+            else "no session database is available"
+        )
+        raise IngestError(
+            f"Automatic ingestion failed ({error}); {outcome}.", exit_code=error.exit_code
+        ) from error
+
+
+def run_query(query: str) -> list[dict[str, object]]:
+    """Return the rows of one read-only query.
+
+    The default database refreshes itself when it is old or has another schema
+    version. A ``SESSIONS_DB`` override never refreshes: a missing database or a
+    schema mismatch is an error, so the caller runs ``ingest`` on purpose.
+    """
+    require_duckdb()
+    if os.environ.get("SESSIONS_DB"):
+        if not os.path.exists(DB_PATH):
+            raise IngestError(f"No session database at {DB_PATH}; run `agent-session-analytics ingest`.")
+        if not db_is_stamped():
+            raise IngestError(
+                f"The database at {DB_PATH} is not at schema version "
+                + f"{SCHEMA_VERSION}; run `agent-session-analytics ingest --force`."
+            )
+    else:
+        _refresh_default_database()
+    try:
+        return query_rows(query)
+    except DatabaseError as error:
+        raise QueryError(str(error)) from error

agent_session_analytics/references/canonical-schema.md

@@ -0,0 +1,149 @@
+# Canonical Schema
+
+Contents: [tool_uses](#tool_uses), [tool_results](#tool_results), [stop_events](#stop_events), [model_turns](#model_turns), [agent_spawns](#agent_spawns), [skill_invocations](#skill_invocations), [mcp_calls](#mcp_calls), [sessions](#sessions), [stop_hooks](#stop_hooks), [permission_denials](#permission_denials), [raw_entries](#raw_entries), [schema_info](#schema_info), [Type gotchas](#type-gotchas).
+
+The shape every harness adapter normalizes into and every analytics pack queries
+against. `agent-session-analytics ingest` loads one canonical row shape (the Claude envelope plus a
+`harness` tag) into `${XDG_CACHE_HOME:-$HOME/.cache}/dotfiles/session-analytics/sessions.duckdb` by default, then flattens it into
+the tables below. **Pack authors: write SQL against these tables; never reach
+into a harness's native format.**
+
+Every session-scoped table carries a `harness` column
+(`claude`/`codex`/`omp`/`pi`/`cursor`/`copilot`). Filter or group by it to
+compare sources; omit it to aggregate across all reachable harnesses.
+
+## `tool_uses`
+
+Flattened from assistant `message.content[]` blocks where `type='tool_use'`.
+
+| Column | Type | Description |
+|--------|------|-------------|
+| harness | VARCHAR | Source harness |
+| tool_name | VARCHAR | Tool invoked (Bash, Read, Edit, Agent, Skill, mcp__*, or a harness-native name like `shell`/`apply_patch`) |
+| tool_use_id | VARCHAR | Unique ID for joining with `tool_results` |
+| input | JSON | Full input object |
+| bash_cmd | VARCHAR | Extracted command (Bash only) |
+| skill_name | VARCHAR | Extracted skill (Skill only — claude) |
+| skill_args | VARCHAR | Extracted args (Skill only — claude) |
+| agent_type | VARCHAR | Extracted subagent_type (Agent only — claude) |
+| agent_desc | VARCHAR | Extracted description (Agent only) |
+| agent_mode | VARCHAR | Extracted mode (Agent only) |
+| grep_pattern | VARCHAR | Extracted pattern (Grep only) |
+| file_path | VARCHAR | Extracted file_path (Read/Edit/Write) |
+| query | VARCHAR | Extracted query (ToolSearch) |
+| timestamp | VARCHAR | ISO timestamp |
+| sessionId | VARCHAR | Session identifier |
+| cwd | VARCHAR | Working directory |
+| gitBranch | VARCHAR | Git branch (claude only) |
+
+## `tool_results`
+
+Flattened from user `message.content[]` blocks where `type='tool_result'`.
+
+| Column | Type | Description |
+|--------|------|-------------|
+| harness | VARCHAR | Source harness |
+| tool_use_id | VARCHAR | Matches `tool_uses.tool_use_id` |
+| content | VARCHAR | Result text (truncated to 500 chars) |
+| is_error | VARCHAR | `'true'` if the call failed (string, not boolean). Never NULL — an absent source flag backfills to `'false'` |
+| is_error_explicit | BOOLEAN | Whether the source block carried the flag. `false` means `is_error` was backfilled (claude omits the flag on most successes) |
+| timestamp | VARCHAR | ISO timestamp |
+| sessionId | VARCHAR | Session identifier |
+
+## `stop_events`
+
+Assistant messages where the model stopped generating (claude, cursor, omp, and pi;
+omp and pi quota stalls show as `error`). Columns: `harness`,
+`stop_reason`, `timestamp`, `sessionId`, `cwd`, `gitBranch`.
+
+## `model_turns`
+
+One row per assistant turn that names a model. Use it for round-trip latency,
+batching, and quota analysis. Claude splits one message
+into several raw entries; this table groups them by `message.id`.
+
+| Column | Type | Description |
+|--------|------|-------------|
+| harness | VARCHAR | Source harness (claude, codex, omp, and pi; cursor names no model; codex rows use the latest `turn_context` model, or `unknown` before the first one) |
+| model | VARCHAR | Model id; omp and pi use `<provider>/<model>`, or the bare model when the log names no provider |
+| stop_reason | VARCHAR | Canonical stop reason; omp and pi `toolUse`/`stop` map to `tool_use`/`end_turn` |
+| error_message | VARCHAR | Provider error text on an `error` stop (omp and pi) |
+| input_tokens / output_tokens / cache_read_tokens / cache_creation_tokens | BIGINT | Token usage for the turn. Codex rows come from `token_count` events: one row per event with a non-null `last_token_usage`, skipping an event whose `total_token_usage` repeats the previous one. Codex `input_tokens` includes cached tokens. Claude `input_tokens` excludes cache reads and cache creation. Only Claude reports `cache_creation_tokens` |
+| context_tokens | BIGINT | One context-size measure for both harnesses. Claude: `input_tokens + cache_read_tokens + cache_creation_tokens`. Other harnesses, including Codex: `input_tokens` |
+| prompt_tokens | BIGINT | Full context size sent for the turn (omp and pi) |
+| duration_ms / ttft_ms | DOUBLE | Model round-trip time and time to first token (omp and pi) |
+| tool_calls | BIGINT | Tool calls issued in the turn; 1 means the turn did not batch. NULL for Codex: its token rows carry no content, so Codex tool calls and `stop_reason` are not measured |
+| timestamp, sessionId, cwd | VARCHAR | Join keys |
+
+## `agent_spawns`
+
+Subset of `tool_uses` for `Agent` (claude) and `Task` (cursor) calls. Columns: `harness`,
+`agent_type` (defaults to `general-purpose`), `description`, `mode`, `anchor_id`,
+`timestamp`, `sessionId`, `cwd`. `anchor_id` is the spawn's `tool_use_id`.
+
+## `skill_invocations`
+
+Subset of `tool_uses` for `Skill` calls (claude). Columns: `harness`,
+`skill_name`, `args`, `anchor_id`, `timestamp`, `sessionId`, `cwd`.
+`anchor_id` is the invocation's `tool_use_id`. Window queries use it to exclude the anchor event.
+`anchor_id` is NULL when the log names no tool call id.
+
+## `mcp_calls`
+
+Subset of `tool_uses` where `tool_name LIKE 'mcp__%'`. Same columns as
+`tool_uses`. Names are harness-specific: Claude and Cursor use
+`mcp__<server>__<method>`, while Pi and OMP preserve
+`mcp__<server>_<method>`. Consumers must branch on `harness`; for Pi-family
+rows, split the suffix once at the first underscore.
+
+## `sessions`
+
+One row per `(harness, sessionId, cwd, branch)`. Columns: `harness`,
+`sessionId`, `first_seen`, `last_seen`, `project` (cwd), `branch`, `version`,
+`parent_session_id`, `entry_count`. `version` is the harness CLI version (Claude `version`, Codex
+`session_meta.cli_version`) of the latest entry by timestamp. It is NULL when
+the log names none.
+`entry_count` counts the rows of the session in `raw_entries` except Codex `token_usage` rows. Those rows are synthetic and feed only `model_turns`.
+`parent_session_id` is the Codex `source.subagent.thread_spawn.parent_thread_id` of a sub-agent rollout. It is NULL for any other session.
+A forked Codex sub-agent rollout counts as a standalone session with its own `sessionId`. A Claude sidechain keeps the parent `sessionId`.
+
+## `stop_hooks`
+
+System entries with subtype `stop_hook_summary` (claude only — codex/omp emit
+none). Columns: `harness`, `timestamp`, `sessionId`, `hookCount`,
+`hookInfos` (JSON), `hookErrors` (JSON), `preventedContinuation`, `stopReason`,
+`hasOutput`, `level`.
+
+## `permission_denials`
+
+Pre-filtered `tool_results` for permission/hook denials (claude-dominant).
+Columns: `harness`, `content`, `sessionId`, `timestamp`.
+
+## `raw_entries`
+
+The full unflattened canonical rows (post-adapter). Carries `harness` plus every
+column in the ingest engine's `RAW_COLUMNS`. Use only when the materialized tables
+lack a field you need.
+
+## `schema_info`
+
+One row with one integer column, `version`. It holds the schema version of the
+database. `agent-session-analytics ingest` rebuilds a database whose version differs
+from the package version, even inside the one-hour freshness window.
+
+## Type gotchas
+
+- `is_error` is VARCHAR `'true'`/`'false'` — compare as strings. It is never
+  NULL: an absent source flag is backfilled to `'false'` (`is_error_explicit`
+  records which rows were backfilled). Measured on claude logs: ~99.5% of
+  absent-flag results carry non-error content, so the backfill is sound;
+  claude error rates remain floors, not exact estimates.
+- `is_error_explicit` is a real BOOLEAN — `-json` prints it bare
+  (`true`/`false`), unlike the VARCHAR `is_error`.
+- Timestamps are VARCHAR ISO strings — cast for date math (`timestamp::TIMESTAMP`,
+  `timestamp::DATE`).
+- DuckDB CLI `-json` preserves column types: BOOLEAN/BIGINT print bare, the
+  schema's many VARCHAR columns print as strings.
+- Empty result sets print `[]`.
+- `input` is JSON — use `json_extract_string()` for fields not already
+  materialized as columns.

agent_session_analytics/references/harness-coverage.md

@@ -0,0 +1,182 @@
+# Harness Coverage
+
+Contents: [Coverage status](#coverage-status), [Per-harness format notes](#per-harness-format-notes), [Signal-quality caveats](#signal-quality-caveats).
+
+Which coding-agent harnesses the analytics layer ingests, where their session
+logs live, and how each is parsed. `agent-session-analytics ingest` runs one **normalizing adapter**
+per harness; every adapter is discovery-gated and best-effort. A harness with no
+accessible logs is recorded here and skipped non-fatally — full coverage of what
+is reachable, not parsing the unparseable.
+
+Every canonical table carries a `harness` column (`claude` / `codex` / `omp` /
+`pi` / `cursor` / `copilot`) so one query can compare sources. See
+the schema reference for the table shapes.
+
+## Coverage status
+
+| Harness | Log location | Format | Adapter | Status |
+|---------|-------------|--------|---------|--------|
+| claude | `~/.claude/projects/**/*.jsonl` | JSONL, one turn per line; assistant/user `message.content[]` blocks | `claude_normalize` (pass-through, already canonical) | parsed |
+| codex | `~/.codex/sessions/**/*.jsonl` | JSONL rollout; `session_meta` + `response_item`/`event_msg` payloads | `codex_normalize` | parsed |
+| omp | `~/.omp/agent/sessions/<flattened-project-dir>/*.jsonl` | JSONL; `session` header + `message` entries with `toolCall` / `toolResult` | `omp_normalize` | parsed |
+| pi | `~/.pi/agent/sessions/<flattened-project-dir>/*.jsonl` | Pi-family JSONL | `pi_normalize` | parsed |
+| cursor | `~/.cursor/projects/<project-slug>/agent-transcripts/<uuid>/<uuid>.jsonl` (+ `subagents/*.jsonl`) | JSONL, one message per line; `role`/`message.content[]` blocks, plus `turn_ended` status lines | `cursor_normalize` | parsed |
+| copilot | `~/.copilot/` | holds `skills/` + `mcp-config.json` only; no local transcript found | none | **no accessible logs** |
+
+## Per-harness format notes
+
+### claude
+
+Native format is already the canonical envelope (`type`, `timestamp`,
+`sessionId`, `cwd`, `gitBranch`, `message.content[]`). The adapter only tags
+`harness='claude'`. Subagent JSONL lives in `subagents/` subdirectories — picked
+up by the recursive walk, but those turns have no direct user interaction (no
+stop events, no denials).
+
+Claude omits `is_error` on most successful tool results. The flattener
+backfills those to `'false'` and marks them `is_error_explicit = false`.
+Measured: ~99.5% of absent-flag results carry non-error content.
+Claude error rates are therefore floors, because a handful of harness-side truncation notices lack the flag.
+
+**`bash_cmd` is the model-typed command, pre-hook.** A PreToolUse
+`updatedInput` rewrite can execute a different command while the transcript
+records the original. Hook rewrite coverage is therefore not measurable from
+Claude transcripts.
+
+### codex
+
+A forked Codex sub-agent writes its own rollout, so it counts as a standalone session. A Claude sidechain keeps the parent `sessionId`.
+
+Rollout JSONL. Each line is `{timestamp, type, payload}`:
+
+- `session_meta` — `payload.id` (session id) + `payload.cwd`. Threaded onto every
+  following row in the file.
+- `turn_context` — refreshes `payload.cwd`.
+- `response_item / function_call` and `custom_tool_call` → an assistant
+  `tool_use` block. The tool name (`shell`, `exec_command`, `exec`,
+  `apply_patch`, custom tools) is kept verbatim; `arguments` is JSON-parsed
+  into `input`. For shell-ish tools, `input.command` is **normalized to the
+  executed command string**, so `bash_cmd` populates.
+  `exec_command` copies `cmd`. Legacy `shell` argv arrays collapse to the
+  `-lc`/`-c` payload (or a space-join).
+  The `exec` custom tool's raw code-string argument becomes the command.
+- `response_item / function_call_output` **and `custom_tool_call_output`** → a
+  user `tool_result` block. (Dropping the custom outputs was the ~50%
+  result-join gap — issue #704.) `tool_search_output` items have no matching
+  call item and are dropped.
+
+Codex has no `Skill` / `Agent` tool primitives, so `skill_invocations` and
+`agent_spawns` stay claude-centric. `reasoning` items (encrypted) are dropped.
+
+- Structured `exit_code` (including negative values), failed status, `isError`/`is_error` true, and legacy `Process exited with code N` markers set `is_error`. Pending and successful session outputs remain non-errors. Wrapper parsing trusts complete JSON or an `Output:` JSON envelope, not arbitrary prose. Content-block arrays require an execution header in the first `input_text` block. The parser processes later JSON blocks independently.
+- Wrapper-level errors are lower bounds. Nested function or MCP calls can produce different counts. The adapter omits native Codex timing and user records. It reads two other records. `session_meta.cli_version` becomes `raw_entries.version` on every entry of the session. The first `session_meta` of a sub-agent rollout names its parent in `source.subagent.thread_spawn.parent_thread_id`; that id becomes `raw_entries.parentSessionId` and `sessions.parent_session_id`. Each `event_msg` `token_count` event with a non-null `last_token_usage` becomes one `raw_entries` row of `type` `token_usage`. Only `model_turns` reads that row; `tool_uses`, `stop_events`, and `sessions.entry_count` do not. The row takes its model from the latest `turn_context`, or `unknown` before the first one, and its tokens from `last_token_usage`. The adapter skips an event whose `total_token_usage` repeats the previous event. Other `event_msg` records stay omitted.
+- Codex `is_error` values are adapter-derived. `explicit_error_flag_pct` does not establish source evidence for inferred wrapper, status, or exit-code signals.
+
+### omp and pi
+
+Both harnesses use Pi-family session JSONL, one file per session under a flattened-path project dir
+(e.g. `-Dev-dotfiles`). The `session` header entry (`{type:'session', id, cwd,
+timestamp, title}`) supplies sessionId + cwd for every row. `message` entries:
+
+- assistant `toolCall` content blocks → `tool_use` (`arguments` becomes `input`,
+  so `bash_cmd` extracts from `input.command`); `text`/`thinking` blocks pass
+  through;
+- role `toolResult` → a user `tool_result` block, joined on `toolCallId`;
+- role `user` passes through;
+- assistant `model`, `usage`, `duration`, `ttft`, `contextSnapshot.promptTokens`,
+  `stopReason`, and `errorMessage` map to Claude key names and feed
+  `model_turns`. `stopReason` `error` and `aborted` also land in `stop_events`.
+
+Error flag: every `toolResult` message carries a **msg-level `isError` boolean**.
+It is one convention for builtin and MCP tools.
+For MCP tools a duplicate flag lives
+at `details.xdev.inner.isError`. It matches the msg-level flag across all sessions, so the adapter reads only the msg-level one.
+
+OMP-specific caveats:
+
+- **MCP naming** is a third scheme: `mcp__tilth_search` = `mcp__` + server +
+  *single* underscore + tool.
+  These rows land in `mcp_calls`, because the `mcp__%` prefix filter matches.
+  A query that splits server and method on a double-underscore separator misparses omp names.
+  Split on the prefix + first `_` instead when filtering `harness='omp'`.
+- **Shaken content**: context-compacted tool results are stored as a stub like
+  `[shaken ~275 tokens — recover: artifact://46 (region 2)]`. Kept verbatim —
+  content-based metrics (result length, error-text matching) undercount for
+  shaken rows.
+- **Tool-call id reuse**: `toolCall` ids (`write_0|fc_...`) are not globally
+  unique. A small fraction (~0.3%) repeat across sessions, so session-agnostic
+  `tool_use_id` joins can slightly overcount.
+  Join on `sessionId` too when exactness matters.
+
+### cursor
+
+Each transcript file (top-level or `subagents/<uuid>.jsonl`) is one session,
+session id = the uuid filename. Lines are `{"role": "user"|"assistant",
+"message": {"content": [...]}}` or `{"type": "turn_ended", "status": ...}`;
+content blocks are only `text` and `tool_use` (`{"type":"tool_use","name":...,
+"input":{...}}`).
+
+`cwd` is decoded from the project-slug directory name (dashes stand in for
+slashes).
+A directory whose own name contains a dash is ambiguous if every dash
+is a separator.
+So the adapter walks left-to-right. At each step it takes the longest prefix of remaining segments that exists on disk
+(`Users-paul-Dev-easy-cheese` → `/Users/paul/Dev/easy-cheese` when that path is
+real). Unresolved tails fall back to a naive split. `gitBranch` is always null
+(not recorded).
+
+Cursor tool_use blocks carry no id. There are no `tool_result` blocks at
+all: no result content, no `is_error`, no per-call timestamps.
+The adapter synthesizes a deterministic `tool_use_id` (`session:line:block_idx`), since
+nothing needs to join against it.
+It stamps every row with the most recent
+`<timestamp>Weekday, Mon D, YYYY, H:MM AM (UTC±N)</timestamp>` tag seen in a
+prior user turn (embedded alongside `<user_query>`).
+The adapter converts the tag to UTC and carries it forward, so cursor timestamps are turn-granularity, not per-call.
+Because of this, cursor has 0% `results_joined_pct` by construction (not a
+measurement gap) and is excluded from any error-rate query.
+
+`CallMcpTool` calls that carry both `server` and `toolName`
+(`{"name":"CallMcpTool","input":{"server":..., "toolName":...}}`) are remapped
+to `mcp__<server>__<toolName>` to match the `mcp__%` filter and the
+double-underscore split convention used by claude/codex. Incomplete wrappers
+(missing either key — observed on a subset of live transcripts) keep the native
+`CallMcpTool` name rather than collapsing to `mcp__None__None`. The remapped
+row's `input` stays the wrapper object (`server` / `toolName` / `arguments`);
+packs that read MCP args from `input.query` / `input.cwd` will see those fields
+under `input.arguments` for cursor.
+
+Cursor dispatches sub-agents with `Task` (not Claude's `Agent`). `agent_spawns`
+includes both names so cursor Task rows land there; `subagent_type` still fills
+`agent_type`. Each `subagents/<uuid>.jsonl` file is its own `sessionId`, but the
+adapter sets `isSidechain=true` and `parentUuid` to the parent transcript uuid
+so reconstruction can join the same way Claude packs use `isSidechain`.
+Discovery only walks `**/agent-transcripts/**/*.jsonl` — other JSONL under
+`~/.cursor/projects` is ignored.
+
+`turn_ended` lines (`{"status":"success"|"error"}`) become a stop_events row
+with `stop_reason` set to the status string. User-abort errors
+(`"error": "User aborted request"`) map to `aborted` instead of sharing
+`error` with model failures. The flattening SQL's stop_reason filter lists
+claude's `end_turn`/`stop_sequence`/`max_tokens` and cursor's
+`success`/`error`/`aborted`.
+
+### copilot — no accessible logs
+
+The GitHub Copilot CLI keeps no local session transcript we can locate
+(`~/.copilot` holds only `skills/` and `mcp-config.json`). Discover returns `[]`.
+Re-evaluate if a transcript store appears.
+
+## Signal-quality caveats
+
+Some metrics are only reliable on harnesses that record the underlying field —
+e.g. token/cost data is absent from most logs (`token-economics` degrades to
+"insufficient signal"), and Codex/OMP/Pi lack Claude's hook + permission-denial
+entries, so `stop_hooks` / `permission_denials` are effectively claude-only.
+Packs must degrade gracefully rather than fabricate.
+
+`agent-session-analytics ingest` returns a per-harness **coverage** list after every rebuild. It has two fields.
+`results_joined_pct` counts tool calls with a joined result. A low value means per-tool error rates for that harness are floors, not estimates.
+`explicit_error_flag_pct` counts results whose error flag came from the source rather than the `'false'` backfill.
+Read it before quoting cross-harness error-rate comparisons.
+An empty `model_turns` result or zero errors is not evidence of speed or no failures. Unsupported native events and missing result joins can produce both outcomes. Inspect native Codex JSONL read-only before making either claim.

agent_session_analytics/references/query-conventions.md

@@ -0,0 +1,91 @@
+# Query & Pack-Authoring Conventions
+
+Conventions every analytics **pack** relies on. A pack is a skill-owned file at
+`skills/<skill>/references/<domain>.md` describing one analytics domain. One
+fresh read-only pack context runs exactly one pack, reading the *queries* from
+the pack and the *schema* from the schema reference of this package.
+
+## Pack file shape
+
+```
+# Pack: <domain>
+# target_param: {TARGET}   — the placeholder queries substitute
+# target_kind: skill or agent, from the dispatch prompt
+# start table: {START_TABLE} and {NAME_COLUMN}, set from target_kind (see Substitution)
+# harness: <how the pack uses the harness filter>
+# queries: ordered list of {name, sql}   — sql references the canonical schema
+# output_format: a markdown template the digest fills
+
+## 1. <query name>
+```sql
+SELECT ... FROM tool_uses WHERE ... ;
+```
+
+...
+
+## Output Format
+
+```
+<markdown template — what the ~2 KB digest looks like>
+```
+
+```
+
+Keep a pack to ~4-6 queries. The digest the agent returns must fit ~2 KB.
+
+## Harness filtering
+
+Every spawn carries a `harness=<all|claude|codex|omp|pi|cursor|copilot>`
+parameter. In pack SQL:
+
+- `harness='all'` → omit the harness predicate (aggregate every reachable source).
+- a specific harness → add `WHERE harness = '<name>'` (or `AND harness = ...`).
+
+State in the pack header which mode it expects. Domains that depend on
+claude-only fields (`stop_hooks`, `permission_denials`, `skill_invocations`)
+should say so and degrade to "insufficient signal" on other harnesses rather
+than report zero as if it were meaningful. `agent_spawns` includes Claude
+`Agent` and Cursor `Task`.
+
+## Substitution
+
+Queries use the placeholders that `target_param` and the pack header name
+(e.g. `{TARGET}`, `{START_TABLE}`, `{NAME_COLUMN}`). The caller substitutes the
+literal values before running. Quote the target as a string literal in SQL
+(`WHERE {NAME_COLUMN} = '{TARGET}'`).
+
+A pack that serves both skills and agents takes `target_kind` from the dispatch
+prompt. It sets `{START_TABLE}` and `{NAME_COLUMN}` from this mapping:
+
+- `skill`: `skill_invocations`, `skill_name`
+- `agent`: `agent_spawns`, `agent_type`
+
+## Empty results
+
+If a query returns `[]`, note "no data" for that section and continue — never
+block on one empty result. A pack that returns all-empty should say
+"insufficient signal", not invent findings.
+
+## Running queries
+
+A pack context queries the supplied `database` input. It never runs `ingest`
+or `db-path`. Run each query with the DuckDB CLI:
+
+```bash
+duckdb -init /dev/null -readonly <database> -json -c "SQL"
+```
+
+The `-init /dev/null` flag skips `~/.duckdbrc`. The `-readonly` flag blocks
+writes. The `-json` flag gives machine-readable output.
+
+## Signal-quality honesty
+
+Three domains are known low/medium-signal and must degrade gracefully:
+
+- `token-economics` — token/cost fields are usually absent from logs.
+- `routing-accuracy` — no intent ground-truth exists; correlational at best.
+- `knowledge-gaps` — medium-signal inference.
+
+Record the caveat in the pack and emit "insufficient signal" rather than
+fabricate a confident finding. This pairs with the confidence axis of the calling
+skill's calibration reference (`<don't know>` is never surfaced).

agent_session_analytics-0.1.0.dist-info/METADATA

@@ -0,0 +1,122 @@
+Metadata-Version: 2.5
+Name: agent-session-analytics
+Version: 0.1.0
+Summary: Ingest coding-agent session logs into DuckDB and query them read-only.
+Project-URL: Homepage, https://github.com/paulnsorensen/skillz-that-grillz/tree/main/packages/agent-session-analytics
+Project-URL: Source, https://github.com/paulnsorensen/skillz-that-grillz/tree/main/packages/agent-session-analytics
+Project-URL: Issues, https://github.com/paulnsorensen/skillz-that-grillz/issues
+Project-URL: Changelog, https://github.com/paulnsorensen/skillz-that-grillz/blob/main/packages/agent-session-analytics/CHANGELOG.md
+Author-email: Paul Sorensen <paulnsorensen@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,analytics,duckdb,session-logs
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: fromargs<0.3,>=0.2.0
+Description-Content-Type: text/markdown
+
+# agent-session-analytics
+
+`agent-session-analytics` ingests the session logs of coding agents into one DuckDB
+database. It then answers SQL queries that cannot write or run commands. It
+supports the Claude Code, Codex, Cursor, OMP, and pi harnesses.
+
+The package ships engine primitives only. It has no canned reports. A caller
+writes its own SQL against the schema.
+
+## Install
+
+```bash
+uv tool install agent-session-analytics
+# or
+pip install agent-session-analytics
+```
+
+The only runtime dependency is `fromargs`. The package calls the `duckdb`
+command-line tool and does not need the Python `duckdb` module. Install DuckDB
+with one of these commands:
+
+```bash
+uv tool install duckdb-cli
+brew install duckdb
+mise use -g duckdb
+curl https://install.duckdb.org | sh
+```
+
+The package never downloads DuckDB. When `duckdb` is not on `PATH`, `ingest`
+and `sql` exit 3 and print these options.
+
+## Commands
+
+Every command prints one JSON document on stdout. Every error is one JSON line
+on stderr: `{"error": <message>, "exit_code": <n>}`.
+
+| Command | Result |
+|---|---|
+| `ingest [--force]` | Build or refresh the database. A database inside the one-hour freshness window with the current schema version keeps its data. |
+| `db-path` | The resolved database path, as `{"path": "<abs path>"}`. |
+| `sql <query>` | The rows of one query in DuckDB safe mode. |
+| `schema` | The canonical schema reference. |
+
+```bash
+agent-session-analytics ingest
+agent-session-analytics db-path | jq -r .path
+agent-session-analytics sql "SELECT harness, count(*) AS sessions FROM sessions GROUP BY harness"
+```
+
+`sql` opens the database read-only and runs in DuckDB safe mode. Safe mode
+rejects shell commands, file writes, and reads of files outside the database.
+A rejected query exits 5.
+
+`sql` ingests an old or absent default database first. It does not ingest a
+`SESSIONS_DB` override. It never queries stale data after a failed ingest.
+
+A consumer that queries the database directly runs
+`duckdb -init /dev/null -readonly <database> -json -c "<sql>"`, where
+`<database>` is the `path` field of `db-path`.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 2 | Bad input |
+| 3 | The `duckdb` command is missing |
+| 4 | Ingest failed or timed out, or the database is missing, unreadable, or has another schema version |
+| 5 | DuckDB rejects the query, or the query times out |
+
+## Database path
+
+- `SESSIONS_DB` names the database. A relative value joins the current
+  directory. The package does not expand `~` in a set value.
+- Otherwise an absolute `XDG_CACHE_HOME` selects
+  `<cache>/dotfiles/session-analytics/sessions.duckdb`. A relative or unset
+  value uses `~/.cache`.
+- `SESSIONS_DUCKDB_MEMORY_LIMIT` sets the DuckDB memory limit. The default is
+  `8GB`.
+- `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, and `CURSOR_HOME` move the log roots.
+
+Ingest writes the transient `<db>.tmp` and `<db>.stage`, and a persistent
+`<db>.lock`. An `fcntl` lock serializes ingest runs. Ingest uses umask `077`.
+
+## Schema version
+
+The database holds a one-row `schema_info` table with an integer `version`.
+The package version of that integer is `SCHEMA_VERSION`. `ingest` rebuilds a
+database whose stored version differs, even inside the freshness window. `sql`
+treats a mismatch like a stale database. Only this repository changes the
+schema.
+
+## References
+
+These files ship as package data in `agent_session_analytics/references/`:
+
+- `canonical-schema.md` — tables and columns. `agent-session-analytics schema` prints it.
+- `harness-coverage.md` — what each harness log provides.
+- `query-conventions.md` — rules for writing queries.

agent_session_analytics-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+agent_session_analytics/__init__.py,sha256=JYunnFVOxSPkQ-qpK6yaT26Ldo8u-xy25j4UKtSxtDg,144
+agent_session_analytics/__main__.py,sha256=WcZXdTlpnj_PI7T13h3ExSWAiuWY_8Bfx2ZpzRJux7A,71
+agent_session_analytics/_cli.py,sha256=HOZZfYkRW7FVTle33Sve9aJJ_lFJvHBOHBuOrDRkQfQ,1773
+agent_session_analytics/_db.py,sha256=4Kycvtb1hXVO4Jmr2e2SkHi37nq8lhr-rv1PlRKz7Es,5469
+agent_session_analytics/_ingest.py,sha256=AsHkZEuLj37hXDOTYZdRKpLWlY3X-MA5FDE1pSciDAs,45360
+agent_session_analytics/_query.py,sha256=mkLo5gA_lC43YoThz2a64mc8PpZPvyYMYVbqqE-dteg,1866
+agent_session_analytics/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agent_session_analytics/references/canonical-schema.md,sha256=g_ZO4j00V_VHm4d6cc4RHd0R2gLcZ7HwUJx-b-yN0nw,8397
+agent_session_analytics/references/harness-coverage.md,sha256=zYlORs58ReZMVn2ru5R4TTwnaOR54e7GHw1hsSGKQ0I,11909
+agent_session_analytics/references/query-conventions.md,sha256=LefSUBa0yIeAKKLKvreo5OTiLzzSIVeYHbXlYf_AMbk,3241
+agent_session_analytics-0.1.0.dist-info/METADATA,sha256=8J4NED3p4t67qkeRC3pDXWksY3-jidh-ElxhbWzgjhI,4770
+agent_session_analytics-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+agent_session_analytics-0.1.0.dist-info/entry_points.txt,sha256=lYN2Drp1wruwNv9njqFhRIvUr6rbCei9HfMjlLkmxYw,73
+agent_session_analytics-0.1.0.dist-info/licenses/LICENSE,sha256=lT2oNYDRyYDND9T_fYwnp7OrBEzjeEM5-1Nn9u6FL-g,1070
+agent_session_analytics-0.1.0.dist-info/RECORD,,

agent_session_analytics-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_session_analytics-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agent-session-analytics = agent_session_analytics:main

agent_session_analytics-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Sorensen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.