@blogic-cz/agent-tools 1.11.1 → 1.12.0

package/src/gh-tool/read/telemetry-command.ts

@@ -0,0 +1,45 @@
+import { Effect } from "effect";
+import { Command, Flag } from "effect/cli";
+import { formatOption, logFormatted } from "#shared";
+import { GitHubCommandError } from "#gh/errors";
+import { getRateLimit } from "./reads";
+import { summarizeRequests, Telemetry } from "./telemetry";
+
+export const telemetryCommand = Command.make(
+  "telemetry",
+  {
+    hours: Flag.Int("hours").pipe(
+      Flag.withDefault(1),
+      Flag.withDescription("Report window in hours, up to 168"),
+    ),
+    format: formatOption,
+  },
+  ({ hours, format }) =>
+    Effect.gen(function* () {
+      const store = yield* Telemetry;
+      const report = yield* Effect.try({
+        try: () => {
+          if (!Number.isFinite(hours) || hours <= 0 || hours > 168)
+            throw new Error("hours must be greater than 0 and at most 168");
+          if (store === null) throw new Error("Telemetry database unavailable");
+          const since = new Date(Date.now() - hours * 3600000).toISOString();
+          return { since, ...summarizeRequests(store.read(since)) };
+        },
+        catch: (error) =>
+          new GitHubCommandError({
+            message: String(error),
+            command: "gh-tool telemetry",
+            exitCode: 1,
+            stderr: String(error),
+          }),
+      });
+      const current = yield* getRateLimit().pipe(
+        Effect.catch((error) => Effect.succeed({ error: error.message })),
+      );
+      yield* logFormatted({ ...report, current }, format);
+    }),
+).pipe(
+  Command.withDescription(
+    "Report direct HTTP requests, gh subprocess calls, ReadCache hits and estimated external quota use",
+  ),
+);

package/src/gh-tool/read/telemetry-store.ts

