Skip to content

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

fix(checkpointer): compare and clear pending requests

xfgong11948b08fe79
diff --git a/cubeloop/checkpointer/postgres/checkpointer.py b/cubeloop/checkpointer/postgres/checkpointer.py
index 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.py
index 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.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 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 prior
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.
+
## 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.md
index 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` 列用于支持