Skip to content

feat: add v2 agent residency lru#26632

Merged
jif-oai merged 2 commits into
mainfrom
jif/mav2-residency-lru
Jun 8, 2026
Merged

feat: add v2 agent residency lru#26632
jif-oai merged 2 commits into
mainfrom
jif/mav2-residency-lru

Conversation

@jif-oai

@jif-oai jif-oai commented Jun 5, 2026

Copy link
Copy Markdown
Collaborator

Why

Multi-agent v2 treats agents as durable logical agents, not just live entries in ThreadManager. After the reload-on-delivery change, a v2 agent can be addressed even if its thread is not currently loaded.

This PR adds the next layer: loaded v2 subagents can be paged out of ThreadManager when the session has too many resident agents. That keeps residency separate from logical identity and prepares the stack for making v2 concurrency count active execution instead of existing agents.

What Changed

  • Add an AgentControl-scoped LRU for resident v2 subagents.
  • Reserve residency before spawning or reloading a v2 subagent.
  • If resident capacity is full, unload the least-recently-used idle v2 subagent from ThreadManager.
  • Keep ThreadManager as a primitive loaded-thread store; it does not own the LRU policy.
  • Keep unloaded agents registered and durable so they can be reloaded by the delivery path.
  • Preserve the existing v2 cap semantics by using the derived non-root v2 cap for residency.

Eviction is intentionally conservative. A thread is unloadable only when it is a v2 subagent, has completed or errored, has no active turn, and has no pending mailbox work. Before removal, the rollout is materialized and flushed.

Assumptions And Non-Goals

  • PR feat: reload v2 agents on delivery #26623 provides the reload-on-delivery path for unloaded v2 agents.
  • ThreadManager membership means loaded/resident, not logical agent existence.
  • AgentRegistry remains the logical identity/metadata source for v2 agents that may be unloaded.
  • list_agents remains a recent/resident view for now.
  • This does not change active execution concurrency; that is the next PR.
  • This does not change close_agent semantics.
  • This does not change or remove resume_agent.
  • This does not add a new residency config knob.

Stack

  1. V2 durable lookup and reload on delivery (feat: reload v2 agents on delivery #26623) - reload unloaded v2 agents before delivering follow-up/input.
  2. V2 residency LRU (this PR) - unload idle resident v2 agents from ThreadManager when resident capacity is full.
  3. V2 active-execution concurrency - count running non-root v2 turns instead of logical agents.
  4. V2 close/interrupt semantics - make v2 close interrupt the current turn without deleting durable identity.
  5. V2 resume cleanup - remove the manual resume surface for v2 while keeping internal reload support.

Validation

  • Added focused coverage for the residency LRU eviction path.
  • Local clippy/check/tests were not run; CI will cover them.

@jif-oai jif-oai requested a review from a team as a code owner June 5, 2026 15:30

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bf67b391ab

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread codex-rs/core/src/agent/control/spawn.rs
Comment thread codex-rs/core/src/agent/control/residency.rs
Comment thread codex-rs/core/src/agent/control/residency_tests.rs
Comment thread codex-rs/core/src/agent/control/residency.rs
Base automatically changed from jif/mav2-reload-on-delivery to main June 5, 2026 16:18
@jif-oai jif-oai force-pushed the jif/mav2-residency-lru branch from 4574f24 to 46e2da8 Compare June 5, 2026 16:22
@jif-oai jif-oai merged commit 4e803a0 into main Jun 8, 2026
31 checks passed
@jif-oai jif-oai deleted the jif/mav2-residency-lru branch June 8, 2026 08:24
@github-actions github-actions Bot locked and limited conversation to collaborators Jun 8, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant