Repository navigation
✨ feat: Support Model Spec Handoff Targets - #18089
Conversation
|
@codex review |
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
Codex Review: Didn't find any major issues. Keep it up! Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
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". |
|
/quality risk scopes=api,server |
Quality requestOutdated: this request is for an earlier PR commit. Commit: Status: completed (success). Actions run (attempt 1).
Reports and scores:
Scores are advisory. Failed tests, tool errors and incomplete reports do not clear the gate. |
There was a problem hiding this comment.
🟡 Changes recommended
Model-spec access can fall back to base configuration when effective configuration resolution fails, allowing handoffs disabled for the user to execute without a permission check.
3 open issues
What changed in this PR
Adds opt-in model preset handoffs to the existing agent graph, including presets hidden from the model menu. Targets resolve server-owned settings while exposing only display metadata to the client.
Changes:
- Adds preset target identities, listing, reference validation, and runtime loading.
- Extends the handoff picker and transfer cards with preset metadata.
- Adds configuration examples and backend, component, and end-to-end coverage.
| File | Description |
|---|---|
| packages/data-provider/src/types/agents.ts | Defines safe target display metadata. |
| packages/data-provider/src/parsers.ts | Narrows the user type for variable substitution. |
| packages/data-provider/src/models.ts | Adds the optional handoff setting. |
| packages/data-provider/src/keys.ts | Adds a handoff-target query key. |
| packages/data-provider/src/data-service.ts | Adds the target-list API client. |
| packages/data-provider/src/config.ts | Defines the model-spec agent ID prefix. |
| packages/api/src/modelSpecs/index.ts | Narrows the prompt resolver’s user type. |
| packages/api/src/agents/specs.ts | Implements target projection, validation, and loading. |
| packages/api/src/agents/specs.spec.ts | Tests target settings, references, and identities. |
| packages/api/src/agents/index.ts | Exports model-spec handoff helpers. |
| packages/api/src/agents/discovery.ts | Loads preset graph targets and scopes skills. |
| packages/api/src/agents/discovery.spec.ts | Tests discovery, skill access, and remote exclusion. |
| librechat.example.yaml | Documents opt-in handoff configuration. |
| e2e/specs/mock/agent-handoffs.spec.ts | Tests hidden-preset selection and execution. |
| e2e/config/librechat.e2e.yaml | Adds a hidden handoff test preset. |
| client/src/locales/en/translation.json | Adds localized target-loading error text. |
| client/src/data-provider/Agents/queries.ts | Adds the target-list query hook. |
| client/src/components/SidePanel/Agents/Advanced/AgentList.tsx | Allows preset metadata in agent options. |
| client/src/components/SidePanel/Agents/Advanced/AgentHandoffs.tsx | Loads preset options with loading and retry states. |
| client/src/components/SidePanel/Agents/Advanced/__tests__/OrchestrationHub.spec.tsx | Supplies the new query mock. |
| client/src/components/SidePanel/Agents/Advanced/__tests__/AgentHandoffs.spec.tsx | Tests loading and retry behavior. |
| client/src/components/Share/MessageIcon.tsx | Accepts minimal agent display metadata. |
| client/src/components/Chat/Messages/Content/AgentHandoff.tsx | Resolves preset transfer-card labels. |
| client/src/components/Chat/Messages/Content/__tests__/AgentHandoff.test.tsx | Tests configured preset labels. |
| api/server/routes/agents/v1.js | Registers the handoff-target endpoint. |
| api/server/controllers/agents/v1.js | Delegates reference validation with request configuration. |
Review effort: Balanced
|
@codex review |
|
Codex Review: Didn't find any major issues. You're on a roll. Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
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". |
|
/quality risk scopes=api,server |
Quality requestOutdated: this request is for an earlier PR commit. Commit: Status: completed (cancelled). Actions run (attempt 1).
Reports and scores: Scores are advisory. Failed tests, tool errors and incomplete reports do not clear the gate. |
|
@codex review |
|
Codex Review: Didn't find any major issues. Already looking forward to the next diff. Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
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". |
cecca10 to
1a1b415
Compare
|
/quality risk scopes=api,server |
|
@codex review |
Quality reportOutdated: this request is for an earlier PR commit. Gate: open. The selected checks completed. Scores and risk levels are advisory. Status: completed (success). Actions run, attempt 1.
Change riskTakeaway: Every changed line has a test. Highest CRAP among changed functions:
Refactor hints (highest CRAP first)
13 more functions below the threshold (or cut for size) are in report.md. CRAP = complexity² × (1 − coverage)³ + complexity Jobs (2)
All data ( The gate opens only when the workflow, source selection, tooling verification, and every report job succeed. A report job fails on a failed test in its workspace's own Jest run, a tool error, a job timeout, or an incomplete mutation report, including a mutation shard that reaches its execution budget. A cancelled workflow keeps the gate closed. Scores are advisory. A change-risk file marked incomplete or unavailable, for example by a failed |
|
Codex Review: Didn't find any major issues. What shall we delve into next? Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
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". |
1a1b415 to
ccde899
Compare
|
/quality risk scopes=api,server |
|
@codex review |
Quality reportGate: open. The selected checks completed. Scores and risk levels are advisory. Status: completed (success). Actions run, attempt 1.
Change riskTakeaway: Every changed line has a test. Highest CRAP among changed functions:
Refactor hints (highest CRAP first)
13 more functions below the threshold (or cut for size) are in report.md. CRAP = complexity² × (1 − coverage)³ + complexity Jobs (2)
All data ( The gate opens only when the workflow, source selection, tooling verification, and every report job succeed. A report job fails on a failed test in its workspace's own Jest run, a tool error, a job timeout, or an incomplete mutation report, including a mutation shard that reaches its execution budget. A cancelled workflow keeps the gate closed. Scores are advisory. A change-risk file marked incomplete or unavailable, for example by a failed |
|
Codex Review: Didn't find any major issues. 👍 Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
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". |


Summary
A provider preset in
modelSpecscannot currently be selected as an agent handoff target: the picker, saved-reference validation, and graph discovery only know about database-backed agents. Addhandoff: trueto offer a preset as a target, including presets hidden from the model menu withshowInMenu: false.Handoffs load the preset's current server-owned instructions, provider settings, tools, and caller-accessible skills. The picker, transfer card, transcript headers, and error guidance receive only display metadata. Existing configurations retain their behavior until a preset explicitly opts in.
How it works
GET /api/agents/handoff-targetsprojects enabled presets from the caller's effective configuration. Listing, saving, and execution fail closed if principal or override resolution fails; successful strict reads are reused within the same request. A stable, bounded hash of the preset name identifies the graph node and keeps transfer-tool names valid even for long or non-ASCII preset names. Save-time validation and run-time discovery resolve that reference against the caller's current configuration; missing or disabled presets are unavailable.The target uses the existing ephemeral-agent loader and initialization path with its own settings. Prompt templates remain intact until the shared initializer applies the turn timestamp, timezone, and user variables. Saved-agent references keep their ACL checks, and remote-agent API execution continues to require separately shared saved-agent targets.
Type of change
Testing
Tested environments/configuration: Local Chromium, mock provider, disposable MongoDB; hidden provider preset selected in the Handoff editor and executed through the real agent graph.
Automated tests:
Screenshots / recordings
Same viewport and editor on the base revision and this branch. Before: the configured preset cannot be selected. After: the hidden preset is selected as a handoff target.
Risk / compatibility
Opt-in configuration addition; no database migration. Renaming/removing a preset or disabling
handoffinvalidates existing references to it. Handoff availability is independent of model-menu visibility. Remote API model-spec handoffs are excluded because model specs do not have remote-agent sharing grants.Checklist