hanzoai 8.5.621 → 8.5.640

package/src/models/auto-review-in.ts

@@ -0,0 +1,42 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Hanzo Cloud API
+ * The Hanzo Cloud API as a customer calls it: every operation under /v1/ except the operator\'s admin product, relay routes, legacy spellings and capabilities still reached by flag. Tagged by product: the first path segment after /v1/.
+ *
+ * The version of the OpenAPI document: v1
+ * 
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+
+
+/**
+ * 
+ * @export
+ * @interface AutoReviewIn
+ */
+export interface AutoReviewIn {
+    /**
+     * ID is the automation, and Run its run in review, from the path.
+     * @type {string}
+     * @memberof AutoReviewIn
+     */
+    'id'?: string;
+    /**
+     * Post posts it when true and discards it when false.
+     * @type {boolean}
+     * @memberof AutoReviewIn
+     */
+    'post'?: boolean;
+    /**
+     * 
+     * @type {string}
+     * @memberof AutoReviewIn
+     */
+    'run'?: string;
+}
+

package/src/models/git-workspace-view.ts

@@ -0,0 +1,42 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Hanzo Cloud API
+ * The Hanzo Cloud API as a customer calls it: every operation under /v1/ except the operator\'s admin product, relay routes, legacy spellings and capabilities still reached by flag. Tagged by product: the first path segment after /v1/.
+ *
+ * The version of the OpenAPI document: v1
+ * 
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+
+
+/**
+ * 
+ * @export
+ * @interface GitWorkspaceView
+ */
+export interface GitWorkspaceView {
+    /**
+     * Login is the caller\'s forge account in a made workspace.
+     * @type {string}
+     * @memberof GitWorkspaceView
+     */
+    'login'?: string;
+    /**
+     * Made says the platform made it for the org; false is the estate\'s.
+     * @type {boolean}
+     * @memberof GitWorkspaceView
+     */
+    'made'?: boolean;
+    /**
+     * Owner is the forge namespace.
+     * @type {string}
+     * @memberof GitWorkspaceView
+     */
+    'owner'?: string;
+}
+

package/src/models/iam-user.ts

