Skip to content

Commit a38407b

Browse files
feat(server,web,mobile): an agent sets up a link to another environment
A user asks an agent to "delegate this to my vps" without knowing any address, so t3_environment_link needs none. The agent passes a hint from the user's words, an environmentId when it knows the machine, or an address only when the user gave one. The tool records a card in the thread and returns pending at once, so no provider's tool-call timeout can close it. A machine already linked here returns linked at once, with no card. The card lets the user pick the machine from the ones their app knows (preselected by the hint; "Another address…" for one it does not), and the access (default supervised, or the agent's suggestion). The client answers with every address it knows for that machine and a one-use pairing code, minted there with the user's own session when it can, or pasted. The server links through the first address that answers as that machine, never sends the code to one that answers as another, and keeps only the matching addresses. A machine already linked is answered with "Use this link". The answer reaches the agent as a notification in its thread: linked (with the environment id, label and the access chosen), declined, or failed with the reason. The pairing code is never recorded. Stopping or archiving the thread closes a pending card; a retry with the same clientRequestId returns the card's current outcome. t3_environment_unlink undoes a link. Both tools need a full-access caller and are refused for linked work. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
1 parent d79fdd5 commit a38407b

49 files changed

Lines changed: 3713 additions & 48 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎apps/mobile/src/features/threads/LinkRequestCard.tsx‎

Lines changed: 507 additions & 0 deletions
Large diffs are not rendered by default.

‎apps/mobile/src/features/threads/ThreadFeed.tsx‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import { ThreadContextDivider } from "./thread-context-divider";
22
import { ThreadHandoffRow } from "./thread-handoff-row";
3+
import { LinkRequestCard } from "./LinkRequestCard";
34
import { SecretRequestCard } from "./SecretRequestCard";
45
import {
56
WorktreeWorkingHeader,
@@ -165,6 +166,7 @@ import {
165166
threadFeedRunIsUnsettled,
166167
isContextCompactionActivityGroup,
167168
isContextHandoffActivityGroup,
169+
isLinkRequestActivityGroup,
168170
isSecretRequestActivityGroup,
169171
type ThreadFeedEntry,
170172
type ThreadFeedLatestRun,
@@ -1657,6 +1659,16 @@ function renderFeedEntry(
16571659
);
16581660
}
16591661

1662+
if (entry.type === "activity-group" && isLinkRequestActivityGroup(entry)) {
1663+
return (
1664+
<LinkRequestCard
1665+
environmentId={props.environmentId}
1666+
projectedItem={entry.activities[0]!.projectedItem}
1667+
iconColor={iconSubtleColor}
1668+
/>
1669+
);
1670+
}
1671+
16601672
if (entry.type === "activity-group" && isContextCompactionActivityGroup(entry)) {
16611673
const label = entry.activities[0]!.summary;
16621674
const active =

‎apps/mobile/src/lib/threadActivity.ts‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -351,6 +351,12 @@ export function isSecretRequestActivityGroup(entry: ThreadFeedActivityGroup): bo
351351
);
352352
}
353353

354+
export function isLinkRequestActivityGroup(entry: ThreadFeedActivityGroup): boolean {
355+
return (
356+
entry.activities.length === 1 && entry.activities[0]?.projectedItem.item.type === "link_request"
357+
);
358+
}
359+
354360
function isUserInputActivityGroup(entry: ThreadFeedActivityGroup): boolean {
355361
return entry.activities.some((activity) => activity.workEntry.questionAnswer !== undefined);
356362
}
@@ -459,7 +465,8 @@ function itemIsProminent(item: OrchestrationV2TurnItem): boolean {
459465
item.type === "thread_created" ||
460466
item.type === "system_notice" ||
461467
// An answerable card: it must stand alone and never fold away with the run.
462-
item.type === "secret_request"
468+
item.type === "secret_request" ||
469+
item.type === "link_request"
463470
);
464471
}
465472

@@ -579,6 +586,8 @@ function itemIcon(item: OrchestrationV2TurnItem): ThreadFeedActivity["icon"] {
579586
return "zap";
580587
case "secret_request":
581588
return "lock";
589+
case "link_request":
590+
return "globe";
582591
}
583592
}
584593

