Skip to content

Orca v0.5.20

Choose a tag to compare

@github-actions github-actions released this 14 Nov 19:11
· 43 commits to main since this release

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_search and web_fetch can use DeepSeek's Search and Fetch APIs. Search keeps Brave first when BRAVE_SEARCH_API_KEY is 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_fetch still 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, .lan or .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 a User-Agent, which some sites require instead of answering 403. Every DeepSeek web request goes to the fixed origin https://api.deepseek.com even when the configured endpoint has a path such as /beta, and the key is sent nowhere else: a custom base_url disables 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_days recency. web_search now advertises and honours a fresh_days window of 1 to 365 days instead of the old Brave-style freshness codes, while still accepting those codes from models and transcripts that send them; fresh_days wins when both are present. A value sent as a fraction or a numeric string, such as 7.0 or "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 an after: 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 new read_document tool 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. offset and limit count the lines of the recognized text as read_file counts 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_web is missing. Files over 100 MiB are refused before the upload, and a recognition can take up to three minutes. read_file still reads anything that is text and points the model at read_document when 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 in offset/limit chunks, 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 doctor stays local and read-only by default; --online adds one credentials-online check 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 is https://api.deepseek.com/models even when the endpoint has a path such as /beta; another endpoint gets /models after 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_search uses 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 whose error field 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_usd budgets 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_usd budget. Cancelling a read_document read 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_web defaults to true and can be turned off only in the user configuration; a project .orca/config.toml cannot change it. Orca calls DeepSeek's web and OCR APIs only when the provider is DeepSeek, an API key is set, and base_url is unset or points at https://api.deepseek.com on the default port, with any path. With any other base_url, such as a third-party gateway, web_search and web_fetch work as before (Brave or Exa search, local fetching only) and read_document explains 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_file still reads text files and points a non-text document at read_document instead 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_cache directory to clear it, after which the next read uploads and pays again.
  • Web search and fetch. fresh_days replaces freshness in the advertised schema, but models and transcripts that still send the old Brave codes are accepted (pd, pw, pm, py, and YYYY-MM-DDtoYYYY-MM-DD). A web_search result can now carry a publication date after the title, and a DeepSeek fallback result starts with a note naming the failure. A web_fetch result 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. The prompt filter applies to a page served through DeepSeek too.
  • Doctor exit status and stream errors. orca doctor --online fails 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 empty error field 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:seo

Upgrade

npm install -g @blade-ai/orca@0.5.20
orca --version

Or install the native binary with the installer on https://orcaagent.dev/.