🪶 feat: Resolve Explicit Subagents Lazily

[danny-avila]

Summary

I changed explicit single-agent subagents to advertise lightweight, authorization-checked descriptors and defer their expensive runtime initialization until the SDK selects them. This implements AI-1714 against the lazy resolver contract in @librechat/agents 3.4.3.

• Resolve model validation, tools, MCP servers, files, skills, and isolated agent inputs only for the selected child.
• Recheck VIEW permission and a deterministic versioned configuration fingerprint at invocation, failing closed if access or configuration changed.
• Preserve nested descriptor discovery, cycle/depth/node/expanded-entry limits, handoff overlap behavior, cancellation, reasoning replay, code-environment flags, stateful-session prewarming, and late usage pricing.
• Keep descriptor metadata inert and narrowly retained while the foreground resolver remains request-scoped pending AI-1597.
• Add regressions for unused descriptors, repeated resolution, nested expansion budgets, configuration identity, cancellation, capability traversal, and live pricing-map mutation.

Change Type

• New feature (non-breaking change which adds functionality)

Testing

• Ran scoped ESLint across all changed JavaScript and TypeScript files with zero warnings or errors.
• Ran node --check api/server/services/Endpoints/agents/initialize.js.
• Ran git diff --check.
• Ran the lazy fingerprint suite: 5/5 passing.
• Ran the focused run/subagent summarization suite: 115/115 passing.
• Ran the released SDK lazy-resolver path against OpenAI gpt-4.1-mini and Anthropic claude-haiku-4-5: both selected resolvers ran exactly once, unused sibling resolvers stayed cold, expected output returned, and positive child usage was emitted.
• Deferred the broad matrix to CI as requested; additional borrowed-worktree suites encounter pre-existing local dependency/API skew before test execution.

Test Configuration:

• macOS
• Node.js local development runtime
• @librechat/agents 3.4.3
• Live credentials loaded from the main worktree without printing secret values

Checklist

• My code adheres to this project's style guidelines
• I have performed a self-review of my own code
• I have commented in complex areas where the lifecycle is non-obvious
• My changes do not introduce new warnings
• I have written tests demonstrating that my changes are effective
• Any changes dependent on mine have been merged and published in downstream modules

[Copilot]

Pull request overview

Implements lazy resolution for explicit subagents by advertising lightweight, VIEW-checked descriptors up-front and deferring expensive child initialization (tools/MCP/files/skills/model validation) until the SDK selects a specific subagent, with a fail-closed recheck on selection (VIEW + versioned config fingerprint).

Changes:

• Added lazy subagent descriptor plumbing in the runtime subagent config builder and capability traversals (code env / stateful sessions / reasoning replay).
• Introduced deterministic, secret-scrubbed config fingerprinting for lazy descriptor identity and selection-time drift detection.
• Refactored agent initialization to advertise inert descriptors, initialize selected subagents on-demand, and expanded test coverage for limits/cancellation/config drift.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/api/src/agents/run.ts	Builds subagent configs with support for inert lazy descriptors and resolves selected children on-demand.
api/server/services/Endpoints/agents/initialize.js	Advertises lazy subagent descriptors, enforces selection-time VIEW + fingerprint checks, and initializes selected subagents lazily.
api/server/services/Endpoints/agents/initialize.spec.js	Updates/expands regression coverage for lazy descriptor behavior, limits, cancellation, and config drift.
packages/api/src/agents/lazySubagents.ts	Adds deterministic fingerprinting for lazy descriptor identity with secret-key exclusion and stable canonicalization.
packages/api/src/agents/lazySubagents.spec.ts	Tests fingerprint stability, drift detection, secret exclusion, and version inclusion.
packages/api/src/agents/tests/run-summarization.test.ts	Ensures descriptors are advertised without eager inputs and resolves lazily with correct budgeting behavior.
packages/api/src/agents/statefulCodeSessions.spec.ts	Verifies stateful-session prewarm detection includes inert lazy descriptors.
packages/api/src/agents/run.spec.ts	Verifies reasoning replay detection includes inert lazy descriptors.
packages/api/src/agents/usage.spec.ts	Ensures usage pricing resolver observes per-agent pricing entries added after resolver creation.
packages/api/src/agents/index.ts	Exports the new lazy subagent fingerprint helpers.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[danny-avila]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Swish!

Reviewed commit: 280eed3798

ℹ️ 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".