copilot-metrics 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.1.3 - 2026-05-31
+
+### Fixed
+
+- Hook install now avoids embedding transient `npx` cache shims, which can break when their shebang points at a removed Node install. Generated hooks use a stable `npx -y copilot-metrics@<version>` package invocation for those cache paths.
+
+## 0.1.2 - 2026-05-31
+
+### Fixed
+
+- Reports now import Copilot CLI session-state `events.jsonl` files by default, so token statistics are collected after `init` and hooks install without requiring users to export telemetry environment variables.
+- Copilot session-state imports persist only shutdown usage records, while using prompt-bearing session events in memory for label extraction and context.
+- Hook-only report diagnostics now stay quiet when token-bearing Copilot session-state usage is available.
+
 ## 0.1.1 - 2026-05-30
 
 ### Added

package/README.md

@@ -9,8 +9,8 @@ Costs are estimates, not official billing records. GitHub billing remains the so
 From npm:
 
 ```bash
-npx copilot-metrics@0.1.1 --help
-npx copilot-metrics@0.1.1 init
+npx copilot-metrics@0.1.3 --help
+npx copilot-metrics@0.1.3 init
 ```
 
 From this checkout:
@@ -38,24 +38,28 @@ export COPILOT_METRICS_HOME=/path/to/copilot-metrics-data
 Useful commands:
 
 ```bash
-npx copilot-metrics@0.1.1 init
-npx copilot-metrics@0.1.1 paths --json
+npx copilot-metrics@0.1.3 init
+npx copilot-metrics@0.1.3 paths --json
 ```
 
 ## Configure Telemetry
 
+For Copilot CLI, `init` plus hooks are enough for local token reporting. Reports import Copilot's local session-state `events.jsonl` files and extract shutdown usage totals without requiring telemetry environment variables.
+
 Print VS Code Insiders Copilot Chat OpenTelemetry settings:
 
 ```bash
-npx copilot-metrics@0.1.1 setup vscode
+npx copilot-metrics@0.1.3 setup vscode
 ```
 
 Print Copilot CLI OpenTelemetry environment exports:
 
 ```bash
-npx copilot-metrics@0.1.1 setup copilot-cli
+npx copilot-metrics@0.1.3 setup copilot-cli
 ```
 
+This is optional. Use it only when you also want Copilot CLI OTel JSONL output.
+
 Content capture is disabled by default. Do not enable richer prompt capture unless you explicitly accept the privacy tradeoff.
 
 ## Configure Hooks
@@ -63,51 +67,52 @@ Content capture is disabled by default. Do not enable richer prompt capture unle
 Preview repo-local hook config. The default `--surface both` emits the Copilot CLI lower camel case hook format:
 
 ```bash
-npx copilot-metrics@0.1.1 hooks preview --scope local --surface both
+npx copilot-metrics@0.1.3 hooks preview --scope local --surface both
 ```
 
 Install repo-local or user-global hook config:
 
 ```bash
-npx copilot-metrics@0.1.1 hooks install --scope local --surface both
-npx copilot-metrics@0.1.1 hooks install --scope global --surface both
+npx copilot-metrics@0.1.3 hooks install --scope local --surface both
+npx copilot-metrics@0.1.3 hooks install --scope global --surface both
 ```
 
 Local install writes `.github/hooks/copilot-metrics.json`. Global install updates `~/.copilot/settings.json` idempotently, replacing prior `copilot-metrics` hook entries while preserving other settings and hooks. Use `--surface vscode` for VS Code-only PascalCase events or `--surface copilot-cli` for CLI-native lower camel case events. The hook logger writes redacted JSONL metadata to the central data directory. It extracts Jira-style labels such as `DEMO-12345` from safe metadata and does not store full prompt text by default.
 
 ## Import Telemetry
 
-Initialize the local SQLite store and import JSONL files:
+Initialize the local SQLite store and import JSONL files manually:
 
 ```bash
-npx copilot-metrics@0.1.1 store init
-npx copilot-metrics@0.1.1 import --source vscode --file ~/.local/share/copilot-metrics/telemetry/vscode-copilot-otel.jsonl
-npx copilot-metrics@0.1.1 import --source copilot-cli --file ~/.local/share/copilot-metrics/telemetry/copilot-cli-otel.jsonl
-npx copilot-metrics@0.1.1 import --source hooks --file ~/.local/share/copilot-metrics/hooks/copilot-hooks.jsonl
+npx copilot-metrics@0.1.3 store init
+npx copilot-metrics@0.1.3 import --source vscode --file ~/.local/share/copilot-metrics/telemetry/vscode-copilot-otel.jsonl
+npx copilot-metrics@0.1.3 import --source copilot-cli --file ~/.local/share/copilot-metrics/telemetry/copilot-cli-otel.jsonl
+npx copilot-metrics@0.1.3 import --source copilot-session --file ~/.copilot/session-state/<session-id>/events.jsonl
+npx copilot-metrics@0.1.3 import --source hooks --file ~/.local/share/copilot-metrics/hooks/copilot-hooks.jsonl
 ```
 
-Imports persist raw records, normalized LLM usage records, hook events, label evidence, and import warnings. Re-importing the same JSONL rows is idempotent.
+Imports persist raw records, normalized LLM usage records, hook events, label evidence, and import warnings. Re-importing the same JSONL rows is idempotent. For Copilot session-state files, only shutdown usage rows are persisted; prompt-bearing session events are used in memory for label extraction and context and are not stored as raw records.
 
 ## Reports
 
 Run local reports from the SQLite store:
 
 ```bash
-npx copilot-metrics@0.1.1 report labels
-npx copilot-metrics@0.1.1 report label DEMO-12345
-npx copilot-metrics@0.1.1 report label DEMO-12345 --detail
-npx copilot-metrics@0.1.1 report models
-npx copilot-metrics@0.1.1 report repos
-npx copilot-metrics@0.1.1 report unattributed
+npx copilot-metrics@0.1.3 report labels
+npx copilot-metrics@0.1.3 report label DEMO-12345
+npx copilot-metrics@0.1.3 report label DEMO-12345 --detail
+npx copilot-metrics@0.1.3 report models
+npx copilot-metrics@0.1.3 report repos
+npx copilot-metrics@0.1.3 report unattributed
 ```
 
 Every report supports `--json`:
 
 ```bash
-npx copilot-metrics@0.1.1 report labels --json
+npx copilot-metrics@0.1.3 report labels --json
 ```
 
-Report commands automatically import newly appended configured VS Code, Copilot CLI, and hook JSONL files before querying. Label reports include input, output, cache read, cache creation, and reasoning token totals. Labels seen only in hooks remain visible as hook-only evidence with zero usage records, so attribution hints do not imply token-bearing usage.
+Report commands automatically import newly appended configured VS Code OTel, optional Copilot CLI OTel, Copilot CLI session-state, and hook JSONL files before querying. Label reports include input, output, cache read, cache creation, and reasoning token totals. Labels seen only in hooks remain visible as hook-only evidence with zero usage records, so attribution hints do not imply token-bearing usage.
 
 ## Attribution Model
 
@@ -170,7 +175,7 @@ The manual prompt performs one harmless tool call so Copilot CLI hook execution
 ## Current Limits
 
 - Costs are estimates, not official billing records.
-- Official GitHub usage report reconciliation is not included in `0.1.1`.
-- Local OTLP collector mode is not included in `0.1.1`.
-- Richer prompt/content capture and redaction controls are not included in `0.1.1`.
+- Official GitHub usage report reconciliation is not included in `0.1.3`.
+- Local OTLP collector mode is not included in `0.1.3`.
+- Richer prompt/content capture and redaction controls are not included in `0.1.3`.
 - Dashboard views are deferred until the CLI/query model proves useful.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "copilot-metrics",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Local-first Copilot usage telemetry setup and reporting tools.",
   "type": "commonjs",
   "homepage": "https://github.com/nnexai/copilot-metrics#readme",

package/src/cli.js

