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

{copilot_session_usage-0.2.1 → copilot_session_usage-0.2.2}/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.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: copilot-session-usage
-Version: 0.2.1
+Version: 0.2.2
 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/)
+
 ## 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.2/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.2/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.2}/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.2}/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.2/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.2/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.2/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.2/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.2}/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.2}/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.2}/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: []
 ---

copilot_session_usage-0.2.2/knowledge/findings/cache-write-cost-not-tracked.md

@@ -0,0 +1,83 @@
+---
+type: Finding
+title: "cache_write approximated via fresh_input — matches AIC panel exactly"
+description: >
+  VS Code JSONL logs and agent-traces.db both lack cache_creation token counts.
+  Approximating cache_creation as fresh_input = inputTokens - cachedTokens and
+  billing only the incremental delta (cache_write - input) / 1M produces an exact
+  match to the VS Code AIC panel. Implemented in estimate_cost since v0.3.
+tags: [cache-write, anthropic, aic, approximation, verified, implemented]
+confidence: confirmed
+context: >-
+  Verified by comparing copilot-session-usage output against the VS Code AIC
+  panel for multiple sessions. The approximation holds exactly when cache_write
+  is computed as fresh_input = inputTokens - cachedTokens.
+timestamp: 2026-07-02T23:00:00Z
+links: []
+backlinks: [structures/cache-cost-approximation.md]
+---
+
+# Finding: cache_write approximated via fresh_input — now implemented
+
+## Background
+
+VS Code JSONL debug logs do not expose `cacheCreationTokens`. The OTel SQLite
+store (`agent-traces.db`) has the schema column
+`gen_ai.usage.cache_creation.input_tokens` but VS Code does not populate it for
+Claude models (verified: 0 rows on VS Code 1.103+).
+
+## The correct approximation
+
+The key insight is that the current code already bills fresh input at `input_per_m`.
+The incremental cost of cache creation is only the **difference**:
+
+```
+delta = fresh_input × (cache_write_per_m − input_per_m) / 1_000_000
+```
+
+where `fresh_input = inputTokens − cachedTokens`.
+
+## Verification on session 438d24a8 (Claude Sonnet 4.6, 92 calls)
+
+| Metric | Value |
+|--------|-------|
+| Fresh input | 720,122 tokens |
+| Delta formula: 720K × ($3.75 − $3.00)/M | **$0.5401** |
+| Old tool cost (without delta) | $5.3636 |
+| New tool cost (with delta) | $5.9037 |
+| VS Code panel (590.37 AIC ÷ 100) | **$5.9037** |
+
+Exact match.
+
+Note: an earlier version of this finding incorrectly computed
+`720K × $3.75/M = $2.70` (the full rate, not the incremental delta),
+concluding a "5× overestimate". That calculation was wrong; the delta
+formula gives the correct $0.54 increment.
+
+## OTel DB fallback
+
+`vscode.agent_traces_db_paths()` discovers all existing `agent-traces.db` paths
+across Code / Code - Insiders on every platform. When VS Code eventually populates
+`gen_ai.usage.cache_creation.input_tokens`, reading the exact value from the DB
+will replace the proxy. The DB is not required for current operation.
+
+## Implication
+
+For Anthropic-heavy sessions, `copilot-session-usage` now closely matches the
+VS Code AIC panel. The approximation is accurate when the full context prefix is
+cached (typical for long Copilot sessions). Sessions that do not cache (very short
+contexts, no system prompt) may over-count by at most `fresh_input × delta_rate`.
+
+## Follow-up fix: model_breakdown now uses nano_aiu (2026-07-03)
+
+The `model_breakdown` (per-model cost table) previously used `estimate_cost`
+(token-based) on `global_per_model`, which did not accumulate `nano_aiu`.
+This created a minor inconsistency: the session total used nano_aiu while the
+per-model breakdown used token-based pricing (difference ~$0.0002 for session
+438d24a8 = 0.001% error, well within tolerance).
+
+Fix: `global_per_model` now accumulates `nano_aiu` from each file's per-model
+bucket, and `model_breakdown` calls `estimate_cost_for_file({model: v}, pricing)`
+instead of `estimate_cost(...)`. Both session total and per-model breakdown now
+use the same nano_aiu-first logic. Verified: model_breakdown sum = $14.709213
+matches session total $14.7092 (rounding only).

copilot_session_usage-0.2.2/knowledge/findings/index.md

