@blastin-dev/clocktopus-cli 0.1.4 → 0.2.1

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

@@ -0,0 +1,368 @@
+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";
+import { AGENTS } from "../../lib/agents.js";
+/**
+ * SessionStart / SessionEnd hook → Clocktopus. Serves every agent.
+ *
+ * Claude Code and Codex both pipe their hook JSON to stdin, and — verified
+ * against 2.1.234 and 0.147.0 — they pipe the *same* JSON: `session_id`,
+ * `cwd`, `hook_event_name`, `source`, `reason`, same spellings. That is why
+ * one subcommand handles both, and also why `--provider` exists: nothing in
+ * the payload says which agent sent it, so the answer has to come from how
+ * the hook was installed.
+ *
+ * That JSON is the only place `cwd` appears anywhere in the telemetry
+ * pipeline — neither agent's telemetry export carries path, repository or
+ * branch data — 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.
+ *
+ * ## Getting off the session's critical path
+ *
+ * This hook does network I/O — its own POST, plus a sweep of abandoned
+ * sessions at SessionStart — and none of it may be charged to the developer
+ * waiting for their session to start.
+ *
+ * Claude Code solves this for us: `"async": true` in `settings.json` makes
+ * it background the hook. Codex does not, or not reliably — behaviour
+ * verified by running both binaries:
+ *
+ * | `async: true` on | Codex 0.147                    | Codex 0.148          |
+ * | ---------------- | ------------------------------ | -------------------- |
+ * | SessionStart     | **skips the hook**, with a warning | honoured, no warning |
+ * | SessionEnd       | runs it synchronously, with a warning | unchanged       |
+ *
+ * The 0.147 row is the dangerous one: a skipped SessionStart costs every
+ * Codex session its `cwd`, and with it the repository, the branch and the
+ * starting SHA — spend keeps arriving, attributed to nothing, with only a
+ * startup warning to say so.
+ *
+ * Rather than sniff the version, the Codex hooks carry no `async` key at
+ * all and this command backgrounds *itself*: it relays the payload to a
+ * detached copy and returns in a few milliseconds. One mechanism, correct
+ * on every version, and silent on all of them.
+ *
+ * SessionEnd needs it regardless of version. Codex still hard-clamps that
+ * hook to 3s — shorter than this file's own 4s request timeout — so a slow
+ * network would see the hook killed mid-POST and the session never closed.
+ * 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.
+ */
+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;
+function git(cwd, args) {
+    try {
+        return execFileSync("git", args, {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 2000,
+        }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+async function post(endpoint, token, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    try {
+        const response = await fetch(`${endpoint.replace(/\/$/, "")}/v1/agent-session`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${token}`,
+            },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        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.
+        return {
+            status: null,
+            error: error instanceof Error ? error.message : "request failed",
+        };
+    }
+    finally {
+        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, fallbackProvider) {
+    let swept = 0;
+    for (const { sessionId, ageMs, lastActivityAt } of listStartStates()) {
+        if (swept >= MAX_SWEEP_PER_RUN)
+            return;
+        if (sessionId === currentSessionId)
+            continue;
+        if (ageMs < ABANDONED_AFTER_MS)
+            continue;
+        swept++;
+        const state = readStartState(sessionId);
+        // 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. Just collect the file.
+        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.
+                ended_at: lastActivityAt.toISOString(),
+                repository_url: git(state.cwd, ["remote", "get-url", "origin"]),
+                git_branch: git(state.cwd, ["rev-parse", "--abbrev-ref", "HEAD"]),
+                git_head_before: state.sha,
+                git_head_after: head,
+            });
+        }
+        clearStartState(sessionId);
+    }
+}
+/**
+ * Reads a provider back off a state file written by an older CLI.
+ *
+ * Those files have no `provider` at all, and the only agent that could have
+ * written one was Claude Code — so `undefined` is not a missing value here,
+ * it is `claude_code`. That is the caller's fallback, applied by returning
+ * null 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` is what makes it survive: it puts the child in its own
+ * process group, so the host tearing down the session's group at exit —
+ * which is 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 anything.
+ *
+ * Returns false if the spawn could not be arranged at all, in which case
+ * the caller does the work inline — a slow session start is worth more than
+ * a lost one.
+ */
+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(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.
+        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 session.
+    }
+    let payload;
+    try {
+        payload = JSON.parse(raw);
+    }
+    catch {
+        return;
+    }
+    const sessionId = typeof payload.session_id === "string" ? payload.session_id : null;
+    const cwd = typeof payload.cwd === "string" ? payload.cwd : null;
+    if (!sessionId || !cwd)
+        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.
+    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,
+        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.
+    if (isSessionStart) {
+        if (head)
+            writeStartState(sessionId, { sha: head, cwd, provider: agent.provider });
+    }
+    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);
+        }
+        if (before)
+            body.git_head_before = before;
+        // 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, because the next idle would have no
+        // starting SHA to diff against. Rewriting the *original* SHA keeps the
+        // range anchored at the session's start, so each idle re-declares the
+        // whole range; re-declaring is free, since a link is unique per commit
+        // and `declared` already outranks everything else.
+        //
+        // Rewriting rather than leaving it also refreshes the file's mtime, which
+        // is what the sweep ages sessions by — so the 12h abandonment clock runs
+        // from the last turn rather than from session start, and a long
+        // conversation is not swept out from under itself.
+        if (agent.hostRepeatsSessionEnd && before) {
+            writeStartState(sessionId, {
+                sha: before,
+                cwd,
+                provider: agent.provider,
+                // Already closed in the database. The sweep needs to know that, or
+                // it would "close" the session a second time 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.
+    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,
+    });
+    // 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.
+    if (isSessionStart) {
+        await sweepAbandonedSessions(endpoint, token, sessionId, agent.provider);
+    }
+}
+export async function hookCommand(options) {
+    try {
+        // 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

@@ -0,0 +1,28 @@
+/**
+ * Configures this machine's coding agents to report spend to Clocktopus.
+ *
+ * One command, however many agents are installed. It looks for each
+ * supported CLI on PATH and configures what it finds — silently when
+ * there is only one, after a prompt when there are several, and from
+ * `--agent` when there is neither a person nor a terminal to ask.
+ *
+ * Everything for a given agent lands in that agent's own config, and
+ * nowhere else. A single source of truth per agent 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, and adding a newly-installed agent later
+ * reuses the token the first one already has. `--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

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../../src/commands/agent/setup.ts"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,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,CA8LhB"}