Repository navigation
Orca v0.5.20
Orca v0.5.20
This release puts more of DeepSeek's own services behind the tools. When the provider is DeepSeek on its official endpoint, web_search and web_fetch can call DeepSeek's Search and Fetch APIs, and the new read_document tool reads PDF, Word, PowerPoint and image files through DeepSeek OCR, with a disk cache that makes a document paid for once. It also adds orca doctor --online to check the API key against /models, moves today's date out of the system prompt into a per-turn context fragment so a session keeps its cached prefix across midnight and web search counts recency from the user's local date, reports DeepSeek's own reason when a stream ends with an error chunk, and extends the built-in peak/off-peak pricing table to 2027's mainland China public holidays.
Changes
- DeepSeek web backends. When Orca runs against the official DeepSeek endpoint with an API key,
web_searchandweb_fetchcan use DeepSeek's Search and Fetch APIs. Search keeps Brave first whenBRAVE_SEARCH_API_KEYis set, uses DeepSeek next, and keeps Exa as the keyless last resort: a failed DeepSeek search is answered by Exa with a note saying so, while an empty DeepSeek result is not a failure.web_fetchstill requests a page from the local machine first and retries a failure through DeepSeek's Fetch API, with a note at the top of the result saying so. The retry does not happen when Orca's own URL and redirect rules refused the request, when the page answered 404 or 410, or when the address is private or intranet — a LAN, loopback, link-local or otherwise reserved IP address, or a host name ending in.local,.localhost,.localdomain,.internal,.intranet,.private,.corp,.home,.lanor.home.arpa. A page whose body has no readable text also counts as a failure, and DeepSeek's retry runs on its own servers, which follow redirects by their own rules. Direct fetches now send aUser-Agent, which some sites require instead of answering 403. Every DeepSeek web request goes to the fixed originhttps://api.deepseek.comeven when the configured endpoint has a path such as/beta, and the key is sent nowhere else: a custombase_urldisables these calls, so a third-party gateway's key never reaches DeepSeek. HTTP failures carry DeepSeek's own message with the key masked and cut to 200 characters, with specific wording for 401, 402 and 429, and both tools stay cancellable while a request is in flight. fresh_daysrecency.web_searchnow advertises and honours afresh_dayswindow of 1 to 365 days instead of the old Brave-stylefreshnesscodes, while still accepting those codes from models and transcripts that send them;fresh_dayswins when both are present. A value sent as a fraction or a numeric string, such as7.0or"7", is coerced to whole days before schema validation instead of failing the call, values below 1 or unreadable values are dropped, and values above 365 are clamped. Windows count back from the user's local calendar date, so a UTC+8 session does not stretch its window by a day before 08:00 Beijing time, and wording such as "today", "latest" or 最新/本周 still infers a window when the model passes none. DeepSeek receives the window as anafter:date operator (and, for an explicit range,before:) within its 128-character query limit. Results now show the publication date when DeepSeek knows it, and DeepSeek titles and summaries are flattened to one line each, with a summary capped at 800 characters, so results keep the readable numbered format.read_document. The newread_documenttool reads PDF, Word (.doc,.docx), PowerPoint (.ppt,.pptx) and image files (.png,.jpg,.jpeg,.webp,.gif,.bmp,.tif,.tiff) as text through DeepSeek's OCR API. It returns the recognized text with a--- Page N ---marker before each page, numbered as DeepSeek numbers the pages, a header that says when DeepSeek counted more pages than it returned text for (a page without text says so), and a note when a page was cut short at DeepSeek's output limit. OCR layout tokens —<|box|>[[x1, y1, x2, y2]]<|/box|>around regions and<|ref|>around their text — never reach the model; the spans are matched by their shape, so a cut-short or unclosed box does not swallow the text that follows, and real<or[characters stay.offsetandlimitcount the lines of the recognized text asread_filecounts a file's lines. The tool is a network call: plan mode refuses it, suggest mode asks before it runs, and it explains what it needs when the official endpoint, an API key or[tools] deepseek_webis missing. Files over 100 MiB are refused before the upload, and a recognition can take up to three minutes.read_filestill reads anything that is text and points the model atread_documentwhen a document file is not.- OCR caching. A recognition is kept in memory for the 8 documents read most recently and on disk under
$ORCA_HOME/ocr_cache(up to 64 MiB, least recently used entries pruned first), keyed by a hash of the file's content. Reading a long document inoffset/limitchunks, reading a copy, or reading the same file from a subagent or a later session therefore pays DeepSeek once; a file whose bytes changed is recognized again, and only complete recognitions are kept on disk. Concurrent reads of one file share a single recognition while remaining cancellable, and disk writes go through the platform layer's private atomic write, so a reader in another process sees a whole cache entry or none, and only the user account can read the text. An unwritable cache is skipped silently and OCR still answers. orca doctor --online.orca doctorstays local and read-only by default;--onlineadds onecredentials-onlinecheck that asks the configured endpoint to list its models with the configured key. Listing models uses no model and is not billed, the check has a 10-second limit, and the report never shows the key. The check passes when the endpoint accepts the key, fails when the key is rejected (HTTP 401) and, separately, when the request is refused (HTTP 403 — the account, a firewall, a region block or a gateway in between may be responsible, so the remedy does not ask for a new key). Another status, no answer within 10 seconds, or no key to check warns instead, because an endpoint may not serve/models. For the official host the request ishttps://api.deepseek.com/modelseven when the endpoint has a path such as/beta; another endpoint gets/modelsafter its path. The option is documented in the CLI reference, the quickstart and the READMEs.- Today's date, outside the system prompt. The system prompt no longer carries today's date; a turn opening sets a
[Date] Today's date is YYYY-MM-DD.context fragment in the internal context, rendered after the history on every request. A session that crosses midnight or is resumed on a later day learns the new date without its cached prefix changing, the date never enters the conversation history, and a fresh or restored child agent is told the date before its first request.web_searchuses the same local date for its recency windows. - DeepSeek stream errors. A generation that fails after the response has started now reports DeepSeek's own reason from the error chunk that ends the stream, for example
the stream ended with an error (api_error): The model failed to generate a complete response. Please retry.The usage billed up to that point is kept for accounting and retry, and the failure is classified as server-side so the runtime's retry policy applies. Stream chunks whoseerrorfield is empty (false,0, a blank string,{}or[]) no longer end a stream, which some gateways attach to every chunk. - 2027 off-peak holidays in the pricing table. The built-in peak/off-peak pricing table now covers 2027: the 18 mainland China weekday public holidays in the 2027 State Council schedule (January 1; February 5 and 8–12; April 5; May 3–5; June 9; September 15; October 1 and 4–7) are off-peak all day, bringing the table to 37 weekday holidays. Cost estimates and
max_cost_usdbudgets on those days use off-peak rates; peak hours stay 09:00–12:00 and 14:00–18:00 on Beijing weekdays, and weekend make-up workdays remain off-peak because peak hours apply Monday to Friday only.
Compatibility
- DeepSeek web and OCR billing. DeepSeek bills these calls separately from tokens, per its official pricing page: web search and web fetch at $0.75 per 1,000 successful calls, and file parsing/OCR at $0.225 per 1,000 pages (November 2026 prices). Orca's token-cost estimate does not include these per-use fees, so they do not count toward the estimate or a
max_cost_usdbudget. Cancelling aread_documentread does not stop a recognition DeepSeek has already started, and DeepSeek still bills it. The built-in DeepSeek token prices and peak hours were checked against https://api-docs.deepseek.com/quick_start/pricing on 2026-11-15 and are unchanged; peak hours are 09:00–12:00 and 14:00–18:00 Beijing time on weekdays. - Switch and endpoints.
[tools] deepseek_webdefaults totrueand can be turned off only in the user configuration; a project.orca/config.tomlcannot change it. Orca calls DeepSeek's web and OCR APIs only when the provider is DeepSeek, an API key is set, andbase_urlis unset or points athttps://api.deepseek.comon the default port, with any path. With any otherbase_url, such as a third-party gateway,web_searchandweb_fetchwork as before (Brave or Exa search, local fetching only) andread_documentexplains what it needs instead of uploading. read_document. The tool name is additive and existing tool names are unchanged. Reading a document requires a DeepSeek API key, the official endpoint and network access; plan mode refuses it and suggest mode asks. It accepts files up to 100 MiB, and DeepSeek reads at most 1,000 pages of a document; a recognition can take up to three minutes.read_filestill reads text files and points a non-text document atread_documentinstead of returning a UTF-8 error.- OCR cache. Recognized text is kept in memory (the 8 most recent documents) and on disk under
$ORCA_HOME/ocr_cache(up to 64 MiB, least recently used first), keyed by the file's content and readable by your user account only. Reading a document again, a copy of it, or the same file from a subagent or a later session reuses the recognition. Deleting a session does not remove the cache; delete the$ORCA_HOME/ocr_cachedirectory to clear it, after which the next read uploads and pays again. - Web search and fetch.
fresh_daysreplacesfreshnessin the advertised schema, but models and transcripts that still send the old Brave codes are accepted (pd,pw,pm,py, andYYYY-MM-DDtoYYYY-MM-DD). Aweb_searchresult can now carry a publication date after the title, and a DeepSeek fallback result starts with a note naming the failure. Aweb_fetchresult can start with a line saying the page came through the DeepSeek Fetch API; such a page's redirects were followed by DeepSeek's servers under their rules, and a private or intranet URL is never sent to DeepSeek. Thepromptfilter applies to a page served through DeepSeek too. - Doctor exit status and stream errors.
orca doctor --onlinefails with exit status 1 when the endpoint rejects the key (HTTP 401) or refuses the request (HTTP 403); without--online, doctor makes no network call and its exit status is unchanged, and no report prints the credential. A stream that ends with an error chunk is reported as a server-side provider error with its billed usage retained; chunks that carry an emptyerrorfield still stream normally. - Date fragment and pricing table. The date is internal context, not a conversation message, so it never becomes part of the history and existing transcripts load unchanged. The 2027 weekday holidays are correct as of the State Council notice published on 2026-11-05 (https://www.gov.cn/zhengce/zhengceku/202611/content_7085102.htm); weekend make-up workdays remain off-peak because peak hours are Monday to Friday only.
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: DeepSeek web access gating on provider, key, switch and exact official endpoint, search backend choice and fallback notes, fresh_days parsing and coercion, legacy freshness codes and inferred recency, DeepSeek search and fetch request shapes, HTTP error mapping with the key masked, fetch retry decisions for refusals, missing pages and private addresses, URL and redirect guards, the direct request's User-Agent, and cancellation on the local and DeepSeek fetch paths; OCR upload boundaries and multipart shape, page numbering and missing pages, layout-token cleanup, page-count headers, in-memory and disk caches (content keying, LRU pruning, concurrent stores, corrupt entries, an unwritable cache), and parallel reads sharing one recognition; the key check's URL selection and status mapping; the date fragment at turn opening and for fresh and restored child agents, and the system prompt's size limit without the date line; stream error chunks and empty error fields; and the pricing table's holiday dates and built-in rates. A doctor_cli_contract black-box test drives the shipped binary through orca doctor --online against a local fixture, checks the JSON report and that the key is never printed. 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.20
orca --versionOr install the native binary with the installer on https://orcaagent.dev/.