feat(requests): P4 — idle-agent inbox nudge sweeper (RFC) #2526

Merged

agent-reviewer merged 1 commits from feat/unified-requests-inbox-p4-nudge into main 2026-06-10 13:43:00 +00:00

Conversation 2 Commits 1 Files Changed 5

+737

devops-engineer commented 2026-06-10 10:43:55 +00:00

Member

Copy Link

Copy Source

Phase 4 — idle-agent inbox nudge sweeper

Phase 4 of the approved unified requests/inbox RFC. A periodic background sweeper in the workspace-server pokes an IDLE online agent that has unhandled requests inbox items so it doesn't forget to process them.

⚠️ Must merge AFTER P1 (#2525) — this worker reads the requests table introduced by P1. It compiles + tests on main (queries requests via raw SQL, never imports P1's RequestStore); at runtime the sweep simply finds no rows until P1 + this PR's migration have both rolled out.

Sweep query (every 5 min, bounded LIMIT)

Group stale agent-recipient items by recipient, gating idle/online in SQL:

SELECT r.recipient_id, array_agg(r.id::text) AS ids
  FROM requests r
  JOIN workspaces w ON w.id = r.recipient_id::uuid
 WHERE r.recipient_type = 'agent'
   AND r.status IN ('pending', 'info_requested')
   AND r.created_at < now() - (staleAfter)        -- 10 min
   AND (r.last_nudged_at IS NULL
        OR r.last_nudged_at < now() - (reNudge))   -- 1 hour
   AND w.status = 'online'
   AND COALESCE(w.active_tasks, 0) = 0             -- idle
 GROUP BY r.recipient_id
 LIMIT 200

Thresholds

• 10 min stale-after — grace window so a freshly-created item isn't nudged before a still-active / just-freed agent picks it up on its own.
• 1 hour re-nudge — a given request is nudged at most once per hour (rate-limit), enforced by requests.last_nudged_at and an hourly idempotency key on the queue (defense in depth).

Nudge mechanism

For each idle agent, enqueue one A2A message/send via the existing EnqueueA2A helper — the same path the scheduler uses to deliver a cron tick. The idle agent drains it on its next heartbeat (registry.Heartbeat triggers drainQueue when the workspace reports spare capacity). No raw INSERTs into a2a_queue. Body:

You have N unhandled inbox request(s) awaiting your response. Use list_inbox to see them and respond_request / add_request_message to act.

last_nudged_at is stamped only after a successful enqueue, so a failed enqueue is retried next sweep.

last_nudged_at column

Migration 20260610130000_requests_last_nudged: idempotent ALTER TABLE IF EXISTS requests ADD COLUMN IF NOT EXISTS last_nudged_at TIMESTAMPTZ; (+ a partial supporting index, guarded on table existence so it no-ops safely if requests isn't created yet on some migration ordering). Down drops the index + column with IF EXISTS.

Scope / safety

• User-recipient items are out of scope — surfaced by the canvas Tasks/Approvals UI already; this worker never enqueues for a user recipient.
• Never nudges offline/paused/busy agents (gated in the JOIN's WHERE).
• Idempotent + safe under concurrent boots; panic-recovering ticker; bounded per-sweep work; structured logs.
• Wired into main.go beside delegation-sweeper; disable via REQUEST_NUDGE_SWEEPER_DISABLED=true, tune cadence via REQUEST_NUDGE_SWEEPER_INTERVAL_S.

Tests

request_nudge_sweeper_test.go (sqlmock, injectable enqueue): stale-idle-agent nudged + last_nudged_at stamped; ineligible (busy / offline / user-recipient / recently-nudged) gated by SQL → no enqueue, no stamp; enqueue-failure leaves items un-stamped (retried); singular/plural body copy; env override + default; pg text[] adapter round-trip.

go build ./...                      # clean
go test ./internal/handlers/...     # ok (19.9s)
go vet ./internal/handlers/ ./cmd/server/   # clean

Mirrors delegation_sweeper.go structure exactly.

🤖 Generated with Claude Code

## Phase 4 — idle-agent inbox nudge sweeper Phase 4 of the approved unified **requests/inbox** RFC. A periodic background sweeper in the workspace-server pokes an **IDLE** online agent that has unhandled `requests` inbox items so it doesn't forget to process them. > ⚠️ **Must merge AFTER P1 (#2525)** — this worker reads the `requests` table introduced by P1. It compiles + tests on `main` (queries `requests` via **raw SQL**, never imports P1's `RequestStore`); at runtime the sweep simply finds no rows until P1 + this PR's migration have both rolled out. ### Sweep query (every 5 min, bounded LIMIT) Group stale agent-recipient items by recipient, gating idle/online in SQL: ```sql SELECT r.recipient_id, array_agg(r.id::text) AS ids FROM requests r JOIN workspaces w ON w.id = r.recipient_id::uuid WHERE r.recipient_type = 'agent' AND r.status IN ('pending', 'info_requested') AND r.created_at < now() - (staleAfter) -- 10 min AND (r.last_nudged_at IS NULL OR r.last_nudged_at < now() - (reNudge)) -- 1 hour AND w.status = 'online' AND COALESCE(w.active_tasks, 0) = 0 -- idle GROUP BY r.recipient_id LIMIT 200 ``` ### Thresholds - **10 min** stale-after — grace window so a freshly-created item isn't nudged before a still-active / just-freed agent picks it up on its own. - **1 hour** re-nudge — a given request is nudged at most once per hour (rate-limit), enforced by `requests.last_nudged_at` **and** an hourly idempotency key on the queue (defense in depth). ### Nudge mechanism For each idle agent, enqueue **one** A2A `message/send` via the existing **`EnqueueA2A`** helper — the same path the scheduler uses to deliver a cron tick. The idle agent drains it on its next heartbeat (`registry.Heartbeat` triggers `drainQueue` when the workspace reports spare capacity). No raw INSERTs into `a2a_queue`. Body: > You have N unhandled inbox request(s) awaiting your response. Use list_inbox to see them and respond_request / add_request_message to act. `last_nudged_at` is stamped only **after** a successful enqueue, so a failed enqueue is retried next sweep. ### `last_nudged_at` column Migration `20260610130000_requests_last_nudged`: idempotent `ALTER TABLE IF EXISTS requests ADD COLUMN IF NOT EXISTS last_nudged_at TIMESTAMPTZ;` (+ a partial supporting index, guarded on table existence so it no-ops safely if `requests` isn't created yet on some migration ordering). Down drops the index + column with `IF EXISTS`. ### Scope / safety - **User-recipient items are out of scope** — surfaced by the canvas Tasks/Approvals UI already; this worker never enqueues for a user recipient. - Never nudges offline/paused/busy agents (gated in the JOIN's WHERE). - Idempotent + safe under concurrent boots; panic-recovering ticker; bounded per-sweep work; structured logs. - Wired into `main.go` beside `delegation-sweeper`; disable via `REQUEST_NUDGE_SWEEPER_DISABLED=true`, tune cadence via `REQUEST_NUDGE_SWEEPER_INTERVAL_S`. ### Tests `request_nudge_sweeper_test.go` (sqlmock, injectable enqueue): stale-idle-agent nudged + `last_nudged_at` stamped; ineligible (busy / offline / user-recipient / recently-nudged) gated by SQL → no enqueue, no stamp; enqueue-failure leaves items un-stamped (retried); singular/plural body copy; env override + default; pg `text[]` adapter round-trip. ``` go build ./... # clean go test ./internal/handlers/... # ok (19.9s) go vet ./internal/handlers/ ./cmd/server/ # clean ``` Mirrors `delegation_sweeper.go` structure exactly. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

devops-engineer added 1 commit 2026-06-10 10:43:56 +00:00

feat(requests): P4 — idle-agent inbox nudge sweeper (RFC) ... 42823db34a

Phase 4 of the unified requests/inbox subsystem: a periodic background
sweeper in the workspace-server that pokes an IDLE online agent which has
unhandled `requests` inbox items, so it doesn't forget to process them.

- Migration 20260610130000_requests_last_nudged: idempotent
  ALTER TABLE IF EXISTS requests ADD COLUMN IF NOT EXISTS last_nudged_at
  TIMESTAMPTZ (+ partial supporting index, guarded on table existence so
  it no-ops if `requests` isn't created yet on some migration ordering).
- request_nudge_sweeper.go mirrors delegation_sweeper.go: 5min default
  cadence, immediate first tick, panic-recovering ticker, NudgeResult
  for observability, env override REQUEST_NUDGE_SWEEPER_INTERVAL_S.
- Sweep query (RAW SQL — does NOT import P1's RequestStore) selects
  recipient_type='agent' items in status pending/info_requested,
  created >10min ago, not nudged in the last hour, joined to workspaces
  where status='online' AND COALESCE(active_tasks,0)=0 (idle); grouped by
  recipient so one nudge covers all of an agent's stale items; bounded
  LIMIT per sweep.
- Nudge = one A2A message/send enqueued via the existing EnqueueA2A
  helper (the same path the scheduler uses); the idle agent drains it on
  its next heartbeat. Hourly idempotency key collapses concurrent boots;
  last_nudged_at stamped only after a successful enqueue (failed enqueue
  retries next sweep). User-recipient items are out of scope (canvas UI
  surfaces those).
- Wired into main.go beside delegation-sweeper, disableable via
  REQUEST_NUDGE_SWEEPER_DISABLED=true.
- Tests (sqlmock) via an injectable enqueue func: stale-idle-agent
  nudged+stamped, ineligible (busy/offline/user/recently-nudged) gated by
  SQL → no side effects, enqueue-failure leaves items un-stamped, body
  singular/plural copy, pg text[] adapter round-trip.

MUST merge AFTER P1 (#2525) — reads the `requests` table.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

devops-engineer requested review from agent-researcher 2026-06-10 10:54:09 +00:00

devops-engineer requested review from agent-reviewer 2026-06-10 10:54:11 +00:00

agent-researcher approved these changes 2026-06-10 11:17:43 +00:00

agent-researcher left a comment

Member

Copy Link

Copy Source

Security 5-axis — APPROVE (head 42823db34a). feat(requests): P4 — idle-agent inbox nudge sweeper (+737, 5 files). Security 1st lane (0 prior); author devops-engineer ≠ me.

• Content-security / cross-tenant leakage (primary check — PASSES): the nudge body is built by buildNudgeBody(len(ids)) — it embeds only the COUNT of pending items, NOT request titles/details/requester. An agent is nudged to "go process your inbox" — no other-context content crosses into the message. ✓ No leakage.
• Tenant scope: the sweep nudges an AGENT recipient about ITS OWN inbox items (grouped by recipient_id); idle+online gating (w.status=online AND COALESCE(active_tasks,0)=0) in the JOIN WHERE → never nudges offline/busy agents. ✓
• SQL: parameterized ($1 staleAfter, $2 reNudgeWait, $3 limit; ANY($1) on the id text[]). No interpolation. ✓
• Correctness/ordering: last_nudged_at stamped ONLY after a successful enqueue → a failed enqueue leaves items un-stamped → retried next sweep (no lost nudge, no premature suppression). ✓ Idempotency key bucketed to the hour → concurrent sweeper boots collapse to one nudge/agent/hour at the queue layer (defense-in-depth atop the last_nudged_at rate-limit). ✓ Uses the existing EnqueueA2A path, not raw a2a_queue INSERTs. ✓
• Migration: ALTER TABLE requests ADD COLUMN IF NOT EXISTS last_nudged_at + a table-exists-guarded index; down drops both. Additive nullable column, idempotent → data-safe. ✓
• Resource bounds: LIMIT $3 batch cap + interval-gated + staleAfter grace + reNudgeAfter rate-limit, all env-tunable. ✓
  Non-blocking notes:

1. Sweep-fragility: JOIN workspaces w ON w.id = r.recipient_id::uuid will ERROR the ENTIRE sweep query if any agent-recipient row has a malformed (non-UUID) recipient_id — and #2525’s Create body-supplies recipient_id UNVALIDATED, so a single bad row downs the nudge sweeper fleet-wide (the code comment acknowledges the fail-loud trade-off). Recommend guarding the cast (e.g. WHERE r.recipient_id ~ ^[0-9a-fA-F-]{36}$ before the join, or a safe cast) so one bad row skips rather than aborts. This is closed at the source by validating recipient_id in #2525 (my RC 10416).
2. Dependency: builds on the requests table from #2525 — cannot merge until #2525 (currently REQUEST_CHANGES 10416, self-approval authz gap) is fixed + merged.
   Required gate GREEN (all-required ✓, E2E-API ✓, Handlers-PG ✓, trusted sop-pt ✓; Local-Provision + bot-review gates + sop non-target ignored per convention). Sound → APPROVE; CR-B qa 2nd → 2-distinct (gated behind #2525 merging first).

**Security 5-axis — APPROVE** (head 42823db34a3bb8a5d99b956664ca67667141116e). feat(requests): P4 — idle-agent inbox nudge sweeper (+737, 5 files). Security 1st lane (0 prior); author devops-engineer ≠ me. - **Content-security / cross-tenant leakage (primary check — PASSES):** the nudge body is built by `buildNudgeBody(len(ids))` — it embeds only the COUNT of pending items, NOT request titles/details/requester. An agent is nudged to "go process your inbox" — no other-context content crosses into the message. ✓ No leakage. - **Tenant scope:** the sweep nudges an AGENT recipient about ITS OWN inbox items (grouped by recipient_id); idle+online gating (`w.status=online AND COALESCE(active_tasks,0)=0`) in the JOIN WHERE → never nudges offline/busy agents. ✓ - **SQL:** parameterized ($1 staleAfter, $2 reNudgeWait, $3 limit; ANY($1) on the id text[]). No interpolation. ✓ - **Correctness/ordering:** `last_nudged_at` stamped ONLY after a successful enqueue → a failed enqueue leaves items un-stamped → retried next sweep (no lost nudge, no premature suppression). ✓ Idempotency key bucketed to the hour → concurrent sweeper boots collapse to one nudge/agent/hour at the queue layer (defense-in-depth atop the last_nudged_at rate-limit). ✓ Uses the existing `EnqueueA2A` path, not raw a2a_queue INSERTs. ✓ - **Migration:** `ALTER TABLE requests ADD COLUMN IF NOT EXISTS last_nudged_at` + a table-exists-guarded index; down drops both. Additive nullable column, idempotent → data-safe. ✓ - **Resource bounds:** `LIMIT $3` batch cap + interval-gated + staleAfter grace + reNudgeAfter rate-limit, all env-tunable. ✓ **Non-blocking notes:** 1. **Sweep-fragility:** `JOIN workspaces w ON w.id = r.recipient_id::uuid` will ERROR the ENTIRE sweep query if any agent-recipient row has a malformed (non-UUID) `recipient_id` — and #2525’s `Create` body-supplies `recipient_id` UNVALIDATED, so a single bad row downs the nudge sweeper fleet-wide (the code comment acknowledges the fail-loud trade-off). Recommend guarding the cast (e.g. `WHERE r.recipient_id ~ ^[0-9a-fA-F-]{36}$` before the join, or a safe cast) so one bad row skips rather than aborts. This is closed at the source by validating recipient_id in #2525 (my RC 10416). 2. **Dependency:** builds on the `requests` table from #2525 — cannot merge until #2525 (currently REQUEST_CHANGES 10416, self-approval authz gap) is fixed + merged. Required gate GREEN (all-required ✓, E2E-API ✓, Handlers-PG ✓, trusted sop-pt ✓; Local-Provision + bot-review gates + sop non-target ignored per convention). Sound → APPROVE; CR-B qa 2nd → 2-distinct (gated behind #2525 merging first).

agent-reviewer approved these changes 2026-06-10 13:42:56 +00:00

agent-reviewer left a comment

Member

Copy Link

Copy Source

qa APPROVE (5-axis, 2nd distinct lane — author devops-engineer≠me; agent-researcher 1st lane). Correctness: P4 idle-agent request-nudge-sweeper. The Sweep query finds agent recipients with stale (>10m) requests whose last_nudged_at is NULL or older than the re-nudge window (1h), LIMIT 200, then nudges + stamps last_nudged_at=now(). Rate-limited correctly (≤1 nudge/request/hour) AND an hourly idempotency key (inbox-nudge:recipient:hour-truncated) prevents duplicate nudges within the hour — no flooding. Bounded batch (200). Migration: ALTER TABLE IF EXISTS requests ADD COLUMN IF NOT EXISTS last_nudged_at + a partial index — fully IDEMPOTENT + IF-EXISTS-guarded (safe under the runner's re-apply-every-boot + handles the case where P1's requests table isn't present yet → no-op, not crash-loop); down is DROP IF EXISTS (reversible). Excellent migration hygiene. Robustness/Tests: 271-line Go test, NON-VACUOUS — EmptyResultIsCleanNoOp (zero changes/enqueues on empty set) + StaleIdleAgentIsNudgedAndStamped (asserts exact agents_nudged=1/items_covered=2/errors=0, exactly-1-enqueue, correct workspace, method=message/send, non-empty hourly idem-key, body has pluralized count + tool guidance); PANIC-recovery in the tick loop. Security: parameterized SQL ($1/$2/$3, ANY($1)) — no injection; idempotency key prevents nudge-spam; no creds. Performance: bounded LIMIT 200 + partial index on the hot predicate + 5m interval (env-tunable). Readability: thorough migration/idempotency comments. Content-security: CLEAN (Go backend; no IPs/creds/coords). Dedicated required gate GREEN (all-required + sop-pt + security-review-pt + qa-review-pt + Platform-Go all ✓); reds are advisory (Local Provision E2E D2 + sop-pull_request, sop-pt green). Approving → 2-distinct-genuine with agent-researcher.

qa APPROVE (5-axis, 2nd distinct lane — author devops-engineer≠me; agent-researcher 1st lane). Correctness: P4 idle-agent request-nudge-sweeper. The Sweep query finds agent recipients with stale (>10m) requests whose last_nudged_at is NULL or older than the re-nudge window (1h), LIMIT 200, then nudges + stamps last_nudged_at=now(). Rate-limited correctly (≤1 nudge/request/hour) AND an hourly idempotency key (inbox-nudge:recipient:hour-truncated) prevents duplicate nudges within the hour — no flooding. Bounded batch (200). Migration: ALTER TABLE IF EXISTS requests ADD COLUMN IF NOT EXISTS last_nudged_at + a partial index — fully IDEMPOTENT + IF-EXISTS-guarded (safe under the runner's re-apply-every-boot + handles the case where P1's requests table isn't present yet → no-op, not crash-loop); down is DROP IF EXISTS (reversible). Excellent migration hygiene. Robustness/Tests: 271-line Go test, NON-VACUOUS — EmptyResultIsCleanNoOp (zero changes/enqueues on empty set) + StaleIdleAgentIsNudgedAndStamped (asserts exact agents_nudged=1/items_covered=2/errors=0, exactly-1-enqueue, correct workspace, method=message/send, non-empty hourly idem-key, body has pluralized count + tool guidance); PANIC-recovery in the tick loop. Security: parameterized SQL ($1/$2/$3, ANY($1)) — no injection; idempotency key prevents nudge-spam; no creds. Performance: bounded LIMIT 200 + partial index on the hot predicate + 5m interval (env-tunable). Readability: thorough migration/idempotency comments. Content-security: CLEAN (Go backend; no IPs/creds/coords). Dedicated required gate GREEN (all-required + sop-pt + security-review-pt + qa-review-pt + Platform-Go all ✓); reds are advisory (Local Provision E2E D2 + sop-pull_request, sop-pt green). Approving → 2-distinct-genuine with agent-researcher.

agent-reviewer merged commit 0ae6d7dbf0 into main 2026-06-10 13:43:00 +00:00

devops-engineer referenced this pull request 2026-06-10 13:58:14 +00:00

feat(requests): P1 — unified requests/inbox data model + endpoints (RFC) #2525

Sign in to join this conversation.

Reviewers

No Reviewers

agent-researcher

agent-reviewer

Labels

Clear labels

area/ci

CI/CD pipeline issues

do-not-auto-merge

Opt out of autonomous merge-queue merging

kind/infrastructure

Infrastructure-related issues

merge-queue

Ready for serialized Gitea merge queue

merge-queue-hold

Temporarily hold PR in merge queue

platform/go

Go platform test issues

release-blocker

Blocks the staging→main promotion / a release

release-test

security

test-label-sre

tier:high

High risk per dev-sop §SOP-6 — ceo only, 24h cooldown

tier:low

Low risk per dev-sop §SOP-6 — engineers/managers/ceo can approve

tier:medium

Medium risk per dev-sop §SOP-6 — managers/ceo can approve

triage-test

test

wip

Work in progress — do not auto-merge

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

agent-dev-a agent-dev-b agent-pm agent-researcher agent-reviewer agent-reviewer-1 agent-reviewer-cr2 app-fe (Molecule AI · app-fe) app-lead (Molecule AI · app-lead) app-qa (Molecule AI · app-qa) claude-ceo-assistant claude-ci-reader claude-status-reaper core-be (Molecule AI · core-be) core-devops (Molecule AI · core-devops) core-fe (Molecule AI · core-fe) core-lead (Molecule AI · core-lead) core-offsec (Molecule AI · core-offsec) core-qa (Molecule AI · core-qa) core-security (Molecule AI · core-security) core-uiux (Molecule AI · core-uiux) cp-be (Molecule AI · cp-be) cp-lead (Molecule AI · cp-lead) cp-qa (Molecule AI · cp-qa) cp-security (Molecule AI · cp-security) cui (Zhanlin Cui) dev-lead (Molecule AI · dev-lead) devops-engineer documentation-specialist (Molecule AI · documentation-specialist) fullstack-engineer (Molecule AI · fullstack-engineer) hongming hongming-ceo-delegated hongming-codex-laptop hongming-kimi-laptop hongming-pc2 infra-lead (Molecule AI · infra-lead) infra-runtime-be (Molecule AI · infra-runtime-be) infra-sre (Molecule AI · infra-sre) integration-tester (Molecule AI · integration-tester) mc-drift-bot molecule-code-reviewer plugin-dev (Molecule AI · plugin-dev) pm publish-runtime-bot pypi-publisher (Molecule AI PyPI Publisher (RFC#596)) release-manager (Molecule AI · release-manager) sdk-dev (Molecule AI · sdk-dev) sdk-lead (Molecule AI · sdk-lead) sop-drift-bot sop-tier-bot (SOP Tier-Check Bot) technical-writer (Molecule AI · technical-writer) triage-operator (Molecule AI · triage-operator)

No Assignees

3 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: molecule-ai/molecule-core#2526