@trazum/cli 1.39.0 → 1.41.0

package/README.md

@@ -25,6 +25,8 @@ npm install -g @trazum/cli
 | `trazum route <log.jsonl>` | is the cheaper model good enough? — measured, and it asks before spending |
 | `trazum plan <log\|dir>` | the findings as a ranked plan: what to do first, route+batch combined never summed, projections and money already spent totalled apart, every assumption named. `-o` saves it dated for a later verify; `--min-usd` names what it drops |
 | `trazum verify <plan.json> --against <log>` | did the plan's savings arrive? Three outcomes, never two — arrived, did not, cannot be told — with the world's movement named beside each verdict. `--gate` fails CI on broken promises |
+| `trazum history <dir>` | the long run: series from stored `--json` reports, the climbs and decays no pairwise comparison finds, and plans nobody is executing. Shapes named, nothing forecast |
+| `trazum connect <provider>` | your bill read from the provider's usage API — no export by hand. The credential is borrowed from the environment and never stored; a connected report is restricted on purpose and names the findings a sum cannot support |
 | `trazum doctor [dir]` | the whole workspace: what nothing is watching, and what fixing would be worth |
 | `trazum rank <dir>` | of these forty prompts, which is worth an afternoon |
 | `trazum prune <file> --cases <file>` | which few-shot examples earn their tokens — measured, and it asks before spending |

package/dist/connect.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The fetch half of the connector: credentials, pagination, and what went
+ * missing.
+ *
+ * The transformation lives in `@trazum/core`, where it is testable without a
+ * network. This module does the part that touches the outside world, and it
+ * is written under three rules the rest of the product does not need:
+ *
+ * **A credential is borrowed, never held.** Keys are read from the environment
+ * at the moment of the call and never written to a config, a cache, a report
+ * or an error message. `redact` runs over everything that can reach a terminal
+ * — a key pasted into a CI log by an error handler is a key that has to be
+ * rotated, and the tool that leaked it is the tool that promised to save money.
+ *
+ * **The endpoint is not user-supplied.** Each provider has one fixed base URL
+ * compiled in. Trazum's SSRF story has been, since 1.14, that a request body
+ * must never *name* a host — it selects one. A usage connector that accepted
+ * `--base-url` would hand that property back for the convenience of a
+ * self-hosted proxy nobody has asked for yet.
+ *
+ * **A partial pull is a partial pull, out loud.** Rate limits, page caps and
+ * windows the provider has aged out all return what was gathered, with the
+ * gap named. A bill quietly short by an unknown amount is the failure this
+ * repository refuses everywhere it can occur, and a paginated API is exactly
+ * where it occurs.
+ */
+import type { ConnectorDescriptor, ConnectorPull } from '@trazum/core';
+export interface CredentialSource {
+    /** The environment variable the key came from — the *name*, never the value. */
+    variable: string;
+}
+/**
+ * Finds the credential without ever returning it to a caller that might print
+ * it: the key stays inside this module, and the caller gets the variable name.
+ */
+export declare function findCredential(descriptor: ConnectorDescriptor, env: Record<string, string | undefined>): {
+    key: string;
+    source: CredentialSource;
+} | null;
+/**
+ * Removes credential material from anything on its way to a terminal.
+ *
+ * Two layers on purpose. The exact key is redacted because we hold it; the
+ * shapes are redacted because an error body may quote a *different* key —
+ * the one the caller mistyped, a key from a proxy's log line — and a leak
+ * through somebody else's error message is still a leak through Trazum's
+ * output.
+ */
+export declare function redact(text: string, key?: string): string;
+export interface FetchUsageOptions {
+    descriptor: ConnectorDescriptor;
+    fromMs: number;
+    toMs: number;
+    env: Record<string, string | undefined>;
+    /** Injected so the whole path is testable without a network. */
+    fetchImpl?: typeof fetch;
+}
+export interface FetchUsageResult {
+    pull: ConnectorPull;
+    source: CredentialSource;
+    pages: number;
+}
+/**
+ * Pulls a window of usage, page by page, and reports what it could not get.
+ *
+ * Returns whatever was gathered when a page fails partway through: half a
+ * month with the gap named beats an exception that throws away the half that
+ * arrived, and beats a total that silently describes less traffic than the
+ * caller asked about.
+ */
+export declare function fetchProviderUsage(options: FetchUsageOptions): Promise<FetchUsageResult>;
+//# sourceMappingURL=connect.d.ts.map

