agent-session-analytics 0.1.0__tar.gz

agent_session_analytics-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Python
+__pycache__/
+*.pyc
+.venv/
+
+# OS / editor
+.DS_Store
+*.swp
+.idea/
+.vscode/
+
+# Workflow scratch (age/cure/press reports, planning notes)
+.cheese/
+.context/
+
+# Skill-creator iteration workspaces (eval runs, benchmarks, viewer HTML)
+skills/*-workspace/
+
+# Serena MCP — machine-local; not tracked
+.serena/

agent_session_analytics-0.1.0/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+This file records the notable changes to the `agent-session-analytics` distribution.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+The project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+A `0.x` minor release can contain breaking changes.
+
+The `publish agent-session-analytics` workflow reads the section for the tagged version.
+It uses that section as the GitHub release notes.
+To release, move the `Unreleased` entries into a new version section with the date.
+Then set the same version in `packages/agent-session-analytics/pyproject.toml`.
+Push a `agent-session-analytics-v<version>` tag after the release commit merges.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-11
+
+### Added
+
+- The `agent-session-analytics` console script with four JSON commands: `ingest`, `db-path`, `sql`, and `schema`.
+- A schema version stamped in the database. `ingest` rebuilds a database whose version differs, even inside the one-hour freshness window.
+- The engine moves out of the `skillz` skill and merges the dotfiles `session-analytics` engine at dotfiles commit `6ce36879`.
+- Codex `token_usage` rows reach `model_turns`. They do not count in `sessions.entry_count`.
+- The columns `model_turns.cache_creation_tokens`, `model_turns.context_tokens`, `sessions.version`, and `sessions.parent_session_id`.
+- The references `canonical-schema.md`, `harness-coverage.md`, and `query-conventions.md` ship as package data.
+
+### Changed
+
+- Codex `model_turns.tool_calls` is NULL, because Codex token rows carry no content.
+- Cursor timestamps are UTC.
+
+### Removed
+
+- The canned `query.sh` reports. Callers write their own SQL with `sql`.
+
+[Unreleased]: https://github.com/paulnsorensen/skillz-that-grillz/compare/agent-session-analytics-v0.1.0...HEAD
+[0.1.0]: https://github.com/paulnsorensen/skillz-that-grillz/releases/tag/agent-session-analytics-v0.1.0

agent_session_analytics-0.1.0/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.

agent_session_analytics-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,99 @@
+# 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/pyproject.toml

@@ -0,0 +1,60 @@
+[project]
+name = "agent-session-analytics"
+version = "0.1.0"
+description = "Ingest coding-agent session logs into DuckDB and query them read-only."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Paul Sorensen", email = "paulnsorensen@gmail.com" }]
+keywords = ["duckdb", "agent", "session-logs", "analytics"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+]
+dependencies = ["fromargs>=0.2.0,<0.3"]
+
+[project.scripts]
+agent-session-analytics = "agent_session_analytics:main"
+
+[project.urls]
+Homepage = "https://github.com/paulnsorensen/skillz-that-grillz/tree/main/packages/agent-session-analytics"
+Source = "https://github.com/paulnsorensen/skillz-that-grillz/tree/main/packages/agent-session-analytics"
+Issues = "https://github.com/paulnsorensen/skillz-that-grillz/issues"
+Changelog = "https://github.com/paulnsorensen/skillz-that-grillz/blob/main/packages/agent-session-analytics/CHANGELOG.md"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-xdist>=3", "basedpyright==1.40.1"]
+
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agent_session_analytics"]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+  ".venv",
+  "**/__pycache__",
+  "**/.pytest_cache",
+]
+
+[tool.uv.sources]
+fromargs = { workspace = true }
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--strict-markers"
+
+[tool.basedpyright]
+pythonVersion = "3.11"
+# Workspace members share the root .venv.
+venvPath = "../.."
+venv = ".venv"
+include = ["src", "tests"]

agent_session_analytics-0.1.0/src/agent_session_analytics/__init__.py

@@ -0,0 +1,5 @@
+"""Ingest coding-agent session logs into DuckDB and query them read-only."""
+
+from agent_session_analytics._cli import main
+
+__all__ = ["main"]

