Skip to content

refactor(commands): split AgentAccess god-trait into 15 domain sub-traits#6543

Merged
bug-ops merged 2 commits into
mainfrom
feat/issue-6488/agent-access-trait-split
Jul 20, 2026
Merged

refactor(commands): split AgentAccess god-trait into 15 domain sub-traits#6543
bug-ops merged 2 commits into
mainfrom
feat/issue-6488/agent-access-trait-split

Conversation

@bug-ops

@bug-ops bug-ops commented Jul 20, 2026

Copy link
Copy Markdown
Owner

Summary

AgentAccess (crates/zeph-commands/src/traits/agent.rs) had grown to 53 async
methods across 40+ unrelated slash-command domains in a single flat trait, with a
single ~1,800-line impl AgentAccess for Agent<C> block in
crates/zeph-core/src/agent/agent_access_impl.rs. Every command handler that needed
one method statically depended on the entire 53-method surface, and there was no
seam for adding a new command group without growing an already-huge trait file and
impl block further.

  • Splits AgentAccess into 15 focused sub-traits (MemoryAccess, GraphAccess,
    ModelAccess, SkillAccess, PolicyAccess, SchedulerAccess, LspAccess,
    SessionControlAccess, McpAccess, OrchestrationAccess, SubagentAccess,
    IntegrationAccess, TrackingAccess, WorktreeAccess, MiscAccess), each
    declared in its own file under crates/zeph-commands/src/traits/.
  • AgentAccess becomes an empty marker supertrait
    (pub trait AgentAccess: MemoryAccess + … + Send {}) with a blanket impl, so
    dyn AgentAccess and every existing ctx.agent.<method>() call site are
    unaffected — pure interface-segregation refactor, no behavior change.
  • Agent<C>'s corresponding impl SubTrait blocks move out of the single
    agent_access_impl.rs into per-domain crates/zeph-core/src/agent/*_commands.rs
    files (5 new: memory_commands.rs, graph_commands.rs, skill_commands.rs,
    orchestration_commands.rs, misc_commands.rs; 10 existing files extended),
    mirroring the file layout the issue asked for.
  • The shared delegate_cmd! macro moves to a new
    crates/zeph-core/src/agent/command_macros.rs, re-exported pub(crate) for the
    5 domain files that use it.
  • NullAgent now implements the 15 sub-traits directly instead of one
    AgentAccess impl.
  • A handful of call sites in src/ that invoke AgentAccess methods on a
    concrete Agent<C> (not through dyn AgentAccess) needed a specific sub-trait
    import — Rust's supertrait-method-resolution shortcut only auto-resolves
    through dyn Trait objects, not concrete-type dot-calls.

Went through 3 rounds of architecture review before implementation (plan approval,
then a significant-verdict critique that caught a real trait-name collision with
the existing SessionAccess trait plus a macro lexical-scoping issue, then a
further amendment to combine what was originally scoped as two follow-up PRs into
this single PR per explicit scope decision). Implementation-level adversarial
critique and independent test-coverage validation both approved with no blocking
findings; the developer caught and fixed one real bug along the way (a
#[cfg(feature = "scheduler")] module gate that would have silently broken the
blanket AgentAccess impl under default, non-scheduler features).

Closes #6488

Test plan

  • cargo +nightly fmt --check
  • cargo clippy --profile ci --workspace --all-targets --features "desktop,ide,server,chat,pdf,scheduler,testing" -- -D warnings
  • cargo nextest run --config-file .github/nextest.toml --workspace --features "desktop,ide,server,chat,pdf,scheduler" --lib --bins — 14862 passed, 0 failures
  • RUSTFLAGS="-D warnings" RUSTDOCFLAGS="--deny rustdoc::broken_intra_doc_links" cargo doc --no-deps --workspace --features "desktop,ide,server,chat,pdf,scheduler"
  • gitleaks protect --staged --no-banner --redact
  • Relocated ~1390-line test module for the moved methods verified byte-identical against pre-move bodies (2 intentional UFCS-qualification diffs only)
  • NullAgent's 15 sub-trait impls verified behaviorally identical to the original single impl
  • Rebased onto current origin/main; only conflict was in CHANGELOG.md (kept both entries)

@github-actions github-actions Bot added refactor Code refactoring without functional changes size/XL Extra large PR (500+ lines) documentation Improvements or additions to documentation rust Rust code changes core zeph-core crate ci CI/CD configuration labels Jul 20, 2026
bug-ops added 2 commits July 20, 2026 05:28
…aits

AgentAccess had grown to 53 async methods across 40+ unrelated slash-command
domains in a single trait, forcing every command handler to depend on the
entire surface and blocking targeted testing or review of a single domain.

Split it into 15 focused sub-traits (MemoryAccess, GraphAccess, ModelAccess,
SkillAccess, PolicyAccess, SchedulerAccess, LspAccess, SessionControlAccess,
McpAccess, OrchestrationAccess, SubagentAccess, IntegrationAccess,
TrackingAccess, WorktreeAccess, MiscAccess), each in its own trait file.
AgentAccess becomes an empty marker supertrait with a blanket impl, so
dyn AgentAccess and existing call sites are unaffected. Agent<C>'s impl
blocks move out of the single ~1800-line agent_access_impl.rs into
per-domain *_commands.rs files, mirroring the existing file layout.

Pure refactor, no behavior change.
crates/zeph-core/src/agent/agent_access_impl.rs no longer matches the
integrity-audit gate's trusted-history-reader pattern after #6488 moved its
/conv fork/resume test coverage (the only matching code) verbatim into
slash_commands.rs. Move the allowlist entry to the new location with the
same VERIFIED verdict — same code, same trust characteristics, just relocated.
@bug-ops
bug-ops force-pushed the feat/issue-6488/agent-access-trait-split branch from 4b1fadf to 979f5a0 Compare July 20, 2026 03:28
@bug-ops
bug-ops enabled auto-merge (squash) July 20, 2026 03:28
@bug-ops
bug-ops merged commit e0f3775 into main Jul 20, 2026
43 checks passed
@bug-ops
bug-ops deleted the feat/issue-6488/agent-access-trait-split branch July 20, 2026 03:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci CI/CD configuration core zeph-core crate documentation Improvements or additions to documentation refactor Code refactoring without functional changes rust Rust code changes size/XL Extra large PR (500+ lines)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

zeph-commands: AgentAccess trait has grown to 99 async methods across 40 unrelated command domains

1 participant