feat(0.21.0): MCP delegations dispatch into caller's fleet workspace#50
Merged
Conversation
`agent-runtime-mcp` previously always called `client.create(...)` per
delegation, spawning each worker as a SIBLING sandbox of the caller.
Diffs landed on the worker's filesystem and the caller had to pull them
back through the structured tool result.
Switch to a placement abstraction. When the parent sandbox sets
`TANGLE_FLEET_ID` on the MCP server's env, `delegate_code` and
`delegate_research` now resolve workers via `client.fleets.get(id)` and
dispatch onto existing fleet machines through `fleet.sandbox(machineId)`.
The fleet's shared-workspace policy means the worker machine mounts the
same filesystem as the caller — diffs land in-place, no cross-sandbox
copy step.
- `LoopSandboxClient` gains an optional `describePlacement(box)` so the
kernel emits the new `loop.iteration.dispatch` trace event with either
`{ placement: 'sibling', sandboxId }` or
`{ placement: 'fleet', fleetId, machineId, sandboxId }`. Sandbox SDK
consumers without the method default to sibling.
- `DelegationExecutor` abstracts the two modes:
`createSiblingSandboxExecutor({ client })` and
`createFleetWorkspaceExecutor({ fleet, excludeMachineIds })`. The
fleet executor round-robins through `fleet.ids` (skipping the
coordinator) and records machineId-by-sandboxId so the trace event
can recover the assignment when the kernel hands the SandboxInstance
back.
- `createDefaultCoderDelegate` accepts either `executor` (new) or
`sandboxClient` (legacy shorthand — wraps in a sibling executor).
- `detectExecutor({ sandboxClient, env })` picks the right executor
from env vars; exported so custom bin entry points get the same
detection.
- The bin logs `fleet-aware delegation: fleetId=...` and the executor's
`describe()` to stderr at startup so operators can confirm placement.
- Fleet mode without `TANGLE_API_KEY` fails loud rather than silently
degrading to sibling mode.
Detection mechanism: `TANGLE_FLEET_ID` env var, with optional
`TANGLE_FLEET_EXCLUDE_MACHINES` to skip the coordinator machine.
20 new tests cover sibling placement, fleet round-robin, machine-id
recovery in the trace event, exclusion failure, custom selectMachine,
sandbox-resolution errors, env detection with whitespace handling, and
the structural-shape guards on `client.fleets.get`.
Existing 215 tests pass unchanged. Build + typecheck + biome clean.
…l peer `@tangle-network/agent-knowledge` is an optional peerDep added to package.json a few releases ago but pnpm-lock.yaml was never refreshed. CI runs `pnpm install --frozen-lockfile` which trips on the specifier mismatch and fails before any tests run. `pnpm install` with `autoInstallPeers: true` (the repo default) resolves the peer to 1.4.0; record that in the lockfile. No code or runtime change.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
agent-runtime-mcppreviously created a fresh sibling sandbox for everydelegate_code/delegate_researchcall. Diffs landed on the worker's filesystem and the caller had to pull them back through the structured tool result.With this change, when the parent sandbox sets
TANGLE_FLEET_IDon the MCP server's env, delegations dispatch onto existing machines in the caller's fleet viafleet.sandbox(machineId).streamPrompt(...). The fleet's shared-workspace policy means worker machines mount the same filesystem as the caller — diffs land in-place, no cross-sandbox copy step.Sibling-sandbox mode is still the default when
TANGLE_FLEET_IDis unset.Detection mechanism
TANGLE_FLEET_IDenv var. When present, the bin callsclient.fleets.get(fleetId)to resolve a structuralFleetHandle({ fleetId, ids[], sandbox(machineId) }) and builds a fleet-workspace executor around it. OptionalTANGLE_FLEET_EXCLUDE_MACHINESskips the coordinator machine from round-robin.Fleet mode without
TANGLE_API_KEYfails loud rather than silently degrading.Executor abstraction
LoopSandboxClientgains an optionaldescribePlacement(box)so the kernel emits a newloop.iteration.dispatchtrace event carrying either{ placement: 'sibling', sandboxId }or{ placement: 'fleet', fleetId, machineId, sandboxId }. RawSandboxSDK clients without the method default to sibling — backward compatible.createDefaultCoderDelegateacceptsexecutor(new) ORsandboxClient(legacy shorthand, wraps in a sibling executor).What is NOT in scope
src/loops/) is unchanged structurally — only the new trace event variant + the optionaldescribePlacementhook.Test plan
pnpm typecheckcleanpnpm test— 235 passed (215 existing + 20 new acrosstests/mcp/fleet-detection.test.ts+tests/mcp/fleet-executor.test.ts)pnpm buildcleanpnpm exec biome check src testscleantax-orchestrator(or other consumer) setsTANGLE_FLEET_IDinAgentProfile.mcpServers[].envand confirmsagent-runtime-mcp: fleet-aware delegation: fleetId=...lands on stderr at boot