pr-shepherd 0.44.1 → 0.46.0

package/bin/github/gql/review-thread-comments.gql

@@ -1,4 +1,12 @@
 query ReviewThreadComments($threadId: ID!, $commentsCursor: String) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
   node(id: $threadId) {
     __typename
     ... on PullRequestReviewThread {

package/bin/github/gql/suggestion-threads.gql

@@ -1,4 +1,12 @@
 query SuggestionThreads($owner: String!, $repo: String!, $pr: Int!, $threadIds: [ID!]!) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
   repository(owner: $owner, name: $repo) {
     pullRequest(number: $pr) {
       headRefOid

package/bin/github/graphql-http.mjs

@@ -1,11 +1,14 @@
+/* eslint-disable max-lines */
 import { appendEntry, nextEntry } from "../log/log-file.mjs";
 import { formatRequestEntry, formatResponseEntry } from "../log/session.mjs";
 import { GitHubRequestError } from "./errors.mjs";
 import { withGraphQlInternalRetry } from "./graphql-internal-retry.mjs";
 import { formatGraphQlErrors, parseGraphQlPayload } from "./graphql-response.mjs";
-import { makeHeaders } from "./http-auth.mjs";
+import { makeAuthHeaders } from "./http-auth.mjs";
 import { requestWithTokenRetry } from "./http-request.mjs";
 import { parseRateLimit, parseRetryAfter, redactToken, sanitizeBody, } from "./http-utils.mjs";
+import { mergeGraphqlRateLimit, recordApiTelemetry } from "./api-telemetry.mjs";
+import { recordIntermediateResponse } from "./http-intermediate.mjs";
 const BASE_URL = "https://api.github.com";
 async function graphqlInner(query, vars, opts) {
     const url = `${BASE_URL}/graphql`;
@@ -18,13 +21,26 @@ async function graphqlInner(query, vars, opts) {
         body: { query, variables: vars },
     }));
     const t0 = performance.now();
-    const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => fetch(url, {
+    let authSource = "unknown";
+    const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => {
+        const auth = await makeAuthHeaders();
+        authSource = auth.source;
+        return fetch(url, {
+            method: "POST",
+            headers: auth.headers,
+            body: JSON.stringify({ query, variables: vars }),
+        });
+    }, t0, (response, durationMs) => recordIntermediateResponse({
+        n,
+        kind: "GraphQL",
         method: "POST",
-        headers: await makeHeaders(),
-        body: JSON.stringify({ query, variables: vars }),
-    }), t0, (status, durationMs) => appendEntry(formatResponseEntry({ n, kind: "GraphQL", method: "POST", url, status, durationMs })));
+        url,
+        response,
+        durationMs,
+        authSource,
+    }));
     const durationMs = Math.round(performance.now() - retryT0);
-    const rateLimit = parseRateLimit(res.headers);
+    const headerRateLimit = parseRateLimit(res.headers);
     const retryAfterSeconds = parseRetryAfter(res.headers);
     if (!res.ok) {
         const body = await res.text();
@@ -37,8 +53,22 @@ async function graphqlInner(query, vars, opts) {
             durationMs,
             textBody: redactToken(body),
             attempt: attempt > 1 ? attempt : undefined,
+            authSource,
+            rateLimit: headerRateLimit ?? undefined,
+            retryAfterSeconds,
         }));
-        throw new GitHubRequestError(`GitHub GraphQL request failed: ${res.status} ${sanitizeBody(body)}`, { status: res.status, rateLimit: rateLimit ?? undefined, retryAfterSeconds });
+        recordApiTelemetry({
+            kind: "GraphQL",
+            method: "POST",
+            authSource,
+            rateLimit: headerRateLimit ?? undefined,
+        });
+        throw new GitHubRequestError(`GitHub GraphQL request failed: ${res.status} ${sanitizeBody(body)}`, {
+            status: res.status,
+            rateLimit: headerRateLimit ?? undefined,
+            retryAfterSeconds,
+            authSource,
+        });
     }
     let parsed;
     try {
@@ -55,13 +85,27 @@ async function graphqlInner(query, vars, opts) {
             durationMs,
             textBody: `Invalid JSON response${detail}`,
             attempt: attempt > 1 ? attempt : undefined,
+            authSource,
+            rateLimit: headerRateLimit ?? undefined,
+            retryAfterSeconds,
         }));