@@ -777,7 +777,7 @@ export interface IamUser {
      */
     'name'?: string;
     /**
-     * 
+     * NameKey is Fold(Name), derived on every save (BeforeCreate, BeforeUpdate) and on every open for a row saved without it (store.Prepare): the indexed key a case-insensitive username lookup reads (store.GetUserByName). It is always written, empty or not, so a row that has been keyed is never mistaken for one that has not.
      * @type {string}
      * @memberof IamUser
      */

package/src/models/index.ts

@@ -105,14 +105,16 @@ export * from './ai-anthropic-response';
 export * from './ai-anthropic-tool';
 export * from './ai-anthropic-usage';
 export * from './ai-cache-writes';
+export * from './ai-chat';
+export * from './ai-chat-in';
 export * from './ai-class';
 export * from './ai-cost-stats';
+export * from './ai-decide-in';
+export * from './ai-decision';
 export * from './ai-decision-sides';
-export * from './ai-decision-sides-false';
 export * from './ai-decisions-action';
 export * from './ai-decisions-answer';
 export * from './ai-decisions-choice';
-export * from './ai-decisions-choice-criteria-value';
 export * from './ai-decisions-noul';
 export * from './ai-decisions-question';
 export * from './ai-decisions-reason';
@@ -134,13 +136,16 @@ export * from './ai-limits';
 export * from './ai-limits-set';
 export * from './ai-mcpapp';
 export * from './ai-mcpsurface';
+export * from './ai-model';
 export * from './ai-model-access-info';
 export * from './ai-model-info';
 export * from './ai-model-list';
 export * from './ai-model-pricing-info';
 export * from './ai-model-providers';
+export * from './ai-models';
 export * from './ai-panel-judge';
 export * from './ai-paused';
+export * from './ai-price';
 export * from './ai-provider-usage';
 export * from './ai-provider-usage-model-spend';
 export * from './ai-provider-usage-series-point';
@@ -150,6 +155,7 @@ export * from './ai-rank-usage';
 export * from './ai-ranked-doc';
 export * from './ai-ranked-text';
 export * from './ai-ranking';
+export * from './ai-receipt';
 export * from './ai-response';
 export * from './ai-responses-input-details';
 export * from './ai-responses-output-details';
@@ -162,6 +168,7 @@ export * from './ai-router-stats';
 export * from './ai-routing-edit';
 export * from './ai-routing-probe';
 export * from './ai-routing-proposal';
+export * from './ai-routing-reward-request';
 export * from './ai-routing-reward-result';
 export * from './ai-routing-view';
 export * from './ai-stats-window';
@@ -217,7 +224,9 @@ export * from './auto-flow-version';
 export * from './auto-last-run';
 export * from './auto-patch-flow-in';
 export * from './auto-populated-flow';
+export * from './auto-post-result';
 export * from './auto-prop-spec';
+export * from './auto-review-in';
 export * from './auto-run-handle';
 export * from './auto-run-in';
 export * from './auto-run-page';
@@ -919,6 +928,7 @@ export * from './git-workflow-list';
 export * from './git-workflow-run';
 export * from './git-workflow-runs';
 export * from './git-workflow-view';
+export * from './git-workspace-view';
 export * from './grants';
 export * from './graph';
 export * from './graph-graph-answer-in';
@@ -2684,6 +2694,8 @@ export * from './sync-sync-view';
 export * from './tag-config';
 export * from './task';
 export * from './task-board-view';
+export * from './task-comment';
+export * from './task-comment-list';
 export * from './task-issue-edit';
 export * from './task-issue-hit';
 export * from './task-issue-hits';

package/src/models/provider-github-import-out.ts

@@ -20,6 +20,12 @@
  * @interface ProviderGithubImportOut
  */
 export interface ProviderGithubImportOut {
+    /**
+     * Codebases are the names they take in the org\'s code workspace, in the same order: poll GET /v1/git/repos for each to appear.
+     * @type {Array<string>}
+     * @memberof ProviderGithubImportOut
+     */
+    'codebases'?: Array<string>;
     /**
      * Queued is how many repositories were handed to the background importer.
      * @type {number}

package/src/models/provider-github-repo-item.ts

@@ -20,6 +20,12 @@
  * @interface ProviderGithubRepoItem
  */
 export interface ProviderGithubRepoItem {
+    /**
+     * Codebase is the name it has in the org\'s code workspace once brought in (POST /v1/provider/github/repos/import): listed by GET /v1/git/repos when it is there.
+     * @type {string}
+     * @memberof ProviderGithubRepoItem
+     */
+    'codebase'?: string;
     /**
      * DefaultBranch is the branch GitHub opens it on.
      * @type {string}

package/src/models/task-comment-list.ts

@@ -0,0 +1,39 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Hanzo Cloud API
+ * The Hanzo Cloud API as a customer calls it: every operation under /v1/ except the operator\'s admin product, relay routes, legacy spellings and capabilities still reached by flag. Tagged by product: the first path segment after /v1/.
+ *
+ * The version of the OpenAPI document: v1
+ * 
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+
+// May contain unused imports in some cases
+// @ts-ignore
+import type { TaskComment } from './task-comment';
+
+/**
+ * 
+ * @export
+ * @interface TaskCommentList
+ */
+export interface TaskCommentList {
+    /**
+     * Data is the conversation. Empty is an empty array, never null.
+     * @type {Array<TaskComment>}
+     * @memberof TaskCommentList
+     */
+    'data'?: Array<TaskComment>;
+    /**
+     * Home is the GitHub repository (owner/name) the issue lives on when its board mirrors one; its conversation is read there, and Data is then empty.
+     * @type {string}
+     * @memberof TaskCommentList
+     */
+    'home'?: string;
+}
+

package/src/models/task-comment.ts

@@ -0,0 +1,48 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Hanzo Cloud API
+ * The Hanzo Cloud API as a customer calls it: every operation under /v1/ except the operator\'s admin product, relay routes, legacy spellings and capabilities still reached by flag. Tagged by product: the first path segment after /v1/.
+ *
+ * The version of the OpenAPI document: v1
+ * 
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+
+
+/**
+ * 
+ * @export
+ * @interface TaskComment
+ */
+export interface TaskComment {
+    /**
+     * Author is who wrote it: their name, else their forge login.
+     * @type {string}
+     * @memberof TaskComment
+     */
+    'author'?: string;
+    /**
+     * Body is what was written, as markdown.
+     * @type {string}
+     * @memberof TaskComment
+     */
+    'body'?: string;
+    /**
+     * CreatedAt is when it was written, RFC 3339.
+     * @type {string}
+     * @memberof TaskComment
+     */
+    'createdAt'?: string;
+    /**
+     * ID is the forge\'s id for the comment.
+     * @type {number}
+     * @memberof TaskComment
+     */
+    'id'?: number;
+}
+

package/src/transport.ts

@@ -0,0 +1,190 @@
+// transport — the Configuration this package exports.
+//
+// It is the generated Configuration plus one thing: a request a generated *Api
+// class sends with it that comes back 402 or 429 with a usage refusal in the
+// body throws that refusal's typed error (usage.ts). Every other answer passes
+// through untouched — a 400 is still the AxiosError it was.
+//
+// The error path is axios's own: one response interceptor on the axios instance
+// the generated classes use by default, installed by the first Configuration
+// built. It acts only on requests marked as this package's, and the mark rides
+// in `baseOptions`, which the generated client spreads into every request it
+// builds — so the caller's other axios traffic, adapters and transforms are left
+// as they were. An axios instance passed as an *Api's third argument has
+// interceptors of its own, and a refusal through it stays an AxiosError.
+//
+// hanzo.ts exports this class under the generated one's name, so
+// `new Configuration({ accessToken })` from 'hanzoai' is this one, and so is
+// `Client.configuration`.
+
+import axios, { type AxiosError, type AxiosResponse } from 'axios';
+import { Configuration as Generated, type ConfigurationParameters } from './configuration';
+import { header, limited } from './usage';
+
+/**
+ * The request option that marks a request as sent with this Configuration. Its
+ * value is this module's own interceptor, so two copies of the package sharing
+ * one axios each type only their own requests, with their own classes.
+ */
+const MARK = 'hanzoUsage';
+
+/** A stream body is read this far at most; a refusal is a few hundred bytes of JSON. */
+const CAP = 1 << 16;
+
+type Manager = { handlers?: Array<{ rejected?: unknown } | null> };
+
+export class Configuration extends Generated {
+  constructor(param: ConfigurationParameters = {}) {
+    super(param);
+    this.baseOptions = { ...this.baseOptions, [MARK]: refused };
+    // Checked, not remembered: a test teardown's `interceptors.response.clear()`
+    // removes it, and the next Configuration puts it back.
+    const installed = (axios.interceptors.response as unknown as Manager).handlers?.some((h) => h?.rejected === refused);
+    if (!installed) axios.interceptors.response.use(undefined, refused);
+  }
+}
+
+/** Rethrow a marked 402 or 429 as the usage refusal its body names; anything else as it came. */
+async function refused(err: unknown): Promise<never> {
+  const e = err as AxiosError | undefined;
+  const res = e?.response;
+  const config = e?.config as (Record<string, unknown> & { signal?: unknown; timeout?: number }) | undefined;
+  if (!res || config?.[MARK] !== refused || (res.status !== 402 && res.status !== 429)) throw err;
+  let parsed: unknown;
+  try {
+    parsed = await body(res, config);
+  } catch {
+    // A body that cannot be read names nothing: the answer is the one axios gave.
+    throw err;
+  }
+  throw limited(res.status, parsed, header(res.headers, 'x-request-id'), err) ?? err;
+}
+
+/**
+ * The body as JSON where it is JSON. axios hands it over parsed by default and
+ * raw when the caller asked for a buffer, a blob or a stream. A stream is read
+ * only when it says it is JSON — a refusal is, an event stream never is — at
+ * most CAP bytes, no longer than the caller's signal and timeout allow, and
+ * without taking it from the caller: `res.data` is left holding a stream of the
+ * same family that yields every byte again.
+ */
+async function body(res: AxiosResponse, config: { signal?: unknown; timeout?: number }): Promise<unknown> {
+  let data: unknown = res.data;
+  if (web(data) || node(data)) {
+    if (!/json/i.test(header(res.headers, 'content-type') ?? '')) return undefined;
+    const read = web(data) ? peekWeb(data, config) : peekNode(data, config);
+    const { text, again } = await read;
+    res.data = again;
+    data = text;
+  } else if (typeof Blob !== 'undefined' && data instanceof Blob) {
+    data = await data.text();
+  } else if (data instanceof ArrayBuffer || ArrayBuffer.isView(data)) {
+    data = new TextDecoder().decode(data as Uint8Array);
+  }
+  if (typeof data !== 'string') return data;
+  try {
+    return JSON.parse(data) as unknown;
+  } catch {
+    return data;
+  }
+}
+
+/** A WHATWG stream: the fetch and xhr adapters' `responseType: 'stream'`. */
+const web = (v: unknown): v is ReadableStream<Uint8Array> =>
+  typeof (v as ReadableStream | null)?.tee === 'function' && typeof (v as ReadableStream).getReader === 'function';
+
+/** A Node stream: the http adapter's `responseType: 'stream'`. */
+type Stream = AsyncIterable<unknown> & { pipe: unknown; constructor: { from(source: AsyncIterable<unknown>): unknown } };
+const node = (v: unknown): v is Stream =>
+  typeof (v as Stream | null)?.pipe === 'function' &&
+  typeof (v as Stream)[Symbol.asyncIterator] === 'function' &&
+  typeof (v as Stream).constructor?.from === 'function';
+
+/** Read a WHATWG stream through `peek`, and hand back a WHATWG stream that replays it. */
+async function peekWeb(stream: ReadableStream<Uint8Array>, config: { signal?: unknown; timeout?: number }) {
+  const reader = stream.getReader();
+  const { text, rest } = await peek(() => reader.read(), config);
+  const again = new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      const step = await rest.next();
+      if (step.done) controller.close();
+      else controller.enqueue(step.value as Uint8Array);
+    },
+    cancel: (reason) => reader.cancel(reason),
+  });
+  return { text, again };
+}
+
+/** Read a Node stream through `peek`; `Readable.from` comes off its own constructor, so no bundle gains node:stream. */
+async function peekNode(stream: Stream, config: { signal?: unknown; timeout?: number }) {
+  const it = stream[Symbol.asyncIterator]();
+  const { text, rest } = await peek(() => it.next(), config);
+  return { text, again: stream.constructor.from(rest) };
+}
+
+const STOP = Symbol('stop');
+
+/**
+ * Read chunks until the end, CAP bytes, the caller's abort or its timeout,
+ * whichever comes first. `text` is the whole body only when the end was
+ * reached — anything less names no refusal. `rest` yields every chunk read and
+ * then whatever is left, including a read still in flight and a failure, so the
+ * caller's stream loses nothing.
+ */
+async function peek(next: () => Promise<IteratorResult<unknown>>, config: { signal?: unknown; timeout?: number }) {
+  const seen: unknown[] = [];
+  const decoder = new TextDecoder();
+  let text = '';
+  let done = false;
+  let failed: { error: unknown } | undefined;
+  let pending: Promise<IteratorResult<unknown>> | undefined;
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let quit: (() => void) | undefined;
+  const stop = new Promise<typeof STOP>((resolve) => {
+    quit = () => resolve(STOP);
+    const signal = config.signal as AbortSignal | undefined;
+    if (signal && typeof signal.addEventListener === 'function') {
+      if (signal.aborted) resolve(STOP);
+      signal.addEventListener('abort', () => resolve(STOP), { once: true });
+    }
+    if (config.timeout && config.timeout > 0) timer = setTimeout(() => resolve(STOP), config.timeout);
+  });
+
+  try {
+    while (text.length < CAP) {
+      pending = next();
+      const step = await Promise.race([pending, stop]);
+      if (step === STOP) break;
+      pending = undefined;
+      if (step.done) {
+        done = true;
+        break;
+      }
+      seen.push(step.value);
+      text += typeof step.value === 'string' ? step.value : decoder.decode(step.value as Uint8Array, { stream: true });
+    }
+  } catch (error) {
+    pending = undefined;
+    failed = { error };
+  } finally {
+    if (timer) clearTimeout(timer);
+    quit?.();
+  }
+
+  async function* rest() {
+    yield* seen;
+    if (failed) throw failed.error;
+    if (pending) {
+      const step = await pending;
+      if (step.done) return;
+      yield step.value;
+    }
+    while (!done) {
+      const step = await next();
+      if (step.done) return;
+      yield step.value;
+    }
+  }
+  return { text: done ? text : undefined, rest: rest() };
+}

