Repository navigation
Orca v0.5.21
This release closes the accounting gap v0.5.20 left open: DeepSeek's per-use fees for web search, web fetch and file parsing/OCR now count toward Orca's cost estimate and its --max-cost-usd budget, because every web or OCR tool call reports what it was billed for when it returns. It also keeps Orca's own credentials out of the shells, commands, helper processes and Terminal-Bench artifacts that agent work touches, captures file checkpoints again when the tool cwd is not canonical so orca exec --save-history sessions and native Windows can rewind their writes, keeps a pressure compaction only when it is worth keeping, settles a workflow stop that reaches a child before the host loop, and shares a failed OCR recognition with the reads waiting for it. The site's configuration, models and context-window docs are updated in English and Chinese.
Changes
- DeepSeek tool fees in the cost estimate. DeepSeek's per-use fees for web search, web fetch and file parsing/OCR now count toward
estimated_cost_usd— the cost theusage.updatedevent carries and the cost the TUI status line,/statusand ACP usage updates show — and toward the--max-cost-usdbudget. The rates are the November 2026 ones, built in: $0.75 per 1,000 searches, the same per 1,000 fetches, and $0.225 per 1,000 pages DeepSeek recognized. They are flat at every hour, so peak hours never double them, and neither the background pricing refresh nor a[models."<name>".pricing]override changes them. A fee is charged when a tool call returns: a search counts once DeepSeek returns results, counted before Orca drops any result it cannot show, while an empty search is free; a fetch counts only when the local request failed or found no readable text and DeepSeek's Fetch API returned the page, so a direct fetch and a failed DeepSeek retry are free; an OCR read counts the pages DeepSeek counted, or the pages it returned when it gave no count, while a read served from the cache, and a read that waited for another read of the same file, costs nothing. A cancelled recognition DeepSeek billed but never counted has no page count to price, so it stays out of the estimate. The fee is charged once and never written into a transcript, so a resumed session cannot charge it again; fees from a child agent's tool calls fold into the child's cost tracker and reach the parent's budget through the usual lease sync. A budget that a fee passes stops the run at the next turn or tool admission, as a provider response's cost does. When writing the fee'susage.updatedevent or itssession.usagerecord fails, the fee stays in the tracker and the journal, and the tool turn's event-error cleanup still gives the calls that never started their terminal results. - Credentials kept out of agent shells and helpers.
ORCA_API_KEY,DEEPSEEK_API_KEYandBRAVE_SEARCH_API_KEYare now removed from the environment of everything an agent command or Orca helper starts: both bash tool paths, interactive shell sessions including full-access shells, the Windows AppContainer environment block, and Orca's own helper processes — git, ripgrep and the clipboard tools, and through git a repository's hooks. A command that prints its environment can no longer put Orca's key into the transcript; that is how a v0.5.20 Terminal-Bench trajectory captured it (#178). Matching ignores ASCII case on Windows. A variable a caller sets on purpose still applies, so shell-session environment overrides, MCP servers, hooks and external tools are unchanged. The configuration docs say so, and point a project whose own tests read one of these variables at a project.envfile or a differently named variable. - Terminal-Bench artifacts. The Terminal-Bench adapters keep the key out of the run's environment and command lines:
OrcaInstalledAgentwrites it to the agent user's~/.orca/auth.json(mode 0600,umask 077) with a one-shot setup command that gets it through its own environment, and replaces it with<REDACTED_DEEPSEEK_API_KEY>intrajectory.jsonl,stderr.txtandexecution_metadata.json;OrcaExternalAgentpasses it in the wrapper shell's environment, which copies and unsets it and hands it toorcaalone, so no command line carries it. - Headless rewind checkpoints.
orca exec --save-historysessions now recordsession.snapshotrecords, andorca rewind --mode code|bothrestores their writes, where before the file modes failed with "no file snapshot recorded for message …; use --mode conversation" (#163). Checkpoint path resolution now canonicalizes the cwd it is handed before comparing it with the workspace root, falling back to the raw path when that fails, so a workspace reached through/tmpon macOS or through any symlink no longer recordsoutside_rootand loses the turn's capture. Native Windows file checkpoints were likewise likely never kept, because a configured plain path is not the verbatim\\?\formcanonicalizereturns; they capture too now. - Pressure compaction that keeps a real gain. When the conversation is under pressure, automatic compaction now keeps its result only when it brings the prompt under the soft compaction limit or shrinks it by at least a tenth. Otherwise the history stays as it was, recent tool results intact, no snapshot is written, and Orca remembers the prompt size where it tried (in memory, not persisted) and does not try again until the prompt has grown a tenth past it. This matters most when the current prompt alone is larger than the limit: before, a pinned prompt past the line made every request fold the previous tool exchange into the summary for a few percent, so the agent lost its own recent tool results and the session took a full snapshot per request (#175). A kept compaction clears the hold. Emergencies are untouched: a request with no room left for a reply, or a prompt-too-long response, still compacts and keeps any reduction. The context-window docs describe the rule in English and Chinese.
- Workflow stops that settle. A task-level stop — a host shutdown, or a typed workflow stop from the TUI or ACP — marks the workflow task stopping, and a child agent submitted after that is created cancelled. When the child's pre-execution check saw the stop before the host loop did, the script rethrew a plain "workflow child cancelled before execution" failure, which could fail the stopped run; after a restart the operation recovered as
Failed{RuntimeInvariant}instead of the expectedHostShutdownterminal. The check now reports the stop with the stop marker, as the checks before the call do, so the run settles as stopped (#169). - OCR reads share a failure, and cache housekeeping. A read that waits for another read's recognition of the same file now takes that attempt's outcome: when DeepSeek cannot read the file, the waiting read fails at once with the same reason and a note that a parallel read of the file got that answer, instead of each waiting read retrying in turn, which took up to three minutes apiece. A read cancelled before it recognizes the file no longer hashes it, asks the disk cache or uploads it, and when the read that held a recognition stops without an outcome, a waiting read takes over and recognizes the file itself. The OCR disk cache names its version (
orca-ocr-v1), so entries v0.5.20 wrote keep hitting, and pruning now removes the dotfile temp files a killed writer leaves behind once they are an hour old. The error-field check that ends a provider stream and the one that fails an OCR reply are now one shared helper; a real error behaves as before.
Compatibility
- Tool fees and budgets. DeepSeek bills web search, web fetch and file parsing/OCR apart from tokens, and v0.5.20 left those fees out of the estimate. v0.5.21 counts them, so a cost estimate or
--max-cost-usdbudget that only had to cover tokens can now stop earlier; a run that makes no DeepSeek web or OCR calls is unaffected. The rates are $0.75 per 1,000 successful searches, the same per 1,000 successful fetches, and $0.225 per 1,000 pages recognized (November 2026 prices). They are built in and flat at every hour, so neither the models.dev pricing refresh nor a[models."<name>".pricing]override changes them. A fee is charged once per returned tool result and skipped when a result is read back from a transcript. Orca still leaves out a cancelled OCR recognition whose page count it never learned, although DeepSeek bills that recognition. Where the session records history, the cumulative figure is also appended as asession.usagerecord. - Credentials in agent shells. Agent shells, agent commands and Orca's helper processes no longer inherit
ORCA_API_KEY,DEEPSEEK_API_KEYorBRAVE_SEARCH_API_KEY. A project whose tests or scripts read one of these variables must be given the value another way — a project.envfile or a differently named variable — as the configuration docs describe. Variables passed on purpose through a shell session's environment, and to user-configured MCP servers, hooks and external tools, are unchanged. Terminal-Bench artifacts no longer contain the key; a persisted trajectory that would have shown it shows<REDACTED_DEEPSEEK_API_KEY>instead. - Rewind capture. No CLI flag, configuration key, transcript record type or event field is added, removed or changed by this release;
session.snapshotrecords are still written as before, so transcripts and snapshots stay readable and older sessions load unchanged. The capture fix applies to turns recorded from v0.5.21 on: a session that recorded no snapshot for a turn still reports "no file snapshot recorded" for that turn and keeps conversation rewind. - Pressure compaction. The hold that follows a discarded compaction is remembered per conversation in memory and is not persisted, so a resumed session starts without one. Compaction thresholds, configuration and emergency behavior are unchanged.
- Pricing table. The built-in DeepSeek token prices and peak hours were checked against https://api-docs.deepseek.com/quick_start/pricing on 2026-11-16 and are unchanged; peak hours are 09:00–12:00 and 14:00–18:00 Beijing time on weekdays, and weekends and mainland China public holidays are off-peak all day. The 2027 weekday-holiday table from the State Council's schedule remains in place.
- No breaking changes. This release removes no CLI flag, configuration key, transcript record type or event field and changes no existing meaning beyond the fee accounting described above; the per-call billing data is internal and is skipped when a tool result is serialized.
Verification
Release gates run with framework retries disabled. Linux and native Windows x64/ARM64 checks must pass on the final main commit before the tag is pushed; a tag-triggered release reuses those results instead of rerunning the full suites, while a manual dispatch runs every gate below. The release workflow builds all six target archives, publishes the npm packages, and checks the published archive and package checksums and clean installs.
The changes ship with unit and contract tests across the core, provider, tools and runtime crates: the built-in tool rates and flat pricing, per-call billing and search/fetch/OCR counting rules, cache hits and recognitions shared by parallel reads, child-agent fee folding, budget crossing, the transcript-skipped billing field, and the event-error cleanup; credential scrubbing in both bash paths, helper processes, a full-access shell session and the Windows environment block, plus the Terminal-Bench adapter's key-free run environment and command lines, its 0600 auth file and its redacted artifacts; rewind capture through a symlinked or otherwise non-canonical cwd, and a black-box orca exec --save-history then orca rewind --last --mode both run through the shipped binary; the pressure-compaction thresholds, hold and emergency exemption; the workflow stop marker and the restart-recovery path it settles; OCR shared failures, handover after a cancelled owner and stale temp-file pruning; and the shared error-field helper. The final gates run in CI.
cargo fmt --all -- --check
cargo clippy --workspace --all-targets --locked -j 1
cargo nextest run -p orca-tui --lib --locked --profile ci-serial --retries 0
cargo nextest run --test tui_pty_contract --locked --profile ci-serial --retries 0
cargo nextest run --workspace --all-targets --locked --profile ci --no-fail-fast --retries 0
node scripts/release/verify-version-sync.mjs
node scripts/release/test-stage-npm.mjs
node scripts/release/test-verify-published.mjs
npm --prefix site run build
npm --prefix site run check:seoUpgrade
npm install -g @blade-ai/orca@0.5.21
orca --versionOr install the native binary with the installer on https://orcaagent.dev/.