agent_session_analytics-0.1.0/src/agent_session_analytics/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from agent_session_analytics import main
+
+sys.exit(main())

agent_session_analytics-0.1.0/src/agent_session_analytics/_cli.py

@@ -0,0 +1,57 @@
+"""The `agent-session-analytics` command line: JSON in, JSON out."""
+
+from __future__ import annotations
+
+from importlib import resources
+
+import fromargs
+
+from agent_session_analytics._db import DB_PATH, DatabaseError
+from agent_session_analytics._ingest import ingest as run_ingest
+from agent_session_analytics._query import run_query
+
+app = fromargs.App(
+    "agent-session-analytics",
+    help="Ingest coding-agent session logs into DuckDB and query them read-only.",
+)
+
+SCHEMA_REFERENCE = "canonical-schema.md"
+
+
+def _cli_error(error: DatabaseError) -> fromargs.CliError:
+    return fromargs.CliError(str(error), exit_code=error.exit_code)
+
+
+@app.command
+def ingest(*, force: bool = False) -> dict[str, object]:
+    """Build or refresh the session database. A database under one hour old keeps its data."""
+    try:
+        return run_ingest(force=force)
+    except DatabaseError as error:
+        raise _cli_error(error) from error
+
+
+@app.command
+def db_path() -> dict[str, str]:
+    """Print the resolved database path. SESSIONS_DB and XDG_CACHE_HOME apply."""
+    return {"path": DB_PATH}
+
+
+@app.command
+def sql(query: str) -> list[dict[str, object]]:
+    """Run one read-only query and return its rows. The default database ingests itself when stale."""
+    try:
+        return run_query(query)
+    except DatabaseError as error:
+        raise _cli_error(error) from error
+
+
+@app.command
+def schema() -> dict[str, str]:
+    """Print the canonical schema reference that ships with the package."""
+    reference = resources.files("agent_session_analytics").joinpath("references", SCHEMA_REFERENCE)
+    return {"reference": SCHEMA_REFERENCE, "content": reference.read_text(encoding="utf-8")}
+
+
+def main(argv: list[str] | None = None) -> int:
+    return app.run(argv)

agent_session_analytics-0.1.0/src/agent_session_analytics/_db.py

