4 Commits

Author	SHA1	Message	Date
Nan Gao	13f0a7f263	feat(extensions): let an out-of-tree extension observe what the agent did (#4863) ... * feat(extensions): let an out-of-tree extension observe what the agent did DeerFlow's extension system can contribute middleware, services and routes, but an extension cannot answer basic questions about a run without reaching into host internals. Several of the facts it would need are destroyed by the operations that produce them: * The middleware chain injects and rewrites a lot of context — date reminders, recalled memory, compaction summaries, durable-context data, image payloads, activated skill bodies. Downstream, none of it is attributable: at the model-call boundary an injected HumanMessage is indistinguishable from the user's own, and anything wanting to tell them apart has to pattern-match prompt wording, which breaks on the next copy edit. * Two runs of "the same agent" are only comparable if the chain enforced the same limits, prompts and thresholds. Recovering that from outside means reading private attributes and guessing which of them change behaviour — a guess that rots silently as middlewares gain fields. * The lead-agent factory resolves a model after runtime overrides, renders a prompt, filters tools through authorization and composes a stack, all inside one synchronous call, and none of it survives: a middleware sees its neighbours but not the prompt, the run worker sees a graph but not what went into it. * Summarization is destructive by design. N messages leave the context and one summary enters it; afterwards only the summary exists, so "which messages became this?" is not reconstructible. This adds seven neutral facilities so those facts are recorded where they are still true, and releases the contract package as 0.2.0. Message provenance Producers stamp `deerflow_content_kind` / `deerflow_producer_kind` onto the messages they inject or rewrite. Stamping is unconditional — a fact whose presence depends on whether an observer is installed is not a fact — and the keys are server-owned, so provenance cannot be forged from a request. Middleware self-description Twelve middlewares declare their own behaviour-affecting parameters through a duck-typed `release_policy_parameters()`. Long text is hashed rather than embedded: a declaration is an identity, not a copy of the prompt. Agent assembly descriptor `assemble_lead_agent()` returns the graph plus a descriptor whose fingerprint answers "did anything about this agent change between these two runs?". `make_lead_agent()` keeps its graph-only signature — it is the LangGraph Server ABI declared in langgraph.json. Tools and skills are sorted before hashing because their assembly order is incidental; middlewares are not, because stack order decides what wraps what. Host build identity is reported but excluded from the fingerprint, so a redeploy does not invalidate every agent's identity. Context compaction observation Summarization emits the content hashes of the messages it is about to remove joined to the summary that replaced them. Content is the only identity available at that seam: the summary does not become a message, and what later projects it into a request renders it bounded and escaped rather than verbatim. Neutral policy, transform and MCP-source facts Guardrail decisions are published to runtime context under a `__`-prefixed key; result-rewriting middlewares append a declared, ordered transform trail; MCP tools carry their credential-free logical origin. Extension route identity Contributed routes are session-authenticated and cannot opt out, but "logged in" and "administrator" are different questions. Extensions get a neutral projection of the caller rather than the host's auth context, and `require_admin` fails closed when identity cannot be determined. Extension-owned tables An extension that persists data owns its own MetaData and migration chain, so its tables are absent from Base.metadata and `alembic revision --autogenerate` proposes dropping them. Extensions declare a table prefix, which is rejected at registration if it would shadow a host table. The contract package stays dependency-free and imports no host code; every new Protocol method has a default so later additions remain additive. The loader's pre-1.0 rule requires an exact major.minor match, so extensions written against 0.1 are now refused at startup with an actionable install hint rather than loading into a host that implements a different surface. uv.lock records the contract package's new version, so `uv sync --locked` still resolves on a fresh checkout. * fix(backend): sort gateway service imports	2026-08-23 09:57:12 +08:00
Vanzeren	c48de5e70b	feat(checkpoint): make delta snapshot_frequency configurable (#4516) ... * feat(checkpoint): make delta snapshot_frequency configurable * fix(config): carry legacy checkpoint_delta_snapshot_frequency with warning Addresses review on #4516: the rename from the flat database.checkpoint_delta_snapshot_frequency key to nested database.checkpoint_delta.snapshot_frequency silently dropped the old value (pydantic extra="ignore"). Add a before-validator that maps the legacy key onto the nested one with a deprecation warning (nested key wins when both are set), plus a CHANGELOG breaking-change note covering the rename and the 1000 -> 10 default change. * fix(checkpoint): validate frozen snapshot frequency	2026-07-28 23:21:23 +08:00
Vanzeren	e01173d8b2	bench(checkpoint): production-shaped full/delta benchmark with configurable snapshot frequency (#4467) ... * feat(checkpoint): production-shaped full/delta benchmark with configurable snapshot frequency - Group benchmark scripts into per-family folders (checkpoint/, sandbox/) - Extract shared benchmark infrastructure into checkpoint_bench_common.py - Add checkpoint_delta_snapshot_frequency config (default 1000, process-frozen); freeze it in make_lead_agent and DeerFlowClient; key the state-schema adaptation cache by resolved frequency - New bench_production.py: per-case child processes run N ainvoke turns through the real lead-agent graph (scripted deterministic model, real AsyncSqliteSaver), then measure GET /state + POST /history through the real Gateway route stack in one event loop (httpx ASGITransport), cold/warm accessor-cache split, cross-mode digest gates - New summarize_production.py: delta/full ratios plus decision metrics (snapshot_write_spike, cache_effect_ms, checkpoint_write_share, auto-discovered history per-limit ratios) * fix(checkpoint): address production benchmark review	2026-07-27 11:47:49 +08:00
Vanzeren	42baed8c8c	feat(checkpoint): dual-mode checkpoint storage with LangGraph DeltaChannel (#4292) ... * feat(checkpoint): dual-mode checkpoint storage with LangGraph DeltaChannel Add a restart-required database.checkpoint_channel_mode ("full" default, "delta") that stores the messages channel via LangGraph 1.2 DeltaChannel, cutting checkpoint storage from O(n^2) to O(n) for append-only history. Existing full checkpoints seed delta state transparently; no data migration. - config: mode schema + freeze-on-first-use with CheckpointModeReconfigurationError; mode marker persisted in checkpoint metadata; unsafe delta->full downgrade rejected fail-closed with CheckpointModeMismatchError (run-level error, failed state read) - state: delta message state schema; CheckpointStateAccessor centralizes materialized reads for all consumers (threads API, branches, regeneration, compaction, state updates, memory, goal workers) - runtime: raw writers (run durations, interrupted title, thread goal) parent their checkpoints to the checkpoint they derive from, preserving delta ancestry; rollback forks the pre-run lineage through a state mutation graph with Overwrite restores; InMemorySaver delta-history override delegates to the base walk (fixes dropped first write after migration, also present upstream) - tests: conformance suite over {memory, sqlite, postgres} covering migration replay, stable message IDs, storage shape and writer preservation; conftest fixture isolates the frozen mode between tests; stale config fakes refreshed - ci: backend unit tests gain a postgres service * fix(checkpoint): close materialization gaps in goal flow, guard public factory - Route goal-continuation message reads through CheckpointStateAccessor: raw channel_values reads see the delta sentinel in delta mode, which disabled goal continuation (stand_down=no_durable_end_of_turn) after durable assistant turns. Raw tuples remain for tuple-only metadata (checkpoint id, pending_writes). - Reject checkpoint_channel_mode='delta' + checkpointer in create_deerflow_agent at construction: factory-built persisted graphs bypass mode-marker injection and the fail-closed gate, reproducing silent mixed-mode state loss. Delta without persistence stays allowed. - Import the postgres saver lazily (pytest.importorskip in the fixture) so the documented default install collects the suite; add a CI job running pytest --collect-only on uv sync --group dev without extras. - Fix test_checkpointer fallback test to patch get_app_config at its use site (provider module), making it deterministic when a local config.yaml selects a persistent backend. * fix(gateway): preserve extension-owned channels in state mutations, bump config version - build_state_mutation_graph / build_checkpoint_state_mutation_accessor accept an explicit state_schema; branch and POST /state now compile the mutation graph from the thread's effective schema (graph_state_schema on the assistant graph). The base-ThreadState fallback silently discarded channels contributed by custom AgentMiddleware.state_schema on branch (data loss) and returned a false-success 200 on POST /state. - POST /state validates values keys against the mutation graph's channels and rejects unknown fields with 422 instead of ignoring them; reducer detection covers extension channels (BinaryOperatorAggregate or DeltaChannel) so Overwrite replace semantics work for middleware reducers in both modes. - Endpoint regression: custom AgentMiddleware.state_schema value survives branch, updates through POST /state, and an unknown field receives 422. - config_version 26 -> 27 for the new database.checkpoint_channel_mode (example, Helm chart values + README, support-bundle fixture), so existing installs get the outdated-config warning and make config-upgrade merges the field; covered by a test driving the real example file and the real config-upgrade script. * fix(gateway): resolve assistant schema via one boundary, copy branch reducer values with Overwrite GET /threads/{id}/state now resolves the thread's assistant_id through a single reusable boundary (thread metadata -> assistant_id -> effective graph), so channels contributed by a custom AgentMiddleware.state_schema are materialized instead of dropped by the default lead schema. POST /state uses the same boundary instead of resolving the schema ad hoc. Branch writes wrap every copied reducer channel in Overwrite (derived from the effective mutation graph: BinaryOperatorAggregate + DeltaChannel), not just messages, so already-aggregated values are never re-merged. Regression tests use a real AgentMiddleware.state_schema with a non-identity reducer in both full and delta modes: GET /state returns the extension value, POST /state replaces it, branch preserves it byte-for-byte; the unknown-field 422 is a separate assertion. * refactor(checkpoint): collapse read-path round-trips and ship dual-mode parity tests Address review round 4 on PR #4292: - Push ahistory/history limit through Pregel into checkpointer.alist (SQL LIMIT) instead of materializing all rows and breaking in Python - Fold the read-side mode-compat gate onto the returned snapshot's metadata; only writes keep the pre-write tuple fetch (fail-closed) - Cache factory-built accessor graphs per (assistant_id, mode) with factory-identity revalidation; state reads no longer build a lead agent per request - get_thread: one snapshot fetch + one raw pending_writes fetch on the resolved checkpoint (post-checkpoint __error__ writes never surface in snapshot.tasks; verified empirically) - DeerFlowClient.get_thread: single checkpointer.list walk collects pending_writes per checkpoint instead of N get_tuple calls - InMemorySaver delta-history patch: stand-down when the upstream override disappears, try/except guard, validated-version warning, guard tests - make_lead_agent mode precedence: first freeze is owned by app_config (client-supplied configurable key ignored); once frozen, injected key/app_config must match or fail closed - Rollback: lock in non-message channel restoration via fork inheritance with a dedicated reducer-channel test - Add tests/test_threads_checkpoint_mode.py and tests/test_gateway_checkpoint_mode.py referenced by AGENTS.md and the PR validation section: lifecycle parity (memory + sqlite), per-step blob-count storage guard, gateway endpoint parity Counted-saver tests pin checkpoint round-trips for aget/ahistory so these regressions cannot silently return. * fix(checkpoint): precise mode-mismatch HTTP mapping, gate E2E, and accessor resilience - threads router: map CheckpointModeMismatchError to 409 (with cause and thread id) and CheckpointModeReconfigurationError to 503 across all state endpoints instead of swallowing both into a generic 500 - gate coverage: seed a real delta checkpoint into AsyncSqliteSaver and assert aget/aupdate/ahistory fail closed; assert 409 at the HTTP boundary through the real route stack - rollback: compile the restore mutation graph with the thread's effective state schema per the build_state_mutation_graph contract - inheritance contract locks: rollback and manual compaction preserve middleware-contributed channels via checkpoint fork cloning - services: revalidate the accessor-graph cache against app_config identity so config.yaml hot-reloads never serve a stale compiled graph - services: degrade full-mode state reads to raw checkpointer reads when the agent factory is unavailable (delta gate still applies; delta mode has no fallback) - deps: override websockets==16.0 (langgraph-sdk 0.4.2's <16 pin silently downgraded 16.0 -> 15.0.1; pin is not grounded in any API incompatibility) and bump the langchain lower bound to what the lockfile actually resolves * fix(checkpoint): include anchor checkpoint in degraded history walk + cover get_thread - _RawCheckpointReadAccessor.ahistory: alist(before=...) is exclusive while pregel's get_state_history treats config.checkpoint_id as the inclusive start; fetch the anchor explicitly so both read paths paginate identically - extend the degraded-path gateway test: GET /thread returns raw values, and POST /history with before starts at the anchor checkpoint * fix(gateway): preserve degraded checkpoint timestamps * fix(gateway): harden degraded checkpoint access * fix(gateway): resolve assistants for checkpoint reads --------- Co-authored-by: Willem Jiang <willem.jiang@gmail.com>	2026-07-22 08:33:29 +08:00