Skip to content

feat(agent-org): flatten Team definitions and freeze capabilities - #825

Open
ShiboSheng wants to merge 8 commits into
codex/issue-756-pr1-clean-rebuildfrom
codex/issue-757-pr2-clean-stack
Open

feat(agent-org): flatten Team definitions and freeze capabilities#825
ShiboSheng wants to merge 8 commits into
codex/issue-756-pr1-clean-rebuildfrom
codex/issue-757-pr2-clean-stack

Conversation

@ShiboSheng

@ShiboSheng ShiboSheng commented Aug 16, 2026

Copy link
Copy Markdown
Collaborator

Problem

Agent Org Team definitions still used the recursive hierarchy contract while the long-lived runtime introduced by PR #824 needs a stable, flat launch contract. Writer grants and Member communication policy were not represented as independent, validated capabilities, and the legacy Agent Org runtime schema could prevent upgraded installations from starting a new Team. The superseded PR #786 also mixed its PR2 work with an incomplete PR1 merge and audit follow-ups that were not all intended to ship.

Solution

This PR is a clean PR2 stack on the exact current head of PR #824. It replaces recursive Team definitions with Coordinator + flat Members, assigns stable Member IDs, persists independent additional TaskGraphWriter grants and canonical undirected Member communication links, and freezes roster/grants/links into the immutable launch snapshot used by PR1 materialization and recovery.

The Team settings UI uses one canonical pair draft set: each Member row shows its Writer state and connected count, while a right-side panel edits at most the other 49 Members. The panel has no independent save action; the main Team form performs the single trusted full-replace save. New Teams and newly added Members explicitly materialize all default communication pairs.

The PR also retains the narrowly scoped P0 fixes from the original PR2: exact recognition and transactional reset of the official 15-column legacy Agent Org runtime envelope, plus exclusion of orphan Agent Org Member sessions from standalone SDE pagination. Ordinary Rust/CLI Sessions and all non-Agent-Org data remain untouched.

Supersedes #786

Fixes #757

Potential risks

  • This PR is stacked on Draft PR feat(agent-org): add authoritative Team lifecycle #824 and must not merge before that PR. Its base branch is codex/issue-756-pr1-clean-rebuild so the review diff contains PR2 only.
  • An exact v1.2.3-v1.2.5 15-column agent_org_runs fingerprint causes the four Agent Org runtime envelope tables to be rebuilt. Old Team runs are intentionally abandoned and are not recoverable by reverting this code; ordinary Rust/CLI Sessions are preserved. Unknown schemas fail closed and are never destructively reset.
  • Legacy recursive Team definition files are backed up byte-for-byte and reset to the new built-ins rather than guessed into a flat topology.
  • Writer grants and communication links are stored and frozen but remain inactive until their dedicated later PRs; this PR does not grant PR7 graph-write authority or enable PR9 peer messaging.
  • Focused Rust and frontend checks passed, but packaged/rendered WDIO acceptance and screenshots were not rerun for this clean-history rebuild. The PR remains Draft until that risk-proportionate UI evidence is completed.

Architecture and performance audit

  • Reviewed the relevant ownership, types, FSM integration, persistence, wire, initialization parity, resolver symmetry, naming, and dead-code layers against the two design documents.
  • No recursive hierarchy, communication matrix, new virtualization adapter, frontend dependency, polling loop, timer, or subscription was added.
  • Store mutations use one bounded spawn_blocking ownership boundary; no latency improvement is claimed from static inspection alone.
  • Team payloads remain bounded at 50 Members and 1,225 canonical edges. Runtime capability checks compile into HashSet indexes, and a communication panel renders at most 49 peers.

Verification

Passed:

cargo check -p agent_core --all-targets
cargo clippy -p agent_core --all-targets -- -D warnings
cargo test -p agent_core agent_org_runs                         # 43 passed
cargo test -p agent_core model_update                           # 2 passed
cargo test -p agent_core launch_validation_rejects              # 5 passed
cargo test -p agent_core core::definitions::orgs::tests         # 11 passed
cargo test -p org2 orphan_org_members_do_not_break_standalone_cursor_or_has_more
npm run typecheck
npm run lint -- --quiet
vitest: Agent Org RPC schema, canonical pair helpers, communication panel # 16 passed
vitest: Agent Org Run View store/hooks                              # 23 passed
node --check on the three changed Agent Org E2E/support files
git diff --check

cargo fmt --all -- --check was also run. It reports three pre-existing formatting differences in PR #824 files outside this PR diff:

  • core/tools/impls/coding/render_inline_canvas.rs
  • core/tools/tests/ui_metadata_tests.rs
  • session-persistence/src/turn_window.rs

Not run in this rebuild:

  • Packaged Tauri / rendered WDIO Agent Org acceptance
  • Live-provider Team launch and crash-recovery walkthrough
  • UI screenshots for theme and narrow viewport states

Commit provenance

Cherry-picking and adapting the selected work onto the current PR #824 head produced new commit hashes. The exact mapping is:

Original commit Commit in this PR Author Purpose / adaptation
5738470865863d4364704aa3f9a45326cc4edc5c b0ceb1df3 Shibo Sheng Flat Team capabilities, stable Member IDs, immutable capability snapshot, and Team communication UI.
8aa187a70d9b68e88c6cf040b6c523d844b00f3b ba47fe237 Shibo Sheng Exact legacy runtime reset and orphan Agent Org Session pagination fix.
f10afc2 2f0abb8da Neonforge Reject malformed model-update Members and preserve survivor runtime configuration; adapted so malformed IDs fail before unknown-ID lookup.
e228c83 d6c82b184 Neonforge Reuse the shared write-path snapshot serializer without taking the rejected read-path changes.
226bdba a7656df0f Neonforge Route store mutations through one spawn_blocking owner.
a40a169 7b99d0f5a Neonforge Shared constant, frontend cap mirror, locale copy, and participant naming cleanup.
3413595 335b8ca3b Neonforge Separate the empty-ID test from the reserved-ID test without depending on the rejected validator commit.
N/A — new integration commit d4ab6de9c Shibo Sheng Adapt the selected work to the latest PR1 flat snapshot and async store contracts.

Intentionally excluded commits have no corresponding commit in this PR:

  • 4ac8568 — excluded because this PR is rebuilt directly on the selected, current PR feat(agent-org): add authoritative Team lifecycle #824 stack instead of using the old merge commit.
  • ce3f5d3 — excluded in its entirety; none of its validator, read-path, quarantine, or migration changes are included.

Rollback

The branch can be reverted as a unit before merge. After an exact legacy runtime reset has committed, reverting the application cannot reconstruct discarded old Team run envelopes; recovery is to continue with newly created Team runs. Ordinary Session data is outside the reset scope.

ShiboSheng and others added 8 commits August 16, 2026 23:46
Replace recursive Agent Org hierarchies with stable flat Member rosters and
persist additional Writer grants independently from canonical undirected
Member communication links. Freeze the roster and both capability sets into
immutable launch snapshots while keeping PR7 Writer authority and PR9 peer
messaging fail closed.

Replace the communication matrix with per-Member connection summaries and a
right-side peer panel backed by one canonical draft pair set. Preserve trusted
full-replace validation, atomic persistence, stable Member identities, locale
parity, and the PR1 lifecycle contracts.

