@tekyzinc/gsd-t 2.74.13 → 2.76.10

package/scripts/context-meter/count-tokens-client.js

@@ -0,0 +1,221 @@
+/**
+ * count-tokens-client.js
+ *
+ * Zero-dependency Node.js client for Anthropic's `POST /v1/messages/count_tokens`
+ * endpoint. Built on the built-in `https` / `http` modules so the Context Meter
+ * hook ships with no runtime dependencies.
+ *
+ * Contract: `.gsd-t/contracts/context-meter-contract.md` — "count_tokens API usage"
+ *
+ * Design notes:
+ *
+ *   - Every failure mode returns `null`. The caller (the hook in Task 4) treats
+ *     `null` as "fail open" — it simply emits `{}` on stdout and Claude is never
+ *     blocked. This function NEVER throws.
+ *
+ *   - The `system` field on the Messages API rejects an empty string
+ *     (`system: ""` → 400). The `{ system, messages }` shape produced by
+ *     `transcript-parser.js` starts with an empty system string when the
+ *     transcript has no system blocks, so this client DROPS the `system` key
+ *     from the request body when the input is an empty string. Any non-empty
+ *     system is forwarded as-is.
+ *
+ *   - The hard timeout uses `req.setTimeout(ms)`; on fire we `req.destroy()` to
+ *     release the socket and return `null`. Without the explicit destroy the
+ *     socket can linger for the OS-level keep-alive window, which matters when
+ *     the hook is already at its ~200ms latency budget.
+ *
+ *   - We NEVER log the request body. The only diagnostic signal this module
+ *     produces is the returned value itself (`null` on failure). Any logging
+ *     is the caller's responsibility — the hook writes to `logPath` per config.
+ *
+ *   - A hidden `_baseUrl` option lets the tests point the client at a local
+ *     stub HTTP server bound to `127.0.0.1:0`. Production callers never pass
+ *     `_baseUrl`. Parsing uses `URL` so either http or https works transparently.
+ *
+ * @module scripts/context-meter/count-tokens-client
+ */
+
+"use strict";
+
+const https = require("https");
+const http = require("http");
+const { URL } = require("url");
+
+const DEFAULT_BASE_URL = "https://api.anthropic.com";
+const COUNT_TOKENS_PATH = "/v1/messages/count_tokens";
+const ANTHROPIC_VERSION = "2023-06-01";
+
+/**
+ * Call Anthropic count_tokens.
+ *
+ * @param {object} opts
+ * @param {string} opts.apiKey - Anthropic API key (from env var named in config)
+ * @param {string} opts.model - model id, e.g. "claude-opus-4-6"
+ * @param {string} opts.system - system prompt text; dropped from body if ""
+ * @param {Array}  opts.messages - messages array from transcript-parser.js
+ * @param {number} opts.timeoutMs - hard timeout for the whole request
+ * @param {string} [opts._baseUrl] - TEST ONLY: override the base URL
+ * @returns {Promise<{inputTokens: number} | null>} tokens on success, null on any failure
+ */
+function countTokens(opts) {
+  return new Promise((resolve) => {
+    // Single outer try/catch — any synchronous throw below becomes `null`.
+    try {
+      if (!opts || typeof opts !== "object") {
+        resolve(null);
+        return;
+      }
+
+      const {
+        apiKey,
+        model,
+        system,
+        messages,
+        timeoutMs,
+        _baseUrl,
+      } = opts;
+
+      if (typeof apiKey !== "string" || apiKey.length === 0) {
+        resolve(null);
+        return;
+      }
+      if (typeof model !== "string" || model.length === 0) {
+        resolve(null);
+        return;
+      }
+      if (!Array.isArray(messages)) {
+        resolve(null);
+        return;
+      }
+      if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        resolve(null);
+        return;
+      }
+
+      // Build request body. Drop `system` when it's an empty string —
+      // the endpoint rejects `system: ""` with a 400.
+      const body = { model, messages };
+      if (typeof system === "string" && system.length > 0) {
+        body.system = system;
+      } else if (system != null && typeof system !== "string") {
+        // Unusual shape — do not forward.
+        resolve(null);
+        return;
+      }
+
+      let payload;
+      try {
+        payload = JSON.stringify(body);
+      } catch (_) {
+        resolve(null);
+        return;
+      }
+
+      // Parse base URL — test code passes http://127.0.0.1:<port>, prod uses https.
+      let parsed;
+      try {
+        parsed = new URL(COUNT_TOKENS_PATH, _baseUrl || DEFAULT_BASE_URL);
+      } catch (_) {
+        resolve(null);
+        return;
+      }
+
+      const isHttps = parsed.protocol === "https:";
+      const transport = isHttps ? https : http;
+
+      const reqOptions = {
+        method: "POST",
+        hostname: parsed.hostname,
+        port: parsed.port || (isHttps ? 443 : 80),
+        path: parsed.pathname + parsed.search,
+        headers: {
+          "x-api-key": apiKey,
+          "anthropic-version": ANTHROPIC_VERSION,
+          "content-type": "application/json",
+          "content-length": Buffer.byteLength(payload),
+        },
+      };
+
+      let settled = false;
+      const settle = (value) => {
+        if (settled) return;
+        settled = true;
+        resolve(value);
+      };
+
+      let req;
+      try {
+        req = transport.request(reqOptions, (res) => {
+          const status = res.statusCode || 0;
+          const chunks = [];
+          res.on("data", (chunk) => {
+            chunks.push(chunk);
+          });
+          res.on("end", () => {
+            if (status !== 200) {
+              // 401 / 403 / 429 / 5xx — fail open silently.
+              settle(null);
+              return;
+            }
+            let text;
+            try {
+              text = Buffer.concat(chunks).toString("utf8");
+            } catch (_) {
+              settle(null);
+              return;
+            }
+            let parsedBody;
+            try {
+              parsedBody = JSON.parse(text);
+            } catch (_) {
+              settle(null);
+              return;
+            }
+            if (!parsedBody || typeof parsedBody !== "object") {
+              settle(null);
+              return;
+            }
+            const n = Number(parsedBody.input_tokens);
+            if (!Number.isFinite(n)) {
+              settle(null);
+              return;
+            }
+            settle({ inputTokens: n });
+          });
+          res.on("error", () => {
+            settle(null);
+          });
+        });
+      } catch (_) {
+        settle(null);
+        return;
+      }
+
+      req.on("error", () => {
+        settle(null);
+      });
+
+      req.setTimeout(timeoutMs, () => {
+        // Destroy the socket so it doesn't linger beyond the hook's latency budget.
+        try {
+          req.destroy();
+        } catch (_) {
+          /* ignore */
+        }
+        settle(null);
+      });
+
+      try {
+        req.write(payload);
+        req.end();
+      } catch (_) {
+        settle(null);
+      }
+    } catch (_) {
+      resolve(null);
+    }
+  });
+}
+
+module.exports = { countTokens };

package/scripts/context-meter/count-tokens-client.test.js

@@ -0,0 +1,308 @@
+"use strict";
+
+const { test } = require("node:test");
+const assert = require("node:assert/strict");
+const http = require("http");
+
+const { countTokens } = require("./count-tokens-client");
+
+/* ----------------------------- stub server helpers ----------------------------- */
+
+/**
+ * Start a stub HTTP server bound to 127.0.0.1:0 (OS-assigned port).
+ *
+ * @param {(req, res, body) => void} handler
+ *   Called on every incoming request. `body` is the full request body as string.
+ *   The handler is responsible for writing the response (unless it intentionally
+ *   hangs — see the timeout test).
+ * @returns {Promise<{server: http.Server, baseUrl: string, lastBody: {value: string|null}}>}
+ */
+function startStub(handler) {
+  return new Promise((resolve, reject) => {
+    const lastBody = { value: null };
+    const server = http.createServer((req, res) => {
+      const chunks = [];
+      req.on("data", (c) => chunks.push(c));
+      req.on("end", () => {
+        const body = Buffer.concat(chunks).toString("utf8");
+        lastBody.value = body;
+        try {
+          handler(req, res, body);
+        } catch (err) {
+          try {
+            res.statusCode = 500;
+            res.end(String(err && err.message));
+          } catch (_) {
+            /* ignore */
+          }
+        }
+      });
+    });
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      resolve({ server, baseUrl: `http://127.0.0.1:${addr.port}`, lastBody });
+    });
+  });
+}
+
+function closeServer(server) {
+  return new Promise((resolve) => {
+    if (!server) {
+      resolve();
+      return;
+    }
+    // Destroy any lingering sockets so hung handlers don't keep the event loop alive.
+    try {
+      server.closeAllConnections && server.closeAllConnections();
+    } catch (_) {
+      /* ignore */
+    }
+    server.close(() => resolve());
+  });
+}
+
+/* ---------------------------------- tests ---------------------------------- */
+
+test("happy path → returns { inputTokens }", async () => {
+  const { server, baseUrl } = await startStub((req, res) => {
+    res.statusCode = 200;
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify({ input_tokens: 12345 }));
+  });
+  try {
+    const got = await countTokens({
+      apiKey: "sk-test",
+      model: "claude-opus-4-6",
+      system: "you are helpful",
+      messages: [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+      timeoutMs: 2000,
+      _baseUrl: baseUrl,
+    });
+    assert.deepEqual(got, { inputTokens: 12345 });
+  } finally {
+    await closeServer(server);
+  }
+});
+
+test("401 → returns null", async () => {
+  const { server, baseUrl } = await startStub((req, res) => {
+    res.statusCode = 401;
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify({ error: { type: "authentication_error", message: "bad key" } }));
+  });
+  try {
+    const got = await countTokens({
+      apiKey: "sk-bad",
+      model: "claude-opus-4-6",
+      system: "",
+      messages: [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+      timeoutMs: 2000,
+      _baseUrl: baseUrl,
+    });
+    assert.equal(got, null);
+  } finally {
+    await closeServer(server);
+  }
+});
+
+test("429 → returns null", async () => {
+  const { server, baseUrl } = await startStub((req, res) => {
+    res.statusCode = 429;
+    res.end("rate limited");
+  });
+  try {
+    const got = await countTokens({
+      apiKey: "sk-test",
+      model: "claude-opus-4-6",
+      system: "",
+      messages: [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+      timeoutMs: 2000,
+      _baseUrl: baseUrl,
+    });
+    assert.equal(got, null);
+  } finally {
+    await closeServer(server);
+  }
+});
+
+test("500 → returns null", async () => {
+  const { server, baseUrl } = await startStub((req, res) => {
+    res.statusCode = 500;
+    res.end("internal");
+  });
+  try {
+    const got = await countTokens({
+      apiKey: "sk-test",
+      model: "claude-opus-4-6",
+      system: "",
+      messages: [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+      timeoutMs: 2000,
+      _baseUrl: baseUrl,
+    });
+    assert.equal(got, null);
+  } finally {
+    await closeServer(server);
+  }
+});
+
+test("timeout → returns null", async () => {
+  // Handler never responds — the client's timeoutMs should fire first.
+  const { server, baseUrl } = await startStub(() => {
+    /* never calls res.end() */
+  });
+  try {
+    const t0 = Date.now();
+    const got = await countTokens({
+      apiKey: "sk-test",
+      model: "claude-opus-4-6",
+      system: "",
+      messages: [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+      timeoutMs: 500,
+      _baseUrl: baseUrl,
+    });
+    const elapsed = Date.now() - t0;
+    assert.equal(got, null);
+    // Should resolve shortly after the 500ms timeout, well under the 5s test budget.
+    assert.ok(elapsed < 3000, `timeout path took too long: ${elapsed}ms`);
+  } finally {
+    await closeServer(server);
+  }
+});
+
+test("malformed response JSON → returns null", async () => {
+  const { server, baseUrl } = await startStub((req, res) => {
+    res.statusCode = 200;
+    res.setHeader("content-type", "application/json");
+    res.end('not json{');
+  });
+  try {
+    const got = await countTokens({
+      apiKey: "sk-test",
+      model: "claude-opus-4-6",
+      system: "",
+      messages: [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+      timeoutMs: 2000,
+      _baseUrl: baseUrl,
+    });
+    assert.equal(got, null);
+  } finally {
+    await closeServer(server);
+  }
+});
+
+test("missing input_tokens field → returns null", async () => {
+  const { server, baseUrl } = await startStub((req, res) => {
+    res.statusCode = 200;
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify({ other_field: 99 }));
+  });
+  try {
+    const got = await countTokens({
+      apiKey: "sk-test",
+      model: "claude-opus-4-6",
+      system: "",
+      messages: [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+      timeoutMs: 2000,
+      _baseUrl: baseUrl,
+    });
+    assert.equal(got, null);
+  } finally {
+    await closeServer(server);
+  }
+});
+
+test('empty system string → request body OMITS "system" key', async () => {
+  const { server, baseUrl, lastBody } = await startStub((req, res) => {
+    res.statusCode = 200;
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify({ input_tokens: 1 }));
+  });
+  try {
+    await countTokens({
+      apiKey: "sk-test",
+      model: "claude-opus-4-6",
+      system: "",
+      messages: [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+      timeoutMs: 2000,
+      _baseUrl: baseUrl,
+    });
+    assert.ok(lastBody.value, "stub did not receive a body");
+    const parsed = JSON.parse(lastBody.value);
+    assert.equal(Object.prototype.hasOwnProperty.call(parsed, "system"), false);
+    assert.equal(parsed.model, "claude-opus-4-6");
+    assert.ok(Array.isArray(parsed.messages));
+  } finally {
+    await closeServer(server);
+  }
+});
+
+test('non-empty system → request body INCLUDES "system"', async () => {
+  const { server, baseUrl, lastBody } = await startStub((req, res) => {
+    res.statusCode = 200;
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify({ input_tokens: 2 }));
+  });
+  try {
+    await countTokens({
+      apiKey: "sk-test",
+      model: "claude-opus-4-6",
+      system: "some text",
+      messages: [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+      timeoutMs: 2000,
+      _baseUrl: baseUrl,
+    });
+    assert.ok(lastBody.value, "stub did not receive a body");
+    const parsed = JSON.parse(lastBody.value);
+    assert.equal(parsed.system, "some text");
+  } finally {
+    await closeServer(server);
+  }
+});
+
+test("sends required Anthropic headers", async () => {
+  let seenHeaders = null;
+  const { server, baseUrl } = await startStub((req, res) => {
+    seenHeaders = req.headers;
+    res.statusCode = 200;
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify({ input_tokens: 3 }));
+  });
+  try {
+    await countTokens({
+      apiKey: "sk-abc-123",
+      model: "claude-opus-4-6",
+      system: "",
+      messages: [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+      timeoutMs: 2000,
+      _baseUrl: baseUrl,
+    });
+    assert.ok(seenHeaders, "stub did not receive headers");
+    assert.equal(seenHeaders["x-api-key"], "sk-abc-123");
+    assert.equal(seenHeaders["anthropic-version"], "2023-06-01");
+    assert.equal(seenHeaders["content-type"], "application/json");
+  } finally {
+    await closeServer(server);
+  }
+});
+
+test("invalid opts → returns null without throwing", async () => {
+  assert.equal(await countTokens(null), null);
+  assert.equal(await countTokens({}), null);
+  assert.equal(
+    await countTokens({ apiKey: "", model: "m", messages: [], timeoutMs: 100 }),
+    null
+  );
+  assert.equal(
+    await countTokens({ apiKey: "k", model: "", messages: [], timeoutMs: 100 }),
+    null
+  );
+  assert.equal(
+    await countTokens({ apiKey: "k", model: "m", messages: "no", timeoutMs: 100 }),
+    null
+  );
+  assert.equal(
+    await countTokens({ apiKey: "k", model: "m", messages: [], timeoutMs: 0 }),
+    null
+  );
+});

package/scripts/context-meter/test-injector.js

@@ -0,0 +1,55 @@
+/**
+ * test-injector.js — TEST-ONLY INFRASTRUCTURE. DO NOT REQUIRE FROM PRODUCTION CODE.
+ *
+ * Loaded into the child process via NODE_OPTIONS=--require when running the
+ * E2E test at `scripts/gsd-t-context-meter.e2e.test.js`. Its job is to monkey-
+ * patch `count-tokens-client.countTokens` so the real child-process hook (which
+ * normally calls https://api.anthropic.com) is redirected to a local stub HTTP
+ * server bound on 127.0.0.1:{random-port}.
+ *
+ * Production NEVER loads this file:
+ *   - The hook script (`scripts/gsd-t-context-meter.js`) does not require it.
+ *   - The npm installer does not ship `NODE_OPTIONS` anywhere near it.
+ *   - The file lives under `scripts/context-meter/` only so the E2E test can
+ *     point `--require` at a stable absolute path; nothing in the runtime
+ *     require graph pulls it in on its own.
+ *
+ * Activation:
+ *   - Reads `process.env.GSD_T_CONTEXT_METER_TEST_BASE_URL`. If unset, the file
+ *     is a no-op (and `NODE_OPTIONS=--require` with this path on a production
+ *     invocation would still be a harmless no-op).
+ *   - When set, resolves and requires `./count-tokens-client`, wraps its
+ *     `countTokens` export to inject `_baseUrl` before every call, and
+ *     reassigns the property on the same module.exports object — so any later
+ *     `require('./count-tokens-client')` from the hook sees the patched fn.
+ *
+ * Why this exists:
+ *   Tasks 1–4 tested `runMeter()` via dependency injection. Task 5 tests the
+ *   real child-process hook as Claude Code would invoke it, which means no DI
+ *   seams are available — only stdin, stdout, and env. The hook's CLI shim does
+ *   not accept `_baseUrl` as a config param (by design: production must never
+ *   be routable to a non-Anthropic host). So the only honest way to redirect
+ *   HTTP in a black-box test is to monkey-patch the HTTP client *inside* the
+ *   child process, gated on a test-only env var. That is what this file does.
+ *
+ * @module scripts/context-meter/test-injector
+ */
+
+"use strict";
+
+const baseUrl = process.env.GSD_T_CONTEXT_METER_TEST_BASE_URL;
+if (baseUrl && typeof baseUrl === "string" && baseUrl.length > 0) {
+  try {
+    const clientPath = require.resolve("./count-tokens-client");
+    const client = require(clientPath);
+    const original = client.countTokens;
+    if (typeof original === "function") {
+      client.countTokens = function patchedCountTokens(opts) {
+        const merged = Object.assign({}, opts || {}, { _baseUrl: baseUrl });
+        return original(merged);
+      };
+    }
+  } catch (_) {
+    // Silent — an injector failure must never break the child process.
+  }
+}

package/scripts/context-meter/threshold.js

@@ -0,0 +1,88 @@
+/**
+ * scripts/context-meter/threshold.js
+ *
+ * Pure-function module for the context-meter PostToolUse hook.
+ *
+ * Responsibilities:
+ *   1. Compute the context-window percentage from a token count + window size.
+ *   2. Map that percentage to a token-budget band (normal / warn / stop).
+ *      Boundaries mirror bin/token-budget.js v3.0.0 exactly so the
+ *      `threshold` field in the state file is consistent across consumers.
+ *   3. Build the exact `additionalContext` string the hook emits when the
+ *      measured percentage meets or exceeds the configured thresholdPct.
+ *
+ * v3.0.0 (M35): The `downgrade` and `conserve` bands were REMOVED. The
+ * three-band model is: normal < 70 ≤ warn < 85 ≤ stop. Silent model
+ * degradation and silent phase-skipping violate GSD-T's quality principles.
+ *
+ * Zero side effects. Zero dependencies. CommonJS.
+ */
+
+// ── Band boundaries (must match bin/token-budget.js THRESHOLDS exactly) ──────
+// Lower bound inclusive, upper bound exclusive.
+const BANDS = Object.freeze({
+  warn: 70,
+  stop: 85,
+});
+
+/**
+ * Compute context-window percentage (0–100+).
+ *
+ * Fail-safe: any non-finite, negative, or zero-window input returns 0 — the
+ * caller should treat 0 as "normal/safe, no action needed".
+ *
+ * Does NOT clamp above 100. If real usage reports 102.3%, return 102.3; the
+ * band mapping handles it (>= 95 → stop).
+ *
+ * @param {{ inputTokens: number, modelWindowSize: number }} args
+ * @returns {number}
+ */
+function computePct({ inputTokens, modelWindowSize } = {}) {
+  if (!Number.isFinite(inputTokens) || !Number.isFinite(modelWindowSize)) {
+    return 0;
+  }
+  if (inputTokens < 0 || modelWindowSize <= 0) {
+    return 0;
+  }
+  return (inputTokens / modelWindowSize) * 100;
+}
+
+/**
+ * Map a percentage to a token-budget band (v3.0.0 three-band model).
+ *
+ * Boundaries (inclusive on the lower edge):
+ *   pct <  70 → "normal"
+ *   pct <  85 → "warn"
+ *   pct >= 85 → "stop"
+ *
+ * Non-finite input → "normal" (fail-safe — never escalate on garbage).
+ *
+ * @param {number} pct
+ * @returns {"normal"|"warn"|"stop"}
+ */
+function bandFor(pct) {
+  if (!Number.isFinite(pct)) return "normal";
+  if (pct >= BANDS.stop) return "stop";
+  if (pct >= BANDS.warn) return "warn";
+  return "normal";
+}
+
+/**
+ * Build the `additionalContext` string the hook emits, or null if the
+ * measured percentage is below the configured thresholdPct.
+ *
+ * Exact format (from .gsd-t/contracts/context-meter-contract.md line 139):
+ *   ⚠️ Context window at {pct.toFixed(1)}% of {modelWindowSize}. Run /user:gsd-t-pause to checkpoint and clear before continuing.
+ *
+ * `modelWindowSize` is emitted as the raw integer — no commas, no "K" suffix.
+ *
+ * @param {{ pct: number, modelWindowSize: number, thresholdPct: number }} args
+ * @returns {string|null}
+ */
+function buildAdditionalContext({ pct, modelWindowSize, thresholdPct } = {}) {
+  if (!Number.isFinite(pct) || !Number.isFinite(thresholdPct)) return null;
+  if (pct < thresholdPct) return null;
+  return `⚠️ Context window at ${pct.toFixed(1)}% of ${modelWindowSize}. Run /user:gsd-t-pause to checkpoint and clear before continuing.`;
+}
+
+module.exports = { computePct, bandFor, buildAdditionalContext, BANDS };