@@ -0,0 +1,158 @@
+"""The session database: its paths, exit codes, errors, DuckDB runner, and freshness checks."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import time
+from typing import TYPE_CHECKING, cast
+
+if TYPE_CHECKING:
+    from typing import TypeAlias
+
+_JsonValue: TypeAlias = "None | bool | int | float | str | list[_JsonValue] | dict[str, _JsonValue]"
+
+
+def configured_path(name: str, default: str) -> str:
+    # SESSIONS_DB: a set value gets no `~` expansion, and a
+    # relative value joins to cwd. The adapter log roots use the same rule by
+    # choice. Only the built-in default expands `~` to HOME.
+    value = os.environ.get(name) or os.path.expanduser(default)
+    return os.path.abspath(value)
+
+
+def _xdg_cache_home() -> str:
+    # The XDG Base Directory spec requires ignoring a relative value.
+    # No `~` expansion; only an absolute value counts.
+    value = os.environ.get("XDG_CACHE_HOME")
+    if value and value.startswith("/"):
+        return os.path.abspath(value)
+    return os.path.abspath(os.path.expanduser("~/.cache"))
+
+
+DEFAULT_DB_DIR = os.path.join(_xdg_cache_home(), "dotfiles", "session-analytics")
+DB_PATH = configured_path("SESSIONS_DB", os.path.join(DEFAULT_DB_DIR, "sessions.duckdb"))
+DB_DIR = os.path.dirname(DB_PATH)
+DB_TMP_PATH = f"{DB_PATH}.tmp"
+# Derived from the database file name, not DB_DIR, so a SESSIONS_DB pointed
+# into an existing directory never aliases (and rmtree's) that directory's
+# own "stage" subdir.
+STAGE_DIR = f"{DB_PATH}.stage"
+TTL_SECONDS = 3600  # 1 hour
+
+# The schema version is an integer stamped in the one-row `schema_info` table.
+# Raise it on every change to a table or column; a database with another
+# version is stale, so ingest rebuilds it even inside the freshness window.
+SCHEMA_VERSION = 1
+
+EXIT_NO_DUCKDB = 3
+EXIT_INGEST = 4
+EXIT_QUERY = 5
+
+DUCKDB_TIMEOUT_SECONDS = 600
+
+DUCKDB_MISSING = (
+    "DuckDB CLI not found. Install it with one of: "
+    "`uv tool install duckdb-cli`, `brew install duckdb`, `mise use -g duckdb`, "
+    "or `curl https://install.duckdb.org | sh`. Nothing is downloaded automatically."
+)
+
+
+class DatabaseError(Exception):
+    """A database step failed; ``exit_code`` is the CLI exit status."""
+
+    def __init__(self, message: str, *, exit_code: int = EXIT_INGEST) -> None:
+        super().__init__(message)
+        self.exit_code: int = exit_code
+
+
+class IngestError(DatabaseError):
+    """An ingest step failed. The default exit status is 4."""
+
+
+class QueryError(DatabaseError):
+    """A query step failed. The default exit status is 5."""
+
+    def __init__(self, message: str, *, exit_code: int = EXIT_QUERY) -> None:
+        super().__init__(message, exit_code=exit_code)
+
+
+def require_duckdb() -> None:
+    if not shutil.which("duckdb"):
+        raise DatabaseError(DUCKDB_MISSING, exit_code=EXIT_NO_DUCKDB)
+
+
+def _duckdb(sql: str, *, as_json: bool = False) -> str:
+    """Run SQL in the DuckDB CLI.
+
+    The JSON mode reads the database file in read-only safe mode. Safe mode locks
+    the configuration, so the memory limit applies first. The other mode writes
+    the temporary database that ingest builds.
+    """
+    limit = os.environ.get("SESSIONS_DUCKDB_MEMORY_LIMIT") or "8GB"
+    argv = ["duckdb", "-init", "/dev/null"]
+    if as_json:
+        argv += ["-readonly", "-json"]
+    argv += [DB_PATH if as_json else DB_TMP_PATH, "-cmd", f"SET memory_limit='{limit}'"]
+    if as_json:
+        argv += ["-cmd", ".safe_mode"]
+    argv += ["-c", sql]
+    try:
+        result = subprocess.run(
+            argv,
+            capture_output=True,
+            text=True,
+            timeout=DUCKDB_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except subprocess.TimeoutExpired as error:
+        raise DatabaseError(f"DuckDB timed out after {DUCKDB_TIMEOUT_SECONDS} seconds.") from error
+    if result.returncode != 0:
+        raise DatabaseError(f"DuckDB failed: {result.stderr[:500].strip()}")
+    return result.stdout.strip()
+
+
+def run_sql(sql: str) -> None:
+    _ = _duckdb(sql)
+
+
+def query_rows(sql: str) -> list[dict[str, object]]:
+    """Run one read-only query against the database and return its rows."""
+    output = _duckdb(sql, as_json=True)
+    if not output:
+        return []
+    try:
+        rows = cast(_JsonValue, json.loads(output))
+    except json.JSONDecodeError as error:
+        raise DatabaseError(f"DuckDB returned unreadable output: {error}") from error
+    if not isinstance(rows, list):
+        raise DatabaseError("DuckDB returned a non-list result")
+    return [dict(row) for row in rows if isinstance(row, dict)]
+
+
+def stored_schema_version() -> int | None:
+    """The schema version stamped in the database, or None when `schema_info` is missing.
+
+    Every other DuckDB failure, such as a lock conflict or an invalid file, raises.
+    """
+    try:
+        rows = query_rows("SELECT version FROM schema_info")
+    except DatabaseError as error:
+        if "Table with name schema_info does not exist" in str(error):
+            return None
+        raise
+    version = rows[0]["version"] if rows else None
+    return version if isinstance(version, int) else None
+
+
+def db_is_stamped() -> bool:
+    return os.path.exists(DB_PATH) and stored_schema_version() == SCHEMA_VERSION
+
+
+def db_is_fresh() -> bool:
+    if not os.path.exists(DB_PATH):
+        return False
+    age = time.time() - os.path.getmtime(DB_PATH)
+    return age < TTL_SECONDS and stored_schema_version() == SCHEMA_VERSION