@blogic-cz/agent-tools 1.10.1 → 1.12.0

package/src/gh-tool/main.ts

@@ -4,7 +4,8 @@ import { BunRuntime, BunServices } from "@effect/platform-bun";
 import { Effect, Layer } from "effect";
 
 import { makeSchemaCommand, renderCauseToStderr, VERSION } from "#shared";
-import { AuditServiceLayer, withAudit } from "#shared/audit";
+import { AuditService, AuditServiceLayer, withAudit } from "#shared/audit";
+import { openRequestTelemetry } from "#gh/read/telemetry-store";
 import { withRedactedOutput } from "#shared/output-boundary";
 import { ConfigServiceLayer } from "#config";
 import {
@@ -80,7 +81,9 @@ import {
 import { labelCreateCommand } from "./label";
 import { GitHubService } from "./read/transport";
 import { withReadCache } from "./read";
-import { cacheCommand } from "./read/commands";
+import { Telemetry } from "./read/telemetry";
+import { telemetryCommand } from "./read/telemetry-command";
+import { cacheCommand, rateLimitCommand } from "./read/commands";
 import {
   workflowAnnotationsCommand,
   workflowCancelCommand,
@@ -221,6 +224,7 @@ const mainCommand = Command.make("gh-tool", {}).pipe(
 
 Wraps the GitHub CLI (gh) with structured output for AI agents.
 Supports PR management, issue management, reviews, CI checks, and repo info.
+Use 'rate-limit' to inspect GitHub API quota without consuming it.
 
 WORKFLOW FOR AI AGENTS:
   1. Use 'pr view' to inspect current PR
@@ -250,6 +254,8 @@ WORKFLOW FOR AI AGENTS:
   24. Use 'gist list/view' to read gists and 'gist create --files a.ts --desc "..."' to share snippets`,
   ),
   Command.withSubcommands([
+    rateLimitCommand,
+    telemetryCommand,
     prCommand,
     issueCommand,
     repoCommand,
@@ -274,10 +280,28 @@ const MainLayer = GitHubService.layer.pipe(
   Layer.provideMerge(ConfigServiceLayer),
 );
 
-const program = withReadCache(withRedactedOutput(withAudit("gh", cli))).pipe(
-  Effect.provide(MainLayer),
-  Effect.tapCause(renderCauseToStderr),
-);
+const observed = Effect.gen(function* () {
+  const audit = yield* AuditService;
+  let store = null;
+  try {
+    store = openRequestTelemetry(audit.dbPath);
+  } catch {
+    /* Telemetry is optional. */
+  }
+  return yield* withReadCache(withRedactedOutput(withAudit("gh", cli))).pipe(
+    Effect.provideService(Telemetry, store),
+    Effect.ensuring(
+      Effect.sync(() => {
+        try {
+          store?.close();
+        } catch {
+          /* Best effort. */
+        }
+      }),
+    ),
+  );
+});
+const program = observed.pipe(Effect.provide(MainLayer), Effect.tapCause(renderCauseToStderr));
 
 BunRuntime.runMain(program, {
   disableErrorReporting: true,

package/src/gh-tool/pr/commands.ts

@@ -524,8 +524,15 @@ export const prStatusCommand = Command.make(
     withRepo(
       repo,
       Effect.gen(function* () {
-        const result: PRStatusResult = yield* detectPRStatus();
-        yield* logFormatted(result, format);
+        const [result, rateLimit] = yield* Effect.all([
+          detectPRStatus(),
+          reads.getPRStatusRateLimit(),
+        ]);
+        const status: PRStatusResult & { readonly rateLimit: typeof rateLimit } = {
+          ...result,
+          rateLimit,
+        };
+        yield* logFormatted(status, format);
       }),
     ),
 ).pipe(

package/src/gh-tool/pr/core.ts

@@ -248,12 +248,12 @@ const fetchWorkflowRunFailureContext = Effect.fn("pr.fetchWorkflowRunFailureCont
 
 // `gh pr checks` exits 1 on an *empty* result ("no checks reported on the 'x' branch"). Zero checks
 // is an ordinary state, so it is not an error, but it is also not an empty list: a PR with green
-// checks (sabservis/nexus-be#1396) once came back empty.
+// checks (example/example-be#1396) once came back empty.
 export const NO_CHECKS_REPORTED_RE = /no checks reported/i;
 // `gh` reports "no checks reported" both for the seconds after a push, before its checks
 // register, and forever for a PR that has none — the message cannot tell them apart. So the
 // wait for registration gets its own short budget: long enough to cover the race (measured
-// at roughly 40s on blogic-cz/agent-tools#134), short enough that a check-less PR is not held
+// at roughly 40 seconds), short enough that a check-less PR is not held
 // for the caller's whole --timeout.
 const CHECK_REGISTRATION_POLL_SECONDS = 5;
 const CHECK_REGISTRATION_GRACE_SECONDS = 60;

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

@@ -1,3 +1,5 @@
+import { CacheRequest, recordRequest } from "./telemetry";
+
 import { Clock, Context, Effect } from "effect";
 
 import { registerResolvedSecret } from "#shared/content-security";
@@ -24,6 +26,36 @@ export type GitHubApiResponse<T> = {
   rateLimitUsed?: string;
 };
 
+export type GitHubRateLimitHeaders = {
+  readonly resource?: string;
+  readonly limit?: number;
+  readonly used?: number;
+  readonly remaining?: number;
+  readonly reset?: number;
+};
+
+const headerInteger = (headers: Headers, name: string) => {
+  const value = headers.get(name);
+  if (value === null || !/^\d+$/.test(value)) return undefined;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) ? parsed : undefined;
+};
+
+export const parseRateLimitHeaders = (headers: Headers): GitHubRateLimitHeaders => {
+  const resource = headers.get("x-ratelimit-resource");
+  const limit = headerInteger(headers, "x-ratelimit-limit");
+  const used = headerInteger(headers, "x-ratelimit-used");
+  const remaining = headerInteger(headers, "x-ratelimit-remaining");
+  const reset = headerInteger(headers, "x-ratelimit-reset");
+  return {
+    ...(resource === null ? {} : { resource }),
+    ...(limit === undefined ? {} : { limit }),
+    ...(used === undefined ? {} : { used }),
+    ...(remaining === undefined ? {} : { remaining }),
+    ...(reset === undefined ? {} : { reset }),
+  };
+};
+
 const authFailure = (message: string) =>
   new GitHubAuthError({
     message,
@@ -106,6 +138,8 @@ const githubApiAttempt = Effect.fn("gh.githubApiAttempt")(function* <T>(
   const token = yield* resolveGitHubToken();
   const url = `${GITHUB_API_ROOT}/${opts.path.replace(/^\//, "")}`;
 
+  const cached = yield* CacheRequest;
+  const started = new Date().toISOString();
   const response = yield* Effect.tryPromise({
     try: () =>
       fetch(url, {
@@ -128,8 +162,41 @@ const githubApiAttempt = Effect.fn("gh.githubApiAttempt")(function* <T>(
         retryable: true,
         hint: "Check network connectivity and VPN state, then retry.",
       }),
-  });
+  }).pipe(
+    Effect.tapError(() =>
+      recordRequest({
+        ts: started,
+        method,
+        endpoint: opts.path,
+        status: null,
+        outcome: "error",
+        resource: null,
+        used: null,
+        remaining: null,
+        reset: null,
+      }),
+    ),
+  );
 
+  const quota = parseRateLimitHeaders(response.headers);
+  yield* recordRequest({
+    ts: started,
+    method,
+    endpoint: opts.path,
+    status: response.status,
+    outcome:
+      response.status === 304
+        ? "304"
+        : response.status >= 400
+          ? "error"
+          : cached
+            ? "200"
+            : "bypass",
+    resource: quota.resource ?? null,
+    used: quota.used ?? null,
+    remaining: quota.remaining ?? null,
+    reset: quota.reset ?? null,
+  });
   const text = yield* Effect.tryPromise({
     try: () => response.text(),
     catch: (cause) =>
@@ -176,7 +243,8 @@ const githubApiAttempt = Effect.fn("gh.githubApiAttempt")(function* <T>(
   }
 
   const now = yield* Clock.currentTimeMillis;
-  const resetSeconds = Number(response.headers.get("x-ratelimit-reset"));
+  const rateLimitHeaders = parseRateLimitHeaders(response.headers);
+  const resetSeconds = rateLimitHeaders.reset ?? Number.NaN;
   const resetDelay =
     Number.isFinite(resetSeconds) && resetSeconds > 0
       ? Math.max(0, resetSeconds * 1000 - now + 1000)
@@ -200,18 +268,17 @@ const githubApiAttempt = Effect.fn("gh.githubApiAttempt")(function* <T>(
         /rate limit|secondary rate limit|abuse detection/i.test(
           apiErrorMessage(parsed, response.status),
         )));
-
   const error = new GitHubCommandError({
     message: rateLimit
-      ? `${apiErrorMessage(parsed, response.status)}; reset time: ${resetDelay === undefined ? "unavailable" : new Date(resetSeconds * 1000).toISOString()}; remaining quota: ${response.headers.get("x-ratelimit-remaining") ?? "unavailable"}`
+      ? `${apiErrorMessage(parsed, response.status)}; resource: ${rateLimitHeaders.resource ?? "unavailable"}; reset time: ${rateLimitHeaders.reset === undefined ? "unavailable" : new Date(resetSeconds * 1000).toISOString()}; remaining quota: ${rateLimitHeaders.remaining ?? "unavailable"}`
       : apiErrorMessage(parsed, response.status),
     command: `${method} ${opts.path}`,
     exitCode: response.status,
     stderr: text,
     ...(rateLimit
       ? {
-          hint: "Wait for the reset before retrying. Check the remaining quota once with the shown command; it does not consume the quota.",
-          nextCommand: "gh api rate_limit",
+          hint: "Wait for the reset before retrying. Check the named resource with the shown command; the lookup does not consume quota.",
+          nextCommand: "gh-tool rate-limit",
         }
       : {}),
     ...(response.status >= 500 || (rateLimit && canWait) ? { retryable: true } : {}),

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

@@ -1,3 +1,4 @@
+import { CacheRequest, cacheEvent, recordRequest } from "./telemetry";
 import { Console, Context, Effect } from "effect";
 import { resolveGitHubToken, SessionCredential } from "#gh/read/api";
 import { GitHubCommandError } from "#gh/errors";
@@ -86,16 +87,23 @@ export const cachedRead = <A, E, R>(opts: {
       ),
     );
     if (prepared === null) return yield* direct();
-    if (prepared.kind === "hit") return prepared.value;
+    if (prepared.kind === "hit") {
+      yield* recordRequest(cacheEvent(opts.key.op));
+      return prepared.value;
+    }
     return yield* Effect.gen(function* () {
       yield* safe(session, () => store.record(opts.key.op, "fetch"));
       const previousValid =
         prepared.previous === null
           ? false
           : yield* safe(session, () => store.canServeStale(prepared));
-      const fetched = yield* opts.fetch(
-        prepared.previous === null ? null : { ...prepared.previous, valid: previousValid === true },
-      );
+      const fetched = yield* opts
+        .fetch(
+          prepared.previous === null
+            ? null
+            : { ...prepared.previous, valid: previousValid === true },
+        )
+        .pipe(Effect.provideService(CacheRequest, true));
       if (fetched.kind === "unchanged") {
         if (prepared.previous === null)
           return yield* Effect.die(new Error("304 without a cached value"));
@@ -131,6 +139,7 @@ export const cachedRead = <A, E, R>(opts: {
             session.staleWarned = true;
             yield* Console.error(`gh-tool: served cached ${opts.key.op} (rate limited)`);
           }
+          yield* recordRequest(cacheEvent(opts.key.op));
           yield* safe(session, () => store.record(opts.key.op, "stale"));
           return prepared.previous.value;
         }),

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

@@ -2,7 +2,23 @@ import { Effect, Option } from "effect";
 import { Command, Flag } from "effect/cli";
 import { formatOption, logFormatted } from "#shared";
 import { cacheStats, clearCache } from "./cache";
-import { resolveRepo } from "./reads";
+import { getRateLimit, resolveRepo } from "./reads";
+
+export const rateLimitCommand = Command.make(
+  "rate-limit",
+  {
+    resource: Flag.String("resource").pipe(
+      Flag.withDescription("Show one GitHub rate-limit resource"),
+      Flag.optional,
+    ),
+    format: formatOption,
+  },
+  ({ resource, format }) =>
+    Effect.gen(function* () {
+      const summary = yield* getRateLimit(Option.getOrUndefined(resource));
+      yield* logFormatted(summary, format);
+    }),
+).pipe(Command.withDescription("Show GitHub API rate-limit resources and reset times"));
 
 const stats = Command.make("stats", { format: formatOption }, ({ format }) =>
   Effect.gen(function* () {

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

@@ -1,4 +1,4 @@
-import { Effect, Schema } from "effect";
+import { Clock, Effect, Result, Schema } from "effect";
 import { GitHubService } from "#gh/read/transport";
 import { GitHubCommandError } from "#gh/errors";
 import type { CheckRunAnnotation } from "#gh/types";
@@ -21,6 +21,87 @@ import {
 
 export type JobRef = { readonly id: number; readonly status: string };
 
+const RateLimitResponse = Schema.Struct({
+  resources: Schema.Record(
+    Schema.String,
+    Schema.Struct({
+      limit: Schema.Int,
+      used: Schema.Int,
+      remaining: Schema.Int,
+      reset: Schema.Int,
+    }),
+  ),
+});
+
+export type RateLimitResource = {
+  readonly limit: number;
+  readonly used: number;
+  readonly remaining: number;
+  readonly reset: string;
+  readonly secondsUntilReset: number;
+};
+
+export type RateLimitSummary = Readonly<Record<string, RateLimitResource>>;
+export type PRStatusRateLimit =
+  | Readonly<{ core: RateLimitResource; graphql: RateLimitResource }>
+  | Readonly<{ error: string }>;
+
+export const getRateLimit = Effect.fn("reads.getRateLimit")(function* (resource?: string) {
+  const gh = yield* GitHubService;
+  const response = yield* gh.runGhJson<unknown>(["api", "rate_limit"]);
+  const parsed = yield* Effect.try({
+    try: () => parsePreserving(RateLimitResponse)(response),
+    catch: (cause) =>
+      new GitHubCommandError({
+        message: `GitHub rate-limit response was invalid: ${String(cause)}`,
+        command: "gh-tool rate-limit",
+        exitCode: 1,
+        stderr: String(cause),
+      }),
+  });
+  const names = Object.keys(parsed.resources).toSorted();
+  const now = (yield* Clock.currentTimeMillis) / 1000;
+  const selected = resource === undefined ? names : [resource];
+  const entries: Array<[string, RateLimitResource]> = [];
+  for (const name of selected) {
+    const bucket = parsed.resources[name];
+    if (bucket === undefined) {
+      return yield* new GitHubCommandError({
+        message: `Unknown rate-limit resource '${name}'. Available resources: ${names.join(", ")}`,
+        command: "gh-tool rate-limit",
+        exitCode: 1,
+        stderr: "",
+        hint: "Select a resource returned by GitHub, or omit --resource to show all resources.",
+      });
+    }
+    entries.push([
+      name,
+      {
+        limit: bucket.limit,
+        used: bucket.used,
+        remaining: bucket.remaining,
+        reset: new Date(bucket.reset * 1000).toISOString(),
+        secondsUntilReset: Math.max(0, Math.ceil(bucket.reset - now)),
+      },
+    ]);
+  }
+  return Object.fromEntries(entries) satisfies RateLimitSummary;
+});
+
+export const getPRStatusRateLimit = Effect.fn("reads.getPRStatusRateLimit")(function* () {
+  const result = yield* getRateLimit().pipe(Effect.result);
+  if (Result.isFailure(result))
+    return { error: result.failure.message } satisfies PRStatusRateLimit;
+
+  const { core, graphql } = result.success;
+  if (core === undefined || graphql === undefined) {
+    return {
+      error: "GitHub rate-limit response omitted the core or graphql resource.",
+    } satisfies PRStatusRateLimit;
+  }
+  return { core, graphql } satisfies PRStatusRateLimit;
+});
+
 const completedAttemptJobs = Effect.fn("reads.completedAttemptJobs")(function* (
   repo: RepoRef,
   runId: number,
@@ -282,6 +363,8 @@ const jobIdentity = Effect.fn("reads.jobIdentity")(function* (repo: RepoRef, job
 });
 
 export const reads = {
+  getRateLimit,
+  getPRStatusRateLimit,
   completedAttemptJobs,
   jobIdentity,
   reviewGuards,

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),
+  };
+};