+        recordApiTelemetry({
+            kind: "GraphQL",
+            method: "POST",
+            authSource,
+            rateLimit: headerRateLimit ?? undefined,
+        });
         throw new GitHubRequestError(`GitHub GraphQL response was not valid JSON${detail}`, {
             status: res.status,
-            rateLimit: rateLimit ?? undefined,
+            rateLimit: headerRateLimit ?? undefined,
             retryAfterSeconds,
+            authSource,
         });
     }
+    const parsedData = parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+        ? parsed["data"]
+        : undefined;
+    const rateLimit = mergeGraphqlRateLimit(headerRateLimit, parsedData);
     appendEntry(formatResponseEntry({
         n,
         kind: "GraphQL",
@@ -71,7 +115,16 @@ async function graphqlInner(query, vars, opts) {
         durationMs,
         body: parsed,
         attempt: attempt > 1 ? attempt : undefined,
+        authSource,
+        rateLimit: rateLimit ?? undefined,
+        retryAfterSeconds,
     }));
+    recordApiTelemetry({
+        kind: "GraphQL",
+        method: "POST",
+        authSource,
+        rateLimit: rateLimit ?? undefined,
+    });
     const payload = parseGraphQlPayload(parsed, res.status, rateLimit, retryAfterSeconds);
     if (payload.data == null) {
         const detail = formatGraphQlErrors(payload.errors);
@@ -80,6 +133,7 @@ async function graphqlInner(query, vars, opts) {
             rateLimit: rateLimit ?? undefined,
             retryAfterSeconds,
             graphqlErrors: payload.errors,
+            authSource,
         });
     }
     if (payload.errors?.length && !opts.allowPartialData) {
@@ -88,6 +142,7 @@ async function graphqlInner(query, vars, opts) {
             rateLimit: rateLimit ?? undefined,
             retryAfterSeconds,
             graphqlErrors: payload.errors,
+            authSource,
         });
     }
     if (payload.errors?.length) {

package/bin/github/http-auth.d.mts

@@ -1,4 +1,12 @@
+export type AuthSource = "GH_TOKEN" | "GITHUB_TOKEN" | "gh auth token" | "GITHUB_PERSONAL_ACCESS_TOKEN";
 export declare function _resetTokenCache(): void;
 export declare function hasCachedToken(): boolean;
 export declare function clearTokenCache(): void;
-export declare function makeHeaders(): Promise<Record<string, string>>;
+/**
+ * `extra` lets callers layer additional headers (e.g. `If-None-Match` for
+ * conditional REST requests) on top of the standard auth/version headers.
+ */
+export declare function makeAuthHeaders(extra?: Record<string, string>): Promise<{
+    headers: Record<string, string>;
+    source: AuthSource;
+}>;

package/bin/github/http-auth.mjs

@@ -3,29 +3,40 @@ import { promisify } from "node:util";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 const execFile = promisify(execFileCb);
 let _token;
+let _tokenSource;
 export function _resetTokenCache() {
     _token = undefined;
+    _tokenSource = undefined;
 }
 export function hasCachedToken() {
     return _token !== undefined;
 }
 export function clearTokenCache() {
     _token = undefined;
+    _tokenSource = undefined;
 }
 async function resolveToken() {
-    if (_token)
-        return _token;
-    const envToken = process.env["GH_TOKEN"] ?? process.env["GITHUB_TOKEN"];
-    if (envToken) {
-        _token = envToken;
-        return _token;
+    if (_token && _tokenSource)
+        return { token: _token, source: _tokenSource };
+    const ghToken = process.env["GH_TOKEN"];
+    if (ghToken) {
+        _token = ghToken;
+        _tokenSource = "GH_TOKEN";
+        return { token: _token, source: _tokenSource };
+    }
+    const githubToken = process.env["GITHUB_TOKEN"];
+    if (githubToken) {
+        _token = githubToken;
+        _tokenSource = "GITHUB_TOKEN";
+        return { token: _token, source: _tokenSource };
     }
     try {
         const { stdout } = await execFile("gh", ["auth", "token"]);
         const token = stdout.trim();
         if (token) {
             _token = token;
-            return _token;
+            _tokenSource = "gh auth token";
+            return { token: _token, source: _tokenSource };
         }
     }
     catch {
@@ -34,16 +45,26 @@ async function resolveToken() {
     const codexToken = process.env["GITHUB_PERSONAL_ACCESS_TOKEN"];
     if (codexToken) {
         _token = codexToken;
-        return _token;
+        _tokenSource = "GITHUB_PERSONAL_ACCESS_TOKEN";
+        return { token: _token, source: _tokenSource };
     }
     throw new ShepherdError("No GitHub token found. Set GH_TOKEN, GITHUB_TOKEN, or GITHUB_PERSONAL_ACCESS_TOKEN, or run `gh auth login`.", EXIT.NOPERM);
 }
-export async function makeHeaders() {
+/**
+ * `extra` lets callers layer additional headers (e.g. `If-None-Match` for
+ * conditional REST requests) on top of the standard auth/version headers.
+ */
+export async function makeAuthHeaders(extra) {
+    const { token, source } = await resolveToken();
     return {
-        Authorization: `Bearer ${await resolveToken()}`,
-        Accept: "application/vnd.github+json",
-        "X-GitHub-Api-Version": "2022-11-28",
-        "User-Agent": "pr-shepherd",
-        "Content-Type": "application/json",
+        source,
+        headers: {
+            Authorization: `Bearer ${token}`,
+            Accept: "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+            "User-Agent": "pr-shepherd",
+            "Content-Type": "application/json",
+            ...extra,
+        },
     };
 }

package/bin/github/http-intermediate.d.mts

@@ -0,0 +1,9 @@
+export declare function recordIntermediateResponse(opts: {
+    n: number;
+    kind: "GraphQL" | "REST" | "restText";
+    method: string;
+    url: string;
+    response: Response;
+    durationMs: number;
+    authSource: string;
+}): void;

package/bin/github/http-intermediate.mjs

@@ -0,0 +1,20 @@
+import { appendEntry } from "../log/log-file.mjs";
+import { formatResponseEntry } from "../log/session.mjs";
+import { recordApiTelemetry } from "./api-telemetry.mjs";
+import { parseRateLimit, parseRetryAfter } from "./http-utils.mjs";
+export function recordIntermediateResponse(opts) {
+    const rateLimit = parseRateLimit(opts.response.headers) ?? undefined;
+    const retryAfterSeconds = parseRetryAfter(opts.response.headers);
+    appendEntry(formatResponseEntry({
+        ...opts,
+        status: opts.response.status,
+        rateLimit,
+        retryAfterSeconds,
+    }));
+    recordApiTelemetry({
+        kind: opts.kind === "GraphQL" ? "GraphQL" : "REST",
+        method: opts.method,
+        authSource: opts.authSource,
+        rateLimit,
+    });
+}

package/bin/github/http-request.d.mts

@@ -1,4 +1,4 @@
-type RetryLogFn = (status: number, durationMs: number) => void;
+type RetryLogFn = (response: Response, durationMs: number) => void;
 export declare function requestWithTokenRetry(fn: () => Promise<Response>, t0: number, onIntermediate?: RetryLogFn): Promise<{
     res: Response;
     attempt: number;

package/bin/github/http-request.mjs

@@ -23,7 +23,7 @@ async function fetchWithTransportRetry(fn) {
 export async function requestWithTokenRetry(fn, t0, onIntermediate) {
     const res = await fetchWithTransportRetry(fn);
     if (res.status === 401 && hasCachedToken()) {
-        onIntermediate?.(401, Math.round(performance.now() - t0));
+        onIntermediate?.(res, Math.round(performance.now() - t0));
         try {
             await res.arrayBuffer();
         }

package/bin/github/http-utils.d.mts

@@ -3,6 +3,12 @@ export interface RateLimitInfo {
     remaining: number;
     limit: number;
     resetAt: number;
+    used?: number;
+    resource?: string;
+    /** Exact GraphQL query cost when the operation selected rateLimit.cost. */
+    cost?: number;
+    /** Exact GraphQL node count when the operation selected rateLimit.nodeCount. */
+    nodeCount?: number;
 }
 export declare function sanitizeBody(body: string): string;
 export declare function redactToken(body: string): string;

package/bin/github/http-utils.mjs

@@ -45,7 +45,16 @@ export function parseRateLimit(headers) {
     const limit = Number(lRaw);
     const resetAt = Number(tRaw);
     if (Number.isFinite(remaining) && Number.isFinite(limit) && Number.isFinite(resetAt)) {
-        return { remaining, limit, resetAt };
+        const usedRaw = headers.get("x-ratelimit-used");
+        const used = usedRaw === null ? undefined : Number(usedRaw);
+        const resource = headers.get("x-ratelimit-resource") ?? undefined;
+        return {
+            remaining,
+            limit,
+            resetAt,
+            ...(Number.isFinite(used) && { used }),
+            ...(resource !== undefined && resource !== "" && { resource }),
+        };
     }
     return null;
 }

package/bin/github/rest-http.d.mts

@@ -1,7 +1,22 @@
+import { type StateKey } from "../state/rest-cache.mts";
 import { type RateLimitInfo } from "./http-utils.mts";
 export interface RestResult<T = unknown> {
     data: T;
     rateLimit?: RateLimitInfo;
 }
+/**
+ * Enables `If-None-Match` conditional requests for a REST call, backed by a
+ * per-PR on-disk cache (see `src/state/rest-cache.mts`). A 304 response
+ * returns the cached body and — unlike a normal request — does not consume
+ * the primary REST rate-limit quota.
+ */
+export interface RestRequestOptions {
+    conditional?: {
+        key: StateKey;
+        /** Logical cache name; must be unique per distinct resource + page. */
+        name: string;
+        headSha?: string;
+    };
+}
 export declare function rest<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
-export declare function restWithRateLimit<T = unknown>(method: string, path: string, body?: unknown): Promise<RestResult<T>>;
+export declare function restWithRateLimit<T = unknown>(method: string, path: string, body?: unknown, opts?: RestRequestOptions): Promise<RestResult<T>>;

package/bin/github/rest-http.mjs

@@ -1,9 +1,13 @@
+/* eslint-disable max-lines */
 import { appendEntry, nextEntry } from "../log/log-file.mjs";
 import { formatRequestEntry, formatResponseEntry } from "../log/session.mjs";
+import { loadEtagEntry, storeEtagEntry } from "../state/rest-cache.mjs";
 import { GitHubRequestError } from "./errors.mjs";
-import { makeHeaders } from "./http-auth.mjs";
+import { makeAuthHeaders } from "./http-auth.mjs";
 import { requestWithTokenRetry } from "./http-request.mjs";
 import { parseRateLimit, parseRetryAfter, redactToken, sanitizeBody, } from "./http-utils.mjs";
+import { recordApiTelemetry } from "./api-telemetry.mjs";
+import { recordIntermediateResponse } from "./http-intermediate.mjs";
 const BASE_URL = "https://api.github.com";
 const SAFE_GITHUB_REST_PATH = /^\/[A-Za-z0-9._~!$&'()*+,;=:@%/?-]*$/;
 function githubApiUrl(path) {
@@ -24,19 +28,55 @@ export async function rest(method, path, body) {
     const { data } = await restWithRateLimit(method, path, body);
     return data;
 }
-export async function restWithRateLimit(method, path, body) {
+export async function restWithRateLimit(method, path, body, opts) {
     const url = githubApiUrl(path);
     const n = nextEntry();
     appendEntry(formatRequestEntry({ n, kind: "REST", method, url, body }));
     const t0 = performance.now();
-    const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => fetch(url, {
+    let authSource = "unknown";
+    const cached = opts?.conditional
+        ? await loadEtagEntry(opts.conditional.key, opts.conditional.name)
+        : null;
+    const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => {
+        const auth = await makeAuthHeaders(cached ? { "If-None-Match": cached.etag } : undefined);
+        authSource = auth.source;
+        return fetch(url, {
+            method,
+            headers: auth.headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+    }, t0, (response, durationMs) => recordIntermediateResponse({
+        n,
+        kind: "REST",
         method,
-        headers: await makeHeaders(),
-        body: body !== undefined ? JSON.stringify(body) : undefined,
-    }), t0, (status, durationMs) => appendEntry(formatResponseEntry({ n, kind: "REST", method, url, status, durationMs })));
+        url,
+        response,
+        durationMs,
+        authSource,
+    }));
     const durationMs = Math.round(performance.now() - retryT0);
-    const ct = res.headers.get("content-type") ?? "";
     const rateLimit = parseRateLimit(res.headers) ?? undefined;
+    const retryAfterSeconds = parseRetryAfter(res.headers);
+    // A 304 is not `res.ok` but is not an error either — and critically, does
+    // not consume the primary REST request quota — so it must be handled
+    // before the !res.ok branch below.
+    if (res.status === 304 && cached) {
+        appendEntry(formatResponseEntry({
+            n,
+            kind: "REST",
+            method,
+            url,
+            status: res.status,
+            durationMs,
+            attempt: attempt > 1 ? attempt : undefined,
+            authSource,
+            rateLimit,
+            retryAfterSeconds,
+        }));
+        recordApiTelemetry({ kind: "REST", method, authSource, rateLimit });
+        return { data: cached.body, rateLimit };
+    }
+    const ct = res.headers.get("content-type") ?? "";
     if (!res.ok) {
         const text = await res.text();
         appendEntry(formatResponseEntry({
@@ -48,11 +88,16 @@ export async function restWithRateLimit(method, path, body) {
             durationMs,
             textBody: redactToken(text),
             attempt: attempt > 1 ? attempt : undefined,
+            authSource,
+            rateLimit,
+            retryAfterSeconds,
         }));
+        recordApiTelemetry({ kind: "REST", method, authSource, rateLimit });
         throw new GitHubRequestError(`GitHub REST ${method} ${path} failed: ${res.status} ${sanitizeBody(text)}`, {
             status: res.status,
             rateLimit,
-            retryAfterSeconds: parseRetryAfter(res.headers),
+            retryAfterSeconds,
+            authSource,
         });
     }
     if (ct.includes("application/json")) {
@@ -67,7 +112,21 @@ export async function restWithRateLimit(method, path, body) {
             contentType: ct,
             body: json,
             attempt: attempt > 1 ? attempt : undefined,
+            authSource,
+            rateLimit,
+            retryAfterSeconds,
         }));
+        recordApiTelemetry({ kind: "REST", method, authSource, rateLimit });
+        if (opts?.conditional) {
+            const etag = res.headers.get("etag");
+            if (etag) {
+                await storeEtagEntry(opts.conditional.key, opts.conditional.name, {
+                    etag,
+                    body: json,
+                    ...(opts.conditional.headSha !== undefined && { headSha: opts.conditional.headSha }),
+                });
+            }
+        }
         return { data: json, rateLimit };
     }
     appendEntry(formatResponseEntry({
@@ -79,6 +138,10 @@ export async function restWithRateLimit(method, path, body) {
         durationMs,
         contentType: ct || undefined,
         attempt: attempt > 1 ? attempt : undefined,
+        authSource,
+        rateLimit,
+        retryAfterSeconds,
     }));
+    recordApiTelemetry({ kind: "REST", method, authSource, rateLimit });
     return { data: undefined, rateLimit };
 }

package/bin/github/rest-text.mjs

@@ -1,19 +1,45 @@
 import { appendEntry, nextEntry } from "../log/log-file.mjs";
 import { formatRequestEntry, formatResponseEntry } from "../log/session.mjs";
 import { GitHubRequestError } from "./errors.mjs";
-import { makeHeaders } from "./http-auth.mjs";
+import { makeAuthHeaders } from "./http-auth.mjs";
 import { requestWithTokenRetry } from "./http-request.mjs";
 import { parseRateLimit, parseRetryAfter, redactUrl, sanitizeBody } from "./http-utils.mjs";
+import { recordApiTelemetry } from "./api-telemetry.mjs";
+import { recordIntermediateResponse } from "./http-intermediate.mjs";
 const BASE_URL = "https://api.github.com";
 export async function restText(path) {
     const url = `${BASE_URL}${path}`;
     const n = nextEntry();
     appendEntry(formatRequestEntry({ n, kind: "restText", method: "GET", url }));
     const t0 = performance.now();
-    const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => fetch(url, { method: "GET", headers: await makeHeaders(), redirect: "manual" }), t0, (status, durationMs) => appendEntry(formatResponseEntry({ n, kind: "restText", method: "GET", url, status, durationMs })));
+    let authSource = "unknown";
+    const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => {
+        const auth = await makeAuthHeaders();
+        authSource = auth.source;
+        return fetch(url, { method: "GET", headers: auth.headers, redirect: "manual" });
+    }, t0, (response, durationMs) => recordIntermediateResponse({
+        n,
+        kind: "restText",
+        method: "GET",
+        url,
+        response,
+        durationMs,
+        authSource,
+    }));
     const durationMs = Math.round(performance.now() - retryT0);
+    const rateLimit = parseRateLimit(res.headers) ?? undefined;
+    const retryAfterSeconds = parseRetryAfter(res.headers);
+    recordApiTelemetry({ kind: "REST", method: "GET", authSource, rateLimit });
     if ([301, 302, 307, 308].includes(res.status)) {
-        const redirected = await followRestTextRedirect(res, { n, url, durationMs, attempt });
+        const redirected = await followRestTextRedirect(res, {
+            n,
+            url,
+            durationMs,
+            attempt,
+            authSource,
+            rateLimit,
+            retryAfterSeconds,
+        });
         if (redirected !== null)
             return redirected;
     }
@@ -27,11 +53,15 @@ export async function restText(path) {
             status: res.status,
             durationMs,
             attempt: attempt > 1 ? attempt : undefined,
+            authSource,
+            rateLimit,
+            retryAfterSeconds,
         }));
         throw new GitHubRequestError(`GitHub REST GET ${path} failed: ${res.status} ${sanitizeBody(text)}`, {
             status: res.status,
-            rateLimit: parseRateLimit(res.headers) ?? undefined,
-            retryAfterSeconds: parseRetryAfter(res.headers),
+            rateLimit,
+            retryAfterSeconds,
+            authSource,
         });
     }
     appendEntry(formatResponseEntry({
@@ -43,6 +73,9 @@ export async function restText(path) {
         durationMs,
         contentLength: parseContentLength(res.headers),
         attempt: attempt > 1 ? attempt : undefined,
+        authSource,
+        rateLimit,
+        retryAfterSeconds,
     }));
     return res.text();
 }
@@ -55,6 +88,9 @@ async function followRestTextRedirect(res, entry) {
         status: res.status,
         durationMs: entry.durationMs,
         attempt: entry.attempt > 1 ? entry.attempt : undefined,
+        authSource: entry.authSource,
+        rateLimit: entry.rateLimit,
+        retryAfterSeconds: entry.retryAfterSeconds,
     }));
     const location = res.headers.get("location");
     if (!location)

package/bin/index.mjs

@@ -9,6 +9,7 @@
  */
 import { main } from "./cli-parser.mjs";
 import { errorToExitCode } from "./exit-codes.mjs";
+import { formatCliError } from "./cli/error-format.mjs";
 function formatCause(cause, seen = new Set(), depth = 0) {
     if (depth > 5 || seen.has(cause))
         return "[circular or deep cause chain]";
@@ -21,7 +22,7 @@ function formatCause(cause, seen = new Set(), depth = 0) {
     return String(cause);
 }
 main(process.argv).catch((err) => {
-    const msg = err instanceof Error ? err.message : String(err);
+    const msg = formatCliError(err);
     const causeStr = err instanceof Error && err.cause != null ? formatCause(err.cause) : null;
     process.stderr.write(`pr-shepherd error: ${msg}${causeStr !== null ? ` (cause: ${causeStr})` : ""}\n`);
     process.exit(errorToExitCode(err));

package/bin/log/session.d.mts

@@ -24,6 +24,17 @@ interface HttpResponseEntry {
     contentLength?: number;
     /** Set on 401-retry invocations. */
     attempt?: number;
+    authSource?: string;
+    rateLimit?: {
+        resource?: string;
+        limit: number;
+        used?: number;
+        remaining: number;
+        resetAt: number;
+        cost?: number;
+        nodeCount?: number;
+    };
+    retryAfterSeconds?: number;
 }
 export declare function formatRequestEntry(entry: HttpRequestEntry): string;
 export declare function formatResponseEntry(entry: HttpResponseEntry): string;

package/bin/log/session.mjs

@@ -70,6 +70,28 @@ export function formatResponseEntry(entry) {
             ? `restText response — ${entry.status}${attempt} · ${entry.durationMs}ms`
             : `REST response — ${entry.status}${attempt} · ${entry.durationMs}ms`;
     let out = `### #${entry.n} ${label} · ${ts}\n\n`;
+    if (entry.authSource !== undefined)
+        out += `auth-source: \`${entry.authSource}\`\n`;
+    if (entry.rateLimit !== undefined) {
+        const used = entry.rateLimit.used !== undefined ? ` · used ${entry.rateLimit.used}` : "";
+        const resource = entry.rateLimit.resource ?? "unknown";
+        out += `rate-limit: \`${resource}\` · remaining ${entry.rateLimit.remaining}/${entry.rateLimit.limit}${used} · reset ${new Date(entry.rateLimit.resetAt * 1000).toISOString()}\n`;
+        if (entry.rateLimit.cost !== undefined || entry.rateLimit.nodeCount !== undefined) {
+            const parts = [
+                entry.rateLimit.cost !== undefined ? `cost ${entry.rateLimit.cost}` : null,
+                entry.rateLimit.nodeCount !== undefined ? `nodes ${entry.rateLimit.nodeCount}` : null,
+            ].filter(Boolean);
+            out += `graphql-query: ${parts.join(" · ")}\n`;
+        }
+    }
+    if (entry.retryAfterSeconds !== undefined) {
+        out += `retry-after: ${entry.retryAfterSeconds}s\n`;
+    }
+    if (entry.authSource !== undefined ||
+        entry.rateLimit !== undefined ||
+        entry.retryAfterSeconds !== undefined) {
+        out += "\n";
+    }
     if (entry.kind === "restText") {
         if (entry.contentLength !== undefined) {
             out += `content-length: ${entry.contentLength} bytes (body not logged)\n\n`;