v0.19.0

Highlights

v0.19.0 is a feature release that builds on v0.18.0 with a big step up in the record, replay, and improve workflow plus a new framework adapter. You can now replay many executions in one call, structurally diff an original run against its replays checkpoint by checkpoint, select cohorts of executions to replay, and read named LLM cost and token metrics directly from execution statistics across the SDK, CLI, and MCP. This release also adds an experimental Google ADK adapter for recording and replaying Google Agent Development Kit agents, and a LangGraph replay and fork adapter that rebuilds a recorded LangGraph run from a captured trace. Note that replay's override API was redesigned around explicit override groups, which is a breaking change for code written against the earlier prototype.

Added

• Experimental Google ADK adapter (KitaruADKRunner, KitaruADKModel, KitaruADKTool) with docs, direct and persisted-workflow examples, isolated no-dev contract and live smoke paths, explicit-wrapper calls mode, and tool-confirmation resume helpers.
• Replay-mode detection helpers kitaru.is_replay(), kitaru.get_replay_runtime_context(), and kitaru.ReplayRuntimeContext, so side-effectful checkpoints can guard their behavior during replay.
• Named LLM cost and token metric shortcuts for execution statistics across the SDK, CLI, and MCP (llm_total_tokens, llm_incurred_tokens, llm_display_cost, llm_estimated_cost).
• kitaru.diff(original, *executions) for per-checkpoint structural comparison between an original execution and its replays, auto-discovering replays via original_exec_id when omitted.
• Unified multi-execution replay through flow.replay([...], *, at=...), KitaruClient().executions.replay([...], ...), and multi-ID kitaru executions replay. Parents missing the at checkpoint are skipped in collect mode and recorded in ReplaySubmission.skipped.
• kitaru.diff_matrix(exec_ids) to diff many originals against their auto-discovered replays.
• CLI commands kitaru executions diff and kitaru executions diff-matrix, plus MCP tools kitaru_executions_diff, kitaru_executions_diff_matrix, and a unified kitaru_executions_replay that takes explicit execution IDs.
• Client-side cohort selection via kitaru.cohort(...).resolve(), KitaruClient().executions.cohort(...), CLI kitaru executions cohort (dry-run selection), and MCP kitaru_executions_cohort.
• A LangGraph replay and fork adapter (kitaru.adapters.langgraph.replay) that reconstructs a recorded LangGraph run as a directed graph from a captured trace and forks it for replay, exposing KitaruReplayAgent, KitaruAdapter, import_langgraph_trace / import_trace, and graph edit helpers, with Langfuse and JSONL trace import sources.
• kitaru executions replay now prints UI compare URLs (and includes compare_url in JSON output) for the original execution versus the new replay.
• KITARU_UI_URL to override the dashboard base URL used for compare and execution deep links when the Kitaru frontend is hosted separately from the API server.

Changed

• Breaking: Redesigned the replay API. flow.replay(...), KitaruClient().executions.replay(...), CLI kitaru executions replay, and MCP kitaru_executions_replay now take the checkpoint selector as at= (previously from_=) with separate override groups flow_overrides, checkpoint_overrides, and invocation_overrides (previously a single overrides map), and return a shared ReplaySubmission result model (previously a FlowHandle). Code written against the earlier replay signature needs updating.
• Clarified Google ADK MCP docs around the safe subset: Kitaru can checkpoint a replay-safe ADK BaseTool-like object wrapped with KitaruADKTool, but it does not restore ADK MCP processes, sessions, or hidden server state.
• Refreshed the Google ADK dependency note: google-adk stays out of the normal local and dev project environment until the full local server path is certified with the newer FastAPI and Starlette stack.

Fixed

• Kitaru terminal logs now rewrite ZenML's named pipeline completion message to Flow `...` completed successfully., so Pipeline `...` completed successfully. no longer leaks into flow output.
• Replay checkpoint overrides now fan out across repeated adapter-generated model and tool calls, while suffixed selectors still target exactly one recorded call.
• Replay output overrides on terminal checkpoints now fail with a clearer error explaining that output replacement requires a downstream consumer.
• MCP replay now lets an omitted on_error use the shared SDK default (fail for one parent, collect for batches), and kitaru.diff() now scans up to 10,000 same-flow executions when auto-discovering replays before warning that older replays may require explicit IDs.
• Unknown checkpoint override targets now give repeated-call guidance when a likely model or tool family exists, pointing users to family-level checkpoint_overrides or one-call invocation_overrides.
• LangGraph replay import now raises a catchable Kitaru error instead of SystemExit when Langfuse rows never arrive, and live forks support node callables that accept (state, config).
• KitaruClient.executions.replay() and the pipeline fallback replay path now wait for completion and run terminal LLM usage aggregation before returning, so replay executions expose llm_usage_summary for compare and outcomes views.
• Cohort selection now hydrates list summaries when checking replay anchors, so executions cohort matches originals that only expose checkpoints on executions get.
• kitaru.diff() and kitaru executions diff now emit one multi-execution compare URL when auto-discovering replays, not one pairwise URL per replay.
• Replay planning now re-executes the full live tail after at for linear adapter call sequences that lack explicit DAG upstream edges (for example PydanticAI calls checkpoints after lookup_policy_tool).
• FlowHandle.wait() / .get() now return a flow's persisted output instead of raising an ambiguous-result error when an adapter produced several non-result model or tool checkpoints (the common checkpoint_strategy="calls" shape) or the flow has an explicit return value.
• LLM usage summaries are normally written when executions finish, and FlowHandle.wait() / .get() can populate missing summaries for older executions or executions where the finish-time summary was not written.

Security

• Raised the pydantic-ai-slim lower bound and lockfile version to clear CVE-2026-48782.

Full Changelog: v0.18.0...v0.19.0