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): fence pending clear by run
xfgonga6281da14a6e
diff --git a/cubeloop/checkpointer/postgres/checkpointer.py b/cubeloop/checkpointer/postgres/checkpointer.pyindex b147554..9293826 100644--- a/cubeloop/checkpointer/postgres/checkpointer.py+++ b/cubeloop/checkpointer/postgres/checkpointer.py@@ -599,8 +599,9 @@ class PostgresCheckpointer:thread_id: str,*,question_id: str,+ run_id: str,) -> bool:- """Clear pending state only while it still names ``question_id``.+ """Clear pending state only while it still names the question and run.The predicate and mutation run in one PostgreSQL ``UPDATE``. If aconcurrent writer has already checkpointed a replacement request,@@ -613,9 +614,11 @@ class PostgresCheckpointer:"UPDATE cubepi_threads ""SET pending_request = NULL, run_id = NULL, updated_at = now() ""WHERE thread_id = $1 "- "AND pending_request->>'question_id' = $2",+ "AND pending_request->>'question_id' = $2 "+ "AND run_id = $3",thread_id,question_id,+ run_id,)return result == "UPDATE 1"diff --git a/tests/checkpointer/test_postgres_pending_request.py b/tests/checkpointer/test_postgres_pending_request.pyindex 4c8cea6..5ee1005 100644--- a/tests/checkpointer/test_postgres_pending_request.py+++ b/tests/checkpointer/test_postgres_pending_request.py@@ -42,11 +42,13 @@ async def test_postgres_compare_and_clear_pending_request(clean_db) -> None: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"+ "t-1", question_id="q-replaced", run_id="run-1")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.clear_pending_request_if_matches(+ "t-1", question_id="q-current", run_id="run-1"+ )assert await cp.load_pending_request("t-1") is Noneassert await cp.load_pending_run_id("t-1") is None@@ -59,12 +61,25 @@ async def test_postgres_compare_and_clear_preserves_replacement(clean_db) -> Nonawait 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"+ "t-1", question_id="q-answered", run_id="run-1")assert (await cp.load_pending_request("t-1")) == _req(qid="q-follow-up")assert await cp.load_pending_run_id("t-1") == "run-1"+async def test_postgres_compare_and_clear_requires_matching_run(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-same"), run_id="run-new")++ assert not await cp.clear_pending_request_if_matches(+ "t-1", question_id="q-same", run_id="run-old"+ )+ assert (await cp.load_pending_request("t-1")) == _req(qid="q-same")+ assert await cp.load_pending_run_id("t-1") == "run-new"++@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 64a059a..106437f 100644--- a/website/docs/guides/checkpointing/postgres.md+++ b/website/docs/guides/checkpointing/postgres.md@@ -189,10 +189,11 @@ keys.## Conditional pending cleanupHosts 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.+`clear_pending_request_if_matches(thread_id, question_id=..., run_id=...)`. It+clears the pending request and owning run ID only if both stored identifiers+still match. The comparison and clear are one PostgreSQL update, so a newer+request written by another worker is never erased by stale cleanup, even if it+reuses the same question ID in a different run.## Forksdiff --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 1fb16ca..8164cc5 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@@ -169,10 +169,10 @@ extra = cubepi_threads.extra || EXCLUDED.extra## 条件式清理 pending request跨 worker 协调 HITL 恢复的宿主可以调用-`clear_pending_request_if_matches(thread_id, question_id=...)`。只有数据库中-当前 pending request 的问题 ID 仍然匹配时,它才会同时清除该请求及其所属-run ID。比较与清理在一条 PostgreSQL 更新中完成,因此旧 worker 的清理不会-误删另一个 worker 已写入的新 follow-up 请求。+`clear_pending_request_if_matches(thread_id, question_id=..., run_id=...)`。+只有数据库中当前 pending request 的问题 ID 和所属 run ID 都仍然匹配时,+它才会清除这两个字段。比较与清理在一条 PostgreSQL 更新中完成,因此即使+另一个 worker 的新 run 复用了相同问题 ID,旧 worker 也不会误删新请求。## Fork