package/src/usage.ts

@@ -0,0 +1,203 @@
+// usage — how a priced request was paid for, and the refusals when it cannot be.
+//
+// Every AI answer says where the caller's plan stands in six headers, never a
+// figure: X-Hanzo-Usage (ok | near | limited), -Usage-Class (premium | ours |
+// free), -Paid-By (plan | credits | free), -Fallback (the model that answered
+// instead), -Served (the Hanzo SKU that answered) and -Usage-Reason (the refusal
+// code that caused a fallback). `readUsage` reads them off whatever headers the
+// caller holds.
+//
+// A request nothing may pay for is refused in the OpenAI envelope,
+//
+//   {"error": {"message", "type", "code", "class"?, "model"?, "fallback"?,
+//              "resets_at"?, "upgrade_url"?, "actions"?}}
+//
+// and six codes in it are six different facts with six different ways out, so
+// each is a class: a caller tells them apart with `instanceof`, never by parsing
+// the sentence. The names are the Python and Go SDKs' names. Both transports
+// throw them from the error path they already had — an axios response
+// interceptor for the generated client (transport.ts) and the six capabilities'
+// Fault (answer.ts) — through `limited`, the one place a body becomes one.
+
+import { list, obj, type Obj } from './read';
+
+/** One way out of a usage refusal, in the order to offer them. */
+export interface UsageAction {
+  /** upgrade | switch | credits | topup. */
+  kind: string;
+  /** The words to put on the button. */
+  label?: string;
+  /** Where to go: the pay page, or `/v1/ai/limits` for "continue with credits". */
+  url?: string;
+  /** The plan an `upgrade` moves to. */
+  plan?: string;
+  /** The model a `switch` moves to. */
+  model?: string;
+}
+
+/** A string the server sent, or undefined where it sent none — never "". */
+const text = (v: unknown): string | undefined => (typeof v === 'string' && v !== '' ? v : undefined);
+
+/** An RFC 3339 instant, or undefined where none was sent or it does not parse. */
+const instant = (v: unknown): Date | undefined => {
+  const s = text(v);
+  if (!s) return undefined;
+  const d = new Date(s);
+  return Number.isNaN(d.getTime()) ? undefined : d;
+};
+
+/** A priced request refused because nothing the caller holds may pay for it. */
+export class UsageLimitError extends Error {
+  // Literal, not `new.target.name`, which a minifier renames.
+  override name = 'UsageLimitError';
+  /** 402 or 429. */
+  readonly status: number;
+  /** The machine code — one per subclass. */
+  readonly code: string;
+  /** `billing_error` or `rate_limit_error`. */
+  readonly type: string | undefined;
+  /** The class of usage refused: premium, ours or free. */
+  readonly usageClass: string | undefined;
+  /** The model the refusal is about. */
+  readonly model: string | undefined;
+  /** The model that answers instead, where there is one. */
+  readonly fallback: string | undefined;
+  /** When the refusal lifts by itself. */
+  readonly resetsAt: Date | undefined;
+  /** The upgrade page. */
+  readonly upgradeUrl: string | undefined;
+  readonly actions: UsageAction[];
+  /** `x-request-id` — the handle that finds this call in the audit trail. */
+  readonly request: string | undefined;
+  /** What the transport raised: the AxiosError on the generated client, nothing on the six. */
+  readonly cause: unknown;
+
+  constructor(status: number, error: Obj, request?: string, cause?: unknown) {
+    const code = text(error['code']) ?? '';
+    super(text(error['message']) ?? `HTTP ${status} ${code}`);
+    this.status = status;
+    this.code = code;
+    this.type = text(error['type']);
+    this.usageClass = text(error['class']);
+    this.model = text(error['model']);
+    this.fallback = text(error['fallback']);
+    this.resetsAt = instant(error['resets_at']);
+    this.upgradeUrl = text(error['upgrade_url']);
+    // An entry with no kind is not an action, so it is not offered.
+    this.actions = list(error['actions']).flatMap((a) => {
+      const o = obj(a);
+      const kind = text(o['kind']);
+      if (!kind) return [];
+      const out: UsageAction = { kind };
+      for (const k of ['label', 'url', 'plan', 'model'] as const) {
+        const v = text(o[k]);
+        if (v !== undefined) out[k] = v;
+      }
+      return [out];
+    });
+    this.request = request;
+    this.cause = cause;
+  }
+}
+
+/** 402 `plan_allowance_used` — the plan's included usage of the class is used, and nothing else may pay. */
+export class PlanAllowanceUsedError extends UsageLimitError {
+  override name = 'PlanAllowanceUsedError';
+}
+
+/** 402 `paid_plan_required` — the model needs a paid plan or prepaid balance. */
+export class PaidPlanRequiredError extends UsageLimitError {
+  override name = 'PaidPlanRequiredError';
+}
+
+/** 429 `free_plan_cap` — the free plan's daily cap on the model is used; it lifts at `resetsAt`. */
+export class FreePlanCapError extends UsageLimitError {
+  override name = 'FreePlanCapError';
+}
+
+/** 402 `model_cap` — the model has used its share of the plan; `fallback` answers instead. */
+export class ModelCapError extends UsageLimitError {
+  override name = 'ModelCapError';
+}
+
+/** 429 `usage_cap_exceeded` — a session or day request window is spent. */
+export class UsageCapExceededError extends UsageLimitError {
+  override name = 'UsageCapExceededError';
+}
+
+/** 402 `insufficient_balance` — the known wallet balance cannot cover the request. */
+export class InsufficientBalanceError extends UsageLimitError {
+  override name = 'InsufficientBalanceError';
+}
+
+// A Map, not an object literal: a code of "constructor" must find nothing.
+const classes = new Map<string, new (status: number, error: Obj, request?: string, cause?: unknown) => UsageLimitError>([
+  ['plan_allowance_used', PlanAllowanceUsedError],
+  ['paid_plan_required', PaidPlanRequiredError],
+  ['free_plan_cap', FreePlanCapError],
+  ['model_cap', ModelCapError],
+  ['usage_cap_exceeded', UsageCapExceededError],
+  ['insufficient_balance', InsufficientBalanceError],
+]);
+
+/**
+ * The typed error a refusal names, or undefined: only a 402 or 429 whose
+ * `error.code` is one of the six is one. Anything else stays whatever error its
+ * transport already raises.
+ */
+export function limited(status: number, body: unknown, request?: string, cause?: unknown): UsageLimitError | undefined {
+  if (status !== 402 && status !== 429) return undefined;
+  const error = obj(obj(body)['error']);
+  const Class = classes.get(text(error['code']) ?? '');
+  return Class ? new Class(status, error, request, cause) : undefined;
+}
+
+/** What the X-Hanzo-* headers on one answer say. Each is undefined where the header is absent. */
+export interface Usage {
+  /** X-Hanzo-Usage: ok | near | limited — where the class stands. */
+  usage: string | undefined;
+  /** X-Hanzo-Usage-Class: premium | ours | free. */
+  usageClass: string | undefined;
+  /** X-Hanzo-Paid-By: plan | credits | free. Prepaid and granted credit both read `credits`. */
+  paidBy: string | undefined;
+  /** X-Hanzo-Fallback: the model that answered instead (limited mode). */
+  fallback: string | undefined;
+  /** X-Hanzo-Served: the Hanzo SKU that answered. */
+  served: string | undefined;
+  /** X-Hanzo-Usage-Reason: the refusal code that caused a fallback. */
+  reason: string | undefined;
+}
+
+/** A fetch `Headers`, axios's `AxiosHeaders`, or any record of header name to value. */
+export type HeaderSource = { get(name: string): unknown } | Record<string, unknown>;
+
+/**
+ * Read the usage headers off one answer: `readUsage(res.headers)` for an axios
+ * response or a fetch Response alike. Names match case-insensitively. A header
+ * that is absent, or present and empty, reads undefined — never 0 or "", which
+ * would claim the server said something it did not.
+ */
+export function readUsage(headers: HeaderSource | null | undefined): Usage {
+  return {
+    usage: header(headers, 'x-hanzo-usage'),
+    usageClass: header(headers, 'x-hanzo-usage-class'),
+    paidBy: header(headers, 'x-hanzo-paid-by'),
+    fallback: header(headers, 'x-hanzo-fallback'),
+    served: header(headers, 'x-hanzo-served'),
+    reason: header(headers, 'x-hanzo-usage-reason'),
+  };
+}
+
+/** One header by lower-case name, matched case-insensitively; undefined where absent or empty. */
+export function header(headers: HeaderSource | null | undefined, name: string): string | undefined {
+  const h = headers ?? {};
+  let v: unknown;
+  if (typeof (h as { get?: unknown }).get === 'function') {
+    v = (h as { get(name: string): unknown }).get(name);
+  } else {
+    for (const [k, value] of Object.entries(h)) if (k.toLowerCase() === name) v = value;
+  }
+  if (Array.isArray(v)) v = v[0];
+  if (typeof v === 'number' || typeof v === 'boolean') v = String(v);
+  return typeof v === 'string' ? text(v.trim()) : undefined;
+}