@jagit/hook-codex 0.0.2 → 0.0.3

package/README.md

@@ -2,26 +2,50 @@
 
 Reports per-session OpenAI Codex CLI usage to JaGit.
 
-## Setup
+## Setup (recommended — native Codex hook)
 
-Codex has no built-in hook mechanism, so install a shell function that wraps
-the real `codex` binary and reports after each session ends:
+Codex CLI has a built-in hook mechanism. Add a `Stop` hook to
+`~/.codex/hooks.json` (user-level) or `.codex/hooks.json` (repo-level):
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "JAGIT_BASE_URL=https://your-jagit-host JAGIT_API_KEY=<your-token> npx -y @jagit/hook-codex",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Codex passes the session payload on stdin (including `session_id`, `model`,
+`cwd`, `transcript_path`, and `stop_hook_active`). The hook reads token usage
+from the transcript and reports the session to JaGit. The `stop_hook_active`
+guard prevents duplicate reports when Codex re-runs the hook after a
+continuation.
+
+## Setup (legacy — shell wrapper)
+
+If you are on an older Codex CLI version without hook support, install a shell
+function that wraps the real `codex` binary and reports after each session ends:
 
     codex() {
       command codex "$@"
-      local status=$?
+      local exit_code=$?
       npx -y @jagit/hook-codex >/dev/null 2>&1 || true
-      return $status
+      return $exit_code
     }
 
-Add that function to your shell rc (`~/.zshrc`, `~/.bashrc`, etc.) — it must
-appear before any `alias`/`PATH` entry that would otherwise shadow it. On
-exit, the reporter locates the most-recently-modified file under
+Add that function to your shell rc (`~/.zshrc`, `~/.bashrc`, etc.). On exit,
+the reporter locates the most-recently-modified file under
 `~/.codex/sessions/**/*.jsonl`, parses it, and posts the session summary.
-Uninstall by removing the shell function.
-
-For a permanent binary instead of `npx -y`:
-`npm i -g @jagit/hook-codex`, then call `jagit-hook-codex` in the wrapper.
 
 You can also point the reporter at a specific transcript:
 
@@ -37,6 +61,10 @@ override with `JAGIT_GIT_USERNAME`.
 
 ## Notes
 
-- Token counts are cumulative per Codex session; the reporter reads the last
-  non-null `token_count` event, not a sum across events.
-- `costUsd` is always `null` — Codex JSONL logs do not expose a cost field.
+- In native hook mode, `model` is read directly from the Codex stdin payload.
+- In legacy mode, `model` is parsed from `turn_context` records in the JSONL file.
+- Token counts in legacy mode are cumulative per Codex session; the reporter
+  reads the last non-null `token_count` event, not a sum across events.
+- In native hook mode, token counts are summed across all assistant transcript
+  entries (each entry represents one turn).
+- `costUsd` is always `null` — Codex logs do not expose a cost field.

package/dist/index.d.ts

@@ -1,5 +1,25 @@
 #!/usr/bin/env node
 import { type AgentSessionPayload } from "@jagit/agent-reporter";
+export interface CodexStopStdin {
+    /** Current Codex session id */
+    session_id: string;
+    /** Working directory for the session */
+    cwd: string;
+    /** Always "Stop" for this event */
+    hook_event_name: string;
+    /** Active model slug — Codex-specific extension */
+    model: string;
+    /** Active Codex turn id — Codex-specific extension */
+    turn_id: string;
+    /** Whether this turn was already continued by a Stop hook (prevents loops) */
+    stop_hook_active: boolean;
+    /** Path to the session transcript file, or null */
+    transcript_path: string | null;
+    /** Latest assistant message text, or null */
+    last_assistant_message: string | null;
+    /** Current permission mode */
+    permission_mode: "default" | "acceptEdits" | "plan" | "dontAsk" | "bypassPermissions";
+}
 export interface CodexRecord {
     type?: string;
     timestamp?: string;
@@ -18,4 +38,30 @@ export interface CodexRecord {
         } | null;
     };
 }
+export interface CodexTranscriptEntry {
+    type?: string;
+    timestamp?: string;
+    message?: {
+        role?: string;
+        model?: string;
+        content?: unknown;
+        usage?: {
+            input_tokens?: number;
+            output_tokens?: number;
+            cached_tokens?: number;
+            inputTokens?: number;
+            outputTokens?: number;
+            cachedTokens?: number;
+        };
+    };
+}
+/**
+ * Build payload from a real Codex Stop-hook stdin.
+ * Model is read directly from stdin; transcript is parsed for token usage.
+ */
+export declare function buildPayloadFromStdin(stdin: CodexStopStdin, read?: (path: string) => CodexTranscriptEntry[]): AgentSessionPayload;
+/**
+ * Build payload from legacy JSONL session records (file-scan fallback).
+ * Used when hook-codex is invoked via the old shell-wrapper pattern.
+ */
 export declare function buildPayload(sessionId: string, cwd: string | undefined, records: CodexRecord[]): AgentSessionPayload;

package/dist/index.js

