Skip to content

CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.

fix(checkpointer): fence pending clear by run

xfgonga6281da14a6e
diff --git a/cubeloop/checkpointer/postgres/checkpointer.py b/cubeloop/checkpointer/postgres/checkpointer.py
index 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 a
concurrent 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.py
index 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 None
assert 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) -> Non
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"
+ "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.asyncio
async 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.md
index 64a059a..106437f 100644
--- a/website/docs/guides/checkpointing/postgres.md
+++ b/website/docs/guides/checkpointing/postgres.md
@@ -189,10 +189,11 @@ keys.
## 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.
+`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.
## Forks
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.md
index 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