prefixlens 0.0.0-stage → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to prefixlens are recorded here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html) (before 1.0, a minor version may break compatibility).
+
+## [Unreleased]
+
+## [0.5.0] - 2026-11-12
+
+First public release.
+
+### Added
+
+- **Test assertions** (`prefixlens/test`). `assertPrefixStable(prev, next)` fails a test when the second of two requests your harness builds does not keep the first one's prefix. `explainPrefixDiff` returns the same explanation without throwing. A failure names the first changed block, shows a diff and suggests a fix. Options: `allowBreak`, `ignoreParams`, `hints`, `provider`. Pure functions, no network.
+- **Recording proxy** (`prefixlens record`). A local proxy for any client whose base URL can be set. It forwards each request with its body and credentials unchanged, streams the response back, and appends one full-request record per model call. It assigns each call to a lane by shared prefix, so concurrent conversations and subagents are compared with their own previous call.
+- **Recording library.** `wrap(client)` for the official Anthropic and OpenAI TypeScript SDKs, `createLens().fetch()` for any client that takes a fetch function, `lens.observe()` for custom clients, `buildRecord()` to build the same record from a request and a response, and `startProxy()`.
+- **Request formats.** Anthropic Messages, OpenAI Chat Completions and OpenAI Responses, streamed or not. The assertions also read Gemini `generateContent` bodies.
+- **Reports** (`prefixlens report`). For each call: tokens read from the cache, written and uncached, the hit rate and the cost. For each miss: the first changed block, a diff, the tokens lost and the cost. Output as a terminal table, JSON (`--json`) or one self-contained HTML file (`--html`).
+- **Causes.** Tool-list and tool-order changes, system-prompt edits and re-rendered timestamps, ids and relative dates, history rewrites (edited, inserted, removed or reordered messages, rewritten tool output or reasoning, a sliding window, a rewind), merged or split steps, compaction, model and parameter changes, cache expiry and provider-side misses. Each is labelled confirmed, inferred or unknown.
+- **Caching rules.** Explicit breakpoints (Anthropic `cache_control`, OpenAI `prompt_cache_breakpoint`) and implicit caches (OpenAI, Gemini), with the cache step learnt from the trace. A table per provider says which request parameters are part of the cached prefix, each entry marked verified, documented or assumed.
+- **Intentional breaks.** A harness declares a compaction, revert, refusal, model switch or settings change with a `prefix_break` hint, or `allowBreak` in a test. A declared break is reported with its cost, totalled apart from other misses.
+- **Trace format 1.3** ([SPEC.md](SPEC.md)). JSON Lines, one record per model call, with ordered and hashed request blocks, usage and a fidelity flag. Specified with hash test vectors, so a harness in any language can write it.
+- **Pricing.** List prices for Anthropic, OpenAI and Gemini models in `pricing.json`, with sources, cache-write lifetimes, prompt-size tiers and dated prices. `--pricing` and `PREFIXLENS_PRICING` use another table. `prefixlens pricing update`, `check` and `show` add an optional second source, the models.dev catalogue, fetched only on request.
+- **Importers** (`prefixlens import`). For logs you already have: OpenTelemetry GenAI spans (`otel`), and the session logs of Claude Code (`claude-code`), Codex (`codex`) and opencode (`opencode`). `prefixlens adapters` lists what each can diagnose.
+- **Privacy defaults.** Credentials and all but four request headers are never written. Identifying request fields and the bytes of images and documents are left out unless asked for. Trace and report files are created readable by their owner only. Control characters in trace content are written visibly on the terminal. No telemetry. See [SECURITY.md](SECURITY.md).
+- **Runtimes.** Node.js 22 or later and Bun, with type declarations and no runtime dependencies.
+
+[Unreleased]: https://github.com/parthg1901/prefixlens/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/parthg1901/prefixlens/releases/tag/v0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Parth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,180 @@
-# Temporary Holding Version
+# prefixlens
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Explains prompt-cache hits and misses for any agent, harness or framework that calls a model API.
+
+Cache regressions are silent and expensive: one reordered tool list or a timestamp in the system prompt, and every later request pays full price. prefixlens shows which request broke the cache, why, and what it cost. It also catches the break in CI, before it reaches your bill.
+
+It works on the request itself. Anything that sends OpenAI Responses, OpenAI Chat Completions or Anthropic Messages requests can use it with no adapter: your own harness, an SDK, a framework such as the Vercel AI SDK or Mastra, or a gateway.
+
+A session of an agent whose tool list grew before its fourth call:
+
+```
+turn  time (UTC)  model            prompt   read  write  uncached  out    hit   cost  status
+   1  10:00:02    claude-opus-5-5   48.2k      0  48.2k        12  140     0%  $0.24  cold
+   2  10:00:09    claude-opus-5-5   48.6k  48.2k    420        12   95  99.1%  $0.01  hit
+   3  10:00:17    claude-opus-5-5   49.0k  48.6k    380        12  110  99.2%  $0.01  hit
+   4  10:00:26    claude-opus-5-5   49.9k      0  49.9k        12  160     0%  $0.25  miss: tool list changed (+1 tool: 3 → 4)
+   5  10:00:34    claude-opus-5-5   50.3k  49.9k    350        12   60  99.3%  $0.01  hit
+
+Misses
+  turn 4: miss, tool list changed (+1 tool: 3 → 4), ~$0.24
+    lost 49,000 of 49,000 cached tokens · vs turn 3 · confirmed
+    + web_search
+
+1 miss cost $0.24 at list prices; 1 from tool-list changes
+```
+
+## Install
+
+```sh
+npm install --save-dev prefixlens    # or: bun add -d prefixlens
+```
+
+Requires Node.js 22 or later, or Bun (tested with 1.4). There are no runtime dependencies.
+
+## Quickstart
+
+### 1. Test prefix stability in CI
+
+Build the request for two consecutive steps the way your harness does, and assert that the second keeps the first one's prefix. Nothing is sent to a provider.
+
+```ts
+import { test } from "node:test"                  // or "bun:test"
+import { assertPrefixStable } from "prefixlens/test"
+
+// Stand-in for your harness: the request body it sends for a given history.
+const buildRequest = (messages) => ({
+  model: "claude-opus-5-5",
+  max_tokens: 1024,
+  system: "You are a coding agent.",
+  tools: [{ name: "read_file", description: "Read a file", input_schema: { type: "object" } }],
+  messages,
+})
+
+test("a new step extends the previous request", () => {
+  const history = [{ role: "user", content: "Fix the failing test." }]
+  const first = buildRequest(history)
+  const second = buildRequest([...history, { role: "assistant", content: "Reading it now." }, { role: "user", content: "Go on." }])
+  assertPrefixStable(first, second)
+})
+```
+
+When the builder puts the current time in the system prompt, the test fails with the first changed block, a diff and a fix:
+
+```
+PrefixBreakError: prefix not stable: system prompt changed: a timestamp value was updated (2026-01-01T10:00:00Z → 2026-01-01T10:00:01Z)
+
+  first changed block: 2 of 3 (system part 1); block 1 still matches, everything from block 2 on is re-read
+
+      type: text
+    - text: You are a coding agent. Now: 2026-01-01T10:00:00Z
+    + text: You are a coding agent. Now: 2026-01-01T10:00:01Z
+
+  fix: keep clocks and ids out of the system prompt: send them in a new message, or round them (to the day, say).
+  if this change is intentional, pass { allowBreak: { reason: "..." } }
+```
+
+More in [assertions](https://github.com/parthg1901/prefixlens/blob/main/docs/assertions.md).
+
+### 2. Record through the proxy
+
+Point any client's base URL at a local proxy. It forwards every request unchanged and records each model call.
+
+```sh
+npx prefixlens record --provider anthropic -o run.trace.jsonl   # or --provider openai; listens on 127.0.0.1:8787
+```
+
+In another terminal, set the base URL and run your agent as usual:
+
+```sh
+export ANTHROPIC_BASE_URL=http://127.0.0.1:8787   # with --provider openai: OPENAI_BASE_URL=http://127.0.0.1:8787/v1
+```
+
+Stop the proxy with Ctrl-C, then read the report:
+
+```sh
+npx prefixlens report run.trace.jsonl          # add --html for a self-contained page, --json for the data
+```
+
+Credentials are forwarded and never written. More in [proxy](https://github.com/parthg1901/prefixlens/blob/main/docs/proxy.md).
+
+### 3. Wrap your client
+
+Record from inside your own process, with no proxy:
+
+```ts
+import Anthropic from "@anthropic-ai/sdk"
+import { wrap } from "prefixlens"
+
+const client = wrap(new Anthropic(), { trace: "run.trace.jsonl" })   // also wrap(new OpenAI())
+```
+
+For a client or framework that is not one of those SDKs:
+
+```ts
+import { createLens } from "prefixlens"
+
+const lens = createLens({ trace: "run.trace.jsonl" })
+const recordingFetch = lens.fetch()             // pass it to any client or framework that accepts a fetch function
+lens.observe({ request: body, response })       // or report each call yourself: the body as sent, the response as received
+```
+
+`buildRecord` builds the same record from a request and a response you already have. From another language, write the [trace format](SPEC.md) or use the proxy. More in [library](https://github.com/parthg1901/prefixlens/blob/main/docs/library.md).
+
+## Works with
+
+Any client of the Anthropic Messages, OpenAI Chat Completions or OpenAI Responses request formats, on a provider with implicit or explicit prompt caching. There is no per-harness adapter.
+
+| | |
+|---|---|
+| Assertions | Request bodies in those three formats, and Gemini `generateContent` bodies with `provider: "gemini"`. |
+| Proxy, `wrap`, `lens.fetch`, `lens.observe`, `buildRecord` | Calls in those three formats, streamed or not. A gateway's or another provider's compatible endpoint is recorded in the format it uses. |
+| Caching | Implicit caches (OpenAI, Gemini) and explicit breakpoints (Anthropic `cache_control`, OpenAI `prompt_cache_breakpoint`). |
+| Other languages | The proxy, or a trace written to [SPEC.md](SPEC.md). |
+
+## What it tells you
+
+For each call: prompt tokens read from the cache, written and uncached, the hit rate and the cost. For each miss: the first changed block, a diff, the tokens lost, the cost, and one of these causes.
+
+| cause | what happened |
+|---|---|
+| Tool-list changes | A tool added, removed, redefined or reordered. |
+| System-prompt changes | The system prompt edited, or a timestamp, id or relative date in it rendered again. |
+| History rewrites | A sent message edited, inserted, removed or reordered; a tool output or reasoning block rewritten on replay; a sliding window; a rewind. |
+| Reshaped steps | Messages merged or split on replay. |
+| Compaction | History replaced by a summary. |
+| Model or parameter changes | Another model, or a change to a parameter the provider caches on. |
+| Cache expiry | The prefix is intact, but the call came after the cache lifetime. |
+| Provider-side misses | The prefix is intact and in time: the provider evicted the entry or routed the request elsewhere. |
+
+More in [reports](https://github.com/parthg1901/prefixlens/blob/main/docs/report.md).
+
+## Declaring intentional breaks
+
+A compaction, a revert or a model change the user asked for breaks the prefix on purpose. Declare it, and it is reported as an intentional break, with its cost totalled apart from the misses that point at bugs.
+
+In a test: `assertPrefixStable(prev, next, { allowBreak: "compaction" })`. In a trace: a `prefix_break` hint on the first call after the break.
+
+A declaration excuses one call, and only a change its reason allows. See [intentional breaks](https://github.com/parthg1901/prefixlens/blob/main/docs/intentional-breaks.md).
+
+## Limits
+
+- It sees the request your code sends, not what the provider does with it. Server-side context editing, eviction and routing show up as a miss with the prefix intact.
+- Costs are API list prices from a bundled table, not your bill. Subscriptions, discounts and batch tiers are not applied, and the table can be out of date. See [pricing](https://github.com/parthg1901/prefixlens/blob/main/docs/pricing.md).
+- Gemini's native API and WebSocket transports are not recorded. Chat Completions streams are recorded only when they report usage (`stream_options: {"include_usage": true}`).
+- A trace holds your prompts, tool output and the files your agent read. Keep it private and never commit it. See [SECURITY.md](SECURITY.md).
+- The fields of `report --json` may change in a minor version before 1.0. What has been checked on real traffic is listed in [verification](https://github.com/parthg1901/prefixlens/blob/main/docs/verification.md).
+
+## Documentation
+
+- [Assertions](https://github.com/parthg1901/prefixlens/blob/main/docs/assertions.md): `assertPrefixStable`, `explainPrefixDiff`, options, example failures.
+- [Proxy](https://github.com/parthg1901/prefixlens/blob/main/docs/proxy.md): options, the base URL to set, lanes and sessions.
+- [Library](https://github.com/parthg1901/prefixlens/blob/main/docs/library.md): `wrap`, `createLens`, `buildRecord`, `startProxy`, other exports.
+- [Reports](https://github.com/parthg1901/prefixlens/blob/main/docs/report.md): options, the JSON report, how verdicts are decided.
+- [Intentional breaks](https://github.com/parthg1901/prefixlens/blob/main/docs/intentional-breaks.md) and [pricing](https://github.com/parthg1901/prefixlens/blob/main/docs/pricing.md).
+- [Importers](https://github.com/parthg1901/prefixlens/blob/main/docs/adapters.md): for logs you already have, there are importers for OpenTelemetry GenAI spans and for the session logs of a few coding agents.
+- [Trace format](SPEC.md), [security and privacy](SECURITY.md), [changelog](CHANGELOG.md), [development](https://github.com/parthg1901/prefixlens/blob/main/docs/development.md).
+
+## Licence
+
+MIT; see [LICENSE](LICENSE).

package/SECURITY.md

@@ -0,0 +1,82 @@
+# Security and privacy
+
+prefixlens sits between an agent harness and its model provider, or inside the harness's own process, and writes what it sees to a trace file. This page says exactly what it sees, what it writes, and what it never writes. Each statement about what is written, stripped or refused is checked by a test in `test/privacy.test.ts`, `test/record.test.ts`, `test/proxy-guard.test.ts`, `test/binary.test.ts`, `test/cli-private.test.ts` or `test/printable.test.ts`.
+
+## Reporting a vulnerability
+
+Please report security problems privately: [open a private security advisory](https://github.com/parthg1901/prefixlens/security/advisories/new) on the project's repository (the repository's **Security** tab, then **Report a vulnerability**). Do not open a public issue for a vulnerability. Include the version (`prefixlens --version`), what you ran, and what was exposed.
+
+Only the latest released version is supported.
+
+## Traces contain your prompts and code
+
+**Treat every trace like source code plus personal data: keep it private, and never commit one.** By design, a trace records the full request of every model call, as sent: the full system prompt, every tool definition, the instruction files and memory the harness sends with it (`CLAUDE.md`, `AGENTS.md`, memory files), and every message in the conversation, including your prompts, the contents of files the agent read, tool outputs (shell output, search results, anything a tool returned), and earlier assistant replies, which the harness sends back as history. That usually includes working-directory paths, and often your email address, which harnesses put in their system prompts and git context.
+
+Left out by default:
+
+- request fields that identify a person, account, device or installation and are not model input: `metadata` (Anthropic's `metadata.user_id`, where Claude Code puts its account id, a persistent device id and the session id; OpenAI's developer key-value pairs), `user`, `safety_identifier`, and Codex's `client_metadata` (`IDENTIFYING_PARAMS` in `src/params.ts`). The importers drop the same fields. `keepIdentifiers` (`--keep-identifiers`) keeps them. Leaving them out changes no block hash; OpenAI documents `user` as a cache-bucketing key, so without it a miss caused by changing `user` reads as one with the prefix intact;
+- the bytes of base64 images, documents, audio and files, which are written as their SHA-256 and decoded size (SPEC.md section 4.5). Block hashes are still those of the request as sent. `keepBinary` (`--keep-binary`) keeps the bytes.
+
+Kept, because the analysis needs them: `prompt_cache_key` and the `session-id` header, which providers route requests to a cache by. A harness may derive them from a session or user id.
+
+The same applies to traces made by `prefixlens import`, which copy the content of the harness's own session logs, and to `--html` and `--json` reports, which include the changed blocks of each miss.
+
+The repository's `.gitignore` ignores `*.trace.jsonl`, `*.trace.html` and `*.report.html`, and CI fails if a trace, session log or credential is committed. Neither helps if you write a trace under another name.
+
+Trace files prefixlens creates (the proxy, `wrap`, `lens.fetch`, `lens.observe` with a trace path, `prefixlens import -o`) and `report --html` reports are created readable and writable by their owner only (mode 0600), and directories it creates for them owner-only (0700). A file or directory that already exists keeps its permissions: prefixlens never changes a mode you set. The proxy and `import -o` print a warning when such a file is readable by other users. A report printed to stdout (`--json`, the terminal report) or a trace written to stdout by `import` gets whatever permissions you redirect it into.
+
+## Trace content on the terminal
+
+A trace holds whatever the agent read: web pages, file contents, tool output, tool names from third-party servers. Printed as it is, an escape sequence in that content could retitle your terminal, hide or recolour later output, or rewrite lines already printed. So what prefixlens prints from a trace for people to read has its control characters (C0 and C1, and DEL; newline and tab are kept) written visibly, as `\x1b`: the terminal report, the diff excerpt under a miss (in every report form), the message of a `PrefixBreakError` from `prefixlens/test`, which ends up in CI logs, and the proxy's line per call. The HTML report escapes the content it shows. The JSON report (`--json`) keeps the content as it was and prints every control character in it as a JSON escape (`\u001b`, `\u009b`), so it parses to the same values.
+
+A trace itself is not changed, and is not covered: it is JSON Lines, in which the C0 characters are escaped and DEL and the C1 characters are not. That includes a trace `prefixlens import` prints to stdout when `-o` is not given. If you print a trace with another tool (`cat`, `less -r`), that tool decides what reaches the terminal.
+
+## What is never written
+
+From the request headers, only these four are written, under the record's `headers` field: `session-id`, `anthropic-beta`, `anthropic-version` and `openai-beta` (`RECORDED_HEADERS` in `src/record/exchange.ts`). They route a request to a cache or change what is cached. Every other header is dropped before the record is built, including `authorization`, `x-api-key`, `proxy-authorization`, `cookie`, `openai-organization`, `openai-project`, `chatgpt-account-id`, `user-agent` and any custom header. This holds for the proxy, `wrap`, `lens.fetch`, `lens.observe` and `buildRecord`, which all build records with the same function.
+
+From the response, only the usage counts, the response id and the model name are written. The response's content (the model's reply, tool calls, reasoning) is not. It reaches the trace only when the harness sends it back as history in a later request.
+
+Nothing is written for calls that are not model calls (anything other than `POST …/messages`, `…/chat/completions` and `…/responses`), for error responses, or for requests that fail to reach the provider.
+
+## The recording proxy
+
+`prefixlens record` forwards every request to the provider and streams the response back. It sees everything the harness sends and receives, API keys included. The method, path, query, body and credentials go upstream as the harness sent them. The headers and the framing are not byte for byte what the harness sent:
+
+- it removes the hop-by-hop headers (`host`, `connection`, `keep-alive`, `content-length`, `transfer-encoding`) and its own `x-prefixlens-lane` and `x-prefixlens-session` before forwarding;
+- it narrows the client's `accept-encoding` to the encodings the runtime's fetch can decode (this drops `zstd` on Node before 24), because it passes the response on decoded;
+- the runtime's fetch, which sends the request, sets the hop-by-hop headers again for its own connection and adds its defaults for headers the client did not send. With a client that sent none of them, the upstream received on Bun 1.4.0 `accept: */*`, `accept-encoding: gzip, deflate, br, zstd` and `user-agent: Bun/1.4.0`, and on Node 24 `accept: */*`, `accept-encoding: gzip, deflate`, `user-agent: node`, `accept-language: *` and `sec-fetch-mode: cors`. A header the client did send is forwarded with the client's value;
+- it reads each request body whole before forwarding it, so a request is not streamed to the provider as it arrives;
+- the response is streamed back chunk by chunk as it arrives, but decompressed, without the provider's `content-encoding` and `content-length`.
+
+It listens on `127.0.0.1:8787` by default, so only processes on the same machine can reach it. It has no authentication of its own: any local process can send requests through it (with its own credentials; the proxy adds none), and those requests are written to your trace.
+
+A web page in your browser can also send requests to a loopback port. The proxy refuses, with 403 and without forwarding:
+
+- a request whose `Host` header is not a loopback name (`localhost`, `*.localhost`, `127.0.0.0/8`, `::1`) or the address given with `--host`, which defeats DNS rebinding;
+- a request with an `Origin` header, which harness CLIs do not send, unless `--allow-origin` (`allowedOrigins`) names that origin. Browsers send `Origin` on cross-origin `fetch` and XHR requests, on their preflights and on cross-origin `POST`s, which covers every request that could be recorded as a model call.
+
+What the `Origin` check does not cover: a browser sends no `Origin` on a plain `GET` navigation or on an image or script load. Such a `GET`, with a loopback `Host`, is forwarded to the upstream like any other `GET`. Nothing is recorded for it (only `POST`s to the model endpoints are), and the proxy adds no credentials to it.
+
+`--allow-origin` only stops the proxy refusing: the proxy adds no CORS response headers of its own and forwards a preflight upstream like any other request, so a page from an allowed origin can read the answer only if the upstream's CORS headers allow it. `Origin: null` is what every sandboxed frame and every page opened from a file sends, so allowing `null` allows all of them.
+
+This does not make the proxy safe to expose: it does not authenticate the client, and a local process is trusted.
+
+`--host` binds it to another address. Do this only on a network you trust, and understand what it means:
+
+- the harness talks to the proxy over plain HTTP, so API keys and request content cross the network unencrypted;
+- anyone who can reach the port can send requests through it to the provider (with their own credentials; the proxy adds none), and their requests are written to your trace.
+
+`--upstream` sends requests, credentials included, wherever you point it. An `http://` upstream receives them unencrypted.
+
+The proxy prints a warning at start-up when `--host` is not a loopback address and when `--upstream` is plain HTTP to another machine.
+
+## wrap, lens.fetch and lens.observe
+
+`wrap(client)` and `lens.fetch()` run inside your process. They send each request exactly as the client built it, through the client's own fetch, and record a copy as the response streams back; they make no other request. `lens.observe` and `buildRecord` make no network request at all: they build a record from the request and response you pass in. All of them write the same record as the proxy, with the same headers and identifying fields dropped and binary data elided. `wrap` and `lens.fetch` write to `$PREFIXLENS_TRACE`, else `prefixlens.trace.jsonl` in the working directory, unless you pass `trace` (a path, or `false` to write no file).
+
+## No telemetry
+
+prefixlens sends nothing anywhere on its own. The only outgoing network requests in its source are the proxy forwarding each request to the configured upstream, `wrap`/`lens.fetch` passing requests to the fetch you gave them, and the price fetch below. Importers read local files (the opencode database is opened read-only), reports are written locally, and the HTML report is self-contained and makes no external requests. The pricing table is read from a local file.
+
+`prefixlens pricing update` and `prefixlens pricing check` fetch the models.dev price catalogue, and only when you run one of them without `--from`. Each makes one HTTP GET to `https://models.dev/api.json` and to no other URL: it does not follow redirects. The request has no body, cookies or credentials and carries nothing about your traces; its headers are `host`, `accept: application/json`, `accept-encoding`, `connection` and the runtime's default `user-agent` (`Bun/<version>` on Bun, as checked in `test/catalogue.test.ts`; `node` on Node, whose fetch also adds `accept-language: *` and `sec-fetch-mode: cors`). The response is read as data (prices, ids and dates; ids with control characters are dropped), limited to 32 MB and 30 seconds. `update` writes only the converted prices to your user cache directory (see [docs/pricing.md](https://github.com/parthg1901/prefixlens/blob/main/docs/pricing.md#commands)). The data is public, but the file is created owner-only (0600) like every file prefixlens creates, in a directory created owner-only (0700) if it did not exist; each update replaces the file, mode included. `report` and `pricing show` read that file if it exists and never fetch.