package/dist/connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAW,MAAM,cAAc,CAAC;AAqBhF,MAAM,WAAW,gBAAgB;IAC/B,gFAAgF;IAChF,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,mBAAmB,EAC/B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAA;CAAE,GAAG,IAAI,CAQlD;AAED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CASzD;AA2BD,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,mBAAmB,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACxC,gEAAgE;IAChE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,gBAAgB,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAwG9F"}

package/dist/connect.js

@@ -0,0 +1,204 @@
+/**
+ * The fetch half of the connector: credentials, pagination, and what went
+ * missing.
+ *
+ * The transformation lives in `@trazum/core`, where it is testable without a
+ * network. This module does the part that touches the outside world, and it
+ * is written under three rules the rest of the product does not need:
+ *
+ * **A credential is borrowed, never held.** Keys are read from the environment
+ * at the moment of the call and never written to a config, a cache, a report
+ * or an error message. `redact` runs over everything that can reach a terminal
+ * — a key pasted into a CI log by an error handler is a key that has to be
+ * rotated, and the tool that leaked it is the tool that promised to save money.
+ *
+ * **The endpoint is not user-supplied.** Each provider has one fixed base URL
+ * compiled in. Trazum's SSRF story has been, since 1.14, that a request body
+ * must never *name* a host — it selects one. A usage connector that accepted
+ * `--base-url` would hand that property back for the convenience of a
+ * self-hosted proxy nobody has asked for yet.
+ *
+ * **A partial pull is a partial pull, out loud.** Rate limits, page caps and
+ * windows the provider has aged out all return what was gathered, with the
+ * gap named. A bill quietly short by an unknown amount is the failure this
+ * repository refuses everywhere it can occur, and a paginated API is exactly
+ * where it occurs.
+ */
+import { SAFE_FETCH_INIT } from '@trazum/core/node';
+import { normalizeAnthropicUsage, normalizeOpenAIUsage } from '@trazum/core';
+/** Fixed, compiled in, never taken from the caller. See the module note. */
+const ENDPOINTS = {
+    anthropic: 'https://api.anthropic.com/v1/organizations/usage_report/messages',
+    openai: 'https://api.openai.com/v1/organizations/usage/completions',
+};
+/**
+ * How many pages a single pull will walk before it stops and says so.
+ *
+ * A cap rather than an unbounded loop: a wrong window against a busy
+ * organisation is otherwise a request storm against somebody's rate limit,
+ * paid for by them. Reaching it is reported as a gap, never as a complete
+ * bill.
+ */
+const MAX_PAGES = 50;
+/** Requests in flight is always one: usage endpoints are strictly rate limited. */
+const REQUEST_TIMEOUT_MS = 30_000;
+/**
+ * Finds the credential without ever returning it to a caller that might print
+ * it: the key stays inside this module, and the caller gets the variable name.
+ */
+export function findCredential(descriptor, env) {
+    for (const variable of descriptor.credentialEnv) {
+        const value = env[variable];
+        if (typeof value === 'string' && value.trim() !== '') {
+            return { key: value.trim(), source: { variable } };
+        }
+    }
+    return null;
+}
+/**
+ * Removes credential material from anything on its way to a terminal.
+ *
+ * Two layers on purpose. The exact key is redacted because we hold it; the
+ * shapes are redacted because an error body may quote a *different* key —
+ * the one the caller mistyped, a key from a proxy's log line — and a leak
+ * through somebody else's error message is still a leak through Trazum's
+ * output.
+ */
+export function redact(text, key) {
+    let out = text;
+    if (key !== undefined && key.length >= 8) {
+        out = out.split(key).join('[redacted]');
+    }
+    return out
+        .replace(/sk-ant-[A-Za-z0-9_-]{8,}/g, '[redacted]')
+        .replace(/sk-[A-Za-z0-9_-]{16,}/g, '[redacted]')
+        .replace(/\bBearer\s+[A-Za-z0-9._-]{8,}/gi, 'Bearer [redacted]');
+}
+function headersFor(provider, key) {
+    if (provider === 'anthropic') {
+        return { 'x-api-key': key, 'anthropic-version': '2023-06-01', accept: 'application/json' };
+    }
+    return { authorization: `Bearer ${key}`, accept: 'application/json' };
+}
+function urlFor(provider, fromMs, toMs, page) {
+    const url = new URL(ENDPOINTS[provider]);
+    if (provider === 'anthropic') {
+        url.searchParams.set('starting_at', new Date(fromMs).toISOString());
+        url.searchParams.set('ending_at', new Date(toMs).toISOString());
+        url.searchParams.set('bucket_width', '1d');
+        url.searchParams.append('group_by[]', 'model');
+    }
+    else {
+        url.searchParams.set('start_time', String(Math.floor(fromMs / 1000)));
+        url.searchParams.set('end_time', String(Math.floor(toMs / 1000)));
+        url.searchParams.set('bucket_width', '1d');
+        url.searchParams.append('group_by[]', 'model');
+        url.searchParams.set('limit', '31');
+    }
+    if (page !== null)
+        url.searchParams.set('page', page);
+    return url.toString();
+}
+/**
+ * Pulls a window of usage, page by page, and reports what it could not get.
+ *
+ * Returns whatever was gathered when a page fails partway through: half a
+ * month with the gap named beats an exception that throws away the half that
+ * arrived, and beats a total that silently describes less traffic than the
+ * caller asked about.
+ */
+export async function fetchProviderUsage(options) {
+    const { descriptor, fromMs, toMs, env, fetchImpl = fetch } = options;
+    const found = findCredential(descriptor, env);
+    if (found === null) {
+        throw new Error(`No credential for ${descriptor.displayName}. Trazum reads it from the environment and never stores it — set ${descriptor.credentialEnv.join(' or ')} to ${descriptor.keyKind}. See ${descriptor.docs}.`);
+    }
+    const gaps = [];
+    const payloads = [];
+    let page = null;
+    let pages = 0;
+    while (pages < MAX_PAGES) {
+        const url = urlFor(descriptor.id, fromMs, toMs, page);
+        let response;
+        try {
+            response = await fetchImpl(url, {
+                ...SAFE_FETCH_INIT,
+                method: 'GET',
+                headers: headersFor(descriptor.id, found.key),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            gaps.push({
+                kind: 'rate-limited',
+                detail: `the request for page ${pages + 1} did not complete (${redact(message, found.key)}), so everything after it is missing from this window`,
+            });
+            break;
+        }
+        pages += 1;
+        if (response.status === 429) {
+            gaps.push({
+                kind: 'rate-limited',
+                detail: `the provider rate-limited page ${pages}, so this window stops early and the rest of it was not measured`,
+            });
+            break;
+        }
+        if (response.status === 401 || response.status === 403) {
+            throw new Error(`${descriptor.displayName} refused the credential in ${found.source.variable} (HTTP ${response.status}). This endpoint needs ${descriptor.keyKind}; an ordinary API key cannot read the usage report.`);
+        }
+        if (!response.ok) {
+            const body = await response.text().catch(() => '');
+            throw new Error(`${descriptor.displayName} returned HTTP ${response.status}: ${redact(body.slice(0, 400), found.key) || '(no body)'}`);
+        }
+        let payload;
+        try {
+            payload = await response.json();
+        }
+        catch {
+            gaps.push({
+                kind: 'unreadable-entry',
+                detail: `page ${pages} was not readable JSON, so its buckets are missing from this window`,
+            });
+            break;
+        }
+        payloads.push(payload);
+        const more = payload.has_more === true;
+        const next = payload.next_page;
+        if (!more)
+            break;
+        if (typeof next !== 'string' || next === '') {
+            gaps.push({
+                kind: 'cursor-expired',
+                detail: 'the provider said there was more and served no cursor to reach it, so this window is short by an unknown amount',
+            });
+            break;
+        }
+        page = next;
+    }
+    if (pages >= MAX_PAGES) {
+        gaps.push({
+            kind: 'page-limit',
+            detail: `the pull stopped at ${MAX_PAGES} pages, so this window is incomplete — narrow it with --since and --until`,
+        });
+    }
+    const normalize = descriptor.id === 'anthropic' ? normalizeAnthropicUsage : normalizeOpenAIUsage;
+    const pulls = payloads.map((payload) => normalize(payload));
+    const pull = {
+        provider: descriptor.id,
+        granularity: descriptor.granularity,
+        buckets: pulls.flatMap((p) => p.buckets),
+        window: pulls.length === 0
+            ? null
+            : {
+                fromMs: Math.min(...pulls.filter((p) => p.window).map((p) => p.window.fromMs), Infinity),
+                toMs: Math.max(...pulls.filter((p) => p.window).map((p) => p.window.toMs), -Infinity),
+            },
+        gaps: [...pulls.flatMap((p) => p.gaps), ...gaps],
+        unavailable: descriptor.unavailable,
+    };
+    if (pull.window !== null && !Number.isFinite(pull.window.fromMs))
+        pull.window = null;
+    return { pull, source: found.source, pages };
+}
+//# sourceMappingURL=connect.js.map

package/dist/connect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.js","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"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"}

package/dist/i18n/en.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"en.d.ts","sourceRoot":"","sources":["../../src/i18n/en.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAqB9C;;;;;;GAMG;AACH,eAAO,MAAM,EAAE,EAAE,WAy+ChB,CAAC"}
+{"version":3,"file":"en.d.ts","sourceRoot":"","sources":["../../src/i18n/en.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAqB9C;;;;;;GAMG;AACH,eAAO,MAAM,EAAE,EAAE,WAslDhB,CAAC"}

package/dist/i18n/en.js

@@ -32,6 +32,8 @@ ${bold('USAGE')}
   trazum route <log.jsonl> --prompt-file <file> --cases <file> --yes
   trazum plan <log.jsonl|dir> [options]
   trazum verify <plan.json> --against <newer.jsonl|dir> [options]
+  trazum history <dir-of-stored-reports> [options]
+  trazum connect <anthropic|openai> [options]
   trazum diff <before> <after> [options]
   trazum diff --all <dir> <dir> [options]
   trazum rank <dir> [options]
@@ -309,6 +311,49 @@ ${bold('OPTIONS FOR plan')}
   a plan that hides its assumptions is advice pretending to be arithmetic.
   Projected savings and money already spent are separate totals throughout.
 
+${bold('OPTIONS FOR connect')}
+  --since <when>              The window to pull. A UTC day, an ISO timestamp,
+  --until <when>              a relative window (7d, 24h) or "now". Defaults to
+                              the last 30 days.
+  --dry-run                   Say what would be called and which environment
+                              variable the key would come from. Sends nothing
+                              and needs no credential.
+  --payload <file>            Price a usage payload you already have, instead of
+                              pulling one. No credential, no network — the same
+                              arithmetic on the same shape.
+  -o, --out <file>            Save the priced report as JSON.
+  --markdown-out <file>       Also write it as Markdown, for a CI job summary.
+  --json                      The report as data.
+
+  Reads your bill from the provider's usage API, so nothing has to be exported
+  by hand. The credential is read from the environment at the moment of the
+  call and never stored, never printed and never written to a config: set
+  TRAZUM_ANTHROPIC_ADMIN_KEY or TRAZUM_OPENAI_ADMIN_KEY. Each provider needs
+  the narrowest key that can read a usage report, and an ordinary API key
+  cannot.
+
+  These APIs serve sums over a window, not one row per call, so a connected
+  report is a restricted one and says so: the totals, the model split, the day
+  series and the cache verdict are all available, and the per-call findings —
+  input shapes, truncation retries, conversations, context pressure — are
+  listed as unavailable with what would unlock them. A rate limit, a page cap
+  or an expired cursor returns what arrived with the gap named, never a total
+  that quietly describes less traffic than you asked about.
+
+${bold('OPTIONS FOR history')}
+  --markdown-out <file>       Also write the series as Markdown, for a CI job
+                              summary or a pull request comment.
+  --json                      The history as data.
+
+  Takes a directory of stored reports — the --json documents profile already
+  writes — plus any saved plans beside them, and builds the series no
+  pairwise comparison can see: a workload climbing a little every period, a
+  model share rising since a date, a cache share decaying slowly enough that
+  no single week's report called it a finding, and the same action planned
+  again and again with nothing executing it. Derived from stored reports,
+  never re-parsed logs, so a year of JSON is enough and the raw logs can be
+  thrown away. Shapes are named; nothing is forecast.
+
 ${bold('OPTIONS FOR verify')}
   --against <log|dir>         The newer usage log the plan is held to. Required.
   --gate                      Exit 1 when an action did not produce what the
@@ -1121,6 +1166,50 @@ ${bold('EXAMPLES')}
         footer: () => 'Ranked by money, projected or already spent alike. The assumptions are yours to answer: this plan is arithmetic over the log, not knowledge of your product.',
         wrote: (path) => `Plan written to ${path}, dated. Keep it: a prediction nobody wrote down is a prediction nobody can be held to.`,
     },
+    connect: {
+        noTarget: (providers) => `Name a provider to read your bill from: trazum connect anthropic. Available: ${providers}. The credential comes from the environment and is never stored — add --dry-run to see exactly what would be called and which variable it would be read from.`,
+        unknownProvider: (id, providers) => `There is no connector for "${id}". The ones that exist are: ${providers}.`,
+        dryRun: (provider, from, to, envVars, keyKind) => `Would read ${provider} usage from ${from} to ${to}, using ${keyKind} taken from ${envVars}. Nothing was sent and no credential was needed to print this.`,
+        heading: (provider, from, to, usd, calls) => calls === null
+            ? `${provider} · ${from} → ${to} · ${usd}`
+            : `${provider} · ${from} → ${to} · ${usd} · ${calls} calls`,
+        modelRow: (model, usd, share, calls) => calls === null ? `${model}  ${usd}  ${share}` : `${model}  ${usd}  ${share} · ${calls} calls`,
+        nothingBilled: () => 'The provider billed nothing in this window. That is a measurement, not an error — widen it with --since if you expected traffic.',
+        cachePaid: (saved) => `Caching paid for itself: ${saved} less than these tokens would have cost as ordinary input.`,
+        cacheLost: (added) => `Caching added ${added} to this bill against what the same tokens would have cost as ordinary input.`,
+        cacheUnsettled: () => 'This source did not say which TTL the cache writes used, so the cheaper rate was assumed and the verdict moves under the other one. Unsettled, not settled in your favour.',
+        noCallCount: (provider) => `${provider}'s usage report serves token sums and no request count, so there is no call count here and no per-call average. A zero would read as "no traffic", so nothing is printed instead.`,
+        unpriced: (model, tokens) => `${model} is not in the price catalogue, so its ${tokens} tokens are counted and its money is not. Add it with --pricing rather than reading the total as complete.`,
+        gap: (detail) => `This window is incomplete: ${detail}.`,
+        unavailable: (findings) => `Findings this source cannot support: ${findings}. They need one row per call, and a sum has lost the rows — a per-call log still answers them.`,
+        wrote: (path) => `Report written to ${path}.`,
+        footer: () => 'Every figure here is the provider\u2019s own billed token count at the catalogue\u2019s rates. Nothing was estimated, and nothing the provider did not serve was filled in.',
+    },
+    history: {
+        noTarget: () => 'Point this at a directory of stored reports: trazum history reports/. It reads the --json documents "trazum profile" writes (and any saved plans beside them) and builds the series no pairwise comparison can see.',
+        needsThree: (count) => `A series needs at least three dated reports, and this directory has ${count}. Two reports is a comparison, and "trazum profile --against" already does that better.`,
+        heading: (periods, from, to) => `The long run: ${periods} periods, ${from} → ${to}`,
+        periodRow: (name, usd, calls, days) => `${name}  ${usd} · ${calls} calls · ${days} days`,
+        runLabel: (label, periods, sinceName, from, to) => `${label} has climbed for ${periods} consecutive periods since ${sinceName}: ${from} → ${to}. A shape, not a forecast.`,
+        runModel: (model, periods, sinceName, from, to) => `${model}'s share of the bill has climbed for ${periods} consecutive periods since ${sinceName}: ${from} → ${to}. The totals can look flat while the mix moves under them.`,
+        runCache: (periods, sinceName, from, to) => `The cache share has decayed for ${periods} consecutive periods since ${sinceName}: ${from} → ${to} — slowly enough that no single report called it a finding, which is exactly why a series exists.`,
+        repeated: (kind, label, model, appearances, first, last) => {
+            const what = kind === 'route'
+                ? `Routing ${label} (${model})`
+                : kind === 'batch'
+                    ? `Batching ${label} (${model})`
+                    : kind === 'route+batch'
+                        ? `Routing and batching ${label} (${model})`
+                        : kind === 'fix-truncation'
+                            ? `Fixing the truncation retries on ${label} (${model})`
+                            : `Fixing the cache on ${label} (${model})`;
+            const span = first !== null && last !== null ? ` (${first} → ${last})` : '';
+            return `${what} has been planned ${appearances} times${span} and is still in the newest plan — a decision nobody is revisiting.`;
+        },
+        undated: (name) => `${name} carries no span, so it is on no timeline above — named, never silently absorbed.`,
+        unrecognized: (name) => `${name} is neither a stored report nor a saved plan, so it is in no series above.`,
+        footer: () => 'A series names shapes, not futures. Twenty points make a trend visible; they do not make next month knowable — where these lines go next is yours to judge.',
+    },
     verify: {
         noTarget: () => 'Point this at a saved plan and a newer log: trazum verify plan.json --against usage.jsonl. It says, per action, whether the change arrived, did not arrive, or cannot be told — and never fewer than those three.',
         needsAgainst: () => '--against <newer.jsonl|dir> is required. A plan can only be verified against a log that came after it; without one there is nothing to hold the prediction to.',