@@ -6,6 +6,73 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { resolveGitUsername, reportSession } from "@jagit/agent-reporter";
 const TOOL_CALL_SUBTYPES = new Set(["function_call", "custom_tool_call", "web_search_call"]);
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function readJsonl(path) {
+    return readFileSync(path, "utf-8")
+        .split("\n")
+        .filter((l) => l.trim().length > 0)
+        .map((l) => {
+        try {
+            return JSON.parse(l);
+        }
+        catch {
+            return {};
+        }
+    });
+}
+function hasToolUse(content) {
+    return Array.isArray(content) && content.some((b) => b?.type === "tool_use");
+}
+// ─── Payload builders ─────────────────────────────────────────────────────────
+/**
+ * Build payload from a real Codex Stop-hook stdin.
+ * Model is read directly from stdin; transcript is parsed for token usage.
+ */
+export function buildPayloadFromStdin(stdin, read = (p) => readJsonl(p)) {
+    let inputTokens = 0;
+    let cachedInputTokens = 0;
+    let outputTokens = 0;
+    let toolCallCount = 0;
+    const entries = stdin.transcript_path
+        ? (() => {
+            try {
+                return read(stdin.transcript_path);
+            }
+            catch {
+                return [];
+            }
+        })()
+        : [];
+    for (const e of entries) {
+        if (e.message?.role !== "assistant")
+            continue;
+        if (hasToolUse(e.message.content))
+            toolCallCount += 1;
+        const u = e.message.usage;
+        if (u) {
+            inputTokens += u.input_tokens ?? u.inputTokens ?? 0;
+            cachedInputTokens += u.cached_tokens ?? u.cachedTokens ?? 0;
+            outputTokens += u.output_tokens ?? u.outputTokens ?? 0;
+        }
+    }
+    const startedAt = entries.find((e) => e.timestamp)?.timestamp ?? new Date().toISOString();
+    return {
+        tool: "codex",
+        sessionId: stdin.session_id,
+        gitUsername: resolveGitUsername(stdin.cwd),
+        model: stdin.model,
+        inputTokens,
+        cachedInputTokens,
+        outputTokens,
+        costUsd: null,
+        toolCallCount,
+        startedAt,
+    };
+}
+/**
+ * Build payload from legacy JSONL session records (file-scan fallback).
+ * Used when hook-codex is invoked via the old shell-wrapper pattern.
+ */
 export function buildPayload(sessionId, cwd, records) {
     let model = "unknown";
     let inputTokens = 0;
@@ -19,6 +86,7 @@ export function buildPayload(sessionId, cwd, records) {
         if (r.type === "event_msg" && r.payload?.type === "token_count" && r.payload.info) {
             const usage = r.payload.info.total_token_usage;
             if (usage) {
+                // Codex token_count events are cumulative — take the last non-null value
                 inputTokens = usage.input_tokens ?? 0;
                 cachedInputTokens = usage.cached_input_tokens ?? 0;
                 outputTokens = usage.output_tokens ?? 0;
@@ -29,7 +97,9 @@ export function buildPayload(sessionId, cwd, records) {
         }
     }
     const sessionMeta = records.find((r) => r.type === "session_meta");
-    const startedAt = records.find((r) => r.timestamp)?.timestamp ?? sessionMeta?.payload?.timestamp ?? new Date().toISOString();
+    const startedAt = records.find((r) => r.timestamp)?.timestamp ??
+        sessionMeta?.payload?.timestamp ??
+        new Date().toISOString();
     return {
         tool: "codex",
         sessionId,
@@ -43,19 +113,7 @@ export function buildPayload(sessionId, cwd, records) {
         startedAt,
     };
 }
-function readJsonl(path) {
-    return readFileSync(path, "utf-8")
-        .split("\n")
-        .filter((l) => l.trim().length > 0)
-        .map((l) => {
-        try {
-            return JSON.parse(l);
-        }
-        catch {
-            return {};
-        }
-    });
-}
+// ─── Legacy file-scan helpers ─────────────────────────────────────────────────
 function findLatestSessionFile(root) {
     let latestPath;
     let latestMtime = -Infinity;
@@ -95,17 +153,51 @@ function parseArgs(argv) {
     }
     return {};
 }
+// ─── 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 Codex Stop hook payload
+        if (typeof parsed === "object" &&
+            parsed !== null &&
+            parsed["hook_event_name"] === "Stop" &&
+            typeof parsed["session_id"] === "string") {
+            return parsed;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// ─── Entry point ──────────────────────────────────────────────────────────────
 async function main() {
     try {
-        const { file } = parseArgs(process.argv.slice(2));
-        const filePath = file ?? findLatestSessionFile(join(homedir(), ".codex", "sessions"));
-        if (!filePath)
-            return;
-        const records = readJsonl(filePath);
-        const sessionMeta = records.find((r) => r.type === "session_meta");
-        const sessionId = sessionMeta?.payload?.id ?? filePath;
-        const cwd = sessionMeta?.payload?.cwd;
-        await reportSession(buildPayload(sessionId, cwd, records));
+        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);
+        }
+        if (stdin) {
+            // Real Codex hook mode — stdin has session_id, model, transcript_path
+            await reportSession(buildPayloadFromStdin(stdin));
+        }
+        else {
+            // Legacy shell-wrapper mode — scan ~/.codex/sessions/**/*.jsonl
+            const { file } = parseArgs(process.argv.slice(2));
+            const filePath = file ?? findLatestSessionFile(join(homedir(), ".codex", "sessions"));
+            if (!filePath)
+                return;
+            const records = readJsonl(filePath);
+            const sessionMeta = records.find((r) => r.type === "session_meta");
+            const sessionId = sessionMeta?.payload?.id ?? filePath;
+            const cwd = sessionMeta?.payload?.cwd;
+            await reportSession(buildPayload(sessionId, cwd, records));
+        }
     }
     catch (err) {
         console.error("[hook-codex]", err instanceof Error ? err.message : err);

package/package.json

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