@blastin-dev/clocktopus-cli 0.2.0 → 0.2.1

package/dist/src/lib/opencode-config.js

@@ -0,0 +1,330 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+/**
+ * Installs and reads back the OpenCode plugin that reports to Clocktopus.
+ *
+ * OpenCode is the odd one out. Claude Code and Codex both expose a *hook*
+ * — a command they run with JSON on stdin — so wiring them up is a matter
+ * of editing config. OpenCode instead exposes a plugin API: JavaScript
+ * loaded into its own process, handed a stream of typed events. So the
+ * integration is a file of ours rather than a config entry pointing at the
+ * CLI.
+ *
+ * The install is a single file. OpenCode auto-loads everything in
+ * `<config dir>/plugin/`, verified against 1.18.18, so nothing has to be
+ * added to `opencode.json` — which is worth having: that file is the
+ * user's model, provider and permission configuration, and not touching it
+ * removes a whole class of ways to break their setup. Uninstalling is
+ * deleting the file.
+ *
+ * ## Why a plugin and not OpenCode's own OpenTelemetry
+ *
+ * OpenCode has `experimental.openTelemetry`, which exports OTLP/JSON traces
+ * to `OTEL_EXPORTER_OTLP_ENDPOINT` — on the face of it exactly what we
+ * want, and a one-line install. It was measured and rejected:
+ *
+ * - **It ships the conversation.** The AI SDK spans carry `ai.prompt`,
+ *   `ai.prompt.messages` and `ai.response.text` — the system prompt, every
+ *   user message and the model's replies, verbatim, with no switch to turn
+ *   them off. Codex's log stream leaks tool output; this leaks everything.
+ * - **It is enormous.** One prompt produced 230KB, almost all of it
+ *   OpenCode's internal spans — SQLite queries, file reads, lock
+ *   acquisitions — with the AI spans a rounding error inside it.
+ * - **It carries no cost and no repository**, so it could not do the one
+ *   job the feature exists for.
+ *
+ * The plugin sees a better source than the traces do: `AssistantMessage`
+ * carries `cost`, a full token breakdown, the model, and `path.cwd`. It
+ * sends numbers and identifiers, and nothing a person wrote.
+ */
+export const OPENCODE_PLUGIN_FILENAME = "clocktopus.js";
+/** The line `readOpencodeTelemetry` parses back out of the plugin. */
+const CONFIG_MARKER = "const CLOCKTOPUS = ";
+/** Prefix of the line carrying the generation stamp. */
+const VERSION_MARKER = "// clocktopus-plugin-version: ";
+/**
+ * Bumped whenever `buildOpencodePlugin` changes what it emits.
+ *
+ * OpenCode is the only agent whose integration is *generated source* rather
+ * than a command string in a config file. Claude Code and Codex hold
+ * `clocktopus agent hook …`, which means whatever the installed CLI means,
+ * so upgrading the CLI upgrades them. This plugin does not: the file on
+ * disk stays exactly as the CLI that wrote it left it, and a fix shipped to
+ * the plugin body reaches nobody until they re-run `agent setup`.
+ *
+ * Stamping the generation is what makes that visible — `agent doctor`
+ * compares this number against the file and says so when they differ.
+ * Nothing auto-rewrites the file: it holds a token, and a command that
+ * quietly rewrites credentials is worse than one that tells you to.
+ *
+ * A plugin written before the stamp existed parses as `null`, which reads
+ * as stale — correct, since it predates every version that has one.
+ */
+export const OPENCODE_PLUGIN_VERSION = 1;
+export function opencodeConfigDir() {
+    if (process.env.OPENCODE_CONFIG_DIR)
+        return process.env.OPENCODE_CONFIG_DIR;
+    if (process.env.XDG_CONFIG_HOME)
+        return join(process.env.XDG_CONFIG_HOME, "opencode");
+    return join(homedir(), ".config", "opencode");
+}
+export function opencodePluginPath() {
+    return join(opencodeConfigDir(), "plugin", OPENCODE_PLUGIN_FILENAME);
+}
+/**
+ * Splits a shell-quoted command line into argv.
+ *
+ * Only as clever as `resolveHookCommand` is: double quotes around
+ * whitespace, nothing else. It is fed that function's output, never a
+ * user's shell.
+ */
+export function splitCommandLine(command) {
+    return (command.match(/"[^"]*"|\S+/g) ?? []).map((part) => part.startsWith('"') && part.endsWith('"') ? part.slice(1, -1) : part);
+}
+/**
+ * The plugin source, with this machine's configuration baked into one line.
+ *
+ * Generated rather than shipped as a file because the token has to be in
+ * it: OpenCode gives a plugin no way to read our environment, so the
+ * credentials live where every other agent's do — in that agent's config,
+ * written 0600.
+ */
+export function buildOpencodePlugin(config) {
+    return `// Generated by 'clocktopus agent setup'. Edits will be overwritten.
+${VERSION_MARKER}${OPENCODE_PLUGIN_VERSION}
+//
+// Reports what OpenCode sessions cost to Clocktopus. Two channels, for the
+// same reason every other agent has two: spend and repository context come
+// from different places and neither is much use alone.
+//
+//   spend    POSTed straight to the receiver as OTel GenAI spans, because
+//            it happens per assistant message and spawning a process each
+//            time would be absurd.
+//   context  handed to 'clocktopus agent hook', which already knows how to
+//            resolve a git remote, diff a session's commit range and sweep
+//            sessions that died — none of which is worth reimplementing in
+//            here.
+//
+// Nothing a person wrote is read: not the prompt, not the model's reply,
+// not tool output. Only counts, identifiers and timings.
+import { spawn } from "node:child_process";
+
+${CONFIG_MARKER}${JSON.stringify(config)};
+
+const REQUEST_TIMEOUT_MS = 4000;
+
+/** ms since epoch -> the nanosecond string OTLP expects. */
+const nano = (ms) => \`\${Math.round(ms)}000000\`;
+
+const attr = (key, value) =>
+  typeof value === "number"
+    ? { key, value: { doubleValue: value } }
+    : { key, value: { stringValue: String(value) } };
+
+function spans(message, version) {
+  const started = message.time.created;
+  const ended = message.time.completed ?? started;
+  const shared = [
+    attr("gen_ai.client.session_id", message.sessionID),
+    attr("gen_ai.client.name", "opencode"),
+  ];
+
+  return [
+    {
+      // Carries the turn's duration and nothing else. Clocktopus takes
+      // active time from this span alone, so emitting one per assistant
+      // message is what makes the total "time the agent was working"
+      // rather than "time the window was open".
+      name: "gen_ai.client.session",
+      startTimeUnixNano: nano(started),
+      endTimeUnixNano: nano(ended),
+      attributes: shared,
+    },
+    {
+      name: "gen_ai.client.generation",
+      startTimeUnixNano: nano(started),
+      endTimeUnixNano: nano(ended),
+      attributes: [
+        ...shared,
+        attr("gen_ai.request.model", message.modelID),
+        attr("gen_ai.provider.name", message.providerID),
+        // OpenCode reports input already net of the cached prefix, so these
+        // buckets add up rather than overlap — the opposite of Codex, which
+        // reports input inclusive and has to be subtracted.
+        attr("gen_ai.usage.input_tokens", message.tokens.input),
+        // Reasoning tokens are output tokens that were not shown. OpenCode
+        // reports them separately and Clocktopus has no bucket for them, so
+        // they are folded in here rather than dropped: its own totals treat
+        // them this way (input + cache.read + output + reasoning == total)
+        // and it prices them at the output rate, so leaving them out would
+        // under-report tokens against a cost that already includes them.
+        attr(
+          "gen_ai.usage.output_tokens",
+          message.tokens.output + (message.tokens.reasoning ?? 0),
+        ),
+        attr("gen_ai.usage.cache_read_input_tokens", message.tokens.cache.read),
+        attr(
+          "gen_ai.usage.cache_creation_input_tokens",
+          message.tokens.cache.write,
+        ),
+        // Priced by OpenCode from the models.dev rate card, so Clocktopus
+        // records it as an estimate, never as a settled bill.
+        attr("gen_ai.usage.cost", message.cost),
+      ],
+    },
+  ];
+}
+
+async function report(message, version) {
+  const body = {
+    resourceSpans: [
+      {
+        resource: {
+          attributes: [
+            attr("service.name", "opencode"),
+            ...(version ? [attr("service.version", version)] : []),
+          ],
+        },
+        scopeSpans: [
+          {
+            scope: { name: "clocktopus.opencode", version: "1" },
+            spans: spans(message, version),
+          },
+        ],
+      },
+    ],
+  };
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    await fetch(\`\${CLOCKTOPUS.endpoint.replace(/\\/$/, "")}/v1/traces\`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: \`Bearer \${CLOCKTOPUS.token}\`,
+      },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+  } catch {
+    // Telemetry must never break the session it measures.
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Hands a session event to the CLI, which owns all the git logic. */
+function notify(event, sessionID, cwd) {
+  try {
+    const [command, ...args] = CLOCKTOPUS.hookArgv;
+    const child = spawn(command, args, {
+      detached: true,
+      stdio: ["pipe", "ignore", "ignore"],
+    });
+    child.unref();
+    child.stdin.on("error", () => {});
+    child.stdin.end(
+      JSON.stringify({
+        session_id: sessionID,
+        hook_event_name: event,
+        cwd,
+      }),
+    );
+  } catch {
+    // Same contract as everything else here: fail silently.
+  }
+}
+
+export const ClocktopusPlugin = async ({ directory, worktree }) => {
+  const root = worktree || directory;
+  let version = null;
+
+  return {
+    event: async ({ event }) => {
+      if (event.type === "session.created") {
+        version = event.properties.info?.version ?? version;
+        notify("SessionStart", event.properties.sessionID, root);
+        return;
+      }
+
+      // OpenCode has no "session ended" event — 'idle' is what it emits
+      // when the agent stops working and waits for a human. Treating that
+      // as the end keeps the session's end time tracking the last moment it
+      // was actually busy, which is the bound commit attribution needs, and
+      // re-sending it on a later turn is harmless: the receiver merges.
+      if (event.type === "session.idle") {
+        notify("SessionEnd", event.properties.sessionID, root);
+        return;
+      }
+
+      if (event.type === "message.updated") {
+        const message = event.properties.info;
+        // Assistant messages only, and only once finished — an in-flight
+        // message is republished on every token, with counts that are not
+        // final.
+        if (message?.role !== "assistant" || !message.time?.completed) return;
+        await report(message, version);
+      }
+    },
+  };
+};
+`;
+}
+export function readOpencodePlugin(path = opencodePluginPath()) {
+    if (!existsSync(path)) {
+        return { path, exists: false, modifiedAt: null, config: null, version: null };
+    }
+    const modifiedAt = statSync(path).mtime;
+    let config = null;
+    let version = null;
+    try {
+        const lines = readFileSync(path, "utf8").split("\n");
+        const stamp = lines.find((candidate) => candidate.startsWith(VERSION_MARKER));
+        if (stamp) {
+            const parsedVersion = Number.parseInt(stamp.slice(VERSION_MARKER.length).trim(), 10);
+            if (Number.isFinite(parsedVersion))
+                version = parsedVersion;
+        }
+        const line = lines.find((candidate) => candidate.startsWith(CONFIG_MARKER));
+        if (line) {
+            const parsed = JSON.parse(line.slice(CONFIG_MARKER.length).replace(/;\s*$/, ""));
+            if (parsed &&
+                typeof parsed === "object" &&
+                typeof parsed.token === "string" &&
+                typeof parsed.endpoint === "string" &&
+                Array.isArray(parsed.hookArgv)) {
+                config = parsed;
+            }
+        }
+    }
+    catch {
+        // A plugin we cannot read the configuration out of is reported as
+        // unconfigured, which sends the user to `setup` — the right answer
+        // whether it was hand-edited or written by a version that has since
+        // changed shape.
+    }
+    return { path, exists: true, modifiedAt, config, version };
+}
+export function writeOpencodePlugin(source, path = opencodePluginPath()) {
+    mkdirSync(dirname(path), { recursive: true });
+    let backupPath = null;
+    if (existsSync(path)) {
+        backupPath = `${path}.clocktopus-backup`;
+        copyFileSync(path, backupPath);
+    }
+    // Rename rather than write in place: OpenCode loads every file in this
+    // directory at startup, and a half-written one would be a syntax error
+    // that takes the whole plugin system down with it.
+    const temporaryPath = `${path}.clocktopus-tmp`;
+    writeFileSync(temporaryPath, source, { encoding: "utf8", mode: 0o600 });
+    renameSync(temporaryPath, path);
+    return { backupPath };
+}
+export function removeOpencodePlugin(path = opencodePluginPath()) {
+    if (!existsSync(path))
+        return false;
+    rmSync(path, { force: true });
+    return true;
+}

package/dist/src/lib/opencode-config.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=opencode-config.test.d.ts.map

package/dist/src/lib/opencode-config.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"opencode-config.test.d.ts","sourceRoot":"","sources":["../../../src/lib/opencode-config.test.ts"],"names":[],"mappings":""}

