codeburn/docs/providers/zcode.md

# ZCode

ZCode CLI coding agent (z.ai), running GLM-5.2 over the z.ai start-plan.

- **Source:** `src/providers/zcode.ts` (usage), `src/quota/zcode.ts` + `app/electron/quota/zcode.ts` (plan quota)
- **Loading:** lazy (`src/providers/index.ts`). Lazy because we read ZCode's SQLite database with `node:sqlite`.
- **Test:** `tests/providers/zcode.test.ts` (usage, fixture-based), `tests/quota-zcode.test.ts` / `app/electron/quota/zcode.test.ts` (quota)

## Where it reads from

ZCode keeps a single global SQLite database for the CLI.

| Source | Path |
|---|---|
| ZCode CLI db | `~/.zcode/cli/db/db.sqlite` |

The desktop app dir (`~/Library/Application Support/ZCode`) only holds Electron runtime state, and the JSONL activity log (`~/.zcode/cli/log/*.jsonl`) redacts token counts, so neither is used.

## Storage format

SQLite. Schema verified against CLI db v0.14.8. Three tables matter:

```sql
CREATE TABLE session (
  id TEXT PRIMARY KEY,
  directory TEXT NOT NULL,
  ...
);

CREATE TABLE model_usage (
  id TEXT PRIMARY KEY,
  session_id TEXT NOT NULL,
  turn_id TEXT,
  model_id TEXT NOT NULL,
  input_tokens INTEGER NOT NULL DEFAULT 0,
  output_tokens INTEGER NOT NULL DEFAULT 0,
  reasoning_tokens INTEGER NOT NULL DEFAULT 0,
  cache_creation_input_tokens INTEGER NOT NULL DEFAULT 0,
  cache_read_input_tokens INTEGER NOT NULL DEFAULT 0,
  started_at INTEGER NOT NULL,
  completed_at INTEGER,
  ...
);

CREATE TABLE tool_usage (
  session_id TEXT NOT NULL,
  turn_id TEXT,
  tool_name TEXT NOT NULL,
  started_at INTEGER NOT NULL,
  ...
);
```

## Caching

None at the provider level.

## Deduplication

Per `zcode:<model_usage.id>` (`zcode.ts`). `model_usage.id` is the row primary key, unique per request.

## What we extract

| codeburn field | ZCode source |
|---|---|
| `inputTokens` | `model_usage.input_tokens` minus cached + created (see quirks) |
| `outputTokens` | `model_usage.output_tokens` |
| `reasoningTokens` | `model_usage.reasoning_tokens` |
| `cacheCreationInputTokens` | `model_usage.cache_creation_input_tokens` |
| `cacheReadInputTokens` | `model_usage.cache_read_input_tokens` |
| `costUSD` | computed by `calculateCost` (ZCode stores no cost) |
| `model` | `model_usage.model_id` (e.g. `GLM-5.2`) |
| `timestamp` | `model_usage.completed_at` if set, otherwise `started_at` (epoch ms) |
| `tools` | `tool_usage.tool_name` for the turn, attached to one request per turn |

## Quirks worth knowing

- **Cached tokens are folded into `input_tokens` (OpenAI-style).** The row's `input_tokens` is the full prompt size including cache reads/writes, and `provider_total_tokens = input_tokens + output_tokens`. The parser subtracts `cache_read_input_tokens` and `cache_creation_input_tokens` from `input_tokens` so fresh input bills at the input rate and cached at the cache-read rate. Confirmed against the nested Anthropic usage in `provider_metadata_json` (e.g. 100 input = 36 fresh + 64 cached).
- **No cost is stored anywhere.** GLM-5.2 runs on z.ai's `start-plan` subscription, so ZCode logs tokens only. CodeBurn computes a notional cost from the pricing table.
- **GLM-5.2 is priced via an alias.** LiteLLM does not list GLM-5.2 yet, so `GLM-5.2` maps to `glm-5p1` (GLM-5.1) in `BUILTIN_ALIASES` (`src/models.ts`). Reports therefore show the model as `glm-5p1`, the same way any aliased model displays as its priced-as target. Drop the alias once LiteLLM adds GLM-5.2.
- **Timestamps are milliseconds.** Unlike Crush (seconds), ZCode stores epoch ms; the parser passes them straight to `Date`.
- **Tools are attached per turn, not per request.** `tool_usage` links to a turn, not a specific `model_usage` row, so each turn's tools are attached to its first request to avoid double-counting. Bash command text is not stored, so `bashCommands` is always empty.

## Plan quota (live)

The Plans sidebar gauge reads the same usage endpoint the ZCode app's embedded
coding-plan browser calls — the sibling of the `zai` quota provider, which
serves the Pi CLI login; this one serves the ZCode desktop app's own login.

| Source | Path / endpoint |
|---|---|
| Login token | `…/ZCode/session/Partitions/zcode-coding-plan/Local Storage/leveldb/*.log`, key `oauth:zai:access_token` (`ZCODE_DATA_DIR` overrides the app-data root) |
| Quota | `GET https://api.z.ai/api/monitor/usage/quota/limit` with `Authorization: Bearer <token>` |

- **Journal scan, not a leveldb reader.** The token is a single-byte (latin-1)
  string run in the journal file(s): `key + varint length + 0x01 marker + value`.
  We scan `*.log` newest-first (journal names are zero-padded counters) and keep
  the last write of the key. Chromium owns the file's mode bits, so this is a
  plain capped read — `readSecureFile` would reject its group-readable mode.
- **No local expiry.** The stored JWT carries no `exp` claim; validity is
  enforced server-side. A body-level `code: 401/403` on an HTTP 200 is the
  expiry signal → `terminalFailure` with "Open the ZCode app and sign in
  again" guidance (only the app can mint a new login).
- **Compaction is the known blind spot.** When leveldb compacts the journal
  into `.ldb` the records are snappy-compressed and invisible to the raw scan;
  the gauge falls back to `disconnected` until the webview writes a fresh
  journal entry.
- **All surfaces.** The CLI reads it in `src/quota/zcode.ts`, the Electron app
  in `app/electron/quota/zcode.ts`, and the native macOS menubar mirrors both in
  `mac/Sources/CodeBurnMenubar/Data/ZcodeSubscriptionService.swift` (same journal
  scan, same endpoint; catalog id `zcode`, live Capacity Dock adapter).
- **Windows map** as in `zai.ts`: `unit 3 × number 5` → 5-hour,
  `unit 6 × number 1` → Weekly; `percentage` is used percent (fallback
  `currentValue / usage`); `data.level` is the plan label (`"pro"` → "Pro").

## When fixing a bug here

1. Confirm the schema against a real ZCode install; copy `~/.zcode/cli/db/db.sqlite` to a temp file before querying so you do not lock the live db.
2. If costs are $0, check that `GLM-5.2` (or the current model id) still resolves through `BUILTIN_ALIASES` to a priced model.
3. If tokens look ~8x too high, someone likely removed the cache-subtraction in the input normalization; the row's `input_tokens` already includes cached tokens.
4. New fixtures go under the inline schema in `tests/providers/zcode.test.ts`.
5. If the quota gauge shows `disconnected` while the app is logged in, check whether the journal was compacted into `.ldb` (no usable `*.log` entry) and whether the key is still `oauth:zai:access_token`.