copilot-session-usage 0.1.0__py3-none-any.whl

copilot_session_usage/cli.py

@@ -0,0 +1,282 @@
+"""Click CLI entry point for copilot-session-usage."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from copilot_session_usage._internal import core, vscode
+
+CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}
+
+
+def _resolve_agent(agent: str) -> str:
+    """Validate agent choice and return it."""
+    if agent == "cli":
+        raise click.ClickException(
+            "Copilot-CLI session discovery is not yet implemented. "
+            "Use --agent vscode (the default)."
+        )
+    return agent
+
+
+@click.group(context_settings=CONTEXT_SETTINGS)
+@click.option(
+    "--workspace-storage",
+    "workspace_storage",
+    metavar="PATH",
+    help=(
+        "Override workspaceStorage directory (auto-detected by default). "
+        "Required on WSL2 when VS Code runs on the Windows host."
+    ),
+)
+@click.option(
+    "--agent",
+    "agent",
+    type=click.Choice(("vscode", "cli")),
+    default="vscode",
+    show_default=True,
+    help="Provider to use for session discovery. 'cli' is not yet implemented.",
+)
+@click.pass_context
+def cli(
+    ctx: click.Context,
+    workspace_storage: str | None,
+    agent: str,
+) -> None:
+    """Extract VS Code Copilot session cost KPIs from local debug logs.
+
+    Reads JSONL debug logs written by the VS Code Copilot Chat extension to
+    compute per-session token counts, estimated USD spend, model breakdowns,
+    duration, and subagent attribution.
+
+    Sessions are auto-discovered from the VS Code workspaceStorage directory
+    (override with --workspace-storage). Use the subcommands below to analyze
+    individual sessions, the latest session, or batches.
+
+    Output is controlled by --detail (minimal / compact / full) and
+    --format (table / json / detailed). Key capabilities include per-model
+    pricing with cache-hit discounts, threshold-aware tier switching for
+    long-context models, multi-model session handling, subagent cost
+    attribution, and cross-platform support (macOS, Linux, Windows, WSL2).
+    """
+    ctx.ensure_object(dict)
+    ctx.obj["workspace_storage"] = workspace_storage
+    ctx.obj["agent"] = _resolve_agent(agent)
+
+
+@cli.command()
+@core.analysis_options
+@click.argument("log_dir", metavar="PATH")
+def analyze(
+    log_dir: str,
+    detail: str,
+    format_: str,
+    output_path: str | None,
+) -> None:
+    """Analyze a single session by its debug-log directory PATH.
+
+    PATH is typically the VS Code Copilot session debug log directory —
+    this is the fastest path, no discovery needed.
+    """
+    session_dir = Path(log_dir)
+    if not session_dir.exists():
+        msg = f"log directory not found: {session_dir}"
+        raise click.ClickException(msg)
+    pricing = core.load_pricing()
+    result = core.analyze_session(session_dir, pricing)
+    detail = core.resolve_detail(detail, format_)
+    out_path = Path(output_path) if output_path else None
+    core.emit(core.shape_session(result, detail), core.normalize_format(format_), out_path)
+
+
+@cli.command()
+@core.analysis_options
+@click.option(
+    "--workspace", metavar="PATH", help="Only consider sessions from this workspace folder."
+)
+@click.pass_context
+def latest(
+    ctx: click.Context,
+    workspace: str | None,
+    detail: str,
+    format_: str,
+    output_path: str | None,
+) -> None:
+    """Analyze the most recently modified session across all workspaces."""
+    ws_roots = vscode.resolve_ws_roots(ctx.obj.get("workspace_storage"))
+    session_dir = vscode.find_latest_session_dir(ws_roots, workspace_filter=workspace)
+    if not session_dir:
+        msg = "no session debug logs found in workspace storage."
+        raise click.ClickException(msg)
+    pricing = core.load_pricing()
+    result = core.analyze_session(session_dir, pricing)
+    detail = core.resolve_detail(detail, format_)
+    out_path = Path(output_path) if output_path else None
+    core.emit(
+        core.shape_session(result, detail),
+        core.normalize_format(format_),
+        out_path,
+    )
+
+
+@cli.command(name="find")
+@core.analysis_options
+@click.option(
+    "--workspace",
+    metavar="PATH",
+    help="Only consider sessions from this workspace folder.",
+)
+@click.argument("title")
+@click.pass_context
+def find_by_title(
+    ctx: click.Context,
+    title: str,
+    workspace: str | None,
+    detail: str,
+    format_: str,
+    output_path: str | None,
+) -> None:
+    """Find and analyze a session by TITLE (case-insensitive substring match).
+
+    If more than one session matches, candidates are printed and the command
+    exits with an error — re-run with `id <SESSION_ID>` to pick one.
+    """
+    ws_roots = vscode.resolve_ws_roots(ctx.obj.get("workspace_storage"))
+    matches = vscode.find_sessions_by_title(title, ws_roots)
+    if workspace:
+        matches = [m for m in matches if workspace in m.get("workspace_folder", "")]
+    if not matches:
+        msg = f"no sessions found matching title: {title!r}"
+        raise click.ClickException(msg)
+    if len(matches) > 1:
+        click.echo(f"Multiple sessions match {title!r}:", err=True)
+        for m in matches[:10]:
+            ts = core.ts_to_iso(m.get("created_ms")) or "unknown"
+            click.echo(f"  {ts}  {m['title']!r}  (id: {m['session_id']})", err=True)
+        click.echo("Re-run with: copilot-session-usage id <SESSION_ID>", err=True)
+        sys.exit(1)
+    match = matches[0]
+    session_dir = Path(match["debug_log_dir"])
+    if not session_dir.exists():
+        msg = f"debug logs not present at: {session_dir}"
+        raise click.ClickException(msg)
+    pricing = core.load_pricing()
+    result = core.analyze_session(session_dir, pricing)
+    result["title"] = match.get("title") or result.get("title")
+    detail = core.resolve_detail(detail, format_)
+    out_path = Path(output_path) if output_path else None
+    core.emit(
+        core.shape_session(result, detail),
+        core.normalize_format(format_),
+        out_path,
+    )
+
+
+@cli.command(name="id")
+@core.analysis_options
+@click.argument("session_id")
+@click.pass_context
+def analyze_by_id(
+    ctx: click.Context,
+    session_id: str,
+    detail: str,
+    format_: str,
+    output_path: str | None,
+) -> None:
+    """Analyze a session by its exact SESSION_ID (UUID)."""
+    ws_roots = vscode.resolve_ws_roots(ctx.obj.get("workspace_storage"))
+    session_dir = vscode.find_session_dir_by_id(session_id, ws_roots)
+    if not session_dir:
+        msg = f"no debug logs found for session ID: {session_id}"
+        raise click.ClickException(msg)
+    pricing = core.load_pricing()
+    result = core.analyze_session(session_dir, pricing)
+    detail = core.resolve_detail(detail, format_)
+    out_path = Path(output_path) if output_path else None
+    core.emit(core.shape_session(result, detail), core.normalize_format(format_), out_path)
+
+
+@cli.command(name="list")
+@core.format_option
+@core.output_option
+@click.option(
+    "--limit",
+    type=int,
+    default=20,
+    show_default=True,
+    help="Max sessions to return.",
+)
+@click.option(
+    "--since", metavar="DATE", help="Only sessions created after DATE (YYYY-MM-DD or ISO 8601)."
+)
+@click.option(
+    "--workspace", metavar="PATH", help="Only consider sessions from this workspace folder."
+)
+@click.pass_context
+def list_sessions(
+    ctx: click.Context,
+    limit: int,
+    since: str | None,
+    workspace: str | None,
+    format_: str,
+    output_path: str | None,
+) -> None:
+    """List recent sessions (metadata only — no cost analysis)."""
+    ws_roots = vscode.resolve_ws_roots(ctx.obj.get("workspace_storage"))
+    since_ms = core.parse_since_to_ms(since) if since else None
+    sessions = vscode.list_recent_sessions(
+        ws_roots, limit=limit, since_ms=since_ms, workspace_filter=workspace
+    )
+    out_path = Path(output_path) if output_path else None
+    core.emit(sessions, core.normalize_format(format_), out_path)
+
+
+@cli.command()
+@core.analysis_options
+@click.option(
+    "--since", metavar="DATE", help="Only sessions created after DATE (YYYY-MM-DD or ISO 8601)."
+)
+@click.option(
+    "--workspace", metavar="PATH", help="Only consider sessions from this workspace folder."
+)
+@click.argument("count", type=int, metavar="N")
+@click.pass_context
+def batch(
+    ctx: click.Context,
+    count: int,
+    since: str | None,
+    workspace: str | None,
+    detail: str,
+    format_: str,
+    output_path: str | None,
+) -> None:
+    """Analyze the N most recent sessions in one invocation.
+
+    Always returns {"summary": {...}, "sessions": [...]}: a pre-computed
+    aggregate across all N sessions plus a per-session array shaped by
+    --detail. Much faster than N separate `id` invocations.
+    """
+    ws_roots = vscode.resolve_ws_roots(ctx.obj.get("workspace_storage"))
+    since_ms = core.parse_since_to_ms(since) if since else None
+    sessions = vscode.list_recent_sessions(
+        ws_roots,
+        limit=count,
+        since_ms=since_ms,
+        workspace_filter=workspace,
+        require_logs=True,
+    )
+    pricing = core.load_pricing()
+    results: list[dict] = []
+    for session in sessions:
+        session_dir = Path(session["debug_log_dir"])
+        if not session_dir.exists():
+            continue
+        result = core.analyze_session(session_dir, pricing)
+        result["title"] = session.get("title") or result.get("title")
+        results.append(result)
+    detail = core.resolve_detail(detail, format_)
+    out_path = Path(output_path) if output_path else None
+    core.emit(core.shape_batch(results, detail), core.normalize_format(format_), out_path)

copilot_session_usage/data/custom-models-pricing.yml

@@ -0,0 +1,22 @@
+# Custom model pricing for models not included in the GitHub Copilot plan.
+# Prices are per 1 million tokens.
+#
+# Use this file to define pricing for models that appear in debug logs
+# but are not part of the standard Copilot model catalog.
+#
+# Column keys:
+# - model: The model name as it appears in the debug log.
+# - provider: The model provider (optional, defaults to "custom").
+# - input: Input token price per 1M tokens.
+# - cached_input: Cached input token price per 1M tokens.
+# - output: Output token price per 1M tokens.
+# - notes: Optional notes about the model.
+
+- model: 'Kimi-K2.6-azure'
+  provider: custom
+  input: $0.00
+  cached_input: $0.00
+  output: $0.00
+  notes: >
+    Azure-hosted Kimi K2.6 model. Pricing not tracked in Copilot plan;
+    set to $0 as a placeholder. Update if actual per-token pricing becomes available.

copilot_session_usage/data/models-and-pricing.lock

@@ -0,0 +1,7 @@
+{
+  "_captured": "2026-07-01T13:17:03.382420+00:00",
+  "_source": "https://raw.githubusercontent.com/github/docs/main/data/tables/copilot/models-and-pricing.yml",
+  "_yaml_path": "references/models-and-pricing.yml",
+  "model_count": 26,
+  "checksum": "0d398b5cf45bf9ff"
+}

copilot_session_usage/data/models-and-pricing.yml

@@ -0,0 +1,269 @@
+# This file defines per-token pricing for AI models available in GitHub Copilot.
+# Prices are per 1 million tokens.
+#
+# Please keep this list sorted by provider, then alphabetically by model name.
+# Providers in this order: OpenAI, Anthropic, Google, xAI, Fine-tuned (GitHub).
+#
+# Column keys:
+# - model: The model name.
+# - provider: The model provider (openai, anthropic, google, xai, github).
+# - release_status: "GA" or "Public preview".
+# - category: The model category or task area.
+# - input: Input token price per 1M tokens.
+# - cached_input: Cached input token price per 1M tokens.
+# - output: Output token price per 1M tokens.
+# - threshold: Input token threshold for pricing tier (OpenAI and Google only).
+# - tier: Pricing tier label (OpenAI and Google only).
+# - cache_write: Cache write price per 1M tokens (Anthropic only).
+# - notes: Optional notes about the model.
+
+# OpenAI
+- model: 'GPT-5 mini'
+  provider: openai
+  release_status: GA
+  category: Lightweight
+  threshold: Not applicable
+  tier: Default
+  input: $0.25
+  cached_input: $0.025
+  output: $2.00
+
+- model: GPT-5.3-Codex
+  provider: openai
+  release_status: GA
+  category: Powerful
+  threshold: Not applicable
+  tier: Default
+  input: $1.75
+  cached_input: $0.175
+  output: $14.00
+
+- model: 'GPT-5.4'
+  provider: openai
+  release_status: GA
+  category: Versatile
+  threshold: '≤ 272K'
+  tier: Default
+  input: $2.50
+  cached_input: $0.25
+  output: $15.00
+
+- model: GPT-5.4
+  provider: openai
+  release_status: GA
+  category: Versatile
+  threshold: '> 272K'
+  tier: Long context
+  input: $5.00
+  cached_input: $0.50
+  output: $22.50
+
+- model: GPT-5.4 mini
+  provider: openai
+  release_status: GA
+  category: Lightweight
+  threshold: Not applicable
+  tier: Default
+  input: $0.75
+  cached_input: $0.075
+  output: $4.50
+
+- model: GPT-5.4 nano
+  provider: openai
+  release_status: GA
+  category: Lightweight
+  threshold: Not applicable
+  tier: Default
+  input: $0.20
+  cached_input: $0.02
+  output: $1.25
+
+- model: GPT-5.5
+  provider: openai
+  release_status: GA
+  category: Powerful
+  threshold: '≤ 272K'
+  tier: Default
+  input: $5.00
+  cached_input: $0.50
+  output: $30.00
+
+- model: GPT-5.5
+  provider: openai
+  release_status: GA
+  category: Powerful
+  threshold: '> 272K'
+  tier: 'Long context'
+  input: $10.00
+  cached_input: $1.00
+  output: $45.00
+
+# Anthropic
+- model: Claude Haiku 4.5
+  provider: anthropic
+  release_status: GA
+  category: Versatile
+  input: $1.00
+  cached_input: $0.10
+  output: $5.00
+  cache_write: $1.25
+
+- model: Claude Sonnet 4
+  provider: anthropic
+  release_status: GA
+  category: Versatile
+  input: $3.00
+  cached_input: $0.30
+  output: $15.00
+  cache_write: $3.75
+
+- model: Claude Sonnet 4.5
+  provider: anthropic
+  release_status: GA
+  category: Versatile
+  input: $3.00
+  cached_input: $0.30
+  output: $15.00
+  cache_write: $3.75
+
+- model: Claude Sonnet 4.6
+  provider: anthropic
+  release_status: GA
+  category: Versatile
+  input: $3.00
+  cached_input: $0.30
+  output: $15.00
+  cache_write: $3.75
+
+- model: Claude Opus 4.5
+  provider: anthropic
+  release_status: GA
+  category: Powerful
+  input: $5.00
+  cached_input: $0.50
+  output: $25.00
+  cache_write: $6.25
+
+- model: Claude Opus 4.6
+  provider: anthropic
+  release_status: GA
+  category: Powerful
+  input: $5.00
+  cached_input: $0.50
+  output: $25.00
+  cache_write: $6.25
+
+- model: Claude Opus 4.7
+  provider: anthropic
+  release_status: GA
+  category: Powerful
+  input: $5.00
+  cached_input: $0.50
+  output: $25.00
+  cache_write: $6.25
+
+- model: Claude Opus 4.8
+  provider: anthropic
+  release_status: GA
+  category: Powerful
+  input: $5.00
+  cached_input: $0.50
+  output: $25.00
+  cache_write: $6.25
+
+- model: Claude Sonnet 5[^sonnet-5-promo]
+  provider: anthropic
+  release_status: GA
+  category: Versatile
+  input: $2.00
+  cached_input: $0.20
+  output: $10.00
+  cache_write: $2.50
+
+- model: Claude Opus 4.8 (fast mode) (preview)
+  provider: anthropic
+  release_status: GA
+  category: Powerful
+  input: $10.00
+  cached_input: $1.00
+  output: $50.00
+  cache_write: $12.50
+
+- model: Claude Fable 5
+  provider: anthropic
+  release_status: GA
+  category: Powerful
+  input: $10.00
+  cached_input: $1.00
+  output: $50.00
+  cache_write: $12.50
+
+# Google
+- model: 'Gemini 2.5 Pro'
+  provider: google
+  release_status: GA
+  category: Powerful
+  threshold: 'Not applicable'
+  tier: 'Default'
+  input: $1.25
+  cached_input: $0.125
+  output: $10.00
+
+- model: 'Gemini 3 Flash'
+  provider: google
+  release_status: Public preview
+  category: Lightweight
+  threshold: 'Not applicable'
+  tier: 'Default'
+  input: $0.50
+  cached_input: $0.05
+  output: $3.00
+
+- model: 'Gemini 3.1 Pro'
+  provider: google
+  release_status: Public preview
+  category: Powerful
+  threshold: '≤ 200K'
+  tier: 'Default'
+  input: $2.00
+  cached_input: $0.20
+  output: $12.00
+
+- model: 'Gemini 3.1 Pro'
+  provider: google
+  release_status: Public preview
+  category: Powerful
+  threshold: '> 200K'
+  tier: 'Long context'
+  input: $4.00
+  cached_input: $0.40
+  output: $18.00
+
+- model: 'Gemini 3.5 Flash'
+  provider: google
+  release_status: GA
+  category: Lightweight
+  threshold: 'Not applicable'
+  tier: 'Default'
+  input: $1.50
+  cached_input: $0.15
+  output: $9.00
+
+# Microsoft
+- model: 'MAI-Code-1-Flash'
+  provider: microsoft
+  release_status: GA
+  category: Lightweight
+  input: $0.75
+  cached_input: $0.075
+  output: $4.50
+
+# Fine-tuned (GitHub)
+- model: 'Raptor mini'
+  provider: github
+  release_status: GA
+  category: Versatile
+  input: $0.25
+  cached_input: $0.025
+  output: $2.00
+  notes: Uses GPT-5 mini pricing