@@ -0,0 +1,7 @@
+# Finding
+
+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.
+
+- [cache_write approximated via fresh_input — matches AIC panel exactly](cache-write-cost-not-tracked.md) — VS Code JSONL logs and agent-traces.db both lack cache_creation token counts. Approximating cache_creation as fresh_input = inputTokens - cachedTokens and billing only the incremental delta (cache_write - input) / 1M produces an exact match to the VS Code AIC panel. Implemented in estimate_cost since v0.3.  [Finding]
+- [Subagent Logs Use runSubagent Prefix](subagent-logs-use-runsubagent-prefix.md) — Subagent activity is recorded in separate JSONL files prefixed with "runSubagent-" inside the session debug-logs directory.  [Finding]
+- [title-*.jsonl adds 1 LLM call and its tokens to tool totals; VS Code panel excludes it](title-jsonl-not-counted-as-model-turn.md) — The VS Code Agent Debug panel "Model Turns" counter excludes title-generation calls. copilot-session-usage counts them. The delta is exactly the title-*.jsonl file's token counts.  [Finding]

copilot_session_usage-0.2.2/knowledge/findings/title-jsonl-not-counted-as-model-turn.md

@@ -0,0 +1,50 @@
+---
+type: Finding
+title: "title-*.jsonl adds 1 LLM call and its tokens to tool totals; VS Code panel
+  excludes it"
+description: The VS Code Agent Debug panel "Model Turns" counter excludes
+  title-generation calls. copilot-session-usage counts them. The delta is
+  exactly the title-*.jsonl file's token counts.
+tags: [token-counting, title-generation, panel-vs-tool, verified]
+confidence: confirmed
+context: >-
+  Observed by comparing VS Code Agent Debug panel metrics against
+  copilot-session-usage output for session 438d24a8. The delta in turns,
+  input tokens, and output tokens matched exactly the title-generation
+  JSONL file.
+timestamp: 2026-07-02T22:00:00Z
+links: []
+backlinks: [structures/subagent-cost-tracking.md,
+    structures/vscode-copilot-extension.md]
+---
+
+# Finding: title-*.jsonl not counted as "Model Turn" by VS Code panel
+
+## Observed
+
+Session `438d24a8` at the same snapshot:
+
+| Metric | VS Code panel | copilot-session-usage | Delta |
+|--------|---------------|-----------------------|-------|
+| Turns/calls | 96 | 97 | +1 |
+| Input tokens | 8,831,919 | 8,832,360 | +441 |
+| Output tokens | 58,784 | 60,029 | +1,245 |
+| Cached tokens | 8,097,846 | 8,097,846 | 0 |
+
+The delta matches exactly the `title-ca686498-...jsonl` file:
+`model=Kimi-K2.6-azure  input=441  cached=0  output=1,245`
+
+## Explanation
+
+VS Code "Model Turns" counts only the main conversation turns.
+The title-generation call (one `llm_request` in `title-*.jsonl`) is a
+background call VS Code excludes from the panel display.
+
+`copilot-session-usage` counts **all** `llm_request` events across all
+`*.jsonl` files in the session directory, including `title-*.jsonl`.
+
+## Implication
+
+The tool over-counts by 1 call and the title call's tokens vs. the panel.
+This is intentional: title-generation consumes real tokens and should be
+included in cost tracking.

{copilot_session_usage-0.2.1 → copilot_session_usage-0.2.2}/knowledge/reference/debug-log-format.md

@@ -56,9 +56,10 @@ This is the only event type that contains cost information. All other events (`s
 | Field | Type | Meaning |
 |-------|------|---------|
 | `attrs.model` | string | Model identifier (e.g., `Kimi-K2.6-azure`, `gpt-4o`) |
-| `attrs.inputTokens` | integer | Tokens consumed from context window |
+| `attrs.inputTokens` | integer | **Total** prompt tokens sent — cached and non-cached combined |
 | `attrs.outputTokens` | integer | Tokens generated |
-| `attrs.cachedTokens` | integer | Tokens served from prompt cache |
+| `attrs.cachedTokens` | integer | Subset of `inputTokens` served from the provider's prompt cache (billed at the lower `cached_input` rate) |
+| `attrs.copilotUsageNanoAiu` | integer | VS Code's own AIC cost for this call in nano-units (÷ 1e9 = AIC, ÷ 1e11 = USD). Present for all Copilot-plan models (Claude, GPT, etc.). Absent for Azure-hosted models not billed via Copilot AIC (e.g. `Kimi-K2.6-azure`). |
 | `attrs.ttft` | integer | Time to first token (ms) |
 
 > **Mixed-model sessions:** A single `.jsonl` file can contain `llm_request` events from