@@ -634,6 +643,8 @@ function itemSummary(
634643
return "Thread created";
635644
case "secret_request":
636645
return item.label;
646+
case "link_request":
647+
return `Link ${item.label ?? item.url ?? "an environment"}`;
637648
case "dynamic_tool": {
638649
const classified = classifyToolActivity({
639650
itemType: "dynamic_tool_call",
@@ -692,6 +703,7 @@ function itemPreview(item: OrchestrationV2TurnItem): string | null {
692703
case "thread_created":
693704
return item.targetThreadId;
694705
case "secret_request":
706+
case "link_request":
695707
return item.reason || null;
696708
case "subagent":
697709
return item.result ?? item.progress ?? item.prompt;

‎apps/mobile/src/state/peerLinks.ts‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,40 @@
1+
import { useAtomValue } from "@effect/atom-react";
2+
import { linkableMachines } from "@t3tools/client-runtime/link-request";
13
import { createPeerLinkEnvironmentAtoms } from "@t3tools/client-runtime/state/peerLinks";
4+
import type { EnvironmentId } from "@t3tools/contracts";
5+
import { useMemo } from "react";
26

37
import { connectionAtomRuntime } from "../connection/runtime";
8+
import { useEnvironments } from "./environments";
9+
import { relayEnvironmentDiscovery } from "./relay";
10+
import { useEnvironmentQuery } from "./query";
411

512
export const peerLinkEnvironment = createPeerLinkEnvironmentAtoms(connectionAtomRuntime);
13+
14+
/**
15+
* The user's other machines, for picking one to link `environmentId` to.
16+
* Reads that environment's links only while `enabled`, since listing them
17+
* asks every linked machine whether it answers.
18+
*/
19+
export function useLinkableMachines(environmentId: EnvironmentId, enabled: boolean) {
20+
const { environments } = useEnvironments();
21+
const discovery = useAtomValue(relayEnvironmentDiscovery.stateValueAtom);
22+
const links = useEnvironmentQuery(
23+
enabled ? peerLinkEnvironment.list({ environmentId, input: {} }) : null,
24+
);
25+
return useMemo(
26+
() =>
27+
linkableMachines({
28+
environments,
29+
threadEnvironmentId: environmentId,
30+
linkedIds: new Set(links.data?.links.map((link) => link.environmentId)),
31+
connectAddresses: new Map(
32+
[...discovery.environments].map(([id, found]) => [
33+
id,
34+
found.environment.endpoint.httpBaseUrl,
35+
]),
36+
),
37+
}),
38+
[discovery.environments, environmentId, environments, links.data],
39+
);
40+
}
Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
import { mintPeerPairingCode } from "@t3tools/client-runtime/state/peerPairingCode";
2+
import type { EnvironmentId } from "@t3tools/contracts";
3+
import * as Effect from "effect/Effect";
4+
import * as Option from "effect/Option";
5+
import { Atom, AtomRegistry } from "effect/reactivity";
6+
7+
import { connectionAtomRuntime } from "../connection/runtime";
8+
import { appAtomRegistry } from "./atom-registry";
9+
import { environmentSession } from "./session";
10+
11+
// Each read mints a new one-use code; nothing keeps one once it is read.
12+
const peerPairingCodeAtom = Atom.family((environmentId: EnvironmentId) =>
13+
connectionAtomRuntime
14+
.atom((get) => {
15+
const prepared = Option.getOrNull(
16+
get(environmentSession.preparedConnectionValueAtom(environmentId)),
17+
);
18+
if (prepared === null) return Effect.never;
19+
return mintPeerPairingCode(prepared);
20+
})
21+
.pipe(Atom.withLabel(`mobile-peer-pairing-code:${environmentId}`)),
22+
);
23+
24+
/**
25+
* A fresh pairing code minted on `environmentId` with this client's session
26+
* there, for answering a link request. Fails with `PeerPairingCodeError` when
27+
* the session may not create one.
28+
*/
29+
export function mintPairingCodeOn(environmentId: EnvironmentId): Promise<string> {
30+
const atom = peerPairingCodeAtom(environmentId);
31+
appAtomRegistry.refresh(atom);
32+
return Effect.runPromise(
33+
Effect.scoped(
34+
Effect.gen(function* () {
35+
yield* AtomRegistry.mount(appAtomRegistry, atom);
36+
return yield* AtomRegistry.getResult(appAtomRegistry, atom, {
37+
suspendOnWaiting: true,
38+
}).pipe(Effect.timeout("15 seconds"));
39+
}),
40+
),
41+
);
42+
}

‎apps/server/src/mcp/OrchestratorMcpService.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -736,6 +736,10 @@ function turnItemText(item: OrchestrationV2TurnItem): string | null {
736736
return `Created thread ${item.targetThreadId} with ${item.targetProviderInstanceId} (${item.targetModel}).`;
737737
case "secret_request":
738738
return `Asked the user for ${item.label}: ${item.secretStatus}.`;
739+
case "link_request":
740+
return item.linkStatus === "linked"
741+
? `Linked ${item.linkedLabel ?? item.label ?? item.url ?? "an environment"} (${item.linkedAccess}).`
742+
: `Asked the user to link ${item.label ?? item.url ?? "an environment"}: ${item.linkStatus}.`;
739743
case "subagent":
740744
return item.result ?? item.progress ?? item.prompt;
741745
case "dynamic_tool":

‎apps/server/src/mcp/OrchestratorMcpToolkit.integration.test.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,8 @@ import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
7676
import * as McpHttpServer from "./McpHttpServer.ts";
7777
import * as McpInvocationContext from "./McpInvocationContext.ts";
7878
import * as PeerForwarding from "../peer/PeerForwarding.ts";
79+
import * as PeerLinkRequests from "../peer/PeerLinkRequests.ts";
80+
import * as PeerLinks from "../peer/PeerLinks.ts";
7981
import { delegatedTaskRun, hasPendingChildRuns } from "./OrchestratorMcpService.ts";
8082
import * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter";
8183

@@ -690,6 +692,8 @@ describe("orchestrator MCP toolkit", () => {
690692
Layer.provide(layerProviderRegistry),
691693
Layer.provide(layerScheduledTaskStub),
692694
Layer.provide(Layer.mock(PeerForwarding.PeerForwarding)({})),
695+
Layer.provide(Layer.mock(PeerLinkRequests.PeerLinkRequests)({})),
696+
Layer.provide(Layer.mock(PeerLinks.PeerLinks)({})),
693697
Layer.provide(Layer.mock(ThreadSearch.ThreadSearch)({})),
694698
Layer.provide(
695699
Layer.mock(ProjectService.ProjectService)({
@@ -3844,6 +3848,8 @@ describe("orchestrator MCP toolkit", () => {
38443848
Layer.provide(layerProviderRegistry),
38453849
Layer.provide(layerUnusedScheduledTaskStub),
38463850
Layer.provide(Layer.mock(PeerForwarding.PeerForwarding)({})),
3851+
Layer.provide(Layer.mock(PeerLinkRequests.PeerLinkRequests)({})),
3852+
Layer.provide(Layer.mock(PeerLinks.PeerLinks)({})),
38473853
Layer.provide(Layer.mock(ProjectService.ProjectService)({})),
38483854
Layer.provideMerge(
38493855
SecretRequests.layer.pipe(

‎apps/server/src/mcp/linkOrigin.test.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,8 @@ import * as McpHttpServer from "./McpHttpServer.ts";
4141
import * as McpInvocationContext from "./McpInvocationContext.ts";
4242
import * as PeerForwarding from "../peer/PeerForwarding.ts";
4343
import * as ThreadSearch from "../orchestration-v2/ThreadSearch.ts";
44+
import * as PeerLinkRequests from "../peer/PeerLinkRequests.ts";
45+
import * as PeerLinks from "../peer/PeerLinks.ts";
4446

4547
// A linked environment's session drives this one's real orchestrator through
4648
// its real T3 tools. What the link starts carries its origin, and the link
@@ -129,6 +131,8 @@ const layerTools = Layer.mergeAll(
129131
),
130132
Layer.provide(Layer.mock(SecretRequests.SecretRequests)({})),
131133
Layer.provide(Layer.mock(PeerForwarding.PeerForwarding)({})),
134+
Layer.provide(Layer.mock(PeerLinkRequests.PeerLinkRequests)({})),
135+
Layer.provide(Layer.mock(PeerLinks.PeerLinks)({})),
132136
Layer.provide(Layer.mock(ThreadSearch.ThreadSearch)({})),
133137
Layer.provide(Layer.mock(RemoteDelegation.RemoteDelegation)({})),
134138
Layer.provide(

‎apps/server/src/mcp/toolkits/core.test.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,8 @@ import { ProjectToolkit } from "./project/tools.ts";
5151
import { AttachmentToolkit } from "./attachment/tools.ts";
5252
import * as AttachmentHandlers from "./attachment/handlers.ts";
5353
import * as PeerForwarding from "../../peer/PeerForwarding.ts";
54+
import * as PeerLinkRequests from "../../peer/PeerLinkRequests.ts";
55+
import * as PeerLinks from "../../peer/PeerLinks.ts";
5456
import { ThreadToolkit } from "./thread/tools.ts";
5557
import { WorktreeToolkit } from "./worktree/tools.ts";
5658
import { DeviceToolkit } from "./device/tools.ts";
@@ -77,6 +79,8 @@ const layerThreadToolkit = McpHttpServer.layerThreadToolkit.pipe(
7779
Layer.provide(Layer.mock(ThreadSearch.ThreadSearch)({})),
7880
Layer.provide(Layer.mock(ScheduledTaskService.ScheduledTaskService)({})),
7981
Layer.provide(Layer.mock(PeerForwarding.PeerForwarding)({})),
82+
Layer.provide(Layer.mock(PeerLinkRequests.PeerLinkRequests)({})),
83+
Layer.provide(Layer.mock(PeerLinks.PeerLinks)({})),
8084
);
8185

8286
it("publishes unique tool names with reference-free object-root inputs", () => {
@@ -582,6 +586,8 @@ it.effect("refuses act-as-caller tools to a client caller", () =>
582586
Layer.provide(Layer.mock(ProviderAdapterRegistry.ProviderAdapterRegistryV2)({})),
583587
Layer.provide(Layer.mock(ScheduledTaskService.ScheduledTaskService)({})),
584588
Layer.provide(Layer.mock(PeerForwarding.PeerForwarding)({})),
589+
Layer.provide(Layer.mock(PeerLinkRequests.PeerLinkRequests)({})),
590+
Layer.provide(Layer.mock(PeerLinks.PeerLinks)({})),
585591
Layer.provide(Layer.mock(ProjectService.ProjectService)({})),
586592
Layer.provide(Layer.mock(SecretRequests.SecretRequests)({})),
587593
Layer.provide(Layer.mock(RemoteDelegation.RemoteDelegation)({})),
@@ -638,6 +644,8 @@ it.effect("a caller cannot rewrite a scheduled task that runs above its own mode
638644
Layer.provide(Layer.mock(ProjectService.ProjectService)({})),
639645
Layer.provide(Layer.mock(SecretRequests.SecretRequests)({})),
640646
Layer.provide(Layer.mock(PeerForwarding.PeerForwarding)({})),
647+
Layer.provide(Layer.mock(PeerLinkRequests.PeerLinkRequests)({})),
648+
Layer.provide(Layer.mock(PeerLinks.PeerLinks)({})),
641649
Layer.provide(Layer.mock(RemoteDelegation.RemoteDelegation)({})),
642650
),
643651
),
@@ -707,6 +715,8 @@ it.effect("a caller cannot interrupt a thread that runs above its own modes", ()
707715
Layer.provide(Layer.mock(ProviderAdapterRegistry.ProviderAdapterRegistryV2)({})),
708716
Layer.provide(Layer.mock(ScheduledTaskService.ScheduledTaskService)({})),
709717
Layer.provide(Layer.mock(PeerForwarding.PeerForwarding)({})),
718+
Layer.provide(Layer.mock(PeerLinkRequests.PeerLinkRequests)({})),
719+
Layer.provide(Layer.mock(PeerLinks.PeerLinks)({})),
710720
Layer.provide(Layer.mock(ProjectService.ProjectService)({})),
711721
Layer.provide(Layer.mock(SecretRequests.SecretRequests)({})),
712722
Layer.provide(Layer.mock(RemoteDelegation.RemoteDelegation)({})),

‎apps/server/src/mcp/toolkits/orchestrator/handlers.ts‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
1-
import type { EnvironmentId } from "@t3tools/contracts";
1+
import { type EnvironmentId, OrchestratorMcpFailure } from "@t3tools/contracts";
22
import * as Effect from "effect/Effect";
33
import type * as Tool from "effect/ai/Tool";
44

55
import { OrchestratorToolkit } from "./tools.ts";
66

77
import * as PeerForwarding from "../../../peer/PeerForwarding.ts";
8+
import * as PeerLinkRequests from "../../../peer/PeerLinkRequests.ts";
9+
import * as PeerLinks from "../../../peer/PeerLinks.ts";
810
import * as McpInvocationContext from "../../McpInvocationContext.ts";
911
import * as McpToolAccess from "../../McpToolAccess.ts";
1012
import * as OrchestratorMcpService from "../../OrchestratorMcpService.ts";
@@ -178,6 +180,29 @@ const handlers = {
178180
return yield* forwarding.links(scope);
179181
}),
180182
),
183+
// A link lets every agent here reach the other environment, so it is an
184+
// environment setting: full access, and never for linked work.
185+
t3_environment_link: McpToolAccess.writesEnvironment((input) =>
186+
Effect.gen(function* () {
187+
const scope = yield* McpInvocationContext.McpInvocationContext;
188+
const requests = yield* PeerLinkRequests.PeerLinkRequests;
189+
return yield* requests.request(scope, input);
190+
}),
191+
),
192+
t3_environment_unlink: McpToolAccess.writesEnvironment(({ environmentId }) =>
193+
Effect.gen(function* () {
194+
const links = yield* PeerLinks.PeerLinks;
195+
const removed = yield* links
196+
.unlink(environmentId)
197+
.pipe(
198+
Effect.mapError(
199+
(error) =>
200+
new OrchestratorMcpFailure({ code: "orchestration_error", message: error.message }),
201+
),
202+
);
203+
return { environmentId, removed };
204+
}),
205+
),
181206
t3_thread_interrupt: McpToolAccess.writesThreads(
182207
// A thread in a linked environment is checked there, where it lives.
183208
// This environment's own id names a thread here, which is checked here.

0 commit comments

Comments
 (0)