CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.
Python agent-frameworkagent-harnessagent-runtimeagentic-aiai-agentsai-frameworkanthropicharnessharness-engineeringharness-frameworklanggraphlanggraph-alternativellmmcpopenaipi-agentpi-agent-corepythonpython-agent
fix(checkpointer): compare and clear pending requests
xfgong11948b08fe79
diff --git a/cubeloop/checkpointer/postgres/checkpointer.py b/cubeloop/checkpointer/postgres/checkpointer.pyindex dd1add1..b147554 100644--- a/cubeloop/checkpointer/postgres/checkpointer.py+++ b/cubeloop/checkpointer/postgres/checkpointer.py@@ -594,6 +594,31 @@ class PostgresCheckpointer:return HitlRequest.model_validate_json(raw)return HitlRequest.model_validate(raw)+ async def clear_pending_request_if_matches(+ self,+ thread_id: str,+ *,+ question_id: str,+ ) -> bool:+ """Clear pending state only while it still names ``question_id``.++ The predicate and mutation run in one PostgreSQL ``UPDATE``. If a+ concurrent writer has already checkpointed a replacement request,+ PostgreSQL re-evaluates the predicate after acquiring the row lock and+ leaves that newer request intact.+ """+ assert self._pool is not None+ async with self._pool.acquire() as conn:+ result = await conn.execute(+ "UPDATE cubepi_threads "+ "SET pending_request = NULL, run_id = NULL, updated_at = now() "+ "WHERE thread_id = $1 "+ "AND pending_request->>'question_id' = $2",+ thread_id,+ question_id,+ )+ return result == "UPDATE 1"+async def load_pending_run_id(self, thread_id: str) -> str | None:"""Return the run_id of the currently pending HITL request.diff --git a/tests/checkpointer/test_postgres_pending_request.py b/tests/checkpointer/test_postgres_pending_request.pyindex 66eb0c6..4c8cea6 100644--- a/tests/checkpointer/test_postgres_pending_request.py+++ b/tests/checkpointer/test_postgres_pending_request.py@@ -35,6 +35,36 @@ async def test_postgres_clear_pending_request(clean_db) -> None:assert loaded is None+async def test_postgres_compare_and_clear_pending_request(clean_db) -> None:+ await _setup_schema_v2(clean_db)+ async with PostgresCheckpointer(clean_db) as cp:+ await cp.save_pending_request("t-1", _req(qid="q-current"), run_id="run-1")++ assert not await cp.clear_pending_request_if_matches(+ "t-1", question_id="q-replaced"+ )+ assert (await cp.load_pending_request("t-1")) == _req(qid="q-current")++ assert await cp.clear_pending_request_if_matches("t-1", question_id="q-current")+ assert await cp.load_pending_request("t-1") is None+ assert await cp.load_pending_run_id("t-1") is None+++async def test_postgres_compare_and_clear_preserves_replacement(clean_db) -> None:+ await _setup_schema_v2(clean_db)+ async with PostgresCheckpointer(clean_db) as cp:+ await cp.save_pending_request("t-1", _req(qid="q-answered"), run_id="run-1")+ await cp.save_pending_request("t-1", _req(qid="q-follow-up"), run_id="run-1")++ assert not await cp.clear_pending_request_if_matches(+ "t-1", question_id="q-answered"+ )+ assert (await cp.load_pending_request("t-1")) == _req(qid="q-follow-up")+ assert await cp.load_pending_run_id("t-1") == "run-1"++@pytest.mark.asyncioasync def test_postgres_pending_request_creates_thread_row_lazily(clean_db) -> None:"""save_pending_request must INSERT … ON CONFLICT DO NOTHING for the thread row,diff --git a/website/docs/guides/checkpointing/postgres.md b/website/docs/guides/checkpointing/postgres.mdindex c691f64..64a059a 100644--- a/website/docs/guides/checkpointing/postgres.md+++ b/website/docs/guides/checkpointing/postgres.md@@ -186,6 +186,14 @@ So writing `{"foo": 1}` then `{"bar": 2}` leaves `{"foo": 1, "bar":2}`. Middleware can safely write partial dicts without losing priorkeys.+## Conditional pending cleanup++Hosts that coordinate HITL resumes across workers can use+`clear_pending_request_if_matches(thread_id, question_id=...)`. It clears the+pending request and owning run ID only if the stored request still has that+question ID. The comparison and clear are one PostgreSQL update, so a newer+follow-up request written by another worker is never erased by stale cleanup.+## Forks`PostgresCheckpointer` implements the v4 `snapshot` / `fork` /diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/checkpointing/postgres.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/checkpointing/postgres.mdindex 6deea7c..1fb16ca 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/checkpointing/postgres.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/checkpointing/postgres.md@@ -166,6 +166,14 @@ extra = cubepi_threads.extra || EXCLUDED.extra所以先写 `{"foo": 1}` 再写 `{"bar": 2}` 会得到 `{"foo": 1, "bar": 2}`。中间件可以安全地写入部分 dict 而不会丢失先前的键。+## 条件式清理 pending request++跨 worker 协调 HITL 恢复的宿主可以调用+`clear_pending_request_if_matches(thread_id, question_id=...)`。只有数据库中+当前 pending request 的问题 ID 仍然匹配时,它才会同时清除该请求及其所属+run ID。比较与清理在一条 PostgreSQL 更新中完成,因此旧 worker 的清理不会+误删另一个 worker 已写入的新 follow-up 请求。+## Fork`parent_thread_id` + `forked_at_seq` 列用于支持