@blastin-dev/clocktopus-cli 0.2.0 → 0.3.0

package/dist/src/commands/agent/hook.js

@@ -1,35 +1,87 @@
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
+import { resolve as resolvePath } from "node:path";
 import { maskToken, resolveAgentCredentials } from "../../lib/agent-config.js";
 import { clearStartState, listStartStates, readStartState, recordLastRun, writeStartState, } from "../../lib/agent-hook-state.js";
-/**
- * Claude Code SessionStart / SessionEnd hook → Clocktopus.
- *
- * Claude Code pipes its hook JSON to stdin. That JSON is the only place
- * `cwd` appears anywhere in the telemetry pipeline — the OTLP metric export
- * carries no path, repository or branch data at all — so without this hook
- * every agent session is unattributable and the ledger can only show
- * totals.
- *
- * Previously a standalone script under `scripts/agent-telemetry/`, which
- * meant `settings.json` had to reference an absolute path inside a checkout
- * of this repository. Shipping it as a subcommand is what makes the feature
- * installable by anyone: the hook is wherever the CLI is.
- *
- * Contract with the host process, all three parts load-bearing: never write
- * to stdout (Claude Code parses it), never throw, always exit 0. Telemetry
- * must not be able to break the session it measures.
- */
+import { AGENTS } from "../../lib/agents.js";
+import { buildReflogArgs, parseReflogCommits, } from "../../lib/declared-commits.js";
+import { parseGitRemotes } from "../../lib/git-remotes.js";
+// SessionStart / SessionEnd hook → Clocktopus. Serves every agent.
+//
+// Claude Code and Codex both pipe the *same* hook JSON to stdin — `session_id`,
+// `cwd`, `hook_event_name`, `source`, `reason`, same spellings (verified against
+// 2.1.234 and 0.147.0). That is why one subcommand handles both, and why
+// `--provider` exists: nothing in the payload says which agent sent it.
+//
+// That JSON is the only place `cwd` appears anywhere in the pipeline, so without
+// this hook every agent session is unattributable and the ledger can only show
+// totals. Shipping it as a subcommand rather than a script under `scripts/` is what
+// makes the feature installable by anyone: the hook is wherever the CLI is.
+//
+// Contract with the host process, all three parts load-bearing: never write to
+// stdout (Claude Code parses it), never throw, always exit 0.
+//
+// Getting off the session's critical path: this hook does network I/O, and none of
+// it may be charged to the developer waiting for their session. Claude Code's
+// `"async": true` backgrounds it; Codex does not, or not reliably —
+//
+//   `async: true` on | Codex 0.147                | Codex 0.148
+//   SessionStart     | SKIPS the hook, with warning | honoured, no warning
+//   SessionEnd       | runs it synchronously        | unchanged
+//
+// The 0.147 row is the dangerous one: a skipped SessionStart costs every Codex
+// session its `cwd`, and with it the repository, branch and starting SHA. So rather
+// than sniff the version, the Codex hooks carry no `async` key and this command
+// backgrounds *itself*, relaying the payload to a detached copy. SessionEnd needs
+// that regardless: Codex hard-clamps it to 3s, shorter than this file's own 4s
+// request timeout, and the clamp only has to cover a spawn.
 const TIMEOUT_MS = 4000;
-/**
- * How long a state file must sit untouched before its session is presumed
- * dead. A file only survives SessionEnd if the session never got one —
- * SIGKILL, a crash, or the machine going down — but a long-running session
- * is perfectly normal, so this sits well past a working day rather than at
- * the point a session merely looks idle.
- */
+// How long a state file must sit untouched before its session is presumed dead. A
+// file survives SessionEnd only if the session never got one — SIGKILL, a crash, the
+// machine going down — but a long-running session is normal, so this sits well past
+// a working day rather than at the point one merely looks idle.
 const ABANDONED_AFTER_MS = 12 * 60 * 60 * 1000;
 /** Bound on one sweep, so a directory left full of state cannot stall a start. */
 const MAX_SWEEP_PER_RUN = 10;
+// The commits this checkout authored inside the session's window. Empty when the
+// session's start was never recorded, which is the deliberate answer — see
+// `buildReflogArgs`.
+function declaredCommits(cwd, startedAt, until) {
+    const args = buildReflogArgs({ startedAt, until });
+    if (!args)
+        return [];
+    return parseReflogCommits(git(cwd, args));
+}
+// What the *sweep* may declare, which is nothing at all for most hosts.
+//
+// The upper bound has to be the last moment this machine has evidence the session was
+// alive, and the only such record is the state file's mtime. That is real evidence
+// only where the host re-writes the file as the session goes — OpenCode, whose
+// SessionEnd repeats. Everywhere else the file is written once at SessionStart, so the
+// mtime *is* the start: the window collapses to `[startedAt, startedAt]` and can match
+// nothing the session wrote, only a commit made just before it began. Those would be
+// recorded as `declared`, which outranks the time window and is permanent.
+//
+// Dropping the bound instead is worse. The sweep runs up to twelve hours late, so an
+// unbounded read declares everything the developer committed in between.
+//
+// So: declare nothing, and leave these sessions to `linkCommitsByTimeWindow`, which
+// bounds itself with the server's telemetry-stamped end rather than a file's mtime.
+function sweptCommits(state, lastActivityAt) {
+    const host = AGENTS.find((agent) => agent.provider === state.provider);
+    if (!host?.hostRepeatsSessionEnd)
+        return [];
+    return declaredCommits(state.cwd, state.startedAt, lastActivityAt.toISOString());
+}
+/** Omits the field entirely when there is nothing to declare, rather than sending `[]`. */
+function declaredShasFor(shas) {
+    return shas.length > 0 ? { commit_shas: shas } : {};
+}
+// Shared by the live hook and the sweep so an abandoned session resolves its
+// repository the same way a live one does.
+function remotesFor(cwd) {
+    const remotes = parseGitRemotes(git(cwd, ["remote", "-v"]));
+    return { repository_url: remotes[0], repository_urls: remotes };
+}
 function git(cwd, args) {
     try {
         return execFileSync("git", args, {
@@ -59,8 +111,8 @@ async function post(endpoint, token, body) {
         return { status: response.status, error: null };
     }
     catch (error) {
-        // Telemetry must never break the session it measures. The failure is
-        // recorded for `agent doctor` instead of surfaced here.
+        // Telemetry must never break the session it measures. The failure is recorded for
+        // `agent doctor` instead of surfaced here.
         return {
             status: null,
             error: error instanceof Error ? error.message : "request failed",
@@ -70,27 +122,20 @@ async function post(endpoint, token, body) {
         clearTimeout(timer);
     }
 }
-/**
- * Closes sessions that were never given a SessionEnd.
- *
- * A state file outlives its session only when the process died without
- * running the hook, and until something closes it the session keeps a null
- * `ended_at` and a null `git_head_after` forever.
- *
- * It deliberately does **not** send `commit_shas`. The honest range for a
- * dead session is unknowable after the fact: `before..HEAD` also contains
- * everything committed in the hours since it died, and the receiver records
- * hook-supplied commits as `declared`, which outranks a `time_window` link
- * and would make a bad guess permanent. Closing the session is enough —
- * with a real `ended_at` the webhook's time-window pass can then link its
- * commits from the commit timestamps, which are bounded by data rather than
- * by assumption.
- *
- * For the same reason it sends its own `ended_at` rather than letting the
- * receiver stamp one: this runs when the *next* session starts, potentially
- * a day later.
- */
-async function sweepAbandonedSessions(endpoint, token, currentSessionId) {
+// Closes sessions that were never given a SessionEnd, which otherwise keep a null
+// `ended_at` and `git_head_after` forever.
+//
+// It now declares commits too, which a range could never let it do. `before..HEAD`
+// resolved after the fact also contains everything committed in the hours since, and
+// a hook-supplied commit is recorded as `declared`, which outranks a `time_window`
+// link — a bad guess would be permanent. The reflog is bounded by data instead: it is
+// on disk, it is stamped, and the session's own window brackets it. That closes the
+// case this whole area exists for, an agent left running unattended and killed before
+// it could report anything.
+//
+// It sends its own `ended_at` for a related reason: this runs when the *next* session
+// starts, potentially a day later.
+async function sweepAbandonedSessions(endpoint, token, currentSessionId, fallbackProvider) {
     let swept = 0;
     for (const { sessionId, ageMs, lastActivityAt } of listStartStates()) {
         if (swept >= MAX_SWEEP_PER_RUN)
@@ -101,49 +146,116 @@ async function sweepAbandonedSessions(endpoint, token, currentSessionId) {
             continue;
         swept++;
         const state = readStartState(sessionId);
-        // Nothing recoverable without the originating checkout — drop the file
-        // rather than resolve its SHA against an unrelated repository.
+        // Nothing recoverable without the originating checkout — drop the file rather than
+        // resolve its SHA against an unrelated repository.
         if (!state?.cwd) {
             clearStartState(sessionId);
             continue;
         }
+        // Kept alive only so a repeating SessionEnd could still diff against it. The session
+        // already ended properly; sweeping it would replace a real end with this moment's
+        // HEAD.
+        if (state.closed) {
+            clearStartState(sessionId);
+            continue;
+        }
         const head = git(state.cwd, ["rev-parse", "HEAD"]);
         if (head) {
             await post(endpoint, token, {
+                // The agent that *opened* the session, not the one sweeping it. Closing a Codex
+                // session as `claude_code` would leave the real row hanging and create an empty
+                // duplicate under the wrong provider.
+                provider: readProvider(state.provider) ?? fallbackProvider,
                 session_id: sessionId,
                 hook_event_name: "SessionEnd",
                 cwd: state.cwd,
                 reason: "abandoned",
-                // Never "now": this session died hours ago, and the receiver would
-                // otherwise record a window spanning everything since. The receiver
-                // treats this as a fallback and keeps a telemetry-stamped end if it
-                // has one; this value only fills the gap when it has none.
+                // Never "now": this session died hours ago. The receiver treats this as a fallback
+                // and keeps a telemetry-stamped end if it has one.
                 ended_at: lastActivityAt.toISOString(),
-                repository_url: git(state.cwd, ["remote", "get-url", "origin"]),
-                git_branch: git(state.cwd, ["rev-parse", "--abbrev-ref", "HEAD"]),
+                // A remote is a property of the checkout and does not drift; the branch is a
+                // property of the moment, and this moment is hours after the session died.
+                // Sending one would overwrite the branch SessionStart recorded — `COALESCE` lets
+                // any non-null value win — replacing real evidence with wherever the developer
+                // happens to be now. Omitted so the recorded branch survives.
+                ...remotesFor(state.cwd),
+                ...declaredShasFor(
+                // Spread rather than passed whole so the `state.cwd` guard above narrows.
+                sweptCommits({
+                    cwd: state.cwd,
+                    provider: state.provider,
+                    startedAt: state.startedAt,
+                }, lastActivityAt)),
                 git_head_before: state.sha,
+                // Same objection as the branch, kept only because nothing reads it: it is
+                // diagnostic, and removing it would change what `agent doctor` shows for no gain.
                 git_head_after: head,
             });
         }
         clearStartState(sessionId);
     }
 }
+// Reads a provider back off a state file written by an older CLI. Those files have
+// no `provider`, and the only agent that could have written one was Claude Code — so
+// `undefined` is not a missing value, it is `claude_code`. Returning null lets the
+// caller apply that fallback rather than guessing here.
+function readProvider(value) {
+    const match = AGENTS.find((agent) => agent.provider === value);
+    return match?.provider ?? null;
+}
+// Re-runs this command in a detached copy and hands it the payload.
+//
+// `detached: true` puts the child in its own process group, so the host tearing down
+// the session's group at exit — exactly when SessionEnd fires — cannot take the POST
+// with it.
+//
+// Waiting for `stdin.end` to flush is not optional: the parent returns immediately
+// afterwards and an unflushed write would die with it. A hook payload is well under
+// the pipe buffer, so this resolves without waiting for the child to read.
+//
+// False if the spawn could not be arranged, in which case the caller works inline.
+function detachSelf(provider, payload) {
+    const script = process.argv[1] ? resolvePath(process.argv[1]) : null;
+    if (!script)
+        return Promise.resolve(false);
+    try {
+        const child = spawn(process.execPath, [script, "agent", "hook", "--provider", provider, "--detached"], { detached: true, stdio: ["pipe", "ignore", "ignore"] });
+        child.unref();
+        return new Promise((settle) => {
+            child.once("error", () => settle(false));
+            child.stdin.once("error", () => settle(false));
+            child.stdin.end(payload, () => settle(true));
+        });
+    }
+    catch {
+        return Promise.resolve(false);
+    }
+}
 async function readStdin() {
     const chunks = [];
     for await (const chunk of process.stdin)
         chunks.push(chunk);
     return Buffer.concat(chunks).toString("utf8");
 }
-async function run() {
-    const { token, endpoint } = resolveAgentCredentials();
+async function run(agent, detached) {
+    const { token, endpoint } = resolveAgentCredentials(agent.id);
     if (!token || !endpoint) {
-        // Not configured. Silence is correct: agent telemetry is opt-in, and a
-        // machine that never ran `clocktopus agent setup` should notice nothing.
+        // Not configured. Silence is correct: agent telemetry is opt-in, and a machine that
+        // never ran `clocktopus agent setup` should notice nothing.
         return;
     }
     const raw = await readStdin();
     if (!raw)
         return;
+    // After the empty-stdin check on purpose: `agent doctor` proves the hook command
+    // resolves by running it with no payload, and that probe must not leave a stray
+    // process behind.
+    if (!agent.hostRunsHooksAsync && !detached) {
+        if (await detachSelf(agent.provider, raw))
+            return;
+        // Could not spawn — fall through and do it inline. A slow session start is worth
+        // more than a lost one.
+    }
     let payload;
     try {
         payload = JSON.parse(raw);
@@ -157,73 +269,102 @@ async function run() {
         return;
     const eventName = typeof payload.hook_event_name === "string" ? payload.hook_event_name : "";
     const isSessionStart = eventName === "SessionStart";
-    // HEAD at SessionStart is the *before* SHA; HEAD at SessionEnd is the
-    // *after*. Sending both under one field would let SessionEnd overwrite the
-    // start SHA, collapsing the range to a single point and making
-    // `git rev-list before..after` — the authoritative commit↔session link —
-    // impossible to compute.
+    // HEAD at SessionStart is the *before* SHA, at SessionEnd the *after*. Kept as two
+    // fields so SessionEnd cannot overwrite the start SHA; the commits themselves now
+    // come from the reflog, but the range is still what `repo-readiness` reports on.
     const head = git(cwd, ["rev-parse", "HEAD"]);
-    const repositoryUrl = git(cwd, ["remote", "get-url", "origin"]);
     const body = {
+        provider: agent.provider,
         session_id: sessionId,
         hook_event_name: eventName,
         cwd,
         source: typeof payload.source === "string" ? payload.source : undefined,
         reason: typeof payload.reason === "string" ? payload.reason : undefined,
-        repository_url: repositoryUrl,
+        ...remotesFor(cwd),
         git_branch: git(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]),
         ...(isSessionStart ? { git_head_before: head } : { git_head_after: head }),
     };
-    // Resolve the SHA range into an actual commit list, here on the machine
-    // that has the git object graph. The receiver cannot do this — it has no
-    // checkout — so a range alone would be unusable.
-    //
-    // SessionStart and SessionEnd are separate processes, so the starting SHA
-    // is stashed on disk under the session id rather than passed in the
-    // environment.
+    // Resolve the session's commits here, on the machine that has the git object graph
+    // and the reflog — the receiver has neither. SessionStart and SessionEnd are separate
+    // processes, so the session's start is stashed on disk under the session id rather
+    // than passed in the environment.
     if (isSessionStart) {
-        if (head)
-            writeStartState(sessionId, head, cwd);
+        // SessionStart fires again mid-session on `compact` and `resume`, and our hook is
+        // installed with no matcher, so it sees those too. Writing again would move
+        // `startedAt` forward and drop everything committed before the compaction out of
+        // the declared window — and move the server's `started_at` with it. The first
+        // stamp is the session's real start; keep it.
+        if (head && !readStartState(sessionId))
+            writeStartState(sessionId, {
+                sha: head,
+                cwd,
+                provider: agent.provider,
+                startedAt: new Date().toISOString(),
+            });
     }
     else {
-        const before = readStartState(sessionId)?.sha;
-        if (before && head && before !== head) {
-            const shas = git(cwd, [
-                "rev-list",
-                "--max-count=200",
-                `${before}..${head}`,
-            ]);
-            if (shas)
-                body.commit_shas = shas.split("\n").filter(Boolean);
-        }
+        const start = readStartState(sessionId);
+        const before = start?.sha;
+        const commitShas = declaredCommits(cwd, start?.startedAt);
+        if (commitShas.length > 0)
+            body.commit_shas = commitShas;
         if (before)
             body.git_head_before = before;
-        clearStartState(sessionId);
+        // A host that ends a session once is done with this file. One that can end it
+        // repeatedly — OpenCode, whose SessionEnd is `session.idle` after every turn — is
+        // not: deleting it here would cost the session every commit made after its first
+        // pause. Rewriting the *original* SHA keeps the range anchored at the session's
+        // start, and re-declaring is free since a link is unique per commit.
+        //
+        // Rewriting also refreshes the file's mtime, which the sweep ages sessions by, so
+        // the 12h clock runs from the last turn and a long conversation is not swept out
+        // from under itself.
+        if (agent.hostRepeatsSessionEnd && before) {
+            writeStartState(sessionId, {
+                sha: before,
+                cwd,
+                provider: agent.provider,
+                // Carried over with the SHA: the range stays anchored at the session's start, so
+                // the bound on it has to as well, or every turn after the first would declare
+                // against an unbounded range again.
+                startedAt: start?.startedAt,
+                // Already closed in the database. The sweep needs to know, or it would "close" the
+                // session again 12h later and stamp it with whatever HEAD had become by then.
+                closed: true,
+            });
+        }
+        else {
+            clearStartState(sessionId);
+        }
     }
-    // transcript_path is intentionally NOT forwarded. Claude Code provides it,
-    // and it points at the full conversation on disk — exactly the content
-    // BLA-421 says we must never collect.
+    // transcript_path is intentionally NOT forwarded: it points at the full conversation
+    // on disk, exactly the content BLA-421 says we must never collect.
     const result = await post(endpoint, token, body);
     recordLastRun({
         at: new Date().toISOString(),
         event: eventName,
+        provider: agent.provider,
         sessionId,
         endpoint,
         tokenPrefix: maskToken(token),
         status: result.status,
         error: result.error,
-        repository: repositoryUrl ?? null,
+        repository: body.repository_url ?? null,
     });
-    // After this session's own event, never before it: the sweep talks to the
-    // network once per abandoned session and must not delay the event it is
-    // piggybacking on.
+    // After this session's own event, never before it: the sweep talks to the network
+    // once per abandoned session and must not delay the event it piggybacks on.
     if (isSessionStart) {
-        await sweepAbandonedSessions(endpoint, token, sessionId);
+        await sweepAbandonedSessions(endpoint, token, sessionId, agent.provider);
     }
 }
-export async function hookCommand() {
+export async function hookCommand(options) {
     try {
-        await run();
+        // An unrecognised provider falls back to Claude Code rather than aborting: a hook
+        // installed by an older CLI has no flag at all, and dropping its sessions would be a
+        // worse failure than mislabelling a provider we do not know.
+        const agent = AGENTS.find((candidate) => candidate.provider === options.provider) ??
+            AGENTS[0];
+        await run(agent, options.detached === true);
     }
     catch {
         // Every failure path is silent by design.

package/dist/src/commands/agent/setup.d.ts

@@ -1,21 +1,6 @@
-/**
- * Configures this machine to report agent spend to Clocktopus.
- *
- * Everything lands in one file — `~/.claude/settings.json` — holding both
- * the exporter's environment and the session hooks. A single source of
- * truth is not a tidiness preference: it is what makes `agent doctor` able
- * to say which value is in force. Configuration spread over `.envrc`, a
- * shell profile and a CLI config file can be reported on but never
- * resolved, and this project already lost real spend to exactly that (one
- * session split across two accounts, silently, because two files disagreed
- * about the token).
- *
- * Idempotent by default. Re-running repairs the hooks and refreshes the
- * endpoint while keeping the existing token, so the common case — "did my
- * setup drift?" — costs nothing. `--force` mints a replacement instead.
- */
 export declare function setupCommand(options: {
     name?: string;
     force?: boolean;
+    agent?: string[];
 }): Promise<void>;
 //# sourceMappingURL=setup.d.ts.map

package/dist/src/commands/agent/setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../../src/commands/agent/setup.ts"],"names":[],"mappings":"AA4BA;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+IhB"}
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../../src/commands/agent/setup.ts"],"names":[],"mappings":"AAsCA,wBAAsB,YAAY,CAAC,OAAO,EAAE;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CA0LhB"}