Skip to content

✨ feat: Support Model Spec Handoff Targets - #18089

Merged
dustinhealy merged 4 commits into
fix/side-chat-target-readinessfrom
dustin/model-spec-handoffs
Nov 19, 2026
Merged

dustinhealy merged 4 commits into
fix/side-chat-target-readinessfrom
dustin/model-spec-handoffs

Conversation

@dustinhealy

@dustinhealy dustinhealy commented Nov 12, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

A provider preset in modelSpecs cannot currently be selected as an agent handoff target: the picker, saved-reference validation, and graph discovery only know about database-backed agents. Add handoff: true to offer a preset as a target, including presets hidden from the model menu with showInMenu: 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-targets projects 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

  • Feature

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:

  • Preset/discovery/strict-config suites: 67 tests passed, including failures with preloaded base configuration and request-scoped reuse.
  • Agent route/middleware regressions and actual strict HTTP-route tests passed, including blocked create/update/duplicate/revert operations on config failure.
  • Existing agent-controller regression suite: 233 tests passed.
  • Transcript/error component suites: 165 tests passed, including preset headers, parallel-run suffixes, saved-agent guidance, and retired preset IDs. Shared chat regression suites: 26 tests passed.
  • Shared initializer tests verify explicit turn timestamp/timezone and stable/dynamic prompt separation.
  • Playwright: hidden preset is absent from startup config, appears in the Handoff picker, saves successfully, executes its private instructions, and renders its transfer label.
  • Static checks and all affected workspace typechecks passed.
  • Lighthouse passed with 250 ms injected MongoDB latency: median LCP 1.65 s, CLS 0.0124, and total blocking time 16.8 ms.

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.

Before After
Handoff editor before Handoff editor after selecting a preset

Risk / compatibility

Opt-in configuration addition; no database migration. Renaming/removing a preset or disabling handoff invalidates 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

  • I reviewed my own changes
  • Relevant tests have been added or updated
  • Existing relevant tests pass
  • The change does not introduce new warnings or errors
  • User-facing or complex behavior is documented where necessary
  • Required dependency changes have been merged/published — N/A
  • Required documentation PR: N/A; configuration example included

Copilot AI balanced review requested due to automatic review settings November 12, 2026 15:04
@dustinhealy
dustinhealy marked this pull request as draft November 12, 2026 15:07
@dustinhealy

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-19T01:25:54.855197Z ccde899 Manual request
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Keep it up!

Reviewed commit: 3e1683cd55

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

@dustinhealy
dustinhealy marked this pull request as ready for review November 12, 2026 15:10
@dustinhealy

Copy link
Copy Markdown
Collaborator Author

/quality risk scopes=api,server

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Quality request

Outdated: this request is for an earlier PR commit.

Commit: 3e1683cd55959f46d1d4be400591f8c93142d4aa. Requested by @dustinhealy.
Checks: risk. Scopes: api, server. Static: off (not used).
Risk: api, server. Mutation: none.

Status: completed (success). Actions run (attempt 1).

Check Result
Change risk (api) success
Change risk (server) success

Reports and scores:

  1. change-risk-server-3e1683cd55959f46d1d4be400591f8c93142d4aa
  2. change-risk-api-3e1683cd55959f46d1d4be400591f8c93142d4aa

Scores are advisory. Failed tests, tool errors and incomplete reports do not clear the gate.

Copilot AI 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.

🟡 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

Comment thread packages/api/src/agents/discovery.ts Resolved
Comment thread packages/api/src/agents/specs.ts Resolved
@dustinhealy
dustinhealy marked this pull request as draft November 12, 2026 15:17
@dustinhealy

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. You're on a roll.

Reviewed commit: 44577f6610

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

@dustinhealy

Copy link
Copy Markdown
Collaborator Author

/quality risk scopes=api,server

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Quality request

Outdated: this request is for an earlier PR commit.

Commit: 44577f66100b61af0d684e7428060f06c23c5f15. Requested by @dustinhealy.
Checks: risk. Scopes: api, server. Static: off (not used).
Risk: api, server. Mutation: none.

Status: completed (cancelled). Actions run (attempt 1).

Check Result
Change risk (api) success
Change risk (server) cancelled

Reports and scores:

  1. change-risk-api-44577f66100b61af0d684e7428060f06c23c5f15

Scores are advisory. Failed tests, tool errors and incomplete reports do not clear the gate.

@dustinhealy

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Already looking forward to the next diff.

Reviewed commit: 9186194c1b

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

@dustinhealy
dustinhealy force-pushed the dustin/model-spec-handoffs branch from cecca10 to 1a1b415 Compare November 18, 2026 23:46
@dustinhealy
dustinhealy marked this pull request as ready for review November 18, 2026 23:46
@dustinhealy

Copy link
Copy Markdown
Collaborator Author

/quality risk scopes=api,server

@dustinhealy

Copy link
Copy Markdown
Collaborator Author

@codex review

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Quality report

Outdated: 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.

  • Commit: 1a1b4157036fe8e9de43b51f748a0f8c4712aa1c
  • Requested by: @dustinhealy
  • Check: risk
  • Scopes: api, server
  • Static mutants: off (not used by change risk)
  • Change risk: api, server
  • Mutation testing (experimental, data-schemas only): none

Change risk

Takeaway: Every changed line has a test. Highest CRAP among changed functions: updateAgentHandler at api/server/controllers/agents/v1.js:1099, CRAP 104.3 with 95% coverage.

Workspace Files measured Incomplete Unavailable Changed lines with no test Highest CRAP
api 5 of 5 0 0 0 30.0
server 5 of 5 0 0 0 104.3

Refactor hints (highest CRAP first)

Function Complexity Coverage CRAP Location
updateAgentHandler 103 95% 104.3 api/server/controllers/agents/v1.js:1099
duplicateAgentHandler 44 100% 44.0 api/server/controllers/agents/v1.js:1482
revertAgentVersionHandler 41 90% 42.5 api/server/controllers/agents/v1.js:2101
createAgentHandler 31 91% 31.8 api/server/controllers/agents/v1.js:758
initializeReferencedAgent 30 100% 30.0 packages/api/src/agents/discovery.ts:210
loadModelSpecHandoff 12 93% 12.0 packages/api/src/agents/specs.ts:113
getHandoffModelSpec 11 91% 11.1 packages/api/src/agents/specs.ts:29
getModelSpecHandoffTargets 9 90% 9.1 packages/api/src/agents/specs.ts:54
loadStrictAppConfig 6 100% 6.0 packages/api/src/app/strict.ts:19
validateHandoffReferences 5 100% 5.0 packages/api/src/agents/specs.ts:81

13 more functions below the threshold (or cut for size) are in report.md.

CRAP = complexity² × (1 − coverage)³ + complexity

Jobs (2)
Check Result
Change risk (api) success
Change risk (server) success

All data (quality-report artifact) · Run page

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 api/ source-alias suite, does not close the gate.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. What shall we delve into next?

Reviewed commit: 1a1b415703

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

@dustinhealy
dustinhealy force-pushed the dustin/model-spec-handoffs branch from 1a1b415 to ccde899 Compare November 19, 2026 01:22
@dustinhealy
dustinhealy changed the base branch from dev to fix/side-chat-target-readiness November 19, 2026 01:23
@dustinhealy
dustinhealy added this pull request to stack #18481 November 19, 2026 01:23
@dustinhealy

Copy link
Copy Markdown
Collaborator Author

/quality risk scopes=api,server

@dustinhealy

Copy link
Copy Markdown
Collaborator Author

@codex review

@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Quality report

Gate: open. The selected checks completed. Scores and risk levels are advisory.

Status: completed (success). Actions run, attempt 1.

  • Commit: ccde8997d503c19513670e403047b17195f4d5fe
  • Requested by: @dustinhealy
  • Check: risk
  • Scopes: api, server
  • Static mutants: off (not used by change risk)
  • Change risk: api, server
  • Mutation testing (experimental, data-schemas only): none

Change risk

Takeaway: Every changed line has a test. Highest CRAP among changed functions: updateAgentHandler at api/server/controllers/agents/v1.js:1099, CRAP 104.3 with 95% coverage.

Workspace Files measured Incomplete Unavailable Changed lines with no test Highest CRAP
api 5 of 5 0 0 0 30.0
server 5 of 5 0 0 0 104.3

Refactor hints (highest CRAP first)

Function Complexity Coverage CRAP Location
updateAgentHandler 103 95% 104.3 api/server/controllers/agents/v1.js:1099
duplicateAgentHandler 44 100% 44.0 api/server/controllers/agents/v1.js:1482
revertAgentVersionHandler 41 90% 42.5 api/server/controllers/agents/v1.js:2101
createAgentHandler 31 91% 31.8 api/server/controllers/agents/v1.js:758
initializeReferencedAgent 30 100% 30.0 packages/api/src/agents/discovery.ts:210
loadModelSpecHandoff 12 93% 12.0 packages/api/src/agents/specs.ts:113
getHandoffModelSpec 11 91% 11.1 packages/api/src/agents/specs.ts:29
getModelSpecHandoffTargets 9 90% 9.1 packages/api/src/agents/specs.ts:54
loadStrictAppConfig 6 100% 6.0 packages/api/src/app/strict.ts:19
validateHandoffReferences 5 100% 5.0 packages/api/src/agents/specs.ts:81

13 more functions below the threshold (or cut for size) are in report.md.

CRAP = complexity² × (1 − coverage)³ + complexity

Jobs (2)
Check Result
Change risk (api) success
Change risk (server) success

All data (quality-report artifact) · Run page

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 api/ source-alias suite, does not close the gate.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. 👍

Reviewed commit: ccde8997d5

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

@dustinhealy
dustinhealy merged commit 7d806f4 into dev Nov 19, 2026
79 of 83 checks passed
@dustinhealy
dustinhealy deleted the dustin/model-spec-handoffs branch November 19, 2026 02:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants