@jagit/hook-copilot 0.0.1 → 0.0.3

package/README.md

@@ -1,40 +1,57 @@
 # @jagit/hook-copilot
 
-Reports per-invocation GitHub Copilot CLI usage to JaGit.
+Reports GitHub Copilot agent session usage to JaGit. Supports two modes:
 
-## Setup
+1. **VS Code agent hook** (recommended) — hooks into the VS Code Copilot agent `Stop` lifecycle event, receiving a structured JSON payload from stdin including `session_id`, `cwd`, and `transcript_path`. Token counts and model name are parsed from the session transcript.
+2. **Legacy shell wrapper** — wraps the Copilot CLI binary and fires after each invocation. No per-call telemetry is available under seat-based billing, so token counts are always zero.
 
-The Copilot CLI has no hook mechanism and no persistent session telemetry, so
-install a shell function that wraps the real `copilot` binary and reports
-after each invocation ends:
+## Setup — VS Code Agent Hook (Recommended)
 
-    copilot() {
-      command copilot "$@"
-      local status=$?
-      npx -y @jagit/hook-copilot >/dev/null 2>&1 || true
-      return $status
-    }
+Add the hook to your workspace's `.github/hooks/jagit.json` (or any [supported hook location](https://code.visualstudio.com/docs/agent-customization/hooks#_hook-file-locations)):
 
-Add that function to your shell rc (`~/.zshrc`, `~/.bashrc`, etc.) — it must
-appear before any `alias`/`PATH` entry that would otherwise shadow it. (Users
-on the legacy `gh copilot` preview wrapper can apply the same pattern to a
-`gh` function instead.) Uninstall by removing the shell function.
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "type": "command",
+        "command": "npx -y @jagit/hook-copilot"
+      }
+    ]
+  }
+}
+```
 
-For a permanent binary instead of `npx -y`:
-`npm i -g @jagit/hook-copilot`, then call `jagit-hook-copilot` in the wrapper.
+VS Code automatically loads this file. When the Copilot agent session ends, JaGit receives the session report (session ID, model, aggregated token counts, tool call count).
+
+For a permanent binary instead of `npx -y`: `npm i -g @jagit/hook-copilot`, then use `jagit-hook-copilot` as the command.
+
+## Setup — Legacy Shell Wrapper (Copilot CLI)
+
+If you are using the Copilot CLI directly (not the VS Code agent), install a shell function that wraps the real `copilot` binary and reports after each invocation ends:
+
+```sh
+copilot() {
+  command copilot "$@"
+  local status=$?
+  npx -y @jagit/hook-copilot >/dev/null 2>&1 || true
+  return $status
+}
+```
+
+Add that function to your shell rc (`~/.zshrc`, `~/.bashrc`, etc.). Uninstall by removing the shell function.
 
 ## Environment
 
-    export JAGIT_BASE_URL="https://your-jagit-host"
-    export JAGIT_API_KEY="<your DASHBOARD_API_TOKEN>"
+```sh
+export JAGIT_BASE_URL="https://your-jagit-host"
+export JAGIT_API_KEY="<your DASHBOARD_API_TOKEN>"
+```
 
 Identity defaults to `git config user.email`; override with `JAGIT_GIT_USERNAME`.
 
 ## Notes
 
-- Copilot CLI exposes no local token/usage telemetry (billing is seat-based),
-  so each report uses a synthetic session id (`copilot-<timestamp>-<pid>`),
-  zero token counts, and `model: "copilot"` unless a future CLI version
-  surfaces real usage data.
-- `costUsd` is always `null` and will remain so — there is no per-invocation
-  cost to report under seat-based billing.
+- In **VS Code agent hook mode**, tokens and model are read from the session transcript at `transcript_path`. Both snake_case (`input_tokens`) and camelCase (`inputTokens`) transcript formats are supported.
+- In **legacy shell wrapper mode**, token counts are always zero (`costUsd: null`) since the Copilot CLI exposes no per-invocation telemetry under seat-based billing.
+- `costUsd` is always `null` — there is no per-session USD cost to report.

package/dist/index.d.ts

@@ -1,5 +1,53 @@
 #!/usr/bin/env node
 import { type AgentSessionPayload } from "@jagit/agent-reporter";
+export interface CopilotStopStdin {
+    /** Optional per VS Code spec — common hook field */
+    session_id?: string;
+    cwd?: string;
+    hook_event_name?: string;
+    /** Absolute path to session transcript. Format is unstable — may change in future VS Code releases. */
+    transcript_path?: string;
+    timestamp?: string;
+    /**
+     * true when the agent is already continuing as a result of a previous Stop hook.
+     * Check this to prevent the hook from reporting duplicate sessions.
+     */
+    stop_hook_active?: boolean;
+}
+export interface CopilotTranscriptSessionStart {
+    type: "session.start";
+    timestamp?: string;
+    data: {
+        sessionId?: string;
+        version?: number;
+        producer?: string;
+        copilotVersion?: string;
+        vscodeVersion?: string;
+        startTime?: string;
+    };
+}
+export interface CopilotTranscriptToolRequest {
+    toolCallId?: string;
+    name?: string;
+    arguments?: string;
+    type?: string;
+}
+export interface CopilotTranscriptAssistantMessage {
+    type: "assistant.message";
+    timestamp?: string;
+    id?: string;
+    data: {
+        messageId?: string;
+        content?: string;
+        /** Tool calls made in this assistant turn */
+        toolRequests?: CopilotTranscriptToolRequest[];
+    };
+}
+export type CopilotTranscriptEntry = CopilotTranscriptSessionStart | CopilotTranscriptAssistantMessage | {
+    type: string;
+    timestamp?: string;
+    data?: unknown;
+};
 export interface CopilotInfo {
     model?: string;
     inputTokens?: number;
@@ -7,4 +55,18 @@ export interface CopilotInfo {
     cachedInputTokens?: number;
     toolCallCount?: number | null;
 }
+/**
+ * Build payload from a real VS Code Copilot agent Stop-hook stdin.
+ *
+ * Reads the transcript to count tool calls and extract the session start time.
+ * Token usage (input/cached/output) and model name are NOT available in the
+ * VS Code Copilot transcript — Copilot uses seat-based billing and does not
+ * expose per-call telemetry. These fields are reported as 0/null/"copilot".
+ */
+export declare function buildPayloadFromStdin(stdin: CopilotStopStdin, read?: (path: string) => CopilotTranscriptEntry[]): AgentSessionPayload;
+/**
+ * Build payload in legacy mode (no stdin) — used when hook-copilot is invoked
+ * via the old shell-wrapper pattern around the Copilot CLI. Token counts are
+ * not available in this mode (seat-based billing has no per-call telemetry).
+ */
 export declare function buildPayload(cwd: string | undefined, info?: CopilotInfo): AgentSessionPayload;

package/dist/index.js

@@ -1,7 +1,93 @@
 #!/usr/bin/env node
-import { realpathSync } from "node:fs";
+import { readFileSync, realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { resolveGitUsername, reportSession } from "@jagit/agent-reporter";
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function readTranscript(path) {
+    return readFileSync(path, "utf-8")
+        .split("\n")
+        .filter((l) => l.trim().length > 0)
+        .map((l) => {
+        try {
+            return JSON.parse(l);
+        }
+        catch {
+            return { type: "__parse_error__" };
+        }
+    });
+}
+/**
+ * Count tool calls from assistant.message entries.
+ * Each assistant.message with at least one toolRequest counts as one tool-call turn;
+ * we sum the total number of individual tool requests across all turns.
+ */
+function countToolCalls(entries) {
+    let count = 0;
+    for (const e of entries) {
+        if (e.type !== "assistant.message")
+            continue;
+        const msg = e;
+        count += msg.data?.toolRequests?.length ?? 0;
+    }
+    return count;
+}
+/**
+ * Extract the earliest timestamp from the transcript.
+ * Prefers session.start data.startTime, then falls back to the first entry timestamp.
+ */
+function extractStartTime(entries) {
+    for (const e of entries) {
+        if (e.type === "session.start") {
+            const s = e;
+            if (s.data?.startTime)
+                return s.data.startTime;
+        }
+    }
+    // Fall back to the first entry with a timestamp
+    return entries.find((e) => e.timestamp)?.timestamp;
+}
+// ─── Payload builders ─────────────────────────────────────────────────────────
+/**
+ * Build payload from a real VS Code Copilot agent Stop-hook stdin.
+ *
+ * Reads the transcript to count tool calls and extract the session start time.
+ * Token usage (input/cached/output) and model name are NOT available in the
+ * VS Code Copilot transcript — Copilot uses seat-based billing and does not
+ * expose per-call telemetry. These fields are reported as 0/null/"copilot".
+ */
+export function buildPayloadFromStdin(stdin, read = readTranscript) {
+    const entries = stdin.transcript_path ? (() => {
+        try {
+            return read(stdin.transcript_path);
+        }
+        catch {
+            return [];
+        }
+    })() : [];
+    const toolCallCount = countToolCalls(entries);
+    const startedAt = extractStartTime(entries) ?? stdin.timestamp ?? new Date().toISOString();
+    return {
+        tool: "copilot",
+        // session_id is optional per VS Code spec; synthesize a fallback if absent
+        sessionId: stdin.session_id ?? `copilot-${Date.now()}-${process.pid}`,
+        gitUsername: resolveGitUsername(stdin.cwd),
+        // Model name is not exposed in the Copilot hook transcript (seat-based billing)
+        model: "copilot",
+        // Token usage is not available in the Copilot hook transcript
+        inputTokens: 0,
+        cachedInputTokens: 0,
+        cacheCreationInputTokens: 0,
+        outputTokens: 0,
+        costUsd: null,
+        toolCallCount,
+        startedAt,
+    };
+}
+/**
+ * Build payload in legacy mode (no stdin) — used when hook-copilot is invoked
+ * via the old shell-wrapper pattern around the Copilot CLI. Token counts are
+ * not available in this mode (seat-based billing has no per-call telemetry).
+ */
 export function buildPayload(cwd, info) {
     return {
         tool: "copilot",
@@ -10,15 +96,47 @@ export function buildPayload(cwd, info) {
         model: info?.model ?? "copilot",
         inputTokens: info?.inputTokens ?? 0,
         cachedInputTokens: info?.cachedInputTokens ?? 0,
+        cacheCreationInputTokens: 0,
         outputTokens: info?.outputTokens ?? 0,
         costUsd: null,
         toolCallCount: info?.toolCallCount ?? null,
         startedAt: new Date().toISOString(),
     };
 }
+// ─── Try to read a JSON object from stdin (fd 0) ─────────────────────────────
+function tryReadStdin() {
+    try {
+        const raw = readFileSync(0, "utf-8").trim();
+        if (!raw)
+            return undefined;
+        const parsed = JSON.parse(raw);
+        // Accept any object that looks like a VS Code hook payload (session_id is optional per spec)
+        if (typeof parsed === "object" && parsed !== null && "hook_event_name" in parsed) {
+            return parsed;
+        }
+        // Also accept if session_id is present (legacy / Claude Code compat)
+        if (typeof parsed.session_id === "string") {
+            return parsed;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// ─── Entry point ─────────────────────────────────────────────────────────────
 async function main() {
     try {
-        await reportSession(buildPayload(process.cwd()));
+        const stdin = tryReadStdin();
+        // stop_hook_active=true means the agent is re-running because a previous Stop hook
+        // blocked it. Skip reporting to avoid duplicate session entries.
+        if (stdin?.stop_hook_active === true) {
+            process.exit(0);
+        }
+        const payload = stdin
+            ? buildPayloadFromStdin(stdin)
+            : buildPayload(process.cwd());
+        await reportSession(payload);
     }
     catch (err) {
         console.error("[hook-copilot]", err instanceof Error ? err.message : err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jagit/hook-copilot",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "type": "module",
   "bin": {
     "jagit-hook-copilot": "dist/index.js"
@@ -9,7 +9,7 @@
     "dist"
   ],
   "dependencies": {
-    "@jagit/agent-reporter": "0.0.1"
+    "@jagit/agent-reporter": "0.0.3"
   },
   "devDependencies": {
     "@types/node": "^25.9.3",