copilot-session-usage 0.2.1__tar.gz → 0.2.3__tar.gz

{copilot_session_usage-0.2.1 → copilot_session_usage-0.2.3}/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## Unreleased
 
+### Feat
+
+- accurate AIC cost computation using nanoAiu and cache_write
+
+## v0.2.1 (2026-07-02)
+
 ## v0.2.0 (2026-07-02)
 
 ### Fix

{copilot_session_usage-0.2.1 → copilot_session_usage-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: copilot-session-usage
-Version: 0.2.1
+Version: 0.2.3
 Summary: Usage and cost analytics for GitHub Copilot and Copilot-CLI session logs
 Project-URL: Homepage, https://github.com/gsemet/copilot-session-usage
 Project-URL: Documentation, https://copilot-session-usage.readthedocs.io/en/stable/
@@ -27,6 +27,8 @@ Description-Content-Type: text/markdown
 
 Extract VS Code Copilot session cost KPIs (tokens, estimated USD, model, duration) from local debug logs.
 
+**Full documentation:** [copilot-session-usage.readthedocs.io](https://copilot-session-usage.readthedocs.io/en/stable/)
+
 ## Installation
 
 ```bash
@@ -183,8 +185,6 @@ just docs
 just docs-serve
 ```
 
-**Full documentation:** [copilot-session-usage.readthedocs.io](https://copilot-session-usage.readthedocs.io/)
-
 ## License
 
 MIT — see [LICENSE](LICENSE).

{copilot_session_usage-0.2.1 → copilot_session_usage-0.2.3}/README.md

@@ -11,6 +11,8 @@
 
 Extract VS Code Copilot session cost KPIs (tokens, estimated USD, model, duration) from local debug logs.
 
+**Full documentation:** [copilot-session-usage.readthedocs.io](https://copilot-session-usage.readthedocs.io/en/stable/)
+
 ## Installation
 
 ```bash
@@ -167,8 +169,6 @@ just docs
 just docs-serve
 ```
 
-**Full documentation:** [copilot-session-usage.readthedocs.io](https://copilot-session-usage.readthedocs.io/)
-
 ## License
 
 MIT — see [LICENSE](LICENSE).

{copilot_session_usage-0.2.1 → copilot_session_usage-0.2.3}/docs/source/conf.py

@@ -24,6 +24,11 @@ extensions = [
 myst_enable_extensions = ["colon_fence", "deflist"]
 
 html_theme = "furo"
+html_theme_options = {
+    "source_repository": "https://github.com/gsemet/copilot-session-usage",
+    "source_branch": "main",
+    "source_directory": "docs/source/",
+}
 html_title = f"copilot-session-usage {version}"
 html_static_path = ["_static"]
 html_css_files = ["custom.css"]

copilot_session_usage-0.2.3/docs/source/explanation/how-cost-estimation-works.md

@@ -0,0 +1,138 @@
+# How Cost Estimation Works
+
+`copilot-session-usage` estimates session costs from VS Code debug logs.
+This page explains each step.
+
+---
+
+## Where the logs live
+
+VS Code stores one directory per workspace under `workspaceStorage`. Inside
+each workspace directory, the Copilot extension writes debug logs:
+
+```
+workspaceStorage/
+└── <workspace-hash>/
+    └── GitHub.copilot-chat/
+        └── debug-logs/
+            └── <session-uuid>/
+                ├── *.jsonl      ← token events
+                └── ...
+```
+
+Default locations by platform:
+
+| Platform | Path |
+|----------|------|
+| macOS | `~/Library/Application Support/Code/User/workspaceStorage/` |
+| Linux | `~/.config/Code/User/workspaceStorage/` |
+| Windows | `%APPDATA%\Code\User\workspaceStorage\` |
+| WSL2 (remote) | `~/.vscode-server/data/User/workspaceStorage/` |
+
+The tool also checks `Code - Insiders` variants automatically.
+
+---
+
+## How sessions are discovered
+
+The tool reads the session title from VS Code's SQLite workspace database
+(`state.vscdb`). Sessions are sorted by the last-modified time of their
+debug-log directory, most recent first.
+
+The `list` command reads only metadata (no JSONL parsing). The `analyze`,
+`id`, and `batch` commands parse the full JSONL files.
+
+---
+
+## Parsing JSONL logs
+
+Each `.jsonl` file contains one JSON object per line. The tool extracts
+token-count events emitted by the Copilot extension for each LLM call:
+
+- `input_tokens` — tokens sent to the model
+- `output_tokens` — tokens generated by the model
+- `cached_tokens` — input tokens served from the provider's prompt cache
+- `model` — the model name as reported by the provider
+
+A single session may call multiple models (e.g., Claude Sonnet for the main
+request and Claude Haiku for a subagent). Each model's tokens are summed
+separately, then costs are computed per model and aggregated.
+
+---
+
+## Cost calculation
+
+The VS Code debug log reports `inputTokens` as the **total** prompt sent
+(cached + non-cached combined). `cachedTokens` is the subset served from
+the provider's cache. The non-cached portion is `inputTokens − cachedTokens`.
+
+Each `llm_request` event also carries `copilotUsageNanoAiu` — VS Code's own
+cost for that call in nano-AI Credits (nanoAIU). It is present for all
+Copilot-plan models (Claude, GPT, and others). It is absent for Azure-hosted
+models not billed via Copilot AIC — `Kimi-K2.6-azure` is one such model:
+it is billed through Azure separately and correctly reports $0 AIC.
+
+When `copilotUsageNanoAiu` is present and non-zero, the tool uses it directly:
+
+```
+cost_usd = copilotUsageNanoAiu / 100_000_000_000   (1 nanoAIU = 1e-11 USD)
+```
+
+For models that do not report `copilotUsageNanoAiu` — Azure-hosted models billed
+outside the Copilot plan — the tool falls back to token-based computation
+(or $0 when the model has no Copilot pricing entry):
+
+```
+cost_usd = (
+    (inputTokens - cachedTokens) × rate.input          # fresh tokens
+  +  cachedTokens                × rate.cached_input   # cache-read tokens
+  +  outputTokens                × rate.output
+) / 1_000_000
+```
+
+plus the Anthropic cache-write approximation when applicable.
+
+Verified on a real session: `copilotUsageNanoAiu`-based cost matches the
+VS Code AIC panel at **0.000% error** for Claude models.
+
+---
+
+## Subagent attribution
+
+`runSubagent` calls appear in the JSONL as a distinct event type. The tool
+tracks them separately so `--detail full` can show which fraction of tokens
+was consumed by subagents vs. the main conversation.
+
+---
+
+## Accuracy
+
+For Copilot-plan models (Claude, GPT, etc.), the tool reads
+`copilotUsageNanoAiu` — VS Code's own per-call cost field — directly from the
+JSONL, so the session total matches the VS Code AIC panel at **0% error**.
+
+For Azure-hosted models billed outside the Copilot plan (`Kimi-K2.6-azure` is
+the current example), `copilotUsageNanoAiu` is absent. The tool falls back to
+token-based pricing using rates in `custom-models-pricing.yml`. These models
+are billed through Azure separately; setting their prices to `$0.00` in
+`custom-models-pricing.yml` correctly reflects that they do not consume AIC.
+
+### Why the LLM-call count differs by 1 from the panel
+
+The VS Code Agent Debug panel excludes the `title-*.jsonl` file (background
+title-generation calls). `copilot-session-usage` counts them because they
+consume real tokens. A session with one title-generation call will show one
+more LLM call and the corresponding (small) token counts compared to the panel.
+
+### Why token counts can differ between tool and panel
+
+Token counts in the tool include `title-*.jsonl`; the VS Code panel does not.
+For session `438d24a8`, the delta is exactly one Kimi call: +441 input, +1,245
+output.
+
+### Pricing table updates
+
+The bundled pricing table (`data/models-and-pricing.yml`) is updated with each
+release. Run `just refresh-pricing` to pull the latest rates. Stale rates only
+affect the token-based fallback path; `copilotUsageNanoAiu`-based costs are
+unaffected by the table.

{copilot_session_usage-0.2.1 → copilot_session_usage-0.2.3}/docs/source/index.md

@@ -1,5 +1,7 @@
 # copilot-session-usage
 
+[![GitHub](https://img.shields.io/badge/GitHub-copilot--session--usage-181717?logo=github)](https://github.com/gsemet/copilot-session-usage)
+
 **copilot-session-usage** reads VS Code Copilot debug logs and tells you
 how much each AI coding session cost in USD.
 
@@ -11,6 +13,8 @@ prints a cost report in seconds.
 The most common use: after a heavy agentic session, run
 `copilot-session-usage latest` to see what it cost.
 
+Links to source code: [gsemet/copilot-session-usage](https://github.com/gsemet/copilot-session-usage)
+
 ::::{grid} 1 1 2 2
 :gutter: 3
 

copilot_session_usage-0.2.3/docs/source/reference/pricing.md

@@ -0,0 +1,122 @@
+# Pricing Reference
+
+`copilot-session-usage` ships a bundled pricing table at
+`src/copilot_session_usage/data/models-and-pricing.yml`.
+
+## Upstream source
+
+Prices are synced from the GitHub Copilot official rate card:
+[`github/docs` — `data/tables/copilot/models-and-pricing.yml`](https://github.com/github/docs/blob/main/data/tables/copilot/models-and-pricing.yml)
+
+The bundled copy is updated with each release.
+
+## Cost formula
+
+The VS Code debug log reports three token counts per LLM call:
+
+| Field in log | Meaning |
+|---|---|
+| `inputTokens` | **Total** prompt tokens sent — cached and non-cached combined |
+| `cachedTokens` | Subset of `inputTokens` served from the provider's prompt cache |
+| `outputTokens` | Completion tokens generated |
+
+Non-cached input = `inputTokens − cachedTokens`. The two input
+components are billed at different rates, so the formula splits them:
+
+```
+cost_usd = (
+    (inputTokens - cachedTokens) × rate.input          # fresh prompt tokens
+  +  cachedTokens                × rate.cached_input   # cache-read tokens
+  +  outputTokens                × rate.output         # completion tokens
+) / 1_000_000
+```
+
+Results are summed across all models called in the session.
+
+The equivalent statement using Anthropic-style variable names
+(where `input` already excludes cached tokens) is:
+
+```
+cost_usd = (
+    input          × rate.input
+  + cache_read     × rate.cached_input
+  + cache_creation × (rate.cache_write ?? rate.input)
+  + output         × rate.output
+) / 1_000_000
+```
+
+VS Code debug logs do not expose `cache_creation` tokens directly.
+For Anthropic models, the tool approximates the incremental cache-creation
+cost using fresh input as a proxy (see note below).
+
+:::{note}
+**Anthropic `cache_write` — approximated via fresh input.**
+
+Anthropic models have a `cache_write` rate for tokens written to the provider's
+cache for the first time. VS Code JSONL logs do not expose `cacheCreationTokens`;
+`agent-traces.db` has the schema column but VS Code does not populate it for
+Claude models (verified: 0 rows, VS Code 1.103+).
+
+The tool approximates the incremental cost as:
+
+```
+delta = (inputTokens - cachedTokens) × (cache_write_per_m - input_per_m) / 1_000_000
+```
+
+Verified on a real 92-call Claude Sonnet 4.6 session: this matches the VS Code
+AIC panel exactly ($5.9037 both ways). Models without `cache_write` (OpenAI,
+Google) are unaffected — the delta is zero.
+
+`agent_traces_db_paths()` in `vscode.py` locates `agent-traces.db` on all
+platforms. When VS Code starts populating `gen_ai.usage.cache_creation.input_tokens`,
+reading the exact value from the DB will replace this proxy without API changes.
+:::
+
+## AI Credits and USD
+
+Post-2026-06-01, GitHub Copilot bills in **AI Credits (AIC)**.
+The upstream rate card publishes prices in USD per million tokens.
+The conversion is:
+
+```
+1 AIC = $0.01 USD    →    100 AIC = $1.00 USD
+```
+
+A model priced at `input: $3.00` per million tokens costs **300 AIC**
+per million input tokens. This tool reports USD; multiply by 100 to get AIC.
+
+The per-token AIC rate is identical across all Copilot plans. Plans differ
+only in the monthly AIC allowance included — that allowance is not tracked
+by this tool.
+
+## Cache discounts
+
+All providers discount tokens served from their prompt cache:
+
+| Provider | Cache-read discount vs. input |
+|----------|-------------------------------|
+| OpenAI | ~10× cheaper |
+| Anthropic | ~10× cheaper |
+| Google | ~10× cheaper |
+
+A session with 85% cache hit ratio costs significantly less than raw
+token counts suggest.
+
+## Long-context tier switching
+
+Some models have two pricing tiers based on input token count:
+
+| Model | Threshold | Effect |
+|-------|-----------|--------|
+| GPT-5.4 | > 272K tokens | Input/cached/output prices double |
+| GPT-5.5 | > 272K tokens | Input/cached/output prices double |
+| Gemini 3.1 Pro | > 200K tokens | Input/cached/output prices increase |
+
+`copilot-session-usage` selects the correct tier automatically based on
+the session's total input tokens per model.
+
+## Custom pricing
+
+Override any model's price by editing
+`src/copilot_session_usage/data/custom-models-pricing.yml`. Entries in
+this file take precedence over the main table.

{copilot_session_usage-0.2.1 → copilot_session_usage-0.2.3}/docs/source/tutorials/getting-started.md

@@ -11,7 +11,7 @@ output. It assumes you have installed `copilot-session-usage` — see
 Run this after any VS Code Copilot chat session:
 
 ```bash
-copilot-session-usage latest
+copilot-session-usage latest --format table
 ```
 
 Sample output:
@@ -41,19 +41,16 @@ Each field:
 
 ---
 
-## Switch detail levels
+## Details Tables
 
-`--detail` controls how much data is shown:
+`--format` controls the output type. Default is `json`:
 
 ```bash
 # Just cost and model names
-copilot-session-usage latest --detail minimal
+copilot-session-usage latest --format table
 
-# Default: summary + per-model breakdown
-copilot-session-usage latest --detail compact
-
-# Everything: per-model + subagent attribution
-copilot-session-usage latest --detail full
+# Default: summary + per-subagent breakdown
+copilot-session-usage latest --format detailed
 ```
 
 ---
@@ -76,10 +73,16 @@ copilot-session-usage latest --format json --output session.json
 
 ## List recent sessions
 
-See which sessions exist without computing costs:
+See which sessions exist without computing costs (limit set to 20 by default):
 
 ```bash
 copilot-session-usage list
+
+# Limit to 5 sessions
+copilot-session-usage list --limit 5
+
+# Since a date
+copilot-session-usage list --since 2026-07-01
 ```
 
 Output:
@@ -106,7 +109,14 @@ it lists them so you can pick the right UUID.
 ## Analyze a specific session by UUID
 
 ```bash
+# Default json output
 copilot-session-usage id f5cbde8a-ec40-466f-86e6-f95c343b6c58
+
+# Human readable summary
+copilot-session-usage id f5cbde8a-ec40-466f-86e6-f95c343b6c58 --format table
+
+# Human readable details with per-subagent breakdown
+copilot-session-usage id f5cbde8a-ec40-466f-86e6-f95c343b6c58 --format detailed
 ```
 
 ---
@@ -114,8 +124,11 @@ copilot-session-usage id f5cbde8a-ec40-466f-86e6-f95c343b6c58
 ## Analyze multiple sessions at once
 
 ```bash
-# Last 10 sessions
+# Last 10 sessions (json output)
 copilot-session-usage batch 10
+
+# Summary table for last 10 sessions
+copilot-session-usage batch 10 --format table
 ```
 
 Output includes a summary row with aggregate totals and a per-session table.

{copilot_session_usage-0.2.1 → copilot_session_usage-0.2.3}/justfile

@@ -116,6 +116,7 @@ preflight:
     just typecheck
     just tests-coverage
     just knowledge-lint
+    just knowledge-validate
     just docs
 
 # ─── Cleanup ──────────────────────────────────────────────────────────────────

{copilot_session_usage-0.2.1 → copilot_session_usage-0.2.3}/knowledge/_schema/Base.schema.yaml

@@ -23,4 +23,13 @@ properties:
     description: ISO 8601 creation or last-updated timestamp.
     type: string
     format: date-time
-additionalProperties: false
+  links:
+    type: array
+    items:
+      type: string
+    description: "Bundle-relative paths this concept links to"
+  backlinks:
+    type: array
+    items:
+      type: string
+    description: "Bundle-relative paths of concepts that link to this one"

copilot_session_usage-0.2.3/knowledge/_schema/Experiment.schema.yaml

@@ -0,0 +1,44 @@
+$schema: "http://json-schema.org/draft-07/schema#"
+title: Experiment
+description: >-
+  A reusable, prepared procedure that can be executed one or two times to test a
+  hypothesis. Each execution produces one Finding. The Experiment is a template;
+  its recorded outcomes live as Finding documents.
+allOf:
+  - $ref: "Base.schema.yaml"
+  - type: object
+    properties:
+      type:
+        description: Document type — must be "Experiment".
+        type: string
+        const: Experiment
+      hypothesis:
+        description: The claim the experiment is designed to confirm or falsify.
+        type: string
+        minLength: 1
+      steps:
+        description: Ordered procedure to run the experiment reproducibly.
+        type: array
+        items: { type: string }
+        minItems: 1
+      expected_signals:
+        description: Observable signals that indicate the hypothesis holds or fails.
+        type: array
+        items: { type: string }
+      max_runs:
+        description: How many times this experiment is meant to be run (typically 1–2).
+        type: integer
+        minimum: 1
+      status:
+        description: Lifecycle state of the experiment template.
+        type: string
+        enum: [proposed, active, retired, superseded]
+      derived_findings:
+        description: IDs of Findings produced by running this experiment.
+        type: array
+        items: { type: string }
+      superseded_by:
+        description: IDs of documents that supersede this experiment.
+        type: array
+        items: { type: string }
+    required: [type, hypothesis, steps]

copilot_session_usage-0.2.3/knowledge/_schema/Finding.schema.yaml

@@ -0,0 +1,49 @@
+$schema: "http://json-schema.org/draft-07/schema#"
+title: Finding
+description: >-
+  An empirical, dated, falsifiable record of what an agent or human truthfully
+  observed and believed at a point in time. The body is immutable once written;
+  only lifecycle frontmatter (status, contradicted_by, superseded_by) may be
+  appended later.
+allOf:
+  - $ref: "Base.schema.yaml"
+  - type: object
+    properties:
+      type:
+        description: Document type — must be "Finding".
+        type: string
+        const: Finding
+      confidence:
+        description: How confident the reporter was at the time of recording.
+        type: string
+        enum: [low, medium, high, confirmed]
+      context:
+        description: >-
+          What the reporter believed and the situation at the time — the honest
+          basis for the finding, including assumptions that may later prove wrong.
+        type: string
+        minLength: 1
+      status:
+        description: Lifecycle state. Appended non-destructively; the body never changes.
+        type: string
+        enum: [active, contradicted, superseded]
+      derived_from:
+        description: ID of the Experiment whose run produced this finding, if any.
+        type: string
+      contradicts:
+        description: IDs of earlier Findings this finding contradicts.
+        type: array
+        items: { type: string }
+      supersedes:
+        description: IDs of earlier Findings this finding replaces.
+        type: array
+        items: { type: string }
+      contradicted_by:
+        description: IDs of later Findings that contradict this one (appended by review).
+        type: array
+        items: { type: string }
+      superseded_by:
+        description: IDs of later Findings that replace this one (appended by review).
+        type: array
+        items: { type: string }
+    required: [type, timestamp, confidence, context]

copilot_session_usage-0.2.3/knowledge/_schema/Principle.schema.yaml

@@ -0,0 +1,25 @@
+$schema: "http://json-schema.org/draft-07/schema#"
+title: Principle
+description: >-
+  A standard or convention, usually defined with humans. Principles are stable,
+  normative statements ("we always…", "never…") — not dated observations. They
+  may be supported by Findings but are agreed, not merely observed.
+allOf:
+  - $ref: "Base.schema.yaml"
+  - type: object
+    properties:
+      type:
+        description: Document type — must be "Principle".
+        type: string
+        const: Principle
+      rationale:
+        description: Why this principle exists and what it protects against.
+        type: string
+      authority:
+        description: Who agreed this principle (e.g. "team", "human-reviewed").
+        type: string
+      supported_by:
+        description: IDs of Findings that provide empirical support for this principle.
+        type: array
+        items: { type: string }
+    required: [type]

copilot_session_usage-0.2.3/knowledge/_schema/Structure.schema.yaml

@@ -0,0 +1,26 @@
+$schema: "http://json-schema.org/draft-07/schema#"
+title: Structure
+description: >-
+  A description of how an object, system, or artifact is composed and how its
+  parts relate — the "how it works" view. Distinct from a Concept (an idea) and
+  from a Playbook (a procedure to perform).
+allOf:
+  - $ref: "Base.schema.yaml"
+  - type: object
+    properties:
+      type:
+        description: Document type — must be "Structure".
+        type: string
+        const: Structure
+      subject:
+        description: The object or system whose structure is described.
+        type: string
+      parts:
+        description: The components, fields, or sub-parts that make up the subject.
+        type: array
+        items: { type: string }
+      related_concepts:
+        description: IDs of Concept documents that explain the ideas behind this structure.
+        type: array
+        items: { type: string }
+    required: [type]

{copilot_session_usage-0.2.1 → copilot_session_usage-0.2.3}/knowledge/concepts/overview.md

@@ -19,9 +19,9 @@ Every LLM request made by a coding agent (parent or subagent) is logged as a str
 
 | Metric | Source Field | Description |
 |--------|-------------|-------------|
-| Input Tokens | `attrs.inputTokens` | Tokens sent to the model (prompt + context) |
+| Input Tokens | `attrs.inputTokens` | **Total** prompt tokens sent (cached + non-cached) |
 | Output Tokens | `attrs.outputTokens` | Tokens generated by the model |
-| Cached Tokens | `attrs.cachedTokens` | Prompt tokens served from cache (not billed) |
+| Cached Tokens | `attrs.cachedTokens` | Subset of input tokens served from the provider's prompt cache (billed at a lower rate) |
 | LLM Calls | Count of `llm_request` events | Number of individual model invocations |
 | Model | `attrs.model` | Which model handled the request |
 

{copilot_session_usage-0.2.1 → copilot_session_usage-0.2.3}/knowledge/concepts/session-cost-analysis.md

@@ -6,7 +6,7 @@ description: Process of extracting token usage metrics from Copilot debug logs
 tags: [cost-analysis, tokens, pricing, debug-logs]
 timestamp: 2026-06-30T22:00:00Z
 links: []
-backlinks: []
+backlinks: [structures/cache-cost-approximation.md]
 ---
 
 # Session Cost Analysis

{copilot_session_usage-0.2.1 → copilot_session_usage-0.2.3}/knowledge/experiments/verify-subagent-cost-attribution.md

@@ -18,7 +18,8 @@ steps: [Pick a session directory that contains at least one runSubagent-*.jsonl
 expected_signals: ['Tool total equals independent sum (no double-count, no omission).',
   Each subagent subtotal is attributed to its own runSubagent id.]
 max_runs: 2
-status: proposed
+status: superseded
+superseded_by: [structures/subagent-cost-tracking.md]
 links: []
 backlinks: []
 ---