Skip to content

feat(agent-org): add idempotent task graph writers - #956

Draft
ShiboSheng wants to merge 1 commit into
codex/issue-761-archive-team-deletefrom
codex/issue-762-writer-idempotency-activation
Draft

feat(agent-org): add idempotent task graph writers#956
ShiboSheng wants to merge 1 commit into
codex/issue-761-archive-team-deletefrom
codex/issue-762-writer-idempotency-activation

Conversation

@ShiboSheng

Copy link
Copy Markdown
Collaborator

Problem

PR7 of the Agent Org design tracked by #762 requires model-initiated durable writes to be exactly-once and requires configured Task Graph Writers to edit graph state without gaining another member's Task-owner lifecycle authority.

On the PR6 baseline, retries of the same tool call could re-enter a business mutation because the mutation and its replay evidence were not committed together. Writer authority and sparse graph patches also crossed several independent paths, and an Idle Root user submission passed admission but was rejected by the execute-time lifecycle fence before the Provider could decide whether to create formal work. Cancellation/replacement could additionally leave now-undrainable formal Inbox rows blocking quiescence after the old Provider Turn ended naturally.

Solution

  • Add a strict canonical Agent Org receipt table keyed by Team run, Session, Turn intent, and tool call. The receipt lookup, business mutation, deterministic result, and receipt insert share one BEGIN IMMEDIATE transaction. An identical retry replays without mutating; changed canonical parameters conflict; stale authority and storage failures leave no receipt.
  • Route Task graph creation/update, message writes, completion requests, Inbox repair, and Agent Org plan creation/approval writes through the same exactly-once boundary.
  • Resolve Coordinator and configured additional Writer authority from the frozen Team launch snapshot plus the persisted typed Turn. A Writer receives one union tool schema, may change graph fields, and may execute only the lifecycle of the exact Task bound to its own Turn.
  • Make pending graph patches sparse and merge metadata subkeys instead of replacing unrelated fields.
  • Keep an Idle Root Q&A Turn lifecycle-neutral, then atomically activate Idle -> Running inside the first formal Task writer transaction. The same Team can consequently repeat Working -> Idle -> Working -> Idle without creating a new Team or Root Session.
  • Let an exact cancelled Task Turn persist its final assistant transcript while continuing to reject formal stale mutations, and resolve only the obsolete pre-user-directed-work formal Inbox rows once the member owns no remaining formal work.

The production rollout gate remains off by default. This PR enables only the Root Coordinator and configured Writer boundaries required by PR7; Member Direct and Group user-directed work remain out of scope.

Potential risks

  • The strict Agent Org runtime manifest grows from 19 to 20 tables. Partial or mismatched isolated runtime manifests continue to fail closed rather than being migrated heuristically.
  • The change crosses Task FSM, plan approval, Inbox, completion, Turn admission, and lifecycle reconciliation code. Concurrency regressions are mitigated by immediate SQLite transactions, generation/Turn revalidation, rollback-injection tests, and full crate/App test suites, but this is still the main review risk.
  • Receipt result and error payloads are bounded. A result above the bound fails the transaction and rolls back the business mutation instead of committing partial state.
  • The real Provider journey was run on a packaged macOS Tauri App with one Provider/model configuration. Windows/Linux packaged behavior was not manually exercised.
  • Rollback before rollout is to revert this commit and use the matching isolated Agent Org runtime database. The rollout gate remaining off limits production exposure while the stack is reviewed.

Stacked PR

Verification

Automated checks:

  • cargo test -p agent_core --lib — 3,245 passed, 2 ignored, 0 failed.
  • pnpm run cargo:test — 1,113 passed, 1 ignored, 0 failed.
  • cargo clippy -p agent_core --all-targets -- -D warnings — passed.
  • cargo fmt --all -- --check — passed.
  • pnpm test — 1,116 test files / 8,777 tests passed.
  • pnpm lint — 0 errors; 5 unrelated baseline warnings.
  • pnpm typecheck — passed.
  • git diff --check — passed.

Real packaged-App / Provider journey:

  • Built an isolated packaged Tauri App with the rollout gate enabled only for that artifact and selected orlando > GPT 5.6 Luna through visible UI.
  • Created one Root Coordinator + Builder Team and submitted a small Flappy Bird task through the real Root composer.
  • Exercised PR5 Pause and Resume through visible Team controls while work was active, then switched to the Builder Session and back to the Root through visible UI.
  • Confirmed the first cycle reached Idle with one completed Task, zero active members, zero unresolved Inbox rows, and five receipts.
  • In the same Team and Root Session, submitted a new day/night theme feature. The Idle Root Provider Turn ran while the Team remained Idle; the first formal Task write advanced activation generation exactly once from 3 to 4; the Team returned to Idle with two completed Tasks, zero unresolved Inbox rows, and nine receipts.
  • Verified the resulting workspace contains the visible theme toggle, night palette, and localStorage persistence while preserving the original game controls.
  • Archived through visible UI, quit and relaunched the same packaged App, and confirmed the Team remained Archived and read-only.
  • After explicit user confirmation, permanently deleted through the visible checkbox and confirmation button. Read-back showed zero Run, Session, Task, Inbox, Turn-context, receipt, Pause, and Archive rows; project files remained intact.

Idle performance sampling across five two-second samples showed stable RSS (233,104-233,120 KiB) and 3.4-4.3% process CPU while the packaged UI and automation bridge were open. PR7 adds no polling loop, timer, worker, or retained cache; receipt lookup is a primary-key read and lifecycle cleanup runs only at a Turn boundary.

No UI source files changed, so no product UI screenshots are attached to this backend/runtime PR.

Pre-commit hook ran. Total eslint: 5, total circular: 0
@ShiboSheng
ShiboSheng requested a review from Neonforge98 August 25, 2026 10:47
@Harry19081 Harry19081 added enhancement New feature or request agent Agent runtime, behavior, memory, providers, or orchestration labels Aug 25, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agent Agent runtime, behavior, memory, providers, or orchestration enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants