Skip to content

feat(agent-org): add transactional turn context and member FIFO - #841

Draft
ShiboSheng wants to merge 2 commits into
codex/issue-791-pr3-selected-rebuildfrom
codex/issue-758-turn-context-fifo
Draft

feat(agent-org): add transactional turn context and member FIFO#841
ShiboSheng wants to merge 2 commits into
codex/issue-791-pr3-selected-rebuildfrom
codex/issue-758-turn-context-fifo

Conversation

@ShiboSheng

@ShiboSheng ShiboSheng commented Aug 19, 2026

Copy link
Copy Markdown
Collaborator

Problem

Fixes #758

Agent Org turns currently persist a generic Turn Intent, but they do not have one canonical durable record that says which run, participant, turn kind, authority source, and activation episode own that turn. That leaves later Task, direct-member, group, and inbox producers without a trustworthy identity boundary, and it makes Member ordering vulnerable to per-source queues or half-written state.

PR3 needs to establish that ownership boundary without implementing the later PR4–PR10 product features, without adding a second runtime, and without making ordinary SDE sessions depend on Agent Org context storage.

Solution

  • Add the canonical agent_org_runtime_turn_contexts table with strict row-shape checks, exhaustive typed decoding, source identity, activation/actor versioning, and one context per Agent Org Turn Intent.
  • Add one (org_run_id, member_id) dispatch allocator. Task execution and every future user-directed Member source share the same monotonically increasing FIFO; Coordinator Root turns never consume a Member sequence.
  • Admit the base Turn Intent, Member sequence, and companion context in one BEGIN IMMEDIATE transaction. Exact replay returns the existing identity and sequence; partial pairs, mismatched replay, unknown members, wrong sessions, and invalid authority fail closed without a repair guess or second allocation.
  • Wire Starting initial Root admission into the existing Starting transaction, and route later Root submit, Queue, Force Send, and mid-turn steering through the same Coordinator admission boundary.
  • Keep ordinary SDE restart reconciliation fenced to org_run_id IS NULL; run Agent Org recovery only after its schema is initialized, preserving typed initial Root recovery and isolating contextless historical rows.
  • Accept only an empty Agent Org runtime namespace or the exact current 15-table manifest. The unpublished PR828-to-PR3 forward-upgrade branch has been removed; known legacy namespace retirement used by the supported release downgrade/return boundary remains isolated.
  • Preserve cancelled as the authoritative terminal outcome when user Stop or Force Send interrupts a turn.

This PR is intentionally stacked on #836 (codex/issue-791-pr3-selected-rebuild) so its diff contains only PR3.

Potential risks

  • Persistence: a partial, changed, or unknown agent_org_runtime_* schema now rejects startup instead of being guessed or upgraded. Recovery is to restore a backup or use a fresh namespace; do not hand-edit the tables.
  • Historical local data: contextless terminal Agent Org turns remain readable history but cannot authorize new work. A contextless running turn remains unknown/in-flight and may require explicit local cleanup; PR3 does not invent its missing identity.
  • Member entry points: old Member wake/direct/group/inbox calls that cannot prove typed authority fail before writing base/context/sequence state. Their supported product paths belong to PR4, PR8, and PR9.
  • Concurrency: Agent Org admission adds one short indexed BEGIN IMMEDIATE writer transaction. The 50-connection mixed-source test passed, and packaged-app active/idle measurements showed no new timer, poll, context query, or memory staircase.
  • Compatibility: the full PR3 -> official v1.2.6 -> PR3 UI test is blocked by fix(agent-org): [11/11] harden full-stack upgrade and rollback compatibility #840 because v1.2.6 cannot read the newer WorkStation members tab cache. PR3 does not modify that cache or PR825. Before the old UI failed, and after returning to PR3, the 15 runtime tables and key Agent Org business fingerprints remained intact. The complete cross-version UI matrix remains unverified until fix(agent-org): [11/11] harden full-stack upgrade and rollback compatibility #840.
  • Stack order: fix(agent-org): isolate runtime persistence namespace #836 must land before this PR, or this branch must be rebased to the resulting develop HEAD before merge.

Verification

Automated checks ran on source tree e8ea88f767abed22f57fc7a4f43205b610e2b08d, now published as 32565bdaefd2bc9d051b8f4cfcb6d5923b27d0e9 after a commit-message-only Husky rewrite:

  • cargo test -p agent_core core::coordination::agent_org_turn_contexts -- --nocapture — 8 passed, including strict replay, transaction rollback, delete cascade, shared FIFO, and 50 concurrent connections.
  • cargo test -p agent_core core::coordination::schema -- --nocapture — 8 passed, including fresh/current-only manifest, corruption rejection, atomic legacy cleanup, concurrency, and schema-init timing.
  • cargo test -p agent_core state::commands::session::message -- --nocapture — 21 passed, including steering/Force Send separation and authoritative cancellation.
  • cargo test -p agent_core agent_org -- --nocapture --test-threads=1 — 232 passed.
  • cargo test -p session_persistence turn_intents -- --nocapture — 13 passed, including ordinary SDE recovery with no context schema dependency.
  • cargo check --workspace --all-targets — passed.
  • cargo clippy -p agent_core -p session_persistence -p org2 --all-targets -- -D warnings — passed.
  • rustfmt --edition 2021 --check <12 changed Rust files> — passed.
  • git diff --check fe20ec604902d956b98aa7fab00bdd1469d9f7e3...HEAD — passed.
  • cargo fmt --all -- --check — not clean because seven pre-existing, unchanged files have formatting drift; those unrelated files were deliberately not reformatted in this PR.
  • Frontend lint/rendered E2E — not applicable: this PR changes no TypeScript, TSX, locale, IPC, or visible UI contract.

Packaged-app real-machine verification:

  • BuildFast: /private/tmp/ORG2-PR3-758-no-pr828-upgrade.app, executable SHA-256 dc282e927a3c5eab7d5ad4f9180ea15c1d53dc970e8d789f5a01d029de578bc4.
  • Real UI passed Starting initial Root, later Root, natural Queue, Force Send, ordinary SDE, user Stop, Command+5 active-path observation, clean quit, and three launches/restarts.
  • Old Member entry attempted through the real wake path returned the typed context error with zero base Turn, context, or allocator half-write.
  • SQLite finished with quick_check=ok, the exact 15 runtime tables, 50 contexts, zero active Turn Intents, and zero ordinary-SDE contexts. Coordinator contexts had null dispatch/sequence fields and created no allocator row.
  • Run, Agent Org Turn, context, Task, Inbox, materialization, initial-input, and all-Turn logical fingerprints matched before and after restart.
  • Command+5 showed no context endpoint/polling. Five-minute visible and hidden idle windows kept CPU near zero and RSS stable without staircase growth.
  • Official v1.2.6 downgrade UI leg: blocked by fix(agent-org): [11/11] harden full-stack upgrade and rollback compatibility #840 as described under risks; no PR3 cache change was made.

Screenshots are not attached because PR3 has no new visible UI. The acceptance evidence is the production UI side effects correlated with SQLite, logs, Command+5, restart fingerprints, and performance samples.

Persist a typed context for every Agent Org turn and allocate Member dispatches from a single per-run/member FIFO in the same immediate transaction as the base Turn Intent.

Wire Starting and Coordinator Root admission, keep ordinary SDE turns context-free, and fail closed before persisting legacy Member group/inbox work that lacks typed authority.

Use one strict current-schema manifest and isolated legacy cleanup without adding a second runtime or scheduler.

Refs: #758

Pre-commit hook ran. Total eslint: 5, total circular: 0
Accept only an empty Agent Org runtime namespace or the exact current 15-table manifest.

Remove the obsolete 13-table manifest branch, upgrade-only schema builder, logging, and test. Keep strict corruption checks and supported legacy namespace cleanup unchanged.

Refs: #758

Pre-commit hook ran. Total eslint: 5, total circular: 0
@ShiboSheng
ShiboSheng force-pushed the codex/issue-758-turn-context-fifo branch from 569045e to 32565bd Compare August 19, 2026 17:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(agent-org): [3/10] add Agent Org Turn context and a single Member FIFO

1 participant