@hoilab/ada-cli 0.84.21 → 0.85.0

package/docs/compaction.md

@@ -1,6 +1,6 @@
 # Compaction & Branch Summarization
 
-LLMs have limited context windows. When conversations grow too long, Pi uses compaction to summarize older content while preserving recent work. This page covers both auto-compaction and branch summarization.
+LLMs have limited context windows. When conversations grow too long, Ada uses compaction to summarize older content while preserving recent work. This page covers both auto-compaction and branch summarization.
 
 **Source files** ([pi-mono](https://github.com/earendil-works/pi-mono)):
 - [`packages/coding-agent/src/core/compaction/compaction.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/compaction/compaction.ts) - Auto-compaction logic
@@ -9,11 +9,11 @@ LLMs have limited context windows. When conversations grow too long, Pi uses com
 - [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/session-manager.ts) - Entry types (`CompactionEntry`, `BranchSummaryEntry`)
 - [`packages/coding-agent/src/core/extensions/types.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/extensions/types.ts) - Extension event types
 
-For TypeScript definitions in your project, inspect `node_modules/@earendil-works/pi-coding-agent/dist/`.
+For TypeScript definitions in your project, inspect `node_modules/@hoilab/ada-cli/dist/`.
 
 ## Overview
 
-Pi has two summarization mechanisms:
+Ada has two summarization mechanisms:
 
 | Mechanism | Trigger | Purpose |
 |-----------|---------|---------|
@@ -32,13 +32,13 @@ Auto-compaction triggers when:
 contextTokens > contextWindow - reserveTokens
 ```
 
-By default, `reserveTokens` is 16384 tokens (configurable in `~/.pi/agent/settings.json` or `<project-dir>/.pi/settings.json`). This leaves room for the LLM's response.
+By default, `reserveTokens` is 16384 tokens (configurable in `~/.ada/agent/settings.json` or `<project-dir>/.ada/settings.json`). This leaves room for the LLM's response.
 
 You can also trigger manually with `/compact [instructions]`, where optional instructions focus the summary.
 
 ### How It Works
 
-1. **Find cut point**: Walk backwards from newest message, accumulating token estimates until `keepRecentTokens` (default 20k, configurable in `~/.pi/agent/settings.json` or `<project-dir>/.pi/settings.json`) is reached
+1. **Find cut point**: Walk backwards from newest message, accumulating token estimates until `keepRecentTokens` (default 20k, configurable in `~/.ada/agent/settings.json` or `<project-dir>/.ada/settings.json`) is reached
 2. **Extract messages**: Collect messages from the previous kept boundary (or session start) up to the cut point
 3. **Generate summary**: Call LLM to summarize with structured format, passing the previous summary as iterative context when present
 4. **Append entry**: Save `CompactionEntry` with summary and `firstKeptEntryId`
@@ -76,7 +76,7 @@ What the LLM sees:
     prompt   from cmp          messages from firstKeptEntryId
 ```
 
-On repeated compactions, the summarized span starts at the previous compaction's kept boundary (`firstKeptEntryId`), not at the compaction entry itself, falling back to the entry after the previous compaction if that kept entry cannot be found in the path. This preserves messages that survived the earlier compaction by including them in the next summarization pass as well. Pi also recalculates `tokensBefore` from the rebuilt session context before writing the new `CompactionEntry`, so the token count reflects the actual pre-compaction context being replaced.
+On repeated compactions, the summarized span starts at the previous compaction's kept boundary (`firstKeptEntryId`), not at the compaction entry itself, falling back to the entry after the previous compaction if that kept entry cannot be found in the path. This preserves messages that survived the earlier compaction by including them in the next summarization pass as well. Ada also recalculates `tokensBefore` from the rebuilt session context before writing the new `CompactionEntry`, so the token count reflects the actual pre-compaction context being replaced.
 
 ### Split Turns
 
@@ -102,7 +102,7 @@ Split turn (one huge turn exceeds budget):
   turnPrefixMessages = [usr, ass, tool, ass, tool, tool]
 ```
 
-For split turns, Pi generates two summaries and merges them:
+For split turns, Ada generates two summaries and merges them:
 1. **History summary**: Previous context (if any)
 2. **Turn prefix summary**: The early part of the split turn
 
@@ -149,7 +149,7 @@ See [`prepareCompaction()`](https://github.com/earendil-works/pi-mono/blob/main/
 
 ### When It Triggers
 
-When you use `/tree` to navigate to a different branch, Pi offers to summarize the work you're leaving. This injects context from the left branch into the new branch.
+When you use `/tree` to navigate to a different branch, Ada offers to summarize the work you're leaving. This injects context from the left branch into the new branch.
 
 ### How It Works
 
@@ -178,7 +178,7 @@ After navigation with summary:
 
 ### Cumulative File Tracking
 
-Both compaction and branch summarization track files cumulatively. When generating a summary, pi extracts file operations from:
+Both compaction and branch summarization track files cumulatively. When generating a summary, Ada extracts file operations from:
 - Tool calls in the messages being summarized
 - Previous compaction or branch summary `details` (if any)
 
@@ -346,6 +346,21 @@ pi.on("session_before_compact", async (event, ctx) => {
 
 See [custom-compaction.ts](../examples/extensions/custom-compaction.ts) for a complete example using a different model.
 
+### session_compact_failed
+
+Fired when manual or automatic compaction fails or is aborted. This is useful for telemetry extensions that need to pair `session_before_compact` attempts with terminal outcomes.
+
+```typescript
+pi.on("session_compact_failed", async (event, ctx) => {
+  const { reason, errorMessage, aborted, willRetry, fromExtension } = event;
+  // reason - "manual" (/compact), "threshold", or "overflow"
+  // errorMessage - present for non-abort failures
+  // aborted - true for cancelled/aborted compactions
+  // willRetry - whether the aborted turn would have retried after compaction
+  // fromExtension - whether extension-provided compaction content was being used
+});
+```
+
 ### session_before_tree
 
 Fired before `/tree` navigation. Always fires regardless of whether user chose to summarize. Can cancel navigation or provide custom summary.
@@ -380,7 +395,7 @@ See `SessionBeforeTreeEvent` and `TreePreparation` in the types file.
 
 ## Settings
 
-Configure compaction in `~/.pi/agent/settings.json` or `<project-dir>/.pi/settings.json`:
+Configure compaction in `~/.ada/agent/settings.json` or `<project-dir>/.ada/settings.json`:
 
 ```json
 {

package/docs/compliance.md

@@ -0,0 +1,241 @@
+# Compliance
+
+Ada records what the agent did, in a form an auditor can check. This page
+describes what exists, what each mechanism proves, and — just as importantly —
+what it does not.
+
+Everything here is stated in terms of what has been measured. Where a control
+has a limit, the limit is named rather than left for a customer to discover.
+
+## The session ledger
+
+Every command, tool call, file touched, model invocation and outbound request is
+appended to a hash-chained ledger under `<agentDir>/sesion/`. Each entry carries
+the hash of the previous one, so altering a record is detectable on
+re-verification.
+
+**It records shape, never content.** Of a file it keeps the path and the hash
+before and after — never the text. Of a network call, the destination domain —
+never the path or query, which is where tokens travel.
+
+```bash
+ada-cli audit verify            # re-verify the chain
+ada-cli audit show --limit 50   # the last entries
+ada-cli audit export --out informe.md   # a report for a DPO
+```
+
+### Three answers, not two
+
+`audit verify` distinguishes causes rather than giving one verdict to all of
+them, because "someone edited an entry", "entries are missing" and "the process
+restarted" call for different responses:
+
+| Answer | Meaning |
+|---|---|
+| Chain intact | Every entry verifies and nothing the index remembers is missing. |
+| An entry was **edited** | Its hash does not match its own content. |
+| A link is **broken** | Its `prevHash` does not point at the previous entry: entries are missing or reordered. |
+| The chain **restarts** | A fresh chain begins inside one file. A process restart produces this, and so does someone removing entries and writing a new chain. From the file alone the two cannot be told apart, so this is reported as neither an accusation nor a clean bill of health. |
+| The ledger is **empty** | Nothing has been recorded yet. Not the same as "intact". |
+
+A missing file is detected because a separate index keeps a hard-link anchor for
+each session file. Deleting `sesion/*.jsonl` removes a name, not the bytes: the
+verification notices the absence *and* can still read what was hidden.
+
+### What the ledger does not prove
+
+- **Integrity, not provenance.** The chain shows the log was not edited or
+  reordered. It does not attest who produced it or on which machine. For
+  non-repudiation you need a signature under a managed key (HSM); Ada does not
+  ship one.
+- **A local adversary with disk access wins.** Anyone who can rewrite the whole
+  directory can produce a consistent chain of their choosing. What this removes
+  is that a single `rm` or `truncate` passes unnoticed. Closing it further needs
+  an external anchor.
+
+## Retention and purge (GDPR art. 5.1.e)
+
+Data must not be kept longer than necessary, so a DPO has to be able to delete
+old records. Doing that naively broke either way: deleting `sesion/` made
+`verify` cry tampering, and deleting both directories made the purge vanish
+while the ledger still claimed to be intact.
+
+`audit purge` writes a **chained tombstone** before deleting anything — which
+period, how many entries, under what policy, and the closing hash of the segment
+that goes:
+
+```bash
+ada-cli audit purge --dias 90 --politica "retención 90 días, art. 5.1.e RGPD" --dry-run
+ada-cli audit purge --dias 90 --politica "retención 90 días, art. 5.1.e RGPD"
+```
+
+`--dry-run` shows exactly what would go, down the same code path that removes
+it. There is deliberately no default cut-off: a deletion that decides itself is
+not a retention policy. `--politica` is required for the same reason — it is
+what turns the deletion into a fact someone can defend.
+
+`verify` then reports those gaps as *explained*, naming the policy, and reports
+them even when no gap remains — which is the normal case, since a purge removes
+the file and its anchor.
+
+**What a tombstone is not:** proof that what was purged is what the tombstone
+says. Whoever controls the disk can write any tombstone. It is proof of
+*declared intent*, which is enough to keep a lawful deletion from looking like a
+cover-up, and to force a hostile one to lie in writing.
+
+## Machine policy
+
+Two configuration scopes — global and project — are both files the user owns, so
+a line a CISO adds to forbid `yolo` can be deleted by the very person it applies
+to. Ada adds a third scope, where the operating system requires administrator
+rights to write:
+
+| Platform | Path |
+|---|---|
+| macOS | `/Library/Application Support/Ada/politica.json` |
+| Linux | `/etc/ada/politica.json` |
+| Windows | `%ProgramData%\Ada\politica.json` |
+
+```jsonc
+{
+  "modoMaximo": "auto",
+  "denegadas": ["bash"],
+  "motivo": "norma interna SEC-4"
+}
+```
+
+**It can only ever restrict.** A `modoMaximo` ceiling lowers the permission mode
+the user asks for and never raises it: a ceiling of `yolo` still leaves a user
+who asked for `manual` on `manual`. Tools in `denegadas` stay denied even in
+`yolo`. There is deliberately **no environment variable** pointing at another
+file — that would be the back door that voids the policy with one `export`.
+
+A file that exists but cannot be parsed is not treated as no file: the mode falls
+to `manual`, because a typo in the administrator's file must not end up granting
+more than intended.
+
+```bash
+ada-cli politica     # is it in force, and can this account edit it?
+```
+
+Every decision records which rule decided it, so the ledger shows when the team
+policy overrode the user's preference (`modo-auto-por-politica-de-maquina`).
+
+**Limit:** a user with administrator rights on their own machine can edit the
+file. This does not defend against that and cannot. It defends the case that
+occurs in a company — a corporate laptop where the employee is not an
+administrator — and says so when the file turns out to be writable by the
+current account.
+
+## Special categories (GDPR art. 9 and 10)
+
+Health, trade-union membership, ethnic origin, religion, political opinion, sex
+life, biometrics and genetics are special categories whose processing is
+prohibited save for a listed exception; art. 10 adds criminal convictions.
+
+Ada detects them and masks them **before anything reaches disk**, on both the
+audit ledger and the edit diary. Identifiers are validated rather than
+pattern-matched: a Spanish DNI is checked against its mod-23 control letter and
+an IBAN against mod-97, so an internal 8-digit identifier is not flagged as
+personal data.
+
+Vocabulary categories require a nearby person marker, because "diagnostic"
+appears in every compiler output and "union" in every SQL query. Measured over
+469 real source files of this repository, the detector produces **3 findings**,
+all of them the word "diagnostic" next to a capitalised word — and the finding
+says so: *ambiguous vocabulary*. The starting point of the same measurement was
+116.
+
+A text that cannot be analysed is not silently passed through: it is masked
+whole, with a marker saying why. An unreadable field is an inconvenience; a field
+with health data in the clear is an infringement.
+
+## Telemetry
+
+**Ada sends none.** There is no install ping and there are no default attribution
+headers. Both existed and both were removed — see
+[Telemetry and update checks](settings.md#telemetry-and-update-checks).
+
+What Ada *can* do, if you ask it to, is export its ledger to your own OpenTelemetry
+collector:
+
+```bash
+export OTEL_EXPORTER_OTLP_ENDPOINT=https://colector.interno
+export OTEL_EXPORTER_OTLP_PROTOCOL=http/json
+ada-cli telemetria            # state, and where each signal goes
+ada-cli telemetria --cuerpo   # the exact JSON that would be sent
+ada-cli telemetria --enviar   # send it
+```
+
+The exported attributes come from an **explicit allowlist** of shape: event type,
+tool name, exit code, duration, byte counts, hashes, destination domain,
+provider, model and token counts. Everything else is dropped, and the number
+dropped is recorded in `ada.atributos_descartados` — a silent truncation cannot
+be audited.
+
+Above the allowlist there is a second belt: any value containing a newline or
+longer than 200 characters is discarded even if its key is allowed.
+
+**There is no environment variable, option or parameter that enables content
+export**, deliberately, and a test walks the module's own source to keep it that
+way. `--cuerpo` exists so you can verify this yourself rather than take our word
+for it.
+
+## Constrained decoding
+
+When the provider supports it, each tool's schema can be sent in **strict** mode,
+so the model *cannot* emit a call that does not fit the schema — it is not that
+we reject it afterwards, it is that it never gets generated.
+
+```bash
+export ADA_MUESTREO_RESTRINGIDO=1
+```
+
+**It is off by default, and that is a decision rather than an oversight.** What
+has been measured, by running it: all four tools that declare it — `edit`,
+`write`, `read` and `bash` — accept a strict schema, so the lever is connected
+and not decorative. What could *not* be measured: the end-to-end effect against
+a real model, because the free OpenRouter tier answers a five-token ping but
+does not sustain a thirteen-thousand-token turn, and two attempts timed out.
+
+Turning something on because it sounds good is how a project ends up with a
+green checkbox that protects nothing, so it stays off until there is a
+measurement. It has its own switch — previously the only way in was
+`PI_EXPERIMENTAL=1`, which enables *everything* experimental at once, and in a
+team with change control that means never trying it.
+
+An explicit `ADA_MUESTREO_RESTRINGIDO=0` wins over `PI_EXPERIMENTAL=1`: someone
+who enables all experiments but turns this one off has made a decision.
+
+## Software bill of materials
+
+```bash
+npm run sbom              # CycloneDX 1.5 to sbom.cdx.json
+npm run check:licencias   # gate: fails on a denied or unknown licence
+```
+
+Three states, not two: **allowed**, **denied**, and **unknown**. A dependency
+that declares no licence, or declares one that cannot be parsed, is *unknown* —
+and unknown does not pass. `--check` fails naming it, so someone looks. An empty
+tree also fails: a gate that passes because it inspected nothing is worse than no
+gate.
+
+Compound SPDX expressions are understood: `MIT OR Apache-2.0` passes if either
+branch passes, `MIT AND GPL-3.0` fails if either branch fails, and parentheses
+nest. Anything that cannot be parsed lands in *unknown*, never in *allowed*.
+
+The SBOM omits `serialNumber` and `metadata.timestamp` — both optional in 1.5 —
+so the file is reproducible byte for byte. If your process needs them, inject
+them from outside with a deterministic value.
+
+## Network egress
+
+Web tools resolve the destination and check **every address** the name resolves
+to, not the name and not just the first address. A name that does not resolve is
+rejected: "I could not check" and "it is fine" are different answers.
+
+The DPO report's transfer section always states its scope, including when the
+table has rows — a populated table implies an exhaustive list, which is a
+stronger claim than an empty one. The paths still outside the ledger are named
+there explicitly, and a test walks every `fetch(` in the source so the list
+cannot quietly go stale.

package/docs/containerization.md

@@ -1,31 +1,31 @@
 # Containerization
 
-Pi runs with all permissions by default, but in some cases, you will want to have more control over what directories Pi can write to and which accesses it has.
+Ada runs with all permissions by default, but in some cases, you will want to have more control over what directories Ada can write to and which accesses it has.
 
 There are two general options. You can either
-1. run the whole `pi` process inside an isolated environment, or
-2. run `pi` on the host and route tool execution into an isolated environment.
+1. run the whole `ada-cli` process inside an isolated environment, or
+2. run `ada-cli` on the host and route tool execution into an isolated environment.
 
 ## Choose a pattern
 
 | Pattern | What is isolated | Best for | Notes |
 | --- | --- | --- | --- |
 | Gondolin extension | Built-in tools and `!` commands | Local micro-VM isolation while keeping auth on host | See [`examples/extensions/gondolin/`](../examples/extensions/gondolin/). |
-| Plain Docker | Whole `pi` process in a local container | Simple local isolation | Provider API keys enter the container. |
-| OpenShell | Whole `pi` process in a policy-controlled sandbox | Local or remote managed sandbox | Requires an OpenShell gateway |
+| Plain Docker | Whole `ada-cli` process in a local container | Simple local isolation | Provider API keys enter the container. |
+| OpenShell | Whole `ada-cli` process in a policy-controlled sandbox | Local or remote managed sandbox | Requires an OpenShell gateway |
 
-Extensions run wherever the `pi` process runs. If you run host `pi` with a tool-routing extension, other custom extension tools still run on the host unless they also delegate their operations.
+Extensions run wherever the `ada-cli` process runs. If you run host `ada-cli` with a tool-routing extension, other custom extension tools still run on the host unless they also delegate their operations.
 
 ## Gondolin
 
 [Gondolin](https://github.com/earendil-works/gondolin) is a local Linux micro-VM.
-Use the [example extension](../examples/extensions/gondolin) when you want `pi` on the host but all built-in tools routed into the VM.
+Use the [example extension](../examples/extensions/gondolin) when you want `ada-cli` on the host but all built-in tools routed into the VM.
 
 Setup:
 
 ```bash
-cp -R packages/coding-agent/examples/extensions/gondolin ~/.pi/agent/extensions/gondolin
-cd ~/.pi/agent/extensions/gondolin
+cp -R packages/coding-agent/examples/extensions/gondolin ~/.ada/agent/extensions/gondolin
+cd ~/.ada/agent/extensions/gondolin
 npm install --ignore-scripts
 ```
 
@@ -33,7 +33,7 @@ Run from the project you want mounted:
 
 ```bash
 cd /path/to/project
-pi -e ~/.pi/agent/extensions/gondolin
+ada-cli -e ~/.ada/agent/extensions/gondolin
 ```
 
 The extension mounts the host cwd at `/workspace` in the VM and overrides `read`, `write`, `edit`, `bash`, `grep`, `find`, and `ls`.
@@ -44,9 +44,9 @@ Requirements: Node.js >= 23.6.0 for `@earendil-works/gondolin`, plus QEMU (requi
 
 ## Plain Docker
 
-Run the whole `pi` process in Docker when you want the simplest local container boundary.
+Run the whole `ada-cli` process in Docker when you want the simplest local container boundary.
 
-`Dockerfile.pi`:
+`Dockerfile.ada`:
 
 ```dockerfile
 FROM node:24-bookworm-slim
@@ -54,27 +54,27 @@ FROM node:24-bookworm-slim
 RUN apt-get update \
   && apt-get install -y --no-install-recommends bash ca-certificates git ripgrep \
   && rm -rf /var/lib/apt/lists/*
-RUN npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+RUN npm install -g --ignore-scripts @hoilab/ada-cli
 
 WORKDIR /workspace
-ENTRYPOINT ["pi"]
+ENTRYPOINT ["ada-cli"]
 ```
 
 Build and run:
 
 ```bash
-docker build -t pi-sandbox -f Dockerfile.pi .
+docker build -t ada-sandbox -f Dockerfile.ada .
 
 docker run --rm -it \
   -e ANTHROPIC_API_KEY \
   -v "$PWD:/workspace" \
-  -v pi-agent-home:/root/.pi/agent \
-  pi-sandbox
+  -v ada-agent-home:/root/.ada/agent \
+  ada-sandbox
 ```
 
 The `-v "$PWD:/workspace"` mounts your current directory into the container at /workspace such that reads and writes in `/workspace` inside Docker directly affect your host files, like in the Gondolin example.
 
-Use a named volume for `/root/.pi/agent` if you want container-local settings and sessions. Mounting your host `~/.pi/agent` exposes host auth and session files to the container.
+Use a named volume for `/root/.ada/agent` if you want container-local settings and sessions. Mounting your host `~/.ada/agent` exposes host auth and session files to the container.
 
 ## OpenShell
 
@@ -89,23 +89,23 @@ openshell gateway add <gateway-url> --name <name>
 openshell gateway select <name>
 ```
 
-Launch `pi` inside an OpenShell sandbox:
+Launch `ada-cli` inside an OpenShell sandbox:
 
 ```bash
-openshell sandbox create --name pi-sandbox --from pi -- pi
+openshell sandbox create --name ada-sandbox --from ada -- ada-cli
 ```
 
-In this pattern, the whole `pi` process runs inside the sandbox.
+In this pattern, the whole `ada-cli` process runs inside the sandbox.
 Built-in tools, `!` commands, and extension tools execute inside the OpenShell boundary.
 
 If the gateway is remote, project files are not bind-mounted from the host, meaning writes in the sandbox are not reflected on your machine.
 Clone the repository inside the sandbox or use OpenShell file transfer commands:
 
 ```bash
-openshell sandbox upload pi-sandbox ./repo /workspace
-openshell sandbox download pi-sandbox /workspace/repo ./repo-out
+openshell sandbox upload ada-sandbox ./repo /workspace
+openshell sandbox download ada-sandbox /workspace/repo ./repo-out
 ```
 
 OpenShell providers can keep raw model API keys outside the sandbox.
 When inference routing is configured, code inside the sandbox can call `https://inference.local`, and the gateway injects the configured provider credentials upstream.
-Configure Pi to use the corresponding OpenAI-compatible or Anthropic-compatible endpoint if you want model traffic to use this route.
+Configure Ada to use the corresponding OpenAI-compatible or Anthropic-compatible endpoint if you want model traffic to use this route.

package/docs/custom-provider.md

@@ -30,7 +30,7 @@ See these complete provider examples:
 
 ## Quick Reference
 
-Extensions can register either a complete pi-ai `Provider` or use the legacy provider-config form. Prefer a complete provider when custom authentication, filtering, refresh, or streaming behavior is required. Pi composes `models.json` overrides above registered native providers.
+Extensions can register either a complete pi-ai `Provider` or use the legacy provider-config form. Prefer a complete provider when custom authentication, filtering, refresh, or streaming behavior is required. Ada composes `models.json` overrides above registered native providers.
 
 ```typescript
 import { createProvider, openAICompletionsApi } from "@earendil-works/pi-ai";
@@ -88,7 +88,7 @@ export default function (pi: ExtensionAPI) {
 }
 ```
 
-The extension factory can also be `async`. For dynamic model discovery, fetch and register models in the factory instead of `session_start`. pi waits for the factory before startup continues, so the provider is available during interactive startup and to `pi --list-models`.
+The extension factory can also be `async`. For dynamic model discovery, fetch and register models in the factory instead of `session_start`. Ada waits for the factory before startup continues, so the provider is available during interactive startup and to `ada-cli --list-models`.
 
 ## Override Existing Provider
 
@@ -239,7 +239,7 @@ models: [{
   id: "custom-model",
   // ...
   reasoning: true,
-  thinkingLevelMap: {              // map pi levels to provider values; null hides unsupported levels
+  thinkingLevelMap: {              // map Ada levels to provider values; null hides unsupported levels
     minimal: null,
     low: null,
     medium: null,
@@ -382,7 +382,7 @@ interface OAuthLoginCallbacks {
 
 ### OAuthCredentials
 
-Credentials are persisted in `~/.pi/agent/auth.json`:
+Credentials are persisted in `~/.ada/agent/auth.json`:
 
 ```typescript
 interface OAuthCredentials {
@@ -566,14 +566,14 @@ calculateCost(model, output.usage);
 
 ### Context Overflow Errors
 
-When a request exceeds the model's context window, pi can recover automatically by compacting the conversation and retrying. This recovery only kicks in if pi recognizes the failure as an overflow.
+When a request exceeds the model's context window, Ada can recover automatically by compacting the conversation and retrying. This recovery only kicks in if Ada recognizes the failure as an overflow.
 
 Detection runs on the finalized assistant message:
 
 - `stopReason === "error"`
-- `errorMessage` matches one of pi's known overflow patterns (see [`packages/ai/src/utils/overflow.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/utils/overflow.ts))
+- `errorMessage` matches one of Ada's known overflow patterns (see [`packages/ai/src/utils/overflow.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/utils/overflow.ts))
 
-If your provider returns overflow errors with a message pi does not recognize, normalize the error from the same extension that registers the provider. Use a `message_end` handler to rewrite the assistant message so its `errorMessage` starts with a phrase pi recognizes. The generic fallback `context_length_exceeded` is the safest choice.
+If your provider returns overflow errors with a message Ada does not recognize, normalize the error from the same extension that registers the provider. Use a `message_end` handler to rewrite the assistant message so its `errorMessage` starts with a phrase Ada recognizes. The generic fallback `context_length_exceeded` is the safest choice.
 
 ```typescript
 const MY_PROVIDER_OVERFLOW_PATTERN = /your provider's overflow phrase/i;
@@ -605,7 +605,7 @@ export default function (pi: ExtensionAPI) {
 }
 ```
 
-`message_end` runs before pi tracks the assistant message for auto-compaction, so the rewritten `errorMessage` is what pi checks. With this in place, pi will:
+`message_end` runs before Ada tracks the assistant message for auto-compaction, so the rewritten `errorMessage` is what Ada checks. With this in place, Ada will:
 
 1. Detect the overflow from `errorMessage`.
 2. Drop the failed assistant message from live context.
@@ -615,7 +615,7 @@ export default function (pi: ExtensionAPI) {
 Guard the rewrite carefully:
 
 - Scope it to your provider (`message.provider` and `ctx.model?.provider`) so unrelated errors from other providers are untouched.
-- Match a provider-specific pattern, not pi's generic overflow patterns. Rewriting rate-limit or throttling errors (`rate limit`, `too many requests`) would falsely trigger compaction instead of pi's normal retry-with-backoff path.
+- Match a provider-specific pattern, not Ada's generic overflow patterns. Rewriting rate-limit or throttling errors (`rate limit`, `too many requests`) would falsely trigger compaction instead of Ada's normal retry-with-backoff path.
 - Skip when `errorMessage` already includes `context_length_exceeded` so the handler is idempotent.
 
 ### Registration
@@ -713,7 +713,7 @@ interface ProviderModelConfig {
   /** Whether the model supports extended thinking. */
   reasoning: boolean;
 
-  /** Maps pi thinking levels to provider/model-specific values; null marks a level unsupported. */
+  /** Maps Ada thinking levels to provider/model-specific values; null marks a level unsupported. */
   thinkingLevelMap?: Partial<Record<"off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max", string | null>>;
 
   /** Supported input types. */
@@ -752,8 +752,10 @@ interface ProviderModelConfig {
     requiresThinkingAsText?: boolean;
     requiresReasoningContentOnAssistantMessages?: boolean;
     thinkingFormat?: "openai" | "openrouter" | "deepseek" | "together" | "baseten" | "zai" | "qwen" | "chat-template" | "qwen-chat-template" | "string-thinking" | "ant-ling";
-    chatTemplateKwargs?: Record<string, string | number | boolean | null | { "$var": "thinking.enabled" | "thinking.effort"; omitWhenOff?: boolean }>;
-    chatTemplateArgs?: Record<string, string | number | boolean | null | { "$var": "thinking.enabled" | "thinking.effort"; omitWhenOff?: boolean }>;
+    chatTemplateKwargs?: Record<string, string | number | boolean | null | { "$var": "thinking.enabled" | "thinking.effort" | "thinking.budget"; omitWhenOff?: boolean }>;
+    chatTemplateArgs?: Record<string, string | number | boolean | null | { "$var": "thinking.enabled" | "thinking.effort" | "thinking.budget"; omitWhenOff?: boolean }>;
+    thinkingTokenBudgetField?: "thinking_token_budget" | "thinking_budget" | "thinking_budget_tokens";
+    supportsThinkingTokenBudget?: boolean;
     cacheControlFormat?: "anthropic";
     sessionAffinityFormat?: "openai" | "openai-nosession" | "openrouter";
     sendSessionAffinityHeaders?: boolean;
@@ -771,4 +773,5 @@ interface ProviderModelConfig {
 ```
 
 `openrouter` sends `reasoning: { effort }`. `deepseek` sends `thinking: { type: "enabled" | "disabled" }` and `reasoning_effort` when enabled. `together` sends `reasoning: { enabled }` and also `reasoning_effort` when `supportsReasoningEffort` is enabled. `qwen` is for DashScope-style top-level `enable_thinking`. Use `qwen-chat-template` for local Qwen-compatible servers that read `chat_template_kwargs.enable_thinking` and need `preserve_thinking`. Use `chat-template` for configurable `chat_template_kwargs`, for example DeepSeek V3.x behind vLLM with `chatTemplateKwargs: { "thinking": { "$var": "thinking.enabled" } }`. Use `thinkingFormat: "baseten"` with `chatTemplateArgs` when the provider expects toggle values under `chat_template_args` and optionally supports top-level `reasoning_effort`.
+`thinkingTokenBudgetField` sends a clamped per-level thinking budget as a top-level request field (`thinking_token_budget` on vLLM, `thinking_budget` on Qwen/SGLang, `thinking_budget_tokens` on llama.cpp). `supportsThinkingTokenBudget: true` is an alias for the vLLM field name. Do not combine it with `reasoning_effort` on DashScope Qwen models.
 `cacheControlFormat: "anthropic"` applies Anthropic-style `cache_control` markers to the system prompt, last tool definition, and last user, assistant, or tool-result text content.