@@ -34,6 +34,10 @@ function parseFlags(args) {
   const rest = [];
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
+    if (arg === '--') {
+      rest.push(...args.slice(i + 1));
+      break;
+    }
     if (!arg.startsWith('--')) {
       rest.push(arg);
       continue;
@@ -72,7 +76,7 @@ Usage:
   copilot-metrics hooks install [--scope local|global] [--surface both|vscode|copilot-cli] [--json]
   copilot-metrics hook-log --event <name>
   copilot-metrics store init [--json]
-  copilot-metrics import --source vscode|copilot-cli|hooks --file <path> [--json]
+  copilot-metrics import --source vscode|copilot-cli|copilot-session|hooks --file <path> [--json]
   copilot-metrics report labels [--json]
   copilot-metrics report label <id> [--detail] [--json]
   copilot-metrics report models [--json]
@@ -112,10 +116,55 @@ function formatCopilotCli(env) {
     'Export these variables before running Copilot CLI:',
     shellExports(env),
     '',
+    'This is optional. Copilot CLI session-state usage is imported by reports without these exports.',
+    '',
     'Content capture is disabled by default.',
   ].join('\n');
 }
 
+function telemetryDiagnostics(importResults) {
+  const hookResult = importResults.find((result) => result.source === 'hooks' && result.raw_records > 0);
+  if (!hookResult) return [];
+  const sessionUsage = importResults.find((result) => result.source === 'copilot-session' && result.raw_records > 0);
+  if (sessionUsage) return [];
+
+  const cliTelemetry = importResults.find((result) => result.source === 'copilot-cli');
+  if (!cliTelemetry) return [];
+
+  if (cliTelemetry.skipped && cliTelemetry.reason === 'missing_file') {
+    return [{
+      code: 'missing_copilot_cli_otel',
+      message: `Hook evidence was found, but no token-bearing Copilot session-state or OTel usage was imported. Check that ${cliTelemetry.file} exists for optional OTel data, or that Copilot session-state files are available under the configured COPILOT_HOME.`,
+    }];
+  }
+
+  if (cliTelemetry.raw_records === 0) {
+    return [{
+      code: 'empty_copilot_cli_otel',
+      message: `Hook evidence was found, but Copilot CLI token telemetry is empty at ${cliTelemetry.file}. Run another Copilot session with OTel enabled.`,
+    }];
+  }
+
+  if (cliTelemetry.usage_records === 0) {
+    return [{
+      code: 'no_copilot_cli_usage_records',
+      message: `Copilot CLI telemetry was found at ${cliTelemetry.file}, but no token-bearing LLM spans were normalized from it.`,
+    }];
+  }
+
+  return [];
+}
+
+function appendDiagnostics(output, diagnostics) {
+  if (diagnostics.length === 0) return output;
+  return [
+    output,
+    '',
+    'Diagnostics:',
+    ...diagnostics.map((diagnostic) => `- ${diagnostic.message}`),
+  ].join('\n');
+}
+
 async function main(args, io) {
   const { flags, rest } = parseFlags(args);
   const json = flags.json === true;
@@ -213,8 +262,8 @@ async function main(args, io) {
         : source === 'hooks'
           ? paths.hookEventsJsonl
           : null);
-    if (!['vscode', 'copilot-cli', 'hooks'].includes(source)) {
-      throw new Error('import requires --source vscode|copilot-cli|hooks');
+    if (!['vscode', 'copilot-cli', 'copilot-session', 'hooks'].includes(source)) {
+      throw new Error('import requires --source vscode|copilot-cli|copilot-session|hooks');
     }
     if (!file) throw new Error('import requires --file <path>');
     ensureDataDirs(paths);
@@ -237,14 +286,15 @@ async function main(args, io) {
 
   if (command === 'report') {
     ensureDataDirs(paths);
-    await autoImportConfiguredSources(paths, {
+    const imports = await autoImportConfiguredSources(paths, {
       cwd: io.cwd,
       extractors: loadConfiguredExtractors(paths.configJson, io.cwd),
     });
+    const diagnostics = telemetryDiagnostics(imports);
 
     if (subcommand === 'labels') {
       const rows = await labelOverview(paths.usageDb);
-      writeOutput(io.stdout, json ? { labels: rows } : formatLabels(rows), json);
+      writeOutput(io.stdout, json ? { labels: rows, diagnostics } : appendDiagnostics(formatLabels(rows), diagnostics), json);
       return;
     }
     if (subcommand === 'label') {
@@ -253,10 +303,10 @@ async function main(args, io) {
       const summary = await labelSummary(paths.usageDb, label);
       if (flags.detail === true) {
         const details = await labelDetails(paths.usageDb, label);
-        writeOutput(io.stdout, json ? { label: summary, details } : formatLabelSummary(summary, details), json);
+        writeOutput(io.stdout, json ? { label: summary, details, diagnostics } : appendDiagnostics(formatLabelSummary(summary, details), diagnostics), json);
         return;
       }
-      writeOutput(io.stdout, json ? { label: summary } : formatLabelSummary(summary), json);
+      writeOutput(io.stdout, json ? { label: summary, diagnostics } : appendDiagnostics(formatLabelSummary(summary), diagnostics), json);
       return;
     }
     if (subcommand === 'models') {
@@ -291,4 +341,5 @@ module.exports = {
   main,
   parseFlags,
   helpText,
+  telemetryDiagnostics,
 };

package/src/ingest.js

@@ -4,7 +4,7 @@ const crypto = require('node:crypto');
 const fs = require('node:fs');
 const path = require('node:path');
 const { readJsonl } = require('./jsonl');
-const { normalizePayload, normalizeHookEvent } = require('./otel');
+const { normalizePayload, normalizeHookEvent, normalizeCopilotSessionEvents } = require('./otel');
 const { estimateCost, PRICING_VERSION } = require('./pricing');
 const { existingRawFingerprints, insertImport } = require('./sqlite-store');
 const { attachUsageLabelEvidence, attachHookLabelEvidence } = require('./labels');
@@ -38,6 +38,10 @@ function rawFingerprint(source, file, record) {
     .digest('hex');
 }
 
+function isCopilotSessionUsageRecord(record) {
+  return record.value && record.value.type === 'session.shutdown';
+}
+
 async function ingestFile(options) {
   const { dbPath, file, source } = options;
   const parsed = readJsonl(file);
@@ -47,23 +51,30 @@ async function ingestFile(options) {
     ...record,
     raw_fingerprint: rawFingerprint(source, sourceFile, record),
   }));
+  const importableRecords = source === 'copilot-session'
+    ? parsedRecords.filter(isCopilotSessionUsageRecord)
+    : parsedRecords;
   const existing = await existingRawFingerprints(
     dbPath,
     source,
     sourceFile,
-    parsedRecords.map((record) => record.raw_fingerprint),
+    importableRecords.map((record) => record.raw_fingerprint),
   );
-  const newRecords = parsedRecords.filter((record) => !existing.has(record.raw_fingerprint));
+  const newRecords = importableRecords.filter((record) => !existing.has(record.raw_fingerprint));
   const usageRecords = [];
   const hookEvents = [];
 
-  for (const record of newRecords) {
-    if (source === 'hooks') {
-      const event = normalizeHookEvent(record.value, source, record.line);
-      if (event) hookEvents.push(event);
-      continue;
+  if (source === 'copilot-session') {
+    usageRecords.push(...normalizeCopilotSessionEvents(newRecords, parsedRecords));
+  } else {
+    for (const record of newRecords) {
+      if (source === 'hooks') {
+        const event = normalizeHookEvent(record.value, source, record.line);
+        if (event) hookEvents.push(event);
+        continue;
+      }
+      usageRecords.push(...normalizePayload(record.value, source, record.line));
     }
-    usageRecords.push(...normalizePayload(record.value, source, record.line));
   }
 
   const extractorOptions = { extractors: options.extractors || [] };
@@ -85,9 +96,9 @@ async function ingestFile(options) {
     source,
     file,
     dbPath,
-    raw_records: parsed.records.length,
+    raw_records: importableRecords.length,
     new_raw_records: newRecords.length,
-    skipped_existing_records: parsed.records.length - newRecords.length,
+    skipped_existing_records: importableRecords.length - newRecords.length,
     usage_records: enrichedUsage.length,
     hook_events: enrichedHooks.length,
     label_evidence: enrichedUsage.reduce((sum, usage) => sum + (usage.label_evidence || []).length, 0)
@@ -105,6 +116,7 @@ function configuredSourceFiles(paths, config = {}) {
     { source: 'hooks', file: sourceConfig.vscode?.hooks || paths.hookEventsJsonl },
     { source: 'copilot-cli', file: sourceConfig.copilotCli?.telemetry || telemetryConfig.copilotCli || paths.copilotCliOtelJsonl },
     { source: 'hooks', file: sourceConfig.copilotCli?.hooks || paths.hookEventsJsonl },
+    ...discoverCopilotSessionFiles(sourceConfig.copilotCli?.sessions || paths.copilotSessionStateDir),
   ];
   const seen = new Set();
   return files
@@ -118,6 +130,15 @@ function configuredSourceFiles(paths, config = {}) {
     });
 }
 
+function discoverCopilotSessionFiles(sessionStateDir) {
+  if (!sessionStateDir || !fs.existsSync(sessionStateDir)) return [];
+  return fs.readdirSync(sessionStateDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => path.join(sessionStateDir, entry.name, 'events.jsonl'))
+    .filter((file) => fs.existsSync(file))
+    .map((file) => ({ source: 'copilot-session', file }));
+}
+
 function readConfig(configJson) {
   if (!fs.existsSync(configJson)) return {};
   return JSON.parse(fs.readFileSync(configJson, 'utf8'));
@@ -145,5 +166,6 @@ async function autoImportConfiguredSources(paths, options = {}) {
 module.exports = {
   autoImportConfiguredSources,
   configuredSourceFiles,
+  discoverCopilotSessionFiles,
   ingestFile,
 };

package/src/otel.js

@@ -29,6 +29,23 @@ function number(attrs, keys) {
   return Number.isFinite(parsed) ? parsed : 0;
 }
 
+const LABEL_RE = /\b[A-Z][A-Z0-9]+-\d+\b/g;
+
+function collectLabels(value, labels = new Set()) {
+  if (typeof value === 'string') {
+    for (const match of value.matchAll(LABEL_RE)) labels.add(match[0]);
+    return labels;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) collectLabels(item, labels);
+    return labels;
+  }
+  if (value && typeof value === 'object') {
+    for (const item of Object.values(value)) collectLabels(item, labels);
+  }
+  return labels;
+}
+
 function flattenSpans(payload) {
   if (!payload || typeof payload !== 'object') return [];
   if (payload.name || payload.attributes || payload.spanId) return [payload];
@@ -102,6 +119,76 @@ function normalizePayload(payload, source, rawLine) {
     .filter(Boolean);
 }
 
+function normalizeCopilotSessionEvents(newRecords, allRecords) {
+  const session = {
+    labels: new Set(),
+    id: null,
+    cwd: null,
+    repo: null,
+    branch: null,
+    commit: null,
+    conversationId: null,
+  };
+
+  for (const record of allRecords) {
+    const event = record.value;
+    if (!event || typeof event !== 'object') continue;
+    if (event.type === 'session.start') {
+      const data = event.data || {};
+      const context = data.context || {};
+      session.id = data.sessionId || session.id;
+      session.cwd = context.cwd || session.cwd;
+      session.repo = context.gitRoot || context.repository || session.repo;
+      session.branch = context.branch || session.branch;
+      session.commit = context.headCommit || session.commit;
+      collectLabels(context, session.labels);
+    }
+    if (event.type === 'hook.start') {
+      collectLabels(event.data && event.data.input, session.labels);
+    }
+    if (event.type === 'assistant.message') {
+      const data = event.data || {};
+      session.conversationId = data.interactionId || session.conversationId;
+      collectLabels(data.content, session.labels);
+    }
+  }
+
+  const records = [];
+  for (const record of newRecords) {
+    const event = record.value;
+    if (!event || event.type !== 'session.shutdown') continue;
+    const data = event.data || {};
+    const modelMetrics = data.modelMetrics || {};
+    for (const [model, metrics] of Object.entries(modelMetrics)) {
+      const usage = metrics.usage || {};
+      records.push({
+        raw_line: record.line,
+        span_id: event.id || null,
+        trace_id: session.id || null,
+        parent_span_id: event.parentId || null,
+        timestamp: event.timestamp || null,
+        surface: 'copilot-cli-session',
+        conversation_id: session.conversationId,
+        session_id: session.id,
+        requested_model: model,
+        resolved_model: model,
+        repo: session.repo,
+        branch: session.branch,
+        cwd: session.cwd,
+        commit_sha: session.commit,
+        labels: Array.from(session.labels).sort(),
+        input_tokens: Number(usage.inputTokens || 0),
+        output_tokens: Number(usage.outputTokens || 0),
+        cache_read_tokens: Number(usage.cacheReadTokens || 0),
+        cache_creation_tokens: Number(usage.cacheWriteTokens || 0),
+        reasoning_tokens: Number(usage.reasoningTokens || 0),
+        warnings: [],
+      });
+    }
+  }
+  return records;
+}
+
 function normalizeHookEvent(payload, source, rawLine) {
   if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return null;
   return {
@@ -122,5 +209,6 @@ module.exports = {
   flattenSpans,
   classifySpan,
   normalizePayload,
+  normalizeCopilotSessionEvents,
   normalizeHookEvent,
 };

package/src/paths.js

@@ -28,6 +28,7 @@ function resolvePaths(options = {}) {
   const storeDir = path.join(home, 'store');
   const skillsDir = path.join(home, 'skills');
   const copilotHome = env.COPILOT_HOME || path.join(os.homedir(), '.copilot');
+  const copilotSessionStateDir = path.join(copilotHome, 'session-state');
 
   return {
     home,
@@ -40,6 +41,8 @@ function resolvePaths(options = {}) {
     hookEventsJsonl: path.join(hooksDir, 'copilot-hooks.jsonl'),
     usageDb: path.join(storeDir, 'copilot-metrics.sqlite'),
     configJson: path.join(home, 'config.json'),
+    copilotHome,
+    copilotSessionStateDir,
     localHookConfig: path.join(cwd, '.github', 'hooks', 'copilot-metrics.json'),
     globalHookConfig: path.join(copilotHome, 'settings.json'),
   };

package/src/setup.js

@@ -3,6 +3,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { resolvePaths } = require('./paths');
+const { version: PACKAGE_VERSION } = require('../package.json');
 
 const HOOK_SURFACES = ['both', 'copilot-cli', 'vscode'];
 
@@ -59,6 +60,7 @@ function ensureDataDirs(paths) {
         copilotCli: {
           telemetry: paths.copilotCliOtelJsonl,
           hooks: paths.hookEventsJsonl,
+          sessions: paths.copilotSessionStateDir,
         },
       },
       labelExtractors: [],
@@ -95,10 +97,18 @@ function packageBinCommand(cwd) {
 }
 
 function commandInvocation(command) {
+  if (isEphemeralPackageShim(command)) {
+    return `npx -y copilot-metrics@${PACKAGE_VERSION}`;
+  }
   const quoted = shellQuote(command);
   return command.endsWith('.js') ? `node ${quoted}` : quoted;
 }
 
+function isEphemeralPackageShim(command) {
+  const normalized = String(command || '').replace(/\\/g, '/');
+  return normalized.includes('/.npm/_npx/') || normalized.endsWith('/node_modules/.bin/copilot-metrics');
+}
+
 function hookEventsForSurface(surface) {
   if (surface === 'copilot-cli' || surface === 'both') return COPILOT_CLI_HOOK_EVENTS;
   if (surface === 'vscode') return VSCODE_HOOK_EVENTS;