package/dist/src/lib/opencode-config.test.js

@@ -0,0 +1,140 @@
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { buildOpencodePlugin, OPENCODE_PLUGIN_VERSION, readOpencodePlugin, removeOpencodePlugin, splitCommandLine, writeOpencodePlugin, } from "./opencode-config";
+/**
+ * OpenCode's integration is a JavaScript file we generate and drop into the
+ * user's config directory, which makes two things worth testing that the
+ * other agents do not need: that the file we write is syntactically valid —
+ * OpenCode loads every plugin at startup, so a broken one takes its whole
+ * plugin system down — and that the configuration baked into it survives a
+ * round trip, since that file is also where the ingest token lives.
+ */
+const INSTALL = {
+    endpoint: "https://otel.example.com",
+    token: "ctop_agt_testtoken",
+    hookArgv: ["/usr/bin/node", "/opt/clocktopus/cli.js", "agent", "hook"],
+};
+let dir;
+let pluginPath;
+beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "clocktopus-opencode-"));
+    pluginPath = join(dir, "plugin", "clocktopus.js");
+});
+afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+});
+describe("splitCommandLine", () => {
+    it("keeps a quoted path with spaces in one piece", () => {
+        // The failure this prevents is silent: the plugin spawns argv directly,
+        // so a path torn in two at a space produces a command that does not
+        // exist, and the hook simply never runs.
+        expect(splitCommandLine('"/opt/my node/bin/node" /opt/cli.js agent hook')).toEqual(["/opt/my node/bin/node", "/opt/cli.js", "agent", "hook"]);
+    });
+    it("handles the ordinary unquoted case", () => {
+        expect(splitCommandLine("clocktopus agent hook --provider opencode")).toEqual(["clocktopus", "agent", "hook", "--provider", "opencode"]);
+    });
+});
+describe("the generated plugin", () => {
+    it("is valid JavaScript", async () => {
+        const source = buildOpencodePlugin(INSTALL);
+        const encoded = `data:text/javascript;base64,${Buffer.from(source).toString("base64")}`;
+        // Imported rather than merely parsed: OpenCode loads this file into its
+        // own process, so a syntax error here is not our bug alone — it breaks
+        // every other plugin the user has.
+        const module = await import(encoded);
+        expect(typeof module.ClocktopusPlugin).toBe("function");
+    });
+    it("exports a plugin that registers an event handler", async () => {
+        const source = buildOpencodePlugin(INSTALL);
+        const encoded = `data:text/javascript;base64,${Buffer.from(source).toString("base64")}`;
+        const { ClocktopusPlugin } = (await import(encoded));
+        const hooks = await ClocktopusPlugin({
+            directory: "/repo",
+            worktree: "/repo",
+        });
+        expect(typeof hooks.event).toBe("function");
+    });
+    it("sends counts and identifiers, and nothing a person wrote", () => {
+        const source = buildOpencodePlugin(INSTALL);
+        // OpenCode hands the plugin whole messages, so what it chooses *not* to
+        // read is the entire privacy story. These are the fields on
+        // `AssistantMessage` and its parts that carry content.
+        for (const forbidden of [
+            "message.parts",
+            "\\.text",
+            "message.prompt",
+            "message.summary",
+        ]) {
+            expect(source).not.toMatch(new RegExp(forbidden));
+        }
+    });
+    it("round-trips its configuration back out of the file", () => {
+        writeOpencodePlugin(buildOpencodePlugin(INSTALL), pluginPath);
+        const read = readOpencodePlugin(pluginPath);
+        expect(read.exists).toBe(true);
+        // This is how `doctor`, `status` and the hook find the token: there is
+        // nowhere else it is written.
+        expect(read.config).toEqual(INSTALL);
+    });
+    it("stamps the generation that wrote it", () => {
+        // Unlike the hook agents, this file does not follow the CLI: it stays as
+        // written until `setup` runs again. The stamp is the only way `doctor`
+        // can tell a plugin that predates a fix from one that has it.
+        writeOpencodePlugin(buildOpencodePlugin(INSTALL), pluginPath);
+        expect(readOpencodePlugin(pluginPath).version).toBe(OPENCODE_PLUGIN_VERSION);
+    });
+    it("writes the file readable only by its owner", () => {
+        writeOpencodePlugin(buildOpencodePlugin(INSTALL), pluginPath);
+        // The ingest token is in there in plaintext.
+        expect(readFileSync(pluginPath, "utf8")).toContain(INSTALL.token);
+    });
+    it("backs up whatever was there before overwriting", () => {
+        writeOpencodePlugin("// something the user wrote\n", pluginPath);
+        const { backupPath } = writeOpencodePlugin(buildOpencodePlugin(INSTALL), pluginPath);
+        expect(backupPath).toBe(`${pluginPath}.clocktopus-backup`);
+        expect(readFileSync(backupPath, "utf8")).toBe("// something the user wrote\n");
+    });
+});
+describe("reading a plugin that is not ours to read", () => {
+    it("reports a hand-edited plugin as unconfigured rather than guessing", () => {
+        writeOpencodePlugin("export const Whatever = async () => ({});\n", pluginPath);
+        const read = readOpencodePlugin(pluginPath);
+        // The file exists but tells us nothing, so `setup` is the honest next
+        // step — reporting it as configured would leave the user staring at a
+        // pipeline that cannot possibly deliver.
+        expect(read.exists).toBe(true);
+        expect(read.config).toBeNull();
+    });
+    it("reads a plugin from before stamping existed as unstamped", () => {
+        // Every plugin installed before the stamp shipped lands here. `null`
+        // means "not the current generation", which is exactly right for one
+        // written by a CLI that had no generations at all.
+        const unstamped = buildOpencodePlugin(INSTALL)
+            .split("\n")
+            .filter((line) => !line.startsWith("// clocktopus-plugin-version:"))
+            .join("\n");
+        writeOpencodePlugin(unstamped, pluginPath);
+        const read = readOpencodePlugin(pluginPath);
+        // Still configured — it reports fine, it is just behind.
+        expect(read.config).toEqual(INSTALL);
+        expect(read.version).toBeNull();
+    });
+    it("reports nothing at all when the file is absent", () => {
+        expect(readOpencodePlugin(pluginPath)).toMatchObject({
+            exists: false,
+            config: null,
+        });
+    });
+});
+describe("removing the plugin", () => {
+    it("deletes the file and says so", () => {
+        writeOpencodePlugin(buildOpencodePlugin(INSTALL), pluginPath);
+        expect(removeOpencodePlugin(pluginPath)).toBe(true);
+        expect(readOpencodePlugin(pluginPath).exists).toBe(false);
+    });
+    it("is a no-op when there is nothing installed", () => {
+        expect(removeOpencodePlugin(pluginPath)).toBe(false);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blastin-dev/clocktopus-cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "bin": {
     "clocktopus": "./dist/bin/clocktopus.js"
@@ -12,6 +12,7 @@
     "commander": "^13.0.0",
     "conf": "^13.0.0",
     "date-fns": "4.1.0",
+    "smol-toml": "^1.8.0",
     "zod": "4.4.3"
   },
   "devDependencies": {