refactor(commands): split AgentAccess god-trait into 15 domain sub-traits#6543
Merged
Conversation
…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
force-pushed
the
feat/issue-6488/agent-access-trait-split
branch
from
July 20, 2026 03:28
4b1fadf to
979f5a0
Compare
bug-ops
enabled auto-merge (squash)
July 20, 2026 03:28
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
AgentAccess(crates/zeph-commands/src/traits/agent.rs) had grown to 53 asyncmethods across 40+ unrelated slash-command domains in a single flat trait, with a
single ~1,800-line
impl AgentAccess for Agent<C>block incrates/zeph-core/src/agent/agent_access_impl.rs. Every command handler that neededone 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.
AgentAccessinto 15 focused sub-traits (MemoryAccess,GraphAccess,ModelAccess,SkillAccess,PolicyAccess,SchedulerAccess,LspAccess,SessionControlAccess,McpAccess,OrchestrationAccess,SubagentAccess,IntegrationAccess,TrackingAccess,WorktreeAccess,MiscAccess), eachdeclared in its own file under
crates/zeph-commands/src/traits/.AgentAccessbecomes an empty marker supertrait(
pub trait AgentAccess: MemoryAccess + … + Send {}) with a blanket impl, sodyn AgentAccessand every existingctx.agent.<method>()call site areunaffected — pure interface-segregation refactor, no behavior change.
Agent<C>'s correspondingimpl SubTraitblocks move out of the singleagent_access_impl.rsinto per-domaincrates/zeph-core/src/agent/*_commands.rsfiles (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.
delegate_cmd!macro moves to a newcrates/zeph-core/src/agent/command_macros.rs, re-exportedpub(crate)for the5 domain files that use it.
NullAgentnow implements the 15 sub-traits directly instead of oneAgentAccessimpl.src/that invokeAgentAccessmethods on aconcrete
Agent<C>(not throughdyn AgentAccess) needed a specific sub-traitimport — Rust's supertrait-method-resolution shortcut only auto-resolves
through
dyn Traitobjects, 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
SessionAccesstrait plus a macro lexical-scoping issue, then afurther 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 theblanket
AgentAccessimpl under default, non-scheduler features).Closes #6488
Test plan
cargo +nightly fmt --checkcargo clippy --profile ci --workspace --all-targets --features "desktop,ide,server,chat,pdf,scheduler,testing" -- -D warningscargo nextest run --config-file .github/nextest.toml --workspace --features "desktop,ide,server,chat,pdf,scheduler" --lib --bins— 14862 passed, 0 failuresRUSTFLAGS="-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 --redactNullAgent's 15 sub-trait impls verified behaviorally identical to the original single implorigin/main; only conflict was inCHANGELOG.md(kept both entries)