@@ -0,0 +1,85 @@
+import { Database } from "bun:sqlite";
+
+import { redactSensitiveText } from "#shared/content-security";
+import type { RequestEvent, RequestRow, TelemetryStore } from "./telemetry";
+
+const telemetryCommand = (args: readonly string[]): string => {
+  const commandGroups = new Set([
+    "pr",
+    "issue",
+    "repo",
+    "label",
+    "branch",
+    "workflow",
+    "release",
+    "gist",
+    "cache",
+  ]);
+  const pathLength = commandGroups.has(args[0]) ? 2 : 1;
+  const path = args.slice(0, pathLength).filter((arg) => !arg.startsWith("-"));
+  if (path.join(" ") === "pr stack" && args[2] && !args[2].startsWith("-")) {
+    path.push(args[2]);
+  }
+  const flags: string[] = [];
+
+  for (const arg of args.slice(path.length)) {
+    if (arg === "--") break;
+    if (arg.startsWith("-")) flags.push(arg.split("=", 1)[0]);
+  }
+
+  return [...path, ...flags.toSorted()].join(" ");
+};
+
+export const openRequestTelemetry = (dbPath: string): TelemetryStore => {
+  const db = new Database(dbPath, { create: true, strict: true });
+  try {
+    db.run("PRAGMA busy_timeout=0");
+    db.run(`CREATE TABLE IF NOT EXISTS github_requests (
+      id INTEGER PRIMARY KEY AUTOINCREMENT, ts TEXT NOT NULL, invocation TEXT NOT NULL,
+      command TEXT NOT NULL, method TEXT NOT NULL, endpoint TEXT NOT NULL,
+      status INTEGER, outcome TEXT NOT NULL, resource TEXT, used INTEGER,
+      remaining INTEGER, reset INTEGER
+    ) STRICT`);
+    db.run("CREATE INDEX IF NOT EXISTS idx_github_requests_ts ON github_requests(ts)");
+    db.run(
+      "DELETE FROM github_requests WHERE ts < strftime('%Y-%m-%dT%H:%M:%fZ', 'now', '-7 days')",
+    );
+  } catch (error) {
+    db.close(false);
+    throw error;
+  }
+  const invocation = crypto.randomUUID();
+  const command = telemetryCommand(process.argv.slice(2));
+  return {
+    record: (event: RequestEvent) => {
+      try {
+        db.run(
+          `INSERT INTO github_requests
+          (ts, invocation, command, method, endpoint, status, outcome, resource, used, remaining, reset)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+          [
+            event.ts,
+            invocation,
+            redactSensitiveText(command),
+            event.method,
+            event.endpoint,
+            event.status,
+            event.outcome,
+            event.resource,
+            event.used,
+            event.remaining,
+            event.reset,
+          ],
+        );
+      } catch {
+        /* Never wait for a writer or change command behavior. */
+      }
+    },
+    read: (since) =>
+      db
+        .query<RequestRow, [string]>("SELECT * FROM github_requests WHERE ts >= ? ORDER BY ts, id")
+        .all(since)
+        .map((row) => Object.assign(row, { command: redactSensitiveText(row.command) })),
+    close: () => db.close(false),
+  };
+};

package/src/gh-tool/read/telemetry.ts

@@ -0,0 +1,191 @@
+import { Context, Effect } from "effect";
+import { redactSensitiveText } from "#shared/content-security";
+
+export type RequestEvent = {
+  ts: string;
+  method: string;
+  endpoint: string;
+  status: number | null;
+  outcome: "cache" | "304" | "200" | "bypass" | "error" | "subprocess";
+  resource: string | null;
+  used: number | null;
+  remaining: number | null;
+  reset: number | null;
+};
+export type RequestRow = RequestEvent & { id: number; invocation: string; command: string };
+export type TelemetryStore = {
+  record: (event: RequestEvent) => void;
+  read: (since: string) => readonly RequestRow[];
+  close: () => void;
+};
+
+export const Telemetry = Context.Reference<TelemetryStore | null>("gh/Telemetry", {
+  defaultValue: () => null,
+});
+export const CacheRequest = Context.Reference<boolean>("gh/CacheRequest", {
+  defaultValue: () => false,
+});
+
+export const templateEndpoint = (path: string): string => {
+  const pathname = path.replace(/^https?:\/\/[^/]+/, "").split(/[?#]/, 1)[0] ?? "";
+  return redactSensitiveText(
+    `/${pathname.replace(/^\//, "")}`
+      .replace(/\b[0-9a-f]{7,64}\b/gi, (part) => (/^\d+$/.test(part) ? ":id" : ":sha"))
+      .replace(/\/\d+(?=\/|$)/g, "/:id"),
+  );
+};
+
+export const recordRequest = (event: RequestEvent): Effect.Effect<void> =>
+  Effect.gen(function* () {
+    const store = yield* Telemetry;
+    try {
+      store?.record({
+        ...event,
+        endpoint:
+          event.outcome === "subprocess" ? event.endpoint : templateEndpoint(event.endpoint),
+      });
+    } catch {
+      /* Best effort. */
+    }
+  });
+
+export const cacheEvent = (operation: string): RequestEvent => ({
+  ts: new Date().toISOString(),
+  method: "CACHE",
+  endpoint: `cache/${operation}`,
+  status: null,
+  outcome: "cache",
+  resource: null,
+  used: null,
+  remaining: null,
+  reset: null,
+});
+
+const API_VALUE_FLAGS = new Set([
+  "-X",
+  "--method",
+  "-H",
+  "--header",
+  "-f",
+  "-F",
+  "--field",
+  "--raw-field",
+  "--jq",
+  "-q",
+  "--template",
+  "-t",
+  "--input",
+  "--cache",
+  "-p",
+  "--preview",
+  "--hostname",
+]);
+
+export const ghSubprocessEvent = (args: readonly string[], exitCode: number): RequestEvent => {
+  const api = args[0] === "api";
+  let endpoint: string | undefined;
+  let method: string | undefined;
+  let hasFields = false;
+  if (api) {
+    for (let index = 1; index < args.length; index++) {
+      const arg = args[index];
+      if (arg === undefined) continue;
+      if (arg === "--") {
+        endpoint ??= args[index + 1];
+        break;
+      }
+      if (!arg.startsWith("-")) {
+        endpoint ??= arg;
+        continue;
+      }
+      const equals = arg.indexOf("=");
+      const flag = equals < 0 ? arg : arg.slice(0, equals);
+      if (!API_VALUE_FLAGS.has(flag)) continue;
+      const value = equals < 0 ? args[++index] : arg.slice(equals + 1);
+      if (flag === "-X" || flag === "--method") method = value;
+      if (flag === "-f" || flag === "-F" || flag === "--field" || flag === "--raw-field")
+        hasFields = true;
+    }
+  }
+  return {
+    ...cacheEvent(""),
+    method: api ? (method ?? (hasFields ? "POST" : "GET")) : "GH",
+    endpoint: api ? templateEndpoint(endpoint ?? "") : args.slice(0, 2).join(" "),
+    status: exitCode >= 100 && exitCode <= 599 ? exitCode : null,
+    outcome: "subprocess",
+  };
+};
+
+const counts = (values: readonly string[]) => {
+  const groups = new Map<string, number>();
+  for (const value of values) groups.set(value, (groups.get(value) ?? 0) + 1);
+  return [...groups]
+    .map(([name, requests]) => ({ name, requests }))
+    .toSorted((a, b) => b.requests - a.requests || a.name.localeCompare(b.name));
+};
+
+const subprocessSpendsResource = (row: RequestRow, resource: string): boolean => {
+  if (row.outcome !== "subprocess") return false;
+  if (row.method === "GH") return true;
+  if (row.method === "GET" && row.endpoint === "/rate_limit") return false;
+  return row.endpoint === "/graphql" ? resource === "graphql" : resource !== "graphql";
+};
+
+export const summarizeRequests = (rows: readonly RequestRow[]) => {
+  const requests = rows.filter((row) => row.outcome !== "cache" && row.outcome !== "subprocess");
+  const subprocesses = rows.filter((row) => row.outcome === "subprocess");
+  const previous = new Map<string, { used: number; index: number }>();
+  let externalUsageEstimate = 0;
+  let intervals = 0;
+  for (const [index, row] of rows.entries()) {
+    if (row.outcome === "cache" || row.outcome === "subprocess") continue;
+    if (row.resource === null || row.used === null || row.reset === null) continue;
+    const resource = row.resource;
+    const key = `${resource}:${row.reset}`;
+    const before = previous.get(key);
+    if (before !== undefined && row.used >= before.used) {
+      const interval = rows.slice(before.index + 1, index + 1);
+      const own = interval.filter(
+        (candidate) =>
+          candidate.resource === resource &&
+          (candidate.reset === null || candidate.reset === row.reset) &&
+          candidate.status !== 304 &&
+          candidate.endpoint !== "/rate_limit",
+      ).length;
+      const subprocessCalls = interval.filter((candidate) =>
+        subprocessSpendsResource(candidate, resource),
+      ).length;
+      externalUsageEstimate += Math.max(0, row.used - before.used - own - subprocessCalls);
+      intervals++;
+    }
+    if (before === undefined || row.used >= before.used)
+      previous.set(key, { used: row.used, index });
+  }
+  const notModified = requests.filter((row) => row.status === 304).length;
+  return {
+    directHttpRequests: requests.length,
+    ghSubprocessCalls: subprocesses.length,
+    cacheHits: rows.filter((row) => row.outcome === "cache").length,
+    subprocessTopCommands: counts(subprocesses.map((row) => redactSensitiveText(row.command)))
+      .slice(0, 20)
+      .map(({ name, requests: calls }) => ({ name, calls })),
+    subprocessTopEndpoints: counts(subprocesses.map((row) => `${row.method} ${row.endpoint}`))
+      .slice(0, 20)
+      .map(({ name, requests: calls }) => ({ name, calls })),
+    directHttpByResource: counts(requests.map((row) => row.resource ?? "unknown")),
+    directHttpTopCommands: counts(requests.map((row) => redactSensitiveText(row.command))).slice(
+      0,
+      20,
+    ),
+    directHttpTopEndpoints: counts(requests.map((row) => `${row.method} ${row.endpoint}`)).slice(
+      0,
+      20,
+    ),
+    notModified,
+    ratio304: requests.length === 0 ? null : notModified / requests.length,
+    externalUsageEstimate: intervals === 0 ? null : externalUsageEstimate,
+    observedIntervals: intervals,
+    caveat:
+      "Estimate within observed reset windows only. Missing headers, concurrent requests, different tokens and dropped telemetry reduce accuracy. Direct HTTP counts are exact. Each gh subprocess call may make zero or more HTTP requests; its HTTP status and quota headers are unavailable. For this estimate, subprocess calls count as one request each. Cache hits count ReadCache only.",
+  };
+};

package/src/gh-tool/read/transport.ts

@@ -1,3 +1,4 @@
+import { ghSubprocessEvent, recordRequest } from "./telemetry";
 import { ChildProcess, ChildProcessSpawner } from "effect/process";
 import { Context, Effect, Layer, Stream } from "effect";
 
@@ -182,13 +183,17 @@ export class GitHubService extends Context.Service<
 
               const proc = yield* executor.spawn(command);
 
-              const stdoutChunk = yield* proc.stdout.pipe(Stream.decodeText(), Stream.runCollect);
+              const [stdoutChunk, stderrChunk] = yield* Effect.all(
+                [
+                  proc.stdout.pipe(Stream.decodeText(), Stream.runCollect),
+                  proc.stderr.pipe(Stream.decodeText(), Stream.runCollect),
+                ],
+                { concurrency: "unbounded" },
+              );
               const stdout = stdoutChunk.join("");
-
-              const stderrChunk = yield* proc.stderr.pipe(Stream.decodeText(), Stream.runCollect);
               const stderr = stderrChunk.join("");
-
               const exitCode = yield* proc.exitCode;
+              yield* recordRequest(ghSubprocessEvent(args, Number(exitCode)));
 
               return {
                 stdout,
@@ -246,7 +251,7 @@ export class GitHubService extends Context.Service<
               const quotaFilter =
                 resource === undefined
                   ? '.resources | to_entries[] | "\\(.key): reset time: \\(.value.reset | todateiso8601); remaining quota: \\(.value.remaining)"'
-                  : `.resources.${resource} | "reset time: \\(.reset | todateiso8601); remaining quota: \\(.remaining)"`;
+                  : `.resources.${resource} | "resource: ${resource}; reset time: \\(.reset | todateiso8601); remaining quota: \\(.remaining)"`;
               const quota = yield* executeGh(["api", "rate_limit", "--jq", quotaFilter]).pipe(
                 Effect.orElseSucceed(() => null),
               );

package/src/gh-tool/workflow.ts

@@ -298,7 +298,7 @@ const fetchAnnotations = Effect.fn("workflow.fetchAnnotations")(function* (opts:
     const parts = opts.repo.split("/");
     if (parts.length !== 2 || !parts[0] || !parts[1]) {
       return yield* new GitHubCommandError({
-        message: `Invalid --repo format: "${opts.repo}". Expected "owner/name" (e.g. "blogic-cz/agent-tools").`,
+        message: `Invalid --repo format: "${opts.repo}". Expected "owner/name" (e.g. "example-org/example-repo").`,
         command: "workflow annotations",
         exitCode: 1,
         stderr: "",
@@ -574,7 +574,7 @@ export const fetchJobLogs = Effect.fn("workflow.fetchJobLogs")(function* (
     const parts = opts.repo.split("/");
     if (parts.length !== 2 || !parts[0] || !parts[1]) {
       return yield* new GitHubCommandError({
-        message: `Invalid --repo format: "${opts.repo}". Expected "owner/name" (e.g. "blogic-cz/agent-tools").`,
+        message: `Invalid --repo format: "${opts.repo}". Expected "owner/name" (e.g. "example-org/example-repo").`,
         command: "workflow job-logs",
         exitCode: 1,
         stderr: "",