Verification:
- cargo test -p agent_core agent_org -- --nocapture (227 passed)
- npm test -- --run src/scaffold/WizardSystem/variants/AgentOrg/MemberCommunicationPanel.test.ts src/scaffold/WizardSystem/variants/AgentOrg/orgTree.test.ts src/api/tauri/rpc/schemas/agentOrgs.test.ts (16 passed)
- cargo check -p agent_core --all-targets && cargo check -p org2 --all-targets
- cargo clippy -p agent_core -p org2 --all-targets -- -D warnings
- npm run lint
- npm run check:circular
- ORGII_AGENT_ORG_REDESIGN=1 npm run tauri:build:fast
Reset only the exact published legacy Agent Org run schema while preserving ordinary sessions and unknown layouts. Keep retained Team member sessions out of standalone SDE pagination so orphan coordinators cannot consume page capacity or trigger Retry.

Verification:
- cargo test -p agent_core core::session::persistence -- --nocapture (34 passed)
- cargo test -p org2 agent_sessions::session_directory::aggregation::tests -- --nocapture (13 passed)
- npm test -- --run src/store/session/sessionAtom/__tests__/sidebarLoaders.test.ts src/api/tauri/rpc/__tests__/sessionAggregateSchemas.test.ts (28 passed)
- cargo check -p agent_core --all-targets && cargo check -p org2 --all-targets
- cargo clippy -p agent_core -p org2 --all-targets -- -D warnings
- npm run lint
- npm run check:circular
- ORGII_AGENT_ORG_REDESIGN=1 npm run tauri:build:fast
- Packaged real-data SDE pagination exhausted 10 -> 20 -> 21 without Retry

Pre-commit hook ran. Total eslint: 0, total circular: 0
…formed members

parse_org_members silently dropped any member entry without a string
'name', which cascaded into Writer-grant and communication-link removal
on update — silent member deletion. Malformed entries are now hard,
structured errors naming the entry index and offending field.

update_org also replaced members wholesale with runtime_config: None,
destroying persisted per-member runtime configuration. Survivors now
keep the stored runtime_config, merged by member_id.
…tore

The run store's private serialize_launch_snapshot duplicated
validate + to_string without the size cap; it now imports the shared
definitions::orgs::serialize_launch_snapshot, which validates
structurally and enforces the 256KB cap exactly once at the write
boundary. Read/context/task-persist paths no longer serialize the
snapshot just to check its size.
…owner

Store commits fsync under the store mutex. The model tools
(create/update/remove_org in execute_text) and the launch path
(apply_member_launch_overrides) ran them directly on the async executor,
while the Tauri commands each hand-rolled their own offloading.

AgentOrgsStore now exposes async wrappers (insert/replace/remove/
apply_member_launch_overrides/save_trusted_settings _async) built on a
single run_blocking helper; the Tauri commands, model tool actions, and
launch all go through them. org_store plumbing switched from
&AgentOrgsStore to &Arc<AgentOrgsStore> so callers can share ownership
with the blocking task.
…opy, naming

- COORDINATOR_MEMBER_ID moves to core_types::agent_org as the single
  source of truth; the definitions store and the run coordination layer
  both import it (agent_org_runs keeps its public re-export).
- Frontend member cap now mirrors MAX_AGENT_ORG_MEMBERS via
  AgentOrgs/config/agentConstants.ts instead of hardcoding 50 in
  AgentTeamFormSections.isOrgDraftValid.
- Stale 'team hierarchy' empty-state copy replaced with flat-team
  wording in all 13 locales (agentOrgs.orgWizard.noMembers).
- OrgDefinition::member_count() renamed to participant_count() with a
  doc comment for the coordinator-inclusive semantics.
- Dropped the vestigial _org_store State params from
  debug_agent_org_execute_tool_as_agent and
  debug_agent_org_emit_member_idle.
Use an actual empty string for the empty-id path so the test no longer conflates it with a whitespace-only identifier. This keeps the selected test correction independent of the rejected ce3f5d3 validator changes.
Keep the selected shared write-path serializer self-contained without taking ce3f5d3 read-path changes, validate malformed model-update IDs before unknown-ID lookup, and port the late-launch regression fixture to the flat frozen snapshot contract.\n\nCo-authored-by: Neonforge <[email protected]>
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.

2 participants