copilot-session-usage 0.1.0__tar.gz → 0.2.0__tar.gz

copilot_session_usage-0.2.0/.github/guidelines/knowledge-base.guidelines.md

@@ -0,0 +1,86 @@
+---
+applyTo: "knowledge/**/*.md"
+description: "The minimal rules a coding agent must follow to maintain the OKF knowledge bundle in knowledge/."
+---
+
+# Knowledge Base Maintenance Guidelines
+
+`knowledge/` is an [OKF](https://github.com/gsemet/okf-schema) bundle. Each `.md`
+file has a `type` in its frontmatter that maps to a schema in `_schema/`. This
+document is the strict minimal rule set for maintaining it correctly.
+
+## 1. Choose the right type
+
+| You want to record… | type | Folder | Nature |
+|---------------------|------|--------|--------|
+| A stable idea / "what is this?" | `Concept` | `concepts/` | Explanatory |
+| How an object is composed / works | `Structure` | `structures/` | Descriptive |
+| A standard or convention (agreed with humans) | `Principle` | `principles/` | Normative |
+| A step-by-step procedure to perform | `Playbook` | `guides/` | Procedural |
+| Exact values, fields, or lookup tables | `Reference` | `reference/` | Lookup |
+| What you observed/believed at time T | `Finding` | `findings/` | Empirical, dated |
+| A reusable procedure to test a claim | `Experiment` | `experiments/` | Template, run 1–2× |
+
+Rules of thumb:
+
+- Document only what is **non-trivial** for coding agents. Do not paraphrase code
+  or existing docs — link instead.
+- Keep each file focused and concise, important information first.
+- Findings and Experiments are the empirical layer; the other five are the stable
+  layer. Agents dump Findings freely; stable docs are promoted deliberately by the
+  `consolidate-knowledge-base` skill — never dumped ad hoc.
+
+## 2. Required frontmatter
+
+All documents (except `index.md` and `log.md`) require:
+
+```yaml
+type: <one of the types above>   # must match the const in _schema/<Type>.schema.yaml
+title: Human-Readable Title       # non-empty
+description: Short summary.        # non-empty
+tags: [keyword]                    # optional but encouraged
+timestamp: 2026-07-02T00:00:00Z   # ISO 8601 (YYYY-MM-DDTHH:MM:SSZ)
+```
+
+Type-specific required fields:
+
+- **Finding**: also `timestamp`, `confidence` (`low|medium|high`), and `context`
+  (what you believed and the scope you actually tested).
+- **Experiment**: also `hypothesis` and `steps`.
+
+## 3. Finding immutability & contradictions
+
+- A Finding's **body and claim are frozen** once written. Never reword or delete.
+- To correct a Finding, write a NEW Finding with `contradicts: [<old-id>]` or
+  `supersedes: [<old-id>]`.
+- The only permitted edits to an existing Finding are the lifecycle fields
+  `status` (`contradicted|superseded`), `contradicted_by`, `superseded_by`,
+  appended by the `consolidate-knowledge-base` review.
+- Promotion of converged Findings into Concept/Structure/Principle is done by
+  `consolidate-knowledge-base` with human confirmation — Principles are always
+  agreed with humans.
+
+## 4. Skills
+
+- **`record-finding`** (fast, non-interactive): dump one Finding after an
+  investigation or debugging session.
+- **`consolidate-knowledge-base`** (interactive, human-confirmed): detect
+  contradictions, mark findings, propose Experiments, propose promotions.
+
+## 5. Validate before commit
+
+```bash
+just knowledge-lint          # auto-format frontmatter + rebuild index
+just knowledge-validate      # 0 errors, 0 warnings required
+just knowledge-lint-check    # verify no pending format changes
+```
+
+Pre-commit checklist:
+
+- [ ] Correct `type` and folder for the information recorded.
+- [ ] Required frontmatter present and valid.
+- [ ] No Finding body was reworded or deleted.
+- [ ] All three commands above pass (also covered by `just preflight`).
+
+Add a dated entry to `knowledge/log.md` for significant changes. Use plain
+ISO-8601 date headings; avoid parenthetical annotations (they trigger warnings).

copilot_session_usage-0.2.0/.github/skills/consolidate-knowledge-base/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: consolidate-knowledge-base
+description: 'Interactively review the OKF knowledge base to detect contradictions between Findings, mark contradicted/superseded Findings, propose Experiments to resolve open questions, and propose promotions of converged Findings into stable Concept/Structure/Principle documents. Every mutation is confirmed by a human before it is written. Use periodically or after a batch of recorded Findings.'
+---
+
+# consolidate-knowledge-base
+
+Turn a pile of dated Findings into consolidated, trustworthy knowledge — without
+ever rewriting history. This skill is **interactive**: it proposes, the human
+confirms, then it writes.
+
+## When to use
+
+- After a batch of Findings has been dumped by `record-finding`.
+- Periodically, to keep the empirical layer coherent with the stable layer.
+- When you suspect two findings disagree.
+
+## Guardrails
+
+- NEVER edit or delete a Finding's body. Only append lifecycle frontmatter
+  (`status`, `contradicted_by`, `superseded_by`).
+- NEVER promote to a Principle without explicit human confirmation — principles
+  are agreed with humans.
+- Ask before every write, using `vscode_askQuestions`.
+
+## Procedure
+
+### 1. Scan
+Read `knowledge/findings/`, plus `principles/`, `structures/`, `concepts/`.
+Build a map of claims, tags, and existing `contradicts`/`supersedes` links.
+
+### 2. Detect contradictions
+Identify pairs where a newer Finding disagrees with an older Finding, or where a
+Finding conflicts with a Principle/Structure/Concept. Present each candidate
+contradiction to the human for confirmation.
+
+### 3. Mark (on confirmation)
+For each confirmed contradiction, append metadata-only fields:
+- On the newer finding: `contradicts: [<old-id>]` (if not already present).
+- On the older finding: `status: contradicted` and `contradicted_by: [<new-id>]`.
+Use the same pattern with `supersedes`/`superseded_by` for replacements.
+The body of both files stays untouched.
+
+### 4. Propose Experiments
+For unresolved or low-confidence contradictions, propose a new `Experiment`
+document (hypothesis, steps, expected_signals, `max_runs: 1–2`) that would
+settle the question. Write it to `knowledge/experiments/` only on confirmation.
+
+### 5. Propose promotions
+When several Findings converge on a stable truth, propose promoting the insight
+into the stable layer:
+- "how it works" → `Structure` in `structures/`
+- "the idea" → `Concept` in `concepts/`
+- "the standard/convention" → `Principle` in `principles/` (always human-agreed)
+Link the promoted doc back to its supporting findings (`supported_by` /
+`related_concepts`). Write only on confirmation. Findings remain untouched.
+
+### 6. Validate
+```bash
+just knowledge-lint
+just knowledge-validate
+```
+Both must pass before finishing.
+
+## Output
+
+A short chat summary: contradictions found and marked, experiments proposed,
+promotions made, and any open questions left for a future run.

copilot_session_usage-0.2.0/.github/skills/record-finding/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: record-finding
+description: 'Dump a single empirical Finding into the OKF knowledge base after an investigation or debugging session. Fast and non-interactive. Records what you truthfully observed and believed at this moment, with confidence and context, as an immutable dated note under knowledge/findings/. Use after diagnosing a bug, verifying behavior, or discovering something non-trivial worth remembering.'
+---
+
+# record-finding
+
+Record ONE Finding: a dated, empirical, falsifiable note of what you observed and
+believed right now. Findings can later be wrong — that is fine. Be truthful about
+the moment, not about eternal truth.
+
+## When to use
+
+- You just finished an investigation, debugging session, or verification.
+- You learned something non-trivial about how the external world (VS Code,
+  Copilot, pricing, logs) behaves.
+- You want to hand off "what I found and believed" for later consolidation.
+
+Do NOT use this to record standards/conventions (that is a Principle), how an
+object is composed (Structure), or a stable idea (Concept). Those are promoted
+deliberately by `consolidate-knowledge-base`, not dumped.
+
+## Procedure
+
+1. Write exactly one file to `knowledge/findings/<slug>.md` where `<slug>` is a
+   short hyphenated summary of the claim.
+2. Use this frontmatter (all listed fields are required):
+
+   ```yaml
+   ---
+   type: Finding
+   title: Short claim as a title
+   description: One-sentence summary of the finding.
+   tags: [relevant, keywords]
+   timestamp: <ISO-8601 UTC, e.g. 2026-07-02T14:30:00Z>
+   confidence: low | medium | high
+   context: >-
+     What you believed and the situation at the time — including assumptions
+     that may later prove wrong, and the scope you actually tested.
+   ---
+   ```
+
+3. In the body, state plainly: what was observed, why it matters, and the
+   caveats / limits of what you verified.
+4. If this finding contradicts or replaces an earlier one, add
+   `contradicts: [<finding-id>]` or `supersedes: [<finding-id>]`. Do NOT edit the
+   older finding — the `consolidate-knowledge-base` skill handles backlinks.
+5. If a run of an Experiment produced this finding, add `derived_from: <experiment-id>`.
+
+## Immutability
+
+Once written, never reword or delete a finding's body. This is enforced by the
+`Findings Are Immutable` principle. Corrections happen by writing a NEW finding.
+
+## Validate
+
+```bash
+just knowledge-lint
+just knowledge-validate
+```
+
+Both must pass. Do not run `consolidate-knowledge-base` here — dumping stays fast.

{copilot_session_usage-0.1.0 → copilot_session_usage-0.2.0}/.github/workflows/ci.yml

@@ -43,6 +43,7 @@ jobs:
         with:
           files: ./coverage.xml
           fail_ci_if_error: false
+          token: ${{ secrets.CODECOV_TOKEN }}
 
   cross-platform:
     runs-on: ${{ matrix.os }}

copilot_session_usage-0.2.0/.readthedocs.yaml

@@ -0,0 +1,24 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+  jobs:
+    post_checkout:
+      - git fetch --tags
+    pre_build:
+      - uv run cz changelog
+
+sphinx:
+  configuration: docs/source/conf.py
+
+python:
+  install:
+    - method: uv
+      command: sync
+      groups:
+        - dev

copilot_session_usage-0.2.0/CHANGELOG.md

@@ -0,0 +1,9 @@
+## Unreleased
+
+### Feat
+
+- initial implementation
+
+### Fix
+
+- bad cost compuation for Opus 4.8

{copilot_session_usage-0.1.0 → copilot_session_usage-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: copilot-session-usage
-Version: 0.1.0
+Version: 0.2.0
 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

copilot_session_usage-0.2.0/docs/source/changelog.md

@@ -0,0 +1,4 @@
+# Changelog
+
+```{include} ../../CHANGELOG.md
+```

{copilot_session_usage-0.1.0 → copilot_session_usage-0.2.0}/docs/source/index.md

@@ -31,6 +31,7 @@ copilot-session-usage batch 10
 
 cli
 api
+changelog
 ```
 
 ## Indices and tables

{copilot_session_usage-0.1.0 → copilot_session_usage-0.2.0}/justfile

@@ -56,8 +56,8 @@ tests-coverage:
 
 # ─── Documentation ────────────────────────────────────────────────────────────
 
-# Build Sphinx docs
-docs:
+# Build Sphinx docs (regenerates CHANGELOG first)
+docs: changelog
     uv run -- sphinx-build docs/source docs/_build
 
 # Serve docs locally (auto-reload)
@@ -66,13 +66,17 @@ docs-serve:
 
 # ─── Build & release ──────────────────────────────────────────────────────────
 
+# Regenerate CHANGELOG.md from conventional commits
+changelog:
+    uv run -- cz changelog
+
 # Build wheel + sdist
 build:
     uv build
 
 # Refresh bundled pricing data from upstream
 refresh-pricing:
-    uv run -- python -c "from copilot_session_usage._internal.core import refresh_pricing; refresh_pricing()"
+    uv run -- python scripts/refresh_pricing.py
 
 # ─── Knowledge (OKF) ──────────────────────────────────────────────────────────
 

copilot_session_usage-0.1.0/knowledge/_schema/Concept.schema.yaml → copilot_session_usage-0.2.0/knowledge/_schema/Base.schema.yaml

@@ -1,19 +1,18 @@
 $schema: "http://json-schema.org/draft-07/schema#"
-title: Concept
-description: A core concept or explanatory document in the knowledge base.
+title: Base
+description: Common frontmatter fields shared by all knowledge-base documents.
 type: object
 required: [type, title, description]
 properties:
   type:
-    description: Document type — must be "Concept" for concept documents.
+    description: Document type discriminator.
     type: string
-    const: Concept
   title:
-    description: Human-readable title of the concept.
+    description: Human-readable title of the document.
     type: string
     minLength: 1
   description:
-    description: Short summary of what the concept explains.
+    description: Short summary of what the document covers.
     type: string
     minLength: 1
   tags:

copilot_session_usage-0.2.0/knowledge/_schema/Concept.schema.yaml

@@ -0,0 +1,20 @@
+$schema: "http://json-schema.org/draft-07/schema#"
+title: Concept
+description: A core concept or explanatory document in the knowledge base.
+allOf:
+  - $ref: "Base.schema.yaml"
+  - type: object
+    properties:
+      type:
+        description: Document type — must be "Concept" for concept documents.
+        type: string
+        const: Concept
+      related_concepts:
+        description: IDs of other Concept documents that deepen or contrast this idea.
+        type: array
+        items: { type: string }
+      prerequisites:
+        description: Concepts a reader should understand before engaging with this one.
+        type: array
+        items: { type: string }
+    required: [type]

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

@@ -0,0 +1,55 @@
+$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.
+type: object
+properties:
+  type:
+    description: Document type — must be "Experiment".
+    type: string
+    const: Experiment
+  title:
+    description: Human-readable title of the experiment.
+    type: string
+    minLength: 1
+  description:
+    description: Short summary of what the experiment tests.
+    type: string
+    minLength: 1
+  tags:
+    description: Keywords for categorization and search.
+    type: array
+    items: { type: string }
+  timestamp:
+    description: When the experiment template was created (ISO 8601).
+    type: string
+    format: date-time
+  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]
+  derived_findings:
+    description: IDs of Findings produced by running this experiment.
+    type: array
+    items: { type: string }
+required: [type, title, description, hypothesis, steps]
+additionalProperties: false

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

@@ -0,0 +1,64 @@
+$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.
+type: object
+properties:
+  type:
+    description: Document type — must be "Finding".
+    type: string
+    const: Finding
+  title:
+    description: Human-readable title stating the claim.
+    type: string
+    minLength: 1
+  description:
+    description: One-sentence summary of the finding.
+    type: string
+    minLength: 1
+  tags:
+    description: Keywords for categorization and search.
+    type: array
+    items: { type: string }
+  timestamp:
+    description: When the finding was observed (ISO 8601).
+    type: string
+    format: date-time
+  confidence:
+    description: How confident the reporter was at the time of recording.
+    type: string
+    enum: [low, medium, high]
+  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, title, description, timestamp, confidence, context]
+additionalProperties: false

copilot_session_usage-0.2.0/knowledge/_schema/Playbook.schema.yaml

@@ -0,0 +1,19 @@
+$schema: "http://json-schema.org/draft-07/schema#"
+title: Playbook
+description: A step-by-step guide, script collection, or actionable workflow.
+allOf:
+  - $ref: "Base.schema.yaml"
+  - type: object
+    properties:
+      type:
+        description: Document type — must be "Playbook" for playbook documents.
+        type: string
+        const: Playbook
+      estimated_duration:
+        description: Approximate time to complete the playbook (e.g., "15 min", "2 h").
+        type: string
+      tools_required:
+        description: CLI tools, scripts, or external utilities the reader must have installed.
+        type: array
+        items: { type: string }
+    required: [type]

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

@@ -0,0 +1,40 @@
+$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.
+type: object
+properties:
+  type:
+    description: Document type — must be "Principle".
+    type: string
+    const: Principle
+  title:
+    description: Human-readable title of the principle.
+    type: string
+    minLength: 1
+  description:
+    description: Short summary of the standard or convention.
+    type: string
+    minLength: 1
+  tags:
+    description: Keywords for categorization and search.
+    type: array
+    items: { type: string }
+  timestamp:
+    description: When the principle was agreed or last updated (ISO 8601).
+    type: string
+    format: date-time
+  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, title, description]
+additionalProperties: false

copilot_session_usage-0.2.0/knowledge/_schema/Reference.schema.yaml

@@ -0,0 +1,19 @@
+$schema: "http://json-schema.org/draft-07/schema#"
+title: Reference
+description: A reference document with structured data, schemas, or lookup tables.
+allOf:
+  - $ref: "Base.schema.yaml"
+  - type: object
+    properties:
+      type:
+        description: Document type — must be "Reference" for reference documents.
+        type: string
+        const: Reference
+      schema_version:
+        description: Version of the data schema or API documented here (e.g., "v2.1").
+        type: string
+      authoritative_source:
+        description: URL or identifier of the canonical upstream specification this reference mirrors.
+        type: string
+        format: uri
+    required: [type]

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

@@ -0,0 +1,41 @@
+$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).
+type: object
+properties:
+  type:
+    description: Document type — must be "Structure".
+    type: string
+    const: Structure
+  title:
+    description: Human-readable title of the structure.
+    type: string
+    minLength: 1
+  description:
+    description: Short summary of what is described.
+    type: string
+    minLength: 1
+  tags:
+    description: Keywords for categorization and search.
+    type: array
+    items: { type: string }
+  timestamp:
+    description: When the structure was documented or last updated (ISO 8601).
+    type: string
+    format: date-time
+  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, title, description]
+additionalProperties: false

{copilot_session_usage-0.1.0 → copilot_session_usage-0.2.0}/knowledge/concepts/copilot-cli.md

@@ -43,6 +43,6 @@ When asked to extract costs from a Copilot CLI session:
 
 ## Related
 
-- [VS Code Copilot Extension](./vscode-copilot-extension.md) — The reference implementation
+- [VS Code Copilot Extension](../structures/vscode-copilot-extension.md) — The reference implementation
 - [Overview](./overview.md) — General principles that likely apply to both
 - [Debug Log Format](../reference/debug-log-format.md) — Event structure reference

{copilot_session_usage-0.1.0 → copilot_session_usage-0.2.0}/knowledge/concepts/index.md

@@ -1,10 +1,6 @@
 # concepts
 
 - [Copilot CLI Differences](copilot-cli.md) — How session cost tracking differs when using copilot-cli instead of the VS Code extension.  [Concept]
-- [Cost Optimization Patterns](cost-optimization.md) — Common patterns that inflate session costs and strategies to reduce them.  [Playbook]
 - [Session Cost Analysis](session-cost-analysis.md) — Process of extracting token usage metrics from Copilot debug logs and estimating monetary cost based on per-model pricing.  [Concept]
 - [Session Cost Tracking Overview](overview.md) — How VS Code Copilot tracks and exposes per-session token costs for coding agents.  [Concept]
-- [Session Discovery Algorithm](session-discovery-algorithm.md) — How an agent resolves a session title, date, or workspace to its debug-log directory via `state.vscdb`.  [Concept]
-- [Subagent Cost Tracking](subagent-cost-tracking.md) — How subagent costs are logged, aggregated, and correlated with parent sessions.  [Concept]
 - [Threshold-Based Pricing](threshold-based-pricing.md) — How multi-tier model pricing (e.g. GPT-5.4 ≤272K vs >272K) is parsed from YAML and applied during cost estimation.  [Concept]
-- [VS Code Copilot Extension Debug Logs](vscode-copilot-extension.md) — How the VS Code Copilot extension stores session logs and what agents need to know about path resolution.  [Concept]

{copilot_session_usage-0.1.0 → copilot_session_usage-0.2.0}/knowledge/concepts/overview.md

@@ -44,4 +44,4 @@ Each session directory contains:
 ## Related
 
 - [Debug Log Format](../reference/debug-log-format.md) — Event structure details
-- [Subagent Cost Tracking](./subagent-cost-tracking.md) — How subagent costs are aggregated
+- [Subagent Cost Tracking](../structures/subagent-cost-tracking.md) — How subagent costs are aggregated

copilot_session_usage-0.2.0/knowledge/experiments/index.md

@@ -0,0 +1,3 @@
+# experiments
+
+- [Verify Subagent Cost Attribution](verify-subagent-cost-attribution.md) — Check that subagent token costs are attributed to their runSubagent call and not double-counted in the parent session total.  [Experiment]