v0.21.0

Highlights

Kitaru 0.21.0 is a minor release on top of v0.20.2 that widens the public surface in three places and fixes how replay diffs report tokens and cost.

FlowHandle.wait() now takes an optional timeout, so a caller waiting on a remote execution can stop waiting without abandoning or disturbing the run itself. kitaru.list_secrets() and its MCP counterpart let an agent discover which secrets exist without being able to read their values. And the MCP surface gains resume and abort-wait, bringing it in line with what the SDK and CLI could already do.

On the fixes side, checkpoint token and cost diffs are now computed from canonical LLM usage records, so a replay that reused cached work reports the tokens it would have spent while correctly billing nothing for them.

Added

• FlowHandle.wait(timeout=...) can now stop waiting after a positive, finite number of seconds without changing the remote execution. It raises the new typed KitaruTimeoutError with the execution ID, configured and elapsed timeout, and last observed status. (#523)
• New kitaru.list_secrets() SDK function and matching kitaru_secrets_list MCP tool return secret names and metadata only, never secret values, so an agent can discover which secrets exist without being able to read them. (#527)
• New kitaru_executions_resume and kitaru_executions_abort_wait MCP tools bring the MCP surface in line with the SDK and CLI, letting an agent resume a paused execution or abort a pending kitaru.wait() without shelling out. (#521)

Changed

• kitaru executions get now shows every checkpoint call's current ID and status in human-readable output. Failed executions also include a copyable replay command using the first eligible failed call ID. (#538)

Fixed

• Cohort diff replay discovery now scans each flow once using ZenML's native replay linkage and reuses successful artifact hashes across rows, avoiding repeated flow scans and duplicate successful artifact loads. Unrelated executions consume the 10,000-execution scan bound, and a warning appears only when older executions remain. (#525)
• Checkpoint execution diffs now calculate token and cost changes from canonical LLM usage records, including explicit zero usage, reused work, and unavailable provider-call cost. (#518)
• Retried checkpoint invocations are now exposed as one checkpoint call with attempt history ordered by retry version. (#530)
• Missing stack integration dependencies now fail before deploy, run, or replay with a concise Kitaru explanation followed by ZenML's exact integration and whole-stack installation guidance. (#506)
• Document the openai, anthropic, and llm provider extras on the installation page, and add the kitaru[openai] install step before the quickstart's first LLM call so a base-package user does not crash on the first kitaru.llm() invocation. (#522)

Full Changelog: v0.20.2...v0.21.0