LibreChat/api
Danny Avila 301f9ac634
🚕 feat: Add Per-Call Subagent Machine Selection (#16757)
* 🧭 feat: Let a Parent Choose Its Subagent's Code Machine Per Call

A parent agent can now pass optional `machine` / `workspace` arguments on a
subagent call to pick where the child runs, using the host-argument
extension point added to @librechat/agents.

- Each lazy child declares enums built only from machines it may reach:
  admitted in the conversation's sealed codeWorkspaces, on its default or
  allowlist, in the requesting principal's tenant-scoped list, and served by
  a ready worker. A child the conversation pinned to a machine offers only
  that machine; a child with no reachable machine declares nothing.
- On use, a request-scoped routing session in packages/api re-validates the
  choice against the current request and live worker status and refuses an
  invalid one with a typed, model-visible error instead of falling back. A
  routed child is pinned to the chosen machine at every routing site,
  overriding parent inheritance.
- Omitted arguments keep inherit-by-default routing, extended so a child
  follows the machine a per-call-routed parent runs on (passing through
  agents without code). A subagent keeps one machine for the whole request.
- A child whose default workspace is unavailable stays guarded unless it has
  per-call choices; then it stays callable and its description asks the
  parent to pick a listed machine.
- Routed children keep their tool context per execution for tool loading,
  provisioning and artifact handling.
- Paused-approval bindings, the attached-machine policy hook, skill-file
  priming and tool-output references account for per-call choices.

The declarations are gated on the installed SDK exporting
SubagentHostArgumentError, so this change is inert until LibreChat depends on
an @librechat/agents release that includes it.

* 🧭 fix: Reserve Default Routes Early and Route a Routed Subagent's Graph Members

- Reserve a subagent's default machine when it is placed, as
  initializeAgent will resolve it (including parent inheritance), so a
  concurrent call cannot claim another machine during initialization.
- Graph members spawned by a per-call-routed subagent follow its machine
  when they may, unless they already initialized on their own route this
  request.

* 🧭 fix: Settle Concurrent Inherited Routes and Register Routed Graph Members

- Re-read a subagent's inherited route after resolving targets, so two
  concurrent calls from differently routed parents settle on one machine.
- Attribute a workspace-only conflict to the workspace argument.
- Register graph members a routed subagent initialized, so each gets the
  attached-machine policy of the machine it actually runs on.

* 🧭 fix: Re-read Inherited Routes After Resolving Subagent Targets

- Re-read a subagent's inherited route after the target resolution await,
  so two concurrent omitted-machine calls from differently routed parents
  settle on one machine.
- Attribute a workspace-only conflict to the workspace argument.

* 🧪 test: Prove a Routed Graph Member Takes Its Machine's Policy Through createRun

- Register a resolved child's graph members inline in the lazy resolver
  instead of through an exported generic helper whose test did not
  typecheck.
- Drive the check through createRun's real PreToolUse hook: a member
  routed to a deny machine flips from its metadata machine's allow to deny
  once its parent resolves.

* 🧭 fix: Hold a Lazily Loaded Graph Member's Default Machine While It Initializes

- Pass a graph member's code flags when it initializes on its default
  route, so the routing session reserves that machine before the
  asynchronous initialization instead of only after it, and a concurrent
  call cannot place the same agent on another machine meanwhile.

* 🧭 fix: Validate the Approval Mode Against Every Machine a Subagent May Use

- Collect each agent's default attached route and each attached machine a
  parent may route it to per call, and validate the requested approval
  mode against that set in createRun and both client checks.
- A child whose default is unavailable but whose per-call machine permits
  accept edits no longer fails run creation; full access still requires
  every such machine to permit it.

* 🧭 fix: Admit, Prime, and Cancel Per-Call Subagent Routes Conservatively

- Build scheduled pause admission from every attached machine a parent
  may route an agent to, so a permissive default does not hide a
  per-call machine that asks.
- Walk lazy graph-member metadata when collecting execution routes, so
  historical skill files are primed for every machine such a member may
  run on.
- Stop placing a canceled call after its target resolution resolves, so
  it never claims a machine for an execution that will not initialize.

* 🧭 fix: Release Unused Route Claims and Scope Per-Call Machines to Their Run

- Hold a subagent's route claim per placement: a failed or canceled
  initialization gives the machine back unless another execution still
  holds it, and a claim is permanent once a child on it attaches.
- Fold an agent's default route into its per-call choice digest, so each
  agent contributes at most one paused-approval binding target.
- Use only an agent's route policies for pause admission when it has
  them, so a missing default does not make a decided route look asking.
- Drop a routable child's provisional attached-machine membership when it
  resolves off attached machines.
- Offer and accept no attached machine per call while run files are
  shared, since shared children must run on managed code.

* 🧭 fix: Give Back a Route When Its Placement Verification Fails

- Release a placement's hold when attach finds the child initialized on a
  different machine than the one it was routed to, so a retry that
  follows the unavailable-machine guidance may name another machine.

* 🧭 fix: Commit a Lazy Child's Routes Only When Its Whole Resolution Succeeds

- Keep the routes a lazy child and its routed graph members hold pending
  through the child's entire resolution (settleExecution), committing them
  on success and giving them back on failure or cancellation unless
  another execution still holds them.
- Placements outside any call (shared graph members) still commit when
  they attach.

* 🧭 fix: Drop a Failed Lazy Resolution's Config from the Graph Cache

- When a lazy child's graph resolution fails or is canceled after its
  config was cached for graph reuse, remove that entry with its route, so
  a later graph never reuses a config for a machine the child gave back.

* 🧭 fix: Follow a Routed Agent Through Self-Spawned Runs and Scope Routed Member Configs

- A call whose parent run was never placed (an allowSelf spawn reuses its
  routed inputs) inherits the routed claim of its parent agent, which keeps
  one machine per request.
- Never share a graph member initialized for a routed parent's execution
  through the graph-member cache, so a failed resolution leaves no config
  behind for a route it gave back.
- Race lazy target discovery with the request signal.

* 🧭 fix: Pass a Machine On Through Self-Spawned Runs of Agents Without Code

- Record the machine each agent without stateful code passes on, and let a
  call from that agent's unplaced run (an allowSelf spawn) follow it when
  the agent passed on exactly one machine this request.

* 🧭 fix: Keep a Pass-Through Route Only When Its Resolution Succeeds

- Record the machine an agent without code passes on with the rest of its
  call's routing state: kept when the resolution deciding it succeeds,
  dropped when it fails, so a self-spawn never follows a failed attempt.

* 🧭 fix: Settle a Lazy Child's Routing State at the SDK Handoff

- Wrap the run's whole lazy resolution, through the inputs handed to the
  SDK, in the descriptor's settle hook, so a cancel after the host
  resolver returns still gives the call's routes back.
- Roll back the per-agent tool context a pending placement set (restoring
  the entry it replaced) when its resolution fails, so a retry on another
  machine seeds its own context.
- Drop a failed call's shared config from the graph cache through the
  same settle hook.

* 🧭 fix: Keep Per-Agent Tool Contexts on Live Placements and Queue Target Probes

- Track every pending placement that uses an agent's per-agent tool
  context: a committed one sets it, a failed one hands it to a surviving
  placement, and only the last failure restores the earlier entry.
- Let an unplaced run of an agent (an allowSelf spawn) defer to the routed
  run of the same agent that encloses it when looking up tool contexts.
- Queue live target probes at eight in flight, below the shared status
  poller's ceiling, so concurrent descriptors never misreport a healthy
  machine as unavailable.

* 🧭 refactor: Load Routed Graph Members Through a packages/api Service

- Move the routed graph-member load (shared reuse, skip list, view check,
  execution identity, failure policy) into createRoutedGraphMemberLoader;
  the initializer only injects its dependencies.
- Thread the request and call signals into target resolution so queued
  probes are skipped once canceled.
- Probe nothing in shared-file runs, where every per-call target is
  attached and unusable.
- Retire pending tool-context ownership when a committed placement
  installs the per-agent entry.

* 🧭 fix: Share a Lazy Child's Config with Later Graphs Only After It Commits

- Publish a default-placed lazy child's config to the shared graph cache
  from the settle hook's commit, so no concurrent graph can borrow a config
  whose route may still be given back.
- Resolve a child's own appearance in its graph to the child config itself.
2026-10-05 06:21:15 -04:00
..
app 🕊️ feat: Supply Authorized Scheduled MCP Resource Bearers (#16699) 2026-10-04 22:20:50 -04:00
cache 🔗 feat: use LibreChat prompt groups as agent instructions (#16686) 2026-10-04 21:27:26 -04:00
config 🛬 fix: Land MCP OAuth Callbacks on Waiting Connections (#15876) 2026-09-13 01:46:41 -04:00
db 🛬 fix: Land MCP OAuth Callbacks on Waiting Connections (#15876) 2026-09-13 01:46:41 -04:00
models 🥢 fix: Fit MCP App Snapshots Within Message Documents (#16299) 2026-10-01 03:46:17 +00:00
server 🚕 feat: Add Per-Call Subagent Machine Selection (#16757) 2026-10-05 06:21:15 -04:00
strategies ⚡ perf: Async Local File Saves and Compile Hot-Path Regexes Once (#16712) 2026-10-04 15:52:55 -04:00
test 📔 feat: Preserve Owner Text During PII Redaction (#16311) 2026-10-02 11:43:10 -04:00
utils ⚡ feat: Add Gemini 3.8 Flash Support (#15519) 2026-09-02 15:06:40 -04:00
jest.config.js 🧩 feat: MCP Apps support (#13831) 2026-10-01 03:46:16 +00:00
jsconfig.json
package.json 📦 chore: npm audit fix + bump agents SDK to v4.0.1 (#16581) 2026-09-30 22:12:41 -04:00
typedefs.js 🏦 fix: Reserve Credits for In-Flight Requests (#15879) 2026-09-13 12:53:19 -04:00