From 357c7b6acf02d9831af5d0dcc29bbffe810de0c4 Mon Sep 17 00:00:00 2001 From: Henry Chu Date: Wed, 28 Oct 2026 07:57:01 -0400 Subject: [PATCH 1/4] Route T3 tool calls between workspaces through the gateway hub Helper protocol v3 adds coder.hub.outbox, coder.hub.reply, and coder.hub.invoke. The gateway holds each v3 helper's outbox open, checks the requester's workspace link rule (workspaceLinks in the gateway config, upstream's link access modes), runs the call on the target workspace's helper as that link's caller, and replies. A workspace that is not connected is unreachable; the browser bridge refuses the hub methods. Environment ids are learned from connected helpers and kept in memory only. Co-Authored-By: Claude Opus 5.5 --- apps/coder-gateway/src/hub.test.ts | 249 +++++++++++++++++++ apps/coder-gateway/src/hub.ts | 266 +++++++++++++++++++++ apps/coder-gateway/src/rpcBridge.test.ts | 14 ++ apps/coder-gateway/src/rpcBridge.ts | 7 +- apps/coder-gateway/src/server.ts | 5 + packages/coder-cli/src/configStore.test.ts | 40 ++++ packages/coder-cli/src/configStore.ts | 44 +++- packages/coder-cli/src/profile.ts | 30 ++- packages/coder-cli/src/rpc.ts | 122 +++++++++- packages/contracts/src/coderGateway.ts | 15 ++ 10 files changed, 782 insertions(+), 10 deletions(-) create mode 100644 apps/coder-gateway/src/hub.test.ts create mode 100644 apps/coder-gateway/src/hub.ts diff --git a/apps/coder-gateway/src/hub.test.ts b/apps/coder-gateway/src/hub.test.ts new file mode 100644 index 0000000000000..f192ed56e32c3 --- /dev/null +++ b/apps/coder-gateway/src/hub.test.ts @@ -0,0 +1,249 @@ +import assert from "node:assert/strict"; +import { test } from "node:test"; + +import type { CoderHelperConnection, CoderHelperExit } from "@t3tools/coder-cli/helperConnection"; +import { + CODER_HUB_INVOKE_METHOD, + CODER_HUB_OUTBOX_METHOD, + CODER_HUB_REPLY_METHOD, +} from "@t3tools/coder-cli/rpc"; +import type { CoderProfileConfig, CoderWorkspaceLinkProfile } from "@t3tools/contracts"; +import * as Deferred from "effect/Deferred"; +import * as Effect from "effect/Effect"; + +import { makeCoderHub } from "./hub.ts"; + +interface SentRequest { + readonly _tag: string; + readonly id?: string; + readonly requestId?: string; + readonly tag?: string; + readonly payload?: Record; +} + +interface FakeHelper { + readonly connection: CoderHelperConnection; + readonly sent: Array; + readonly emit: (message: unknown) => void; + readonly exit: () => void; + /** The id of the outbox stream the hub opened. */ + readonly outboxId: () => string; + /** Pushes hub requests down the outbox stream. */ + readonly ask: (...values: Array) => void; + readonly requests: (tag: string) => Array; +} + +function fakeHelper(environmentId: string, protocolVersion = 3): FakeHelper { + const sent: Array = []; + const listeners = new Set<(message: unknown) => void>(); + const closed = Effect.runSync(Deferred.make()); + const requests = (tag: string) => sent.filter((message) => message.tag === tag); + const outboxId = () => { + const outbox = requests(CODER_HUB_OUTBOX_METHOD)[0]; + assert.ok(outbox?.id, "the hub opens the outbox"); + return outbox.id; + }; + const emit = (message: unknown) => { + for (const listener of [...listeners]) listener(message); + }; + return { + connection: { + info: { + protocolVersion, + platform: "linux", + architecture: "x64", + environment: { environmentId } as never, + }, + closed: Deferred.await(closed), + sendRpc: (message) => Effect.sync(() => void sent.push(message as SentRequest)), + needsDrain: () => false, + drained: Effect.void, + onRpcMessage: (listener) => { + listeners.add(listener); + return () => listeners.delete(listener); + }, + close: Effect.void, + }, + sent, + emit, + exit: () => Effect.runSync(Deferred.succeed(closed, { code: 0, signal: null, expected: true })), + outboxId, + ask: (...values) => emit({ _tag: "Chunk", requestId: outboxId(), values }), + requests, + }; +} + +const config = (links: ReadonlyArray): CoderProfileConfig => ({ + version: 1, + deployments: [{ id: "lab", name: "Lab", url: "https://coder.example" }], + workspaces: [ + { id: "api", name: "API", deploymentId: "lab", workspace: "dev/api" }, + { id: "web", name: "Web", deploymentId: "lab", workspace: "dev/web" }, + ], + workspaceLinks: links, +}); + +const API_TO_WEB: CoderWorkspaceLinkProfile = { + id: "api-to-web", + from: "api", + to: "web", + access: "approval-required", +}; + +const call = (id: string, environmentId: string) => ({ + _tag: "Call", + id, + environmentId, + tool: "t3_thread_read", + arguments: { threadId: "thread-1" }, + limits: { runtimeMode: "auto-accept-edits", interactionMode: "default" }, +}); + +async function eventually(assertion: () => void, timeoutMs = 500): Promise { + const deadline = Date.now() + timeoutMs; + for (;;) { + try { + assertion(); + return; + } catch (cause) { + if (Date.now() >= deadline) throw cause; + await new Promise((resolve) => setTimeout(resolve, 5)); + } + } +} + +const replies = (helper: FakeHelper) => + helper.requests(CODER_HUB_REPLY_METHOD).map((message) => message.payload); + +function setup(links: ReadonlyArray = [API_TO_WEB]) { + let current = config(links); + const hub = makeCoderHub({ config: () => current }); + const api = fakeHelper("env-api"); + const web = fakeHelper("env-web"); + const detachApi = hub.attach("api", api.connection); + const detachWeb = hub.attach("web", web.connection); + return { + hub, + api, + web, + detachApi, + detachWeb, + setConfig: (next: ReadonlyArray) => (current = config(next)), + }; +} + +test("routes a linked call to the target workspace as that link's caller", async () => { + const { api, web } = setup(); + api.ask(call("call-1", "env-web")); + + await eventually(() => assert.equal(web.requests(CODER_HUB_INVOKE_METHOD).length, 1)); + const invoke = web.requests(CODER_HUB_INVOKE_METHOD)[0]!; + assert.deepEqual(invoke.payload, { + link: { id: "api-to-web", label: "API", access: "approval-required" }, + tool: "t3_thread_read", + arguments: { threadId: "thread-1" }, + limits: { runtimeMode: "auto-accept-edits", interactionMode: "default" }, + }); + assert.ok( + api.sent.some((message) => message._tag === "Ack" && message.requestId === api.outboxId()), + ); + + web.emit({ + _tag: "Exit", + requestId: invoke.id, + exit: { _tag: "Success", value: { _tag: "Success", value: { status: "idle" } } }, + }); + await eventually(() => + assert.deepEqual(replies(api), [ + { _tag: "Call", id: "call-1", outcome: { _tag: "Success", value: { status: "idle" } } }, + ]), + ); +}); + +test("refuses a call without a link rule, and one whose target is disconnected", async () => { + const { api, web, detachWeb, setConfig } = setup([]); + api.ask(call("no-rule", "env-web")); + api.ask(call("unknown", "env-elsewhere")); + await eventually(() => assert.equal(replies(api).length, 2)); + for (const reply of replies(api)) { + assert.equal((reply?.outcome as { _tag: string })._tag, "Failure"); + assert.equal( + ((reply?.outcome as { failure: { code: string } }).failure as { code: string }).code, + "capability_denied", + ); + } + assert.equal(web.requests(CODER_HUB_INVOKE_METHOD).length, 0); + + setConfig([API_TO_WEB]); + detachWeb(); + api.ask(call("gone", "env-web")); + await eventually(() => assert.equal(replies(api).length, 3)); + const failure = (replies(api)[2]?.outcome as { failure: { code: string; message: string } }) + .failure; + assert.equal(failure.code, "orchestration_error"); + assert.equal(failure.message, "Workspace Web is not connected."); +}); + +test("fails a call whose target exits before answering", async () => { + const { api, web } = setup(); + api.ask(call("call-1", "env-web")); + await eventually(() => assert.equal(web.requests(CODER_HUB_INVOKE_METHOD).length, 1)); + web.exit(); + await eventually(() => assert.equal(replies(api).length, 1)); + const outcome = replies(api)[0]?.outcome as { _tag: string; failure: { code: string } }; + assert.equal(outcome._tag, "Failure"); + assert.equal(outcome.failure.code, "orchestration_error"); +}); + +test("interrupts a requester's calls when it goes away and sends it nothing", async () => { + const { api, web, detachApi } = setup(); + api.ask(call("call-1", "env-web")); + await eventually(() => assert.equal(web.requests(CODER_HUB_INVOKE_METHOD).length, 1)); + const invoke = web.requests(CODER_HUB_INVOKE_METHOD)[0]!; + detachApi(); + assert.ok( + web.sent.some((message) => message._tag === "Interrupt" && message.requestId === invoke.id), + ); + web.emit({ + _tag: "Exit", + requestId: invoke.id, + exit: { _tag: "Success", value: { _tag: "Success", value: {} } }, + }); + await new Promise((resolve) => setTimeout(resolve, 20)); + assert.deepEqual(replies(api), []); +}); + +test("lists this workspace's links to workspaces seen this run", async () => { + const { api, detachWeb } = setup([ + API_TO_WEB, + { id: "web-to-api", from: "web", to: "api", access: "read-only" }, + ]); + api.ask({ _tag: "ListLinks", id: "links-1" }); + await eventually(() => + assert.deepEqual(replies(api), [ + { + _tag: "ListLinks", + id: "links-1", + links: [ + { + environmentId: "env-web", + label: "Web", + access: "approval-required", + connected: true, + }, + ], + }, + ]), + ); + detachWeb(); + api.ask({ _tag: "ListLinks", id: "links-2" }); + await eventually(() => assert.equal(replies(api).length, 2)); + assert.equal((replies(api)[1]?.links as Array<{ connected: boolean }>)[0]?.connected, false); +}); + +test("leaves helpers older than protocol 3 alone", () => { + const hub = makeCoderHub({ config: () => config([API_TO_WEB]) }); + const old = fakeHelper("env-old", 2); + hub.attach("api", old.connection); + assert.deepEqual(old.sent, []); +}); diff --git a/apps/coder-gateway/src/hub.ts b/apps/coder-gateway/src/hub.ts new file mode 100644 index 0000000000000..5600c44d646f9 --- /dev/null +++ b/apps/coder-gateway/src/hub.ts @@ -0,0 +1,266 @@ +import type { CoderHelperConnection } from "@t3tools/coder-cli/helperConnection"; +import { + CODER_HUB_INVOKE_METHOD, + CODER_HUB_OUTBOX_METHOD, + CODER_HUB_REPLY_METHOD, + CoderHubCallOutcome, + CoderHubReply, + CoderHubRequest, + type CoderHubLink, +} from "@t3tools/coder-cli/rpc"; +import { type CoderProfileConfig, OrchestratorMcpFailure } from "@t3tools/contracts"; +import * as Effect from "effect/Effect"; +import * as Fiber from "effect/Fiber"; +import * as Schema from "effect/Schema"; + +/** The first helper protocol that serves the hub methods. */ +const HUB_PROTOCOL_VERSION = 3; + +const decodeRequest = Schema.decodeUnknownSync(CoderHubRequest); +const decodeOutcome = Schema.decodeUnknownSync(CoderHubCallOutcome); +const encodeReply = Schema.encodeSync(CoderHubReply); + +type CallRequest = Extract; +type CallOutcome = CoderHubCallOutcome; + +function isRecord(value: unknown): value is Record { + return typeof value === "object" && value !== null && !Array.isArray(value); +} + +const failed = (code: OrchestratorMcpFailure["code"], message: string): CallOutcome => ({ + _tag: "Failure", + failure: new OrchestratorMcpFailure({ code, message }), +}); + +interface Attached { + readonly workspaceId: string; + readonly connection: CoderHelperConnection; + readonly environmentId: string; + /** Runs when this helper goes away: calls it was asked to run fail, calls it asked for stop. */ + readonly onDetach: Set<() => void>; +} + +export interface CoderHub { + /** + * Routes this helper's hub requests until the returned function runs. A helper older than + * protocol 3 is not attached. + */ + readonly attach: (workspaceId: string, connection: CoderHelperConnection) => () => void; +} + +export interface CoderHubOptions { + /** The gateway's current configuration: link rules and workspace names. */ + readonly config: () => CoderProfileConfig; +} + +/** + * Coder: routes T3 tool calls between two workspace helpers the gateway holds. A helper asks + * through its `coder.hub.outbox` stream; the gateway checks the workspace link rule, runs the call + * on the other helper with `coder.hub.invoke` as that link's caller, and answers with + * `coder.hub.reply`. Both helpers are local `coder ssh` children, so nothing here listens or + * leaves the laptop; a workspace that is not connected is unreachable. + */ +export function makeCoderHub(options: CoderHubOptions): CoderHub { + let nextRequestId = 0; + const attached = new Map(); + // Learned from each helper this run; never persisted. + const workspaceByEnvironment = new Map(); + const environmentByWorkspace = new Map(); + + const send = (connection: CoderHelperConnection, message: unknown): void => { + void Effect.runPromiseExit(connection.sendRpc(message)); + }; + + const workspaceName = (workspaceId: string): string => + options.config().workspaces.find((entry) => entry.id === workspaceId)?.name ?? workspaceId; + + const reply = (requester: Attached, message: CoderHubReply): void => { + if (attached.get(requester.workspaceId) !== requester) return; + send(requester.connection, { + _tag: "Request", + id: `gateway-hub:${String(nextRequestId++)}`, + tag: CODER_HUB_REPLY_METHOD, + payload: encodeReply(message), + headers: [], + }); + }; + + /** Runs one call on the target helper and settles with its outcome. */ + const invoke = ( + requester: Attached, + target: Attached, + request: CallRequest, + link: { readonly id: string; readonly label: string; readonly access: string }, + ): Promise => { + const id = `gateway-hub:${String(nextRequestId++)}`; + const targetName = workspaceName(target.workspaceId); + return new Promise((resolve) => { + let settled = false; + const settle = (outcome: CallOutcome | undefined) => { + if (settled) return; + settled = true; + unsubscribe(); + target.onDetach.delete(onTargetDetach); + requester.onDetach.delete(onRequesterDetach); + resolve(outcome); + }; + const onTargetDetach = () => + settle( + failed( + "orchestration_error", + `Workspace ${targetName} disconnected before it answered. Retry once it is connected again.`, + ), + ); + // The requester is gone, so nobody reads the answer: stop the call there. + const onRequesterDetach = () => { + send(target.connection, { _tag: "Interrupt", requestId: id }); + settle(undefined); + }; + const unsubscribe = target.connection.onRpcMessage((message) => { + if (!isRecord(message) || message.requestId !== id || message._tag !== "Exit") return; + const exit = message.exit; + if (isRecord(exit) && exit._tag === "Success") { + try { + settle(decodeOutcome(exit.value)); + return; + } catch { + // Falls through to the failure below. + } + } + settle( + failed("orchestration_error", `Workspace ${targetName} could not run ${request.tool}.`), + ); + }); + target.onDetach.add(onTargetDetach); + requester.onDetach.add(onRequesterDetach); + void Effect.runPromiseExit( + target.connection.sendRpc({ + _tag: "Request", + id, + tag: CODER_HUB_INVOKE_METHOD, + payload: { + link, + tool: request.tool, + arguments: request.arguments, + limits: request.limits, + }, + headers: [], + }), + ).then((exit) => { + if (exit._tag === "Failure") onTargetDetach(); + }); + }); + }; + + const handleCall = async (requester: Attached, request: CallRequest): Promise => { + const config = options.config(); + const targetWorkspaceId = workspaceByEnvironment.get(request.environmentId); + const rule = + targetWorkspaceId === undefined + ? undefined + : config.workspaceLinks?.find( + (entry) => entry.from === requester.workspaceId && entry.to === targetWorkspaceId, + ); + let outcome: CallOutcome | undefined; + if (targetWorkspaceId === undefined || rule === undefined) { + outcome = failed( + "capability_denied", + "This workspace is not linked to that one. Add a link in T3 Coder's workspace Links settings.", + ); + } else { + const target = attached.get(targetWorkspaceId); + if (target === undefined) { + outcome = failed( + "orchestration_error", + `Workspace ${workspaceName(targetWorkspaceId)} is not connected.`, + ); + } else { + outcome = await invoke(requester, target, request, { + id: rule.id, + label: workspaceName(requester.workspaceId), + access: rule.access, + }); + } + } + if (outcome === undefined) return; + reply(requester, { + _tag: "Call", + id: request.id, + outcome, + }); + }; + + const listLinks = (requester: Attached): ReadonlyArray => + (options.config().workspaceLinks ?? []).flatMap((rule) => { + if (rule.from !== requester.workspaceId) return []; + const environmentId = environmentByWorkspace.get(rule.to); + if (environmentId === undefined) return []; + return [ + { + environmentId: environmentId as CoderHubLink["environmentId"], + label: workspaceName(rule.to), + access: rule.access, + connected: attached.has(rule.to), + }, + ]; + }); + + const attach: CoderHub["attach"] = (workspaceId, connection) => { + if (connection.info.protocolVersion < HUB_PROTOCOL_VERSION) return () => {}; + const environmentId = connection.info.environment.environmentId; + const previous = attached.get(workspaceId); + if (previous !== undefined) detach(previous); + const entry: Attached = { workspaceId, connection, environmentId, onDetach: new Set() }; + attached.set(workspaceId, entry); + const staleWorkspace = workspaceByEnvironment.get(environmentId); + if (staleWorkspace !== undefined && staleWorkspace !== workspaceId) { + environmentByWorkspace.delete(staleWorkspace); + } + workspaceByEnvironment.set(environmentId, workspaceId); + environmentByWorkspace.set(workspaceId, environmentId); + + const outboxId = `gateway-hub:${String(nextRequestId++)}`; + const unsubscribe = connection.onRpcMessage((message) => { + if (!isRecord(message) || message.requestId !== outboxId) return; + if (message._tag !== "Chunk" || !Array.isArray(message.values)) return; + for (const value of message.values) { + let request: CoderHubRequest; + try { + request = decodeRequest(value); + } catch { + continue; + } + if (request._tag === "ListLinks") { + reply(entry, { _tag: "ListLinks", id: request.id, links: listLinks(entry) }); + } else { + void handleCall(entry, request); + } + } + send(connection, { _tag: "Ack", requestId: outboxId }); + }); + // A helper that exits takes its outbox with it. + const closed = Effect.runFork(connection.closed); + closed.addObserver(() => detach(entry)); + entry.onDetach.add(() => { + unsubscribe(); + Effect.runFork(Fiber.interrupt(closed)); + }); + send(connection, { + _tag: "Request", + id: outboxId, + tag: CODER_HUB_OUTBOX_METHOD, + payload: {}, + headers: [], + }); + return () => detach(entry); + }; + + function detach(entry: Attached): void { + if (attached.get(entry.workspaceId) !== entry) return; + attached.delete(entry.workspaceId); + for (const callback of [...entry.onDetach]) callback(); + entry.onDetach.clear(); + } + + return { attach }; +} diff --git a/apps/coder-gateway/src/rpcBridge.test.ts b/apps/coder-gateway/src/rpcBridge.test.ts index 61aebfb037e96..b031d6da05dfa 100644 --- a/apps/coder-gateway/src/rpcBridge.test.ts +++ b/apps/coder-gateway/src/rpcBridge.test.ts @@ -2,6 +2,7 @@ import assert from "node:assert/strict"; import { test } from "node:test"; import type { CoderHelperConnection } from "@t3tools/coder-cli/helperConnection"; +import { CODER_HUB_METHODS } from "@t3tools/coder-cli/rpc"; import * as Effect from "effect/Effect"; import * as Exit from "effect/Exit"; import * as Scope from "effect/Scope"; @@ -143,6 +144,19 @@ test("translates browser request ids for the helper and restores them in respons }); }); +test("refuses the gateway-only hub methods from the browser", async () => { + await withBridge(async ({ bridge, helper }) => { + const session = await Effect.runPromise(bridge.attach(fakeTransport())); + for (const [index, tag] of [...CODER_HUB_METHODS].entries()) { + const exit = await Effect.runPromiseExit( + session.receive({ _tag: "Request", id: index, tag, payload: {}, headers: [] }), + ); + assert.equal(exit._tag, "Failure", tag); + } + assert.deepEqual(helper.sent, []); + }); +}); + test("reconnects with reused browser ids without colliding with detached requests", async () => { await withBridge(async ({ bridge, helper }) => { const firstTransport = fakeTransport(); diff --git a/apps/coder-gateway/src/rpcBridge.ts b/apps/coder-gateway/src/rpcBridge.ts index 92b7676017f74..1235a67691f0f 100644 --- a/apps/coder-gateway/src/rpcBridge.ts +++ b/apps/coder-gateway/src/rpcBridge.ts @@ -1,4 +1,5 @@ import type { CoderHelperConnection } from "@t3tools/coder-cli/helperConnection"; +import { CODER_HUB_METHODS } from "@t3tools/coder-cli/rpc"; import { WS_METHODS } from "@t3tools/contracts"; import type * as Duration from "effect/Duration"; import * as Effect from "effect/Effect"; @@ -95,10 +96,12 @@ function decodeBrowserMessage(message: unknown): BrowserRpcMessage { if (!isRequestId(message.id) || typeof message.tag !== "string") { throw new RpcBridgeSessionError("Browser sent an invalid RPC request."); } - // The gateway's asset and upload routes are the only callers of the helper's asset methods. + // The gateway's asset and upload routes are the only callers of the helper's asset methods, + // and its hub the only caller of the hub methods. if ( message.tag === WS_METHODS.coderServeAsset || - message.tag === WS_METHODS.coderWriteRequestBody + message.tag === WS_METHODS.coderWriteRequestBody || + CODER_HUB_METHODS.has(message.tag) ) { throw new RpcBridgeSessionError("Browser sent a gateway-only RPC request."); } diff --git a/apps/coder-gateway/src/server.ts b/apps/coder-gateway/src/server.ts index 5f39317225b15..a0499fa4b1448 100644 --- a/apps/coder-gateway/src/server.ts +++ b/apps/coder-gateway/src/server.ts @@ -68,6 +68,7 @@ import { type RpcBridgeSession, type WorkspaceRpcBridge, } from "./rpcBridge.ts"; +import { makeCoderHub } from "./hub.ts"; export const CODER_GATEWAY_HOST = "127.0.0.1"; const MAX_CONFIG_BODY_BYTES = 64 * 1024; @@ -707,6 +708,7 @@ export function makeLocalCoderGateway( catch: (cause) => cause, }) : emptyCoderProfileConfig(); + const hub = makeCoderHub({ config: () => profileConfig }); const fibers = yield* FiberSet.make(); const runPromise = yield* FiberSet.runtimePromise(fibers)(); const runFork = yield* FiberSet.runtime(fibers)(); @@ -1073,6 +1075,9 @@ export function makeLocalCoderGateway( return yield* Effect.fail(new Error("Coder workspace connection was cancelled.")); } recordDiagnosticEvent(workspaceId, attempt, "connected"); + // Coder: route hub requests to and from this helper while it is connected. + const detachFromHub = hub.attach(workspaceId, connection); + yield* Scope.addFinalizer(connectionScope, Effect.sync(detachFromHub)); return { connection, rpcBridge } satisfies WorkspaceConnection; }).pipe( Effect.onError(() => diff --git a/packages/coder-cli/src/configStore.test.ts b/packages/coder-cli/src/configStore.test.ts index 5a1a68c23a808..48682999964cb 100644 --- a/packages/coder-cli/src/configStore.test.ts +++ b/packages/coder-cli/src/configStore.test.ts @@ -142,6 +142,46 @@ describe("Coder profile config store", () => { ); }); + it("validates and round-trips workspace link rules", () => { + const base = { + version: 1, + deployments: [{ id: "lab", name: "Lab", url: "https://coder.example" }], + workspaces: [ + { id: "api", name: "API", deploymentId: "lab", workspace: "dev/api" }, + { id: "web", name: "Web", deploymentId: "lab", workspace: "dev/web" }, + ], + } as const; + const config = { + ...base, + workspaceLinks: [ + { id: "api-to-web", from: "api", to: "web", access: "approval-required" }, + { id: "web-to-api", from: "web", to: "api", access: "read-only" }, + ], + } as const; + const link = config.workspaceLinks[0]; + + deepStrictEqual(parseCoderProfileConfig(config), config); + throws(() => + parseCoderProfileConfig({ ...base, workspaceLinks: [link, { ...link, id: "again" }] }), + ); + throws(() => + parseCoderProfileConfig({ + ...base, + workspaceLinks: [link, { ...link, to: "api", from: "web", id: "api-to-web" }], + }), + ); + throws(() => parseCoderProfileConfig({ ...base, workspaceLinks: [{ ...link, to: "api" }] })); + throws(() => + parseCoderProfileConfig({ ...base, workspaceLinks: [{ ...link, to: "missing" }] }), + ); + throws(() => + parseCoderProfileConfig({ ...base, workspaceLinks: [{ ...link, access: "root" }] }), + ); + throws(() => + parseCoderProfileConfig({ ...base, workspaceLinks: [{ ...link, token: "secret" }] }), + ); + }); + it("drops legacy project roots from workspace connection profiles", () => { deepStrictEqual( parseCoderProfileConfig({ diff --git a/packages/coder-cli/src/configStore.ts b/packages/coder-cli/src/configStore.ts index b9da34f496406..5dcacb8cdca44 100644 --- a/packages/coder-cli/src/configStore.ts +++ b/packages/coder-cli/src/configStore.ts @@ -8,9 +8,11 @@ import * as NodePath from "node:path"; import { normalizeCoderDeploymentProfile, normalizeCoderPortForwardProfile, + normalizeCoderWorkspaceLinkProfile, normalizeCoderWorkspaceProfile, type CoderDeploymentProfile, type CoderPortForwardProfile, + type CoderWorkspaceLinkProfile, type CoderWorkspaceProfile, } from "./profile.ts"; @@ -109,6 +111,25 @@ function parsePortForward(value: unknown): CoderPortForwardProfile { }); } +function parseWorkspaceLink(value: unknown): CoderWorkspaceLinkProfile { + if (!isRecord(value)) throw new Error("Coder workspace link must be an object."); + requireAllowedKeys(value, ["id", "from", "to", "access"], "Coder workspace link"); + if ( + typeof value.id !== "string" || + typeof value.from !== "string" || + typeof value.to !== "string" || + typeof value.access !== "string" + ) { + throw new Error("Coder workspace link is missing an id, workspaces, or access mode."); + } + return normalizeCoderWorkspaceLinkProfile({ + id: value.id, + from: value.from, + to: value.to, + access: value.access as CoderWorkspaceLinkProfile["access"], + }); +} + function requireUniqueIds(values: readonly { readonly id: string }[], field: string): void { const ids = new Set(); for (const value of values) { @@ -123,7 +144,7 @@ export function parseCoderProfileConfig(value: unknown): CoderProfileConfig { } requireAllowedKeys( value, - ["version", "deployments", "workspaces", "portForwards"], + ["version", "deployments", "workspaces", "portForwards", "workspaceLinks"], "Coder profile config", ); if (!Array.isArray(value.deployments) || !Array.isArray(value.workspaces)) { @@ -132,13 +153,18 @@ export function parseCoderProfileConfig(value: unknown): CoderProfileConfig { if (value.portForwards !== undefined && !Array.isArray(value.portForwards)) { throw new Error("Coder profile configuration port forwards must be an array."); } + if (value.workspaceLinks !== undefined && !Array.isArray(value.workspaceLinks)) { + throw new Error("Coder profile configuration workspace links must be an array."); + } const deployments = value.deployments.map(parseDeployment); const workspaces = value.workspaces.map(parseWorkspace); const portForwards = (value.portForwards ?? []).map(parsePortForward); + const workspaceLinks = (value.workspaceLinks ?? []).map(parseWorkspaceLink); requireUniqueIds(deployments, "deployment"); requireUniqueIds(workspaces, "workspace"); requireUniqueIds(portForwards, "port forward"); + requireUniqueIds(workspaceLinks, "workspace link"); const deploymentIds = new Set(deployments.map((deployment) => deployment.id)); const workspaceTargets = new Set(); @@ -172,11 +198,27 @@ export function parseCoderProfileConfig(value: unknown): CoderProfileConfig { } localPorts.add(localTarget); } + const linkPairs = new Set(); + for (const link of workspaceLinks) { + for (const workspaceId of [link.from, link.to]) { + if (!workspaceIds.has(workspaceId)) { + throw new Error( + `Coder workspace link ${link.id} references unknown workspace ${workspaceId}.`, + ); + } + } + const pair = `${link.from}\0${link.to}`; + if (linkPairs.has(pair)) { + throw new Error(`Workspace ${link.from} is linked to workspace ${link.to} more than once.`); + } + linkPairs.add(pair); + } return { version: 1, deployments, workspaces, ...(value.portForwards === undefined ? {} : { portForwards }), + ...(value.workspaceLinks === undefined ? {} : { workspaceLinks }), }; } diff --git a/packages/coder-cli/src/profile.ts b/packages/coder-cli/src/profile.ts index 74c1d28179fee..e83e08415aea3 100644 --- a/packages/coder-cli/src/profile.ts +++ b/packages/coder-cli/src/profile.ts @@ -1,14 +1,20 @@ -import type { - CoderDeploymentProfile, - CoderWorkspaceProfile, - CoderPortForwardProfile, +import { + AuthMcpClientAccess, + type CoderDeploymentProfile, + type CoderWorkspaceLinkProfile, + type CoderWorkspaceProfile, + type CoderPortForwardProfile, } from "@t3tools/contracts"; +import * as Schema from "effect/Schema"; export type { CoderDeploymentProfile, + CoderWorkspaceLinkProfile, CoderWorkspaceProfile, CoderPortForwardProfile, } from "@t3tools/contracts"; +const isLinkAccess = Schema.is(AuthMcpClientAccess); + function requireSingleLine(value: string, field: string): string { const normalized = value.trim(); if (normalized.length === 0) { @@ -100,3 +106,19 @@ export function normalizeCoderPortForwardProfile( remotePort: normalizePort(profile.remotePort, "Remote port"), }; } + +export function normalizeCoderWorkspaceLinkProfile( + profile: CoderWorkspaceLinkProfile, +): CoderWorkspaceLinkProfile { + const id = requireSingleLine(profile.id, "Coder workspace link id"); + if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(id)) { + throw new Error("Coder workspace link id contains unsupported characters."); + } + const from = requireSingleLine(profile.from, "Coder workspace link source"); + const to = requireSingleLine(profile.to, "Coder workspace link target"); + if (from === to) throw new Error("A workspace link must name two different workspaces."); + if (!isLinkAccess(profile.access)) { + throw new Error("Coder workspace link access is not a supported access mode."); + } + return { id, from, to, access: profile.access }; +} diff --git a/packages/coder-cli/src/rpc.ts b/packages/coder-cli/src/rpc.ts index 56aae5fe45ee7..bc2f179d9b638 100644 --- a/packages/coder-cli/src/rpc.ts +++ b/packages/coder-cli/src/rpc.ts @@ -1,11 +1,30 @@ +import { + AuthMcpClientAccess, + EnvironmentId, + OrchestratorMcpFailure, + ProviderInteractionMode, + RuntimeMode, +} from "@t3tools/contracts"; import * as Schema from "effect/Schema"; import * as Rpc from "effect/rpc/Rpc"; import * as RpcGroup from "effect/rpc/RpcGroup"; // Version 2 makes browser-session request isolation and synchronization -// completion part of the required gateway/helper contract. -export const CODER_HELPER_PROTOCOL_VERSION = 2; +// completion part of the required gateway/helper contract. Version 3 adds the +// hub methods, which let the gateway route T3 tool calls between two +// workspaces it is connected to. +export const CODER_HELPER_PROTOCOL_VERSION = 3; export const CODER_HELPER_INFO_METHOD = "coder.helper.info"; +export const CODER_HUB_OUTBOX_METHOD = "coder.hub.outbox"; +export const CODER_HUB_REPLY_METHOD = "coder.hub.reply"; +export const CODER_HUB_INVOKE_METHOD = "coder.hub.invoke"; + +/** Only the gateway calls these; the browser bridge refuses them. */ +export const CODER_HUB_METHODS: ReadonlySet = new Set([ + CODER_HUB_OUTBOX_METHOD, + CODER_HUB_REPLY_METHOD, + CODER_HUB_INVOKE_METHOD, +]); export class CoderHelperProtocolError extends Schema.TaggedError()( "CoderHelperProtocolError", @@ -30,4 +49,101 @@ export const CoderHelperInfoRpc = Rpc.make(CODER_HELPER_INFO_METHOD, { error: CoderHelperProtocolError, }); -export const CoderHelperRpcGroup = RpcGroup.make(CoderHelperInfoRpc); +/** The calling agent's modes; the target workspace caps the call at the narrower of these and the link's access. */ +export const CoderHubCallLimits = Schema.Struct({ + runtimeMode: RuntimeMode, + interactionMode: ProviderInteractionMode, +}); +export type CoderHubCallLimits = typeof CoderHubCallLimits.Type; + +/** A link rule as the requesting workspace sees it. */ +export const CoderHubLink = Schema.Struct({ + environmentId: EnvironmentId, + label: Schema.String, + access: AuthMcpClientAccess, + /** Whether the gateway holds a helper connection to that workspace right now. */ + connected: Schema.Boolean, +}); +export type CoderHubLink = typeof CoderHubLink.Type; + +/** + * What a helper asks the gateway for. `Call` runs a T3 tool in another + * workspace; `ListLinks` reads the link rules from this workspace. + */ +export const CoderHubRequest = Schema.Union([ + Schema.TaggedStruct("Call", { + id: Schema.String, + environmentId: EnvironmentId, + tool: Schema.String, + /** The tool's encoded parameters, without `environmentId`. */ + arguments: Schema.Record(Schema.String, Schema.Unknown), + limits: CoderHubCallLimits, + }), + Schema.TaggedStruct("ListLinks", { + id: Schema.String, + }), +]); +export type CoderHubRequest = typeof CoderHubRequest.Type; + +/** A tool call's outcome: its encoded success, or the failure the agent sees. */ +export const CoderHubCallOutcome = Schema.Union([ + Schema.TaggedStruct("Success", { value: Schema.Unknown }), + Schema.TaggedStruct("Failure", { failure: OrchestratorMcpFailure }), +]); +export type CoderHubCallOutcome = typeof CoderHubCallOutcome.Type; + +export const CoderHubReply = Schema.Union([ + Schema.TaggedStruct("Call", { id: Schema.String, outcome: CoderHubCallOutcome }), + Schema.TaggedStruct("ListLinks", { + id: Schema.String, + links: Schema.Array(CoderHubLink), + }), +]); +export type CoderHubReply = typeof CoderHubReply.Type; + +/** + * The gateway holds this stream open on every connected helper: each item is + * a request the helper's agents made of another workspace. + */ +export const CoderHubOutboxRpc = Rpc.make(CODER_HUB_OUTBOX_METHOD, { + payload: Schema.Struct({}), + success: CoderHubRequest, + stream: true, +}); + +/** The gateway's answer to an outbox request; an unknown id is ignored. */ +export const CoderHubReplyRpc = Rpc.make(CODER_HUB_REPLY_METHOD, { + payload: CoderHubReply, +}); + +/** + * Runs a T3 tool here for an agent in another workspace, as that link's + * caller: what it starts here carries the link as its origin, and it may + * change only that work unless the link has full access. + */ +export const CoderHubInvokeRpc = Rpc.make(CODER_HUB_INVOKE_METHOD, { + payload: Schema.Struct({ + link: Schema.Struct({ + /** Stable for the link rule; the origin work started here carries. */ + id: Schema.String, + /** The requesting workspace's name. */ + label: Schema.String, + access: AuthMcpClientAccess, + }), + tool: Schema.String, + arguments: Schema.Record(Schema.String, Schema.Unknown), + limits: CoderHubCallLimits, + }), + success: CoderHubCallOutcome, +}); + +/** The hub methods, served by the workspace runtime that owns the T3 tools. */ +export const CoderHubRpcGroup = RpcGroup.make( + CoderHubOutboxRpc, + CoderHubReplyRpc, + CoderHubInvokeRpc, +); + +export const CoderHelperInfoRpcGroup = RpcGroup.make(CoderHelperInfoRpc); + +export const CoderHelperRpcGroup = CoderHelperInfoRpcGroup.merge(CoderHubRpcGroup); diff --git a/packages/contracts/src/coderGateway.ts b/packages/contracts/src/coderGateway.ts index 706506a66934c..d560c1a95d28d 100644 --- a/packages/contracts/src/coderGateway.ts +++ b/packages/contracts/src/coderGateway.ts @@ -1,4 +1,6 @@ // Non-secret loopback gateway wire types. No process or filesystem imports. +import type { AuthMcpClientAccess } from "./auth.ts"; + export interface CoderDeploymentProfile { readonly id: string; readonly name: string; @@ -21,12 +23,25 @@ export interface CoderPortForwardProfile { readonly remotePort: number; } +/** + * Lets agents in workspace `from` act in workspace `to` through the gateway, capped at + * `access` (upstream's link access modes). Directional; holds no secret. + */ +export interface CoderWorkspaceLinkProfile { + readonly id: string; + readonly from: string; + readonly to: string; + readonly access: AuthMcpClientAccess; +} + export interface CoderProfileConfig { readonly version: 1; readonly deployments: readonly CoderDeploymentProfile[]; readonly workspaces: readonly CoderWorkspaceProfile[]; /** Added by the port-forward gateway change; absent configs are treated as empty. */ readonly portForwards?: readonly CoderPortForwardProfile[]; + /** Absent configs have no links. */ + readonly workspaceLinks?: readonly CoderWorkspaceLinkProfile[]; } export interface CoderPortForwardRuntimeStatus { From 805b08d5fce8a332e4a0c6b1caaa6204894a1c7d Mon Sep 17 00:00:00 2001 From: Henry Chu Date: Wed, 28 Oct 2026 07:57:01 -0400 Subject: [PATCH 2/4] Restore upstream's linked environments over the gateway hub Brings back upstream's PeerForwarding, RemoteDelegation, linkOrigin fence, McpToolAccess forwarding, delegate_task's remote branch, t3_environment_links, and the linked-machine orchestration instructions. The transport is the one seam: PeerMcpClient and PeerLinks keep upstream's service tags but go through coderHub.ts, the helper's side of the hub, whose invoke handler runs a forwarded tool as the link's caller and refuses it while Labs' Linked environments switch is off, as upstream's /mcp does. Advertises peerLinks and linkFence. Upstream's peer tests pair two HTTP servers and are not carried; coderHub.test.ts tests the transport. Co-Authored-By: Claude Opus 5.5 --- apps/coder-helper/src/helper.ts | 3 +- apps/server/package.json | 1 + apps/server/src/coderEnvironment.ts | 16 +- apps/server/src/coderHub.test.ts | 233 +++++ apps/server/src/coderHub.ts | 289 +++++++ apps/server/src/coderServer.ts | 25 +- apps/server/src/mcp/McpInvocationContext.ts | 61 +- .../server/src/mcp/McpSessionRegistry.test.ts | 6 +- apps/server/src/mcp/McpToolAccess.ts | 253 ++++-- .../OrchestratorMcpService.activity.test.ts | 4 + .../src/mcp/OrchestratorMcpService.test.ts | 24 + apps/server/src/mcp/OrchestratorMcpService.ts | 167 +++- ...skCancelNativeSubagent.integration.test.ts | 2 + apps/server/src/mcp/WorktreeMcpService.ts | 4 +- .../src/mcp/bridge/T3ToolBridge.test.ts | 2 + apps/server/src/mcp/bridge/T3ToolBridge.ts | 11 +- apps/server/src/mcp/bridge/T3ToolDispatch.ts | 5 + apps/server/src/mcp/linkOrigin.ts | 60 ++ .../src/mcp/toolkits/orchestrator/handlers.ts | 10 + .../src/mcp/toolkits/orchestrator/tools.ts | 27 +- .../src/mcp/toolkits/project/handlers.ts | 122 +-- apps/server/src/mcp/toolkits/project/tools.ts | 4 +- .../src/orchestration-v2/ProjectionStore.ts | 38 +- .../ProviderSessionManager.test.ts | 8 +- .../ProviderTurnControlService.test.ts | 2 +- .../RemoteDelegatedTask.test.ts | 411 +++++++++ .../orchestration-v2/ThreadLaunchService.ts | 12 +- .../ThreadManagementService.ts | 39 +- apps/server/src/peer/PeerForwarding.ts | 277 ++++++ apps/server/src/peer/PeerLinks.ts | 84 ++ apps/server/src/peer/PeerMcpClient.ts | 79 ++ apps/server/src/peer/RemoteDelegation.ts | 802 ++++++++++++++++++ .../project/ProjectSetupScriptRunner.test.ts | 4 + .../src/project/ProjectSetupScriptRunner.ts | 31 +- knip.jsonc | 2 + packages/client-runtime/src/t3ToolSummary.ts | 3 + .../src/server/orchestrationInstructions.ts | 8 +- packages/shared/src/t3McpToolPresentation.ts | 9 +- pnpm-lock.yaml | 3 + 39 files changed, 2960 insertions(+), 181 deletions(-) create mode 100644 apps/server/src/coderHub.test.ts create mode 100644 apps/server/src/coderHub.ts create mode 100644 apps/server/src/mcp/linkOrigin.ts create mode 100644 apps/server/src/orchestration-v2/RemoteDelegatedTask.test.ts create mode 100644 apps/server/src/peer/PeerForwarding.ts create mode 100644 apps/server/src/peer/PeerLinks.ts create mode 100644 apps/server/src/peer/PeerMcpClient.ts create mode 100644 apps/server/src/peer/RemoteDelegation.ts diff --git a/apps/coder-helper/src/helper.ts b/apps/coder-helper/src/helper.ts index b0717c71addae..177f88c600337 100644 --- a/apps/coder-helper/src/helper.ts +++ b/apps/coder-helper/src/helper.ts @@ -12,6 +12,7 @@ import { CODER_HELPER_INFO_METHOD, CODER_HELPER_PROTOCOL_VERSION, CoderHelperProtocolError, + CoderHelperInfoRpcGroup, CoderHelperRpcGroup, } from "@t3tools/coder-cli/rpc"; import * as ServerConfig from "t3/src/config.ts"; @@ -20,7 +21,7 @@ import { withTerminalOutputWindow } from "t3/src/terminal/OutputProtocol.ts"; import { makeCoderRuntimeLayer } from "t3/src/coderServer.ts"; import { WS_RPC_SERVER_OPTIONS } from "t3/src/ws.ts"; -export const coderHelperHandlers = CoderHelperRpcGroup.toLayer({ +export const coderHelperHandlers = CoderHelperInfoRpcGroup.toLayer({ [CODER_HELPER_INFO_METHOD]: ({ protocolVersion }) => protocolVersion === CODER_HELPER_PROTOCOL_VERSION ? Effect.succeed({ diff --git a/apps/server/package.json b/apps/server/package.json index 6b48f5530b36f..8f1c2717e1af7 100644 --- a/apps/server/package.json +++ b/apps/server/package.json @@ -10,6 +10,7 @@ "dependencies": { "@effect/platform-node": "catalog:", "@ff-labs/fff-node": "0.11.0", + "@t3tools/coder-cli": "workspace:*", "@t3tools/provider-acp": "workspace:*", "@t3tools/provider-acp-registry": "workspace:*", "@t3tools/provider-core": "workspace:*", diff --git a/apps/server/src/coderEnvironment.ts b/apps/server/src/coderEnvironment.ts index 51d84522407a8..6cdbd68af2ff9 100644 --- a/apps/server/src/coderEnvironment.ts +++ b/apps/server/src/coderEnvironment.ts @@ -72,6 +72,9 @@ export const CODER_ENVIRONMENT_CAPABILITIES = { threadStop: true, environmentIcon: true, projectCloneTracking: true, + // Links are the gateway's workspace link rules; calls between workspaces go through its hub. + peerLinks: true, + linkFence: true, } satisfies ExecutionEnvironmentCapabilities; export const CODER_OMITTED_CAPABILITIES = { @@ -90,13 +93,20 @@ export const CODER_OMITTED_CAPABILITIES = { databaseStorage: "No `t3 doctor` in the workspace helper; it compacts and reclaims space itself.", ignoredFileListing: "No Add to another machine: ignored files such as .env would pass through the laptop browser.", - peerLinks: "No linked environments: they need server-to-server /mcp and pairing.", - mcpModeLimitHeader: "No /mcp HTTP server; agents reach T3 tools over the workspace file bridge.", - linkFence: "No linked environments, so no work starts here from another one.", + mcpModeLimitHeader: + "No /mcp HTTP server; the gateway hub carries a linked call's mode limits with the call.", localServerStop: "No dev-server port discovery: the browser preview is not carried.", triage: "No in-app triage: it clones upstream T3 Code to help file upstream issues.", } satisfies Partial>; +/** Upstream's environment identity, from this workspace's descriptor. */ +export const layerIdentity = Layer.effect( + ServerEnvironmentIdentity, + Effect.map(CoderEnvironment, ({ descriptor }) => + ServerEnvironmentIdentity.of({ getEnvironmentId: Effect.succeed(descriptor.environmentId) }), + ), +); + const platformArch = (): ExecutionEnvironmentDescriptor["platform"]["arch"] => { if (process.arch === "arm64" || process.arch === "x64") return process.arch; return "other"; diff --git a/apps/server/src/coderHub.test.ts b/apps/server/src/coderHub.test.ts new file mode 100644 index 0000000000000..ac6b19bb49c27 --- /dev/null +++ b/apps/server/src/coderHub.test.ts @@ -0,0 +1,233 @@ +import { assert, it } from "@effect/vitest"; +import { + CODER_HUB_INVOKE_METHOD, + type CoderHubCallOutcome, + type CoderHubRequest, +} from "@t3tools/coder-cli/rpc"; +import { EnvironmentId, OrchestratorMcpFailure } from "@t3tools/contracts"; +import * as Effect from "effect/Effect"; +import * as Fiber from "effect/Fiber"; +import * as Layer from "effect/Layer"; +import * as Queue from "effect/Queue"; +import * as Stream from "effect/Stream"; +import * as TestClock from "effect/testing/TestClock"; + +import * as CoderHub from "./coderHub.ts"; +import { ServerEnvironmentIdentity } from "./coderEnvironment.ts"; +import { FileBridgeToolFailure } from "./mcp/bridge/FileBridge.ts"; +import * as T3ToolDispatch from "./mcp/bridge/T3ToolDispatch.ts"; +import type * as McpInvocationContext from "./mcp/McpInvocationContext.ts"; +import * as ServerSettings from "./serverSettings.ts"; + +const target = EnvironmentId.make("environment:box"); +const limits = { runtimeMode: "auto-accept-edits", interactionMode: "default" } as const; + +/** Subscribes as the gateway does, keeping the subscription open, and hands out its requests. */ +const subscribe = (hub: CoderHub.CoderHub["Service"]) => + Effect.gen(function* () { + const received = yield* Queue.unbounded(); + yield* hub.outbox.pipe( + Stream.runForEach((request) => Queue.offer(received, request)), + Effect.forkChild, + ); + yield* Effect.yieldNow.pipe(Effect.repeat({ times: 20 })); + return received; + }); + +it.effect("fails a call at once when no gateway is subscribed", () => + Effect.gen(function* () { + const hub = yield* CoderHub.CoderHub; + const failure = yield* hub + .call({ environmentId: target, tool: "t3_thread_read", arguments: {}, limits }) + .pipe(Effect.flip); + assert.strictEqual(failure, CoderHub.noGateway); + }).pipe(Effect.provide(CoderHub.layer)), +); + +it.effect("sends a call through the outbox and returns the gateway's answer", () => + Effect.gen(function* () { + const hub = yield* CoderHub.CoderHub; + const gateway = yield* subscribe(hub); + const call = yield* hub + .call({ environmentId: target, tool: "t3_thread_read", arguments: { a: 1 }, limits }) + .pipe(Effect.forkChild); + const sent = yield* Queue.take(gateway); + const links = yield* hub.listLinks.pipe(Effect.forkChild); + const listed = yield* Queue.take(gateway); + assert.deepStrictEqual(sent, { + _tag: "Call", + id: sent.id, + environmentId: target, + tool: "t3_thread_read", + arguments: { a: 1 }, + limits, + }); + assert.strictEqual(listed._tag, "ListLinks"); + const outcome: CoderHubCallOutcome = { _tag: "Success", value: { ok: true } }; + yield* hub.reply({ _tag: "Call", id: sent.id, outcome }); + yield* hub.reply({ + _tag: "ListLinks", + id: listed.id, + links: [{ environmentId: target, label: "box", access: "read-only", connected: true }], + }); + assert.deepStrictEqual(yield* Fiber.join(call), outcome); + assert.deepStrictEqual(yield* Fiber.join(links), [ + { environmentId: target, label: "box", access: "read-only", connected: true }, + ]); + }).pipe(Effect.provide(CoderHub.layer)), +); + +it.effect("fails what the previous subscriber left unanswered when the gateway resubscribes", () => + Effect.gen(function* () { + const hub = yield* CoderHub.CoderHub; + const first = yield* subscribe(hub); + const call = yield* hub + .call({ environmentId: target, tool: "t3_thread_read", arguments: {}, limits }) + .pipe(Effect.flip, Effect.forkChild); + assert.strictEqual((yield* Queue.take(first))._tag, "Call"); + yield* subscribe(hub); + assert.strictEqual(yield* Fiber.join(call), CoderHub.noGateway); + }).pipe(Effect.provide(CoderHub.layer)), +); + +it.effect("gives up on an unanswered call after the timeout", () => + Effect.gen(function* () { + const hub = yield* CoderHub.CoderHub; + const gateway = yield* subscribe(hub); + const call = yield* hub + .call({ environmentId: target, tool: "t3_thread_read", arguments: {}, limits }) + .pipe(Effect.flip, Effect.forkChild); + yield* Queue.take(gateway); + yield* TestClock.adjust(CoderHub.CODER_HUB_CALL_TIMEOUT); + const failure = yield* Fiber.join(call); + assert.strictEqual(failure.code, "orchestration_error"); + assert.notStrictEqual(failure, CoderHub.noGateway); + }).pipe(Effect.provide(CoderHub.layer)), +); + +const here = EnvironmentId.make("environment:here"); + +/** The hub handlers over a fake tool binding that records each call's scope. */ +const invokeWith = (options: { + readonly linkedEnvironmentsEnabled: boolean; + readonly bound: boolean; + readonly answer?: Effect.Effect; +}) => + Effect.gen(function* () { + const scopes: Array = []; + const tools = yield* T3ToolDispatch.T3ToolDispatch; + if (options.bound) { + yield* tools.bind({ + catalog: [], + dispatch: () => Effect.die("unused dispatch"), + invoke: (scope, request) => { + scopes.push(scope); + return options.answer ?? Effect.succeed({ tool: request.tool, params: request.params }); + }, + }); + } + const handlers = yield* CoderHub.makeHandlers; + const outcome = yield* ( + handlers[CODER_HUB_INVOKE_METHOD] as (payload: unknown) => Effect.Effect + )({ + link: { id: "laptop-to-box", label: "laptop", access: "approval-required" }, + tool: "t3_thread_read", + arguments: { threadId: "thread-1" }, + limits, + }); + return { outcome, scopes }; + }).pipe( + Effect.provide( + Layer.mergeAll( + CoderHub.layer, + T3ToolDispatch.layer, + ServerSettings.layerTest({ linkedEnvironmentsEnabled: options.linkedEnvironmentsEnabled }), + Layer.succeed( + ServerEnvironmentIdentity, + ServerEnvironmentIdentity.of({ getEnvironmentId: Effect.succeed(here) }), + ), + ), + ), + ); + +it.effect("runs an invoked tool as the link's caller, capped by the calling agent's modes", () => + Effect.gen(function* () { + const { outcome, scopes } = yield* invokeWith({ linkedEnvironmentsEnabled: true, bound: true }); + assert.deepStrictEqual(outcome, { + _tag: "Success", + value: { tool: "t3_thread_read", params: { threadId: "thread-1" } }, + }); + const [scope] = scopes; + assert.strictEqual(scope?.environmentId, here); + assert.strictEqual(scope?.thread, undefined); + // As upstream's `/mcp` scopes a linked environment's OAuth session. + assert.deepStrictEqual(scope?.client, { + sessionId: "coder-link:laptop-to-box", + label: "laptop", + access: "approval-required", + linked: true, + narrowedTo: limits, + }); + assert.deepStrictEqual( + [...(scope?.capabilities ?? [])], + ["orchestration", "worktree", "pull-requests"], + ); + }), +); + +it.effect("refuses an invoked tool while Linked environments is off here", () => + Effect.gen(function* () { + const { outcome, scopes } = yield* invokeWith({ + linkedEnvironmentsEnabled: false, + bound: true, + }); + assert.strictEqual(outcome._tag, "Failure"); + if (outcome._tag === "Failure") assert.strictEqual(outcome.failure.code, "capability_denied"); + assert.strictEqual(scopes.length, 0); + }), +); + +it.effect("asks the caller to retry while the tools are still starting", () => + Effect.gen(function* () { + const { outcome } = yield* invokeWith({ linkedEnvironmentsEnabled: true, bound: false }); + assert.strictEqual(outcome._tag, "Failure"); + if (outcome._tag === "Failure") { + assert.strictEqual(outcome.failure.code, "orchestration_error"); + } + }), +); + +it.effect("passes the tool's own failure back, and names any other one", () => + Effect.gen(function* () { + const declared = new OrchestratorMcpFailure({ + code: "thread_not_found", + message: "No such thread.", + }); + const passed = yield* invokeWith({ + linkedEnvironmentsEnabled: true, + bound: true, + answer: Effect.fail( + new FileBridgeToolFailure({ + value: { _tag: "OrchestratorMcpFailure", code: declared.code, message: declared.message }, + }), + ), + }); + assert.strictEqual(passed.outcome._tag, "Failure"); + if (passed.outcome._tag === "Failure") { + assert.strictEqual(passed.outcome.failure.code, "thread_not_found"); + assert.strictEqual(passed.outcome.failure.message, "No such thread."); + } + const other = yield* invokeWith({ + linkedEnvironmentsEnabled: true, + bound: true, + answer: Effect.fail( + new FileBridgeToolFailure({ value: { error: "UnknownTool", message: "Unknown T3 tool." } }), + ), + }); + assert.strictEqual(other.outcome._tag, "Failure"); + if (other.outcome._tag === "Failure") { + assert.strictEqual(other.outcome.failure.code, "orchestration_error"); + assert.strictEqual(other.outcome.failure.message, "Unknown T3 tool."); + } + }), +); diff --git a/apps/server/src/coderHub.ts b/apps/server/src/coderHub.ts new file mode 100644 index 0000000000000..2c3ea467205d0 --- /dev/null +++ b/apps/server/src/coderHub.ts @@ -0,0 +1,289 @@ +/** + * Coder: the workspace helper's side of the gateway hub (helper protocol v3). + * + * Upstream links two T3 Code servers over HTTP `/mcp`. Here the laptop gateway holds every + * workspace's helper connection, so a call bound for another workspace goes out through this + * outbox: the gateway subscribes to it (`coder.hub.outbox`), runs the call on the other + * workspace's helper (`coder.hub.invoke`), and answers here (`coder.hub.reply`). Nothing + * listens and nothing leaves the workspace except this helper's stdio. + * + * @module coderHub + */ +import { + CODER_HUB_INVOKE_METHOD, + CODER_HUB_OUTBOX_METHOD, + CODER_HUB_REPLY_METHOD, + type CoderHubCallLimits, + type CoderHubCallOutcome, + type CoderHubLink, + type CoderHubReply, + type CoderHubRequest, + CoderHubRpcGroup, +} from "@t3tools/coder-cli/rpc"; +import { type EnvironmentId, OrchestratorMcpFailure } from "@t3tools/contracts"; +import * as Cause from "effect/Cause"; +import * as Context from "effect/Context"; +import * as Deferred from "effect/Deferred"; +import * as Duration from "effect/Duration"; +import * as Effect from "effect/Effect"; +import * as Layer from "effect/Layer"; +import * as Queue from "effect/Queue"; +import * as Ref from "effect/Ref"; +import * as Schema from "effect/Schema"; +import * as Stream from "effect/Stream"; + +import { ServerEnvironmentIdentity } from "./coderEnvironment.ts"; +import { T3ToolDispatch } from "./mcp/bridge/T3ToolDispatch.ts"; +import type * as McpInvocationContext from "./mcp/McpInvocationContext.ts"; +import * as ServerSettings from "./serverSettings.ts"; + +/** How long one call waits for the gateway's answer; forwarded waits go in 50 s pieces. */ +export const CODER_HUB_CALL_TIMEOUT = Duration.minutes(2); + +/** The gateway's answer before it is matched to a request kind. */ +type Pending = Deferred.Deferred; + +const hubFailure = (message: string) => + new OrchestratorMcpFailure({ code: "orchestration_error", message }); + +export const noGateway = hubFailure( + "This workspace cannot reach other workspaces: T3 Coder's gateway is not routing between them.", +); +const shuttingDown = hubFailure("This workspace is shutting down."); +const timedOut = hubFailure("The other workspace did not answer in time."); + +export class CoderHub extends Context.Service< + CoderHub, + { + /** + * The gateway's subscription. A new one replaces the previous, whose stream ends and whose + * unanswered requests fail. + */ + readonly outbox: Stream.Stream; + /** The gateway's answer to an outbox request; an unknown id is ignored. */ + readonly reply: (reply: CoderHubReply) => Effect.Effect; + /** Runs `tool` in another workspace and returns its outcome there. */ + readonly call: (input: { + readonly environmentId: EnvironmentId; + readonly tool: string; + readonly arguments: Record; + readonly limits: CoderHubCallLimits; + }) => Effect.Effect; + /** The gateway's link rules from this workspace. */ + readonly listLinks: Effect.Effect, OrchestratorMcpFailure>; + } +>()("t3/coderHub") {} + +interface Subscriber { + readonly generation: number; + readonly queue: Queue.Queue; + readonly pending: Set; +} + +export const make = Effect.gen(function* () { + const subscriber = yield* Ref.make(undefined); + const pending = new Map(); + let nextGeneration = 0; + let nextId = 0; + let closed = false; + + const failPending = (ids: Iterable, failure: OrchestratorMcpFailure) => + Effect.forEach( + Array.from(ids), + (id) => { + const deferred = pending.get(id); + pending.delete(id); + return deferred === undefined ? Effect.void : Deferred.fail(deferred, failure); + }, + { discard: true }, + ); + + yield* Effect.addFinalizer(() => + Effect.gen(function* () { + closed = true; + const current = yield* Ref.getAndSet(subscriber, undefined); + if (current !== undefined) yield* Queue.end(current.queue); + yield* failPending(pending.keys(), shuttingDown); + }), + ); + + const outbox: CoderHub["Service"]["outbox"] = Stream.unwrap( + Effect.gen(function* () { + const queue = yield* Queue.unbounded(); + const own: Subscriber = { generation: nextGeneration++, queue, pending: new Set() }; + const previous = yield* Ref.getAndSet(subscriber, own); + if (previous !== undefined) { + yield* Queue.end(previous.queue); + yield* failPending(previous.pending, noGateway); + } + yield* Effect.addFinalizer(() => + Ref.modify(subscriber, (current) => + current?.generation === own.generation + ? ([true, undefined] as const) + : ([false, current] as const), + ).pipe( + Effect.flatMap((wasCurrent) => + wasCurrent + ? Queue.end(queue).pipe(Effect.andThen(failPending(own.pending, noGateway))) + : Effect.void, + ), + ), + ); + return Stream.fromQueue(queue); + }), + ); + + /** Sends a request to the gateway and waits for its answer. */ + const request = ( + build: (id: string) => CoderHubRequest, + read: (reply: CoderHubReply) => A | undefined, + ): Effect.Effect => + Effect.gen(function* () { + if (closed) return yield* shuttingDown; + const current = yield* Ref.get(subscriber); + if (current === undefined) return yield* noGateway; + const id = `hub:${String(nextId++)}`; + const deferred = yield* Deferred.make(); + pending.set(id, deferred); + current.pending.add(id); + const answer = yield* Queue.offer(current.queue, build(id)).pipe( + Effect.andThen(Deferred.await(deferred)), + Effect.timeoutOrElse({ + duration: CODER_HUB_CALL_TIMEOUT, + orElse: () => Effect.fail(timedOut), + }), + Effect.ensuring( + Effect.sync(() => { + pending.delete(id); + current.pending.delete(id); + }), + ), + ); + const value = read(answer); + if (value === undefined) { + return yield* hubFailure("T3 Coder's gateway answered with the wrong kind of reply."); + } + return value; + }); + + return CoderHub.of({ + outbox, + reply: (reply) => + Effect.suspend(() => { + const deferred = pending.get(reply.id); + return deferred === undefined ? Effect.void : Deferred.succeed(deferred, reply); + }).pipe(Effect.asVoid), + call: (input) => + request( + (id) => ({ _tag: "Call", id, ...input }), + (reply) => (reply._tag === "Call" ? reply.outcome : undefined), + ), + listLinks: request( + (id) => ({ _tag: "ListLinks", id }), + (reply) => (reply._tag === "ListLinks" ? reply.links : undefined), + ), + }); +}); + +export const layer = Layer.effect(CoderHub, make); + +const isOrchestratorMcpFailure = Schema.is(OrchestratorMcpFailure); +const decodeFailure = Schema.decodeUnknownOption(OrchestratorMcpFailure); + +/** The agent-facing failure of a call that failed here, in the shape the caller decodes. */ +const toCallFailure = (value: unknown): OrchestratorMcpFailure => { + if (isOrchestratorMcpFailure(value)) return value; + const decoded = decodeFailure(value); + if (decoded._tag === "Some") return decoded.value; + const message = + typeof value === "object" && value !== null && "message" in value + ? String(value.message) + : "The T3 tool failed in the linked workspace."; + return hubFailure(message); +}; + +/** + * The hub methods the gateway calls. `invoke` runs a tool here as the link's caller, as upstream's + * `/mcp` runs a linked environment's OAuth session: what it starts here carries the link as its + * origin, its modes are capped by the calling agent's, and the Labs beta must be on here. + */ +export const makeHandlers = Effect.gen(function* () { + const hub = yield* CoderHub; + const tools = yield* T3ToolDispatch; + const settings = yield* ServerSettings.ServerSettingsService; + const environmentId = yield* ServerEnvironmentIdentity.pipe( + Effect.flatMap((identity) => identity.getEnvironmentId), + ); + + const invoke = Effect.fn("CoderHub.invoke")(function* (input: { + readonly link: { + readonly id: string; + readonly label: string; + readonly access: McpInvocationContext.McpClientCaller["access"]; + }; + readonly tool: string; + readonly arguments: Readonly>; + readonly limits: CoderHubCallLimits; + }) { + const enabled = yield* settings.getSettings.pipe( + Effect.map((value) => value.linkedEnvironmentsEnabled), + Effect.orElseSucceed(() => false), + ); + if (!enabled) { + return { + _tag: "Failure", + failure: new OrchestratorMcpFailure({ + code: "capability_denied", + message: + "Linked environments is off in that workspace. Turn it on in its Settings → Labs.", + }), + } satisfies CoderHubCallOutcome; + } + const binding = yield* tools.binding; + if (binding === undefined) { + return { + _tag: "Failure", + failure: hubFailure("That workspace is starting. Retry shortly."), + } satisfies CoderHubCallOutcome; + } + const sessionId = `coder-link:${input.link.id}`; + const scope: McpInvocationContext.McpInvocationScope = { + environmentId, + requestNamespace: `client:${sessionId}`, + thread: undefined, + client: { + sessionId, + label: input.link.label, + access: input.link.access, + linked: true, + narrowedTo: input.limits, + }, + capabilities: new Set([ + "orchestration", + "worktree", + "pull-requests", + ]), + issuedAt: yield* Effect.clockWith((clock) => clock.currentTimeMillis), + linkedEnvironments: true, + }; + return yield* binding + .invoke(scope, { id: sessionId, tool: input.tool, params: { ...input.arguments } }) + .pipe( + Effect.map((value): CoderHubCallOutcome => ({ _tag: "Success", value })), + Effect.catch((error) => + Effect.succeed({ + _tag: "Failure", + failure: toCallFailure(error.value), + }), + ), + ); + }); + + return CoderHubRpcGroup.of({ + [CODER_HUB_OUTBOX_METHOD]: () => hub.outbox, + [CODER_HUB_REPLY_METHOD]: (reply) => hub.reply(reply), + [CODER_HUB_INVOKE_METHOD]: invoke, + }); +}); + +export const handlersLayer = CoderHubRpcGroup.toLayer(makeHandlers); diff --git a/apps/server/src/coderServer.ts b/apps/server/src/coderServer.ts index 0692fb5b01731..8f371f6e76574 100644 --- a/apps/server/src/coderServer.ts +++ b/apps/server/src/coderServer.ts @@ -53,6 +53,11 @@ import * as EffectWorker from "./orchestration-v2/EffectWorker.ts"; import * as LegacyV1ThreadImporter from "./orchestration-v2/legacy/LegacyV1ThreadImporter.ts"; import * as ProjectStore from "./orchestration-v2/ProjectStore.ts"; import * as ProjectionStoreV2 from "./orchestration-v2/ProjectionStore.ts"; +import * as CoderHub from "./coderHub.ts"; +import * as PeerForwarding from "./peer/PeerForwarding.ts"; +import * as PeerLinks from "./peer/PeerLinks.ts"; +import * as PeerMcpClient from "./peer/PeerMcpClient.ts"; +import * as RemoteDelegation from "./peer/RemoteDelegation.ts"; import * as AgentSessionScanner from "./project/AgentSessionScanner.ts"; import * as ProviderRuntimeRecovery from "./orchestration-v2/ProviderRuntimeRecoveryService.ts"; import * as ProviderSessionManager from "./orchestration-v2/ProviderSessionManager.ts"; @@ -165,6 +170,16 @@ const PullRequestReviewGuideLive = PullRequestReviewGuideService.layer.pipe( Layer.provide(layerPullRequestService), ); +// Coder: upstream's linked-environment forwarding and delegated tasks, over the gateway hub +// instead of HTTP `/mcp` (`coderHub.ts`, `peer/PeerMcpClient.ts`, `peer/PeerLinks.ts`). +const CoderLinkedWorkspacesLive = RemoteDelegation.layer.pipe( + Layer.provide(ProjectionStoreV2.layer), + Layer.provideMerge(PeerForwarding.layer), + Layer.provideMerge(PeerMcpClient.layer), + Layer.provideMerge(PeerLinks.layer), + Layer.provideMerge(CoderHub.layer), +); + const CoderRuntimeCoreLive = Layer.mergeAll( layerThreadSettlementWorker, layerIdleCompactionWorker, @@ -174,6 +189,7 @@ const CoderRuntimeCoreLive = Layer.mergeAll( DelegatedTaskQuestionWorkerLive, layerPullRequestService, PullRequestReviewGuideLive, + CoderLinkedWorkspacesLive, // As upstream: catches project provider overrides left behind by a project deleted before // ProjectService.delete cleared them, or by a cleanup write that failed. Layer.effectDiscard(ProjectSettingsOverrideSweep.sweep), @@ -206,6 +222,8 @@ const CoderRuntimeDependenciesLive = CoderRuntimeCoreLive.pipe( // As upstream's `layerBackground`: periodic merge request discovery asks the (always-allow) // background policy before each sweep. Layer.provideMerge(BackgroundPolicy.layer), + // Linked-workspace forwarding and the hub name this workspace by upstream's identity service. + Layer.provideMerge(CoderEnvironment.layerIdentity), Layer.provideMerge(CoderEnvironment.layer), Layer.provideMerge(ServerLifecycleEvents.layer), // Coder: credentials are workspace file bridges that carry upstream's T3 toolkits. @@ -242,6 +260,7 @@ const CoderRuntimeStartupLive = Layer.effect( const projectStore = yield* ProjectStore.ProjectStoreV2; const orchestrator = yield* Orchestrator.OrchestratorV2; const t3Tools = yield* T3ToolDispatch.T3ToolDispatch; + const remoteDelegation = yield* RemoteDelegation.RemoteDelegation; const runtimeScope = yield* Scope.make("sequential"); const effectWorkerContext = yield* Effect.context>(); @@ -278,6 +297,9 @@ const CoderRuntimeStartupLive = Layer.effect( yield* providerRuntimeRecovery.recover; // Settles delegated tasks whose runs recovery just terminalized, as upstream's startup does. yield* orchestrator.recoverDelegatedTasks; + // Follows delegated tasks running in linked workspaces, including after a restart, as + // upstream's routes layer does. + yield* remoteDelegation.start().pipe(Scope.provide(runtimeScope)); const effectWorker: Fiber.Fiber = yield* EffectWorker.runDaemon.pipe( Effect.provide(effectWorkerContext), Effect.forkIn(runtimeScope), @@ -343,5 +365,6 @@ export const makeCoderRuntimeLayer = () => { // takes it here. const rpcServices = AgentSessionScanner.layer.pipe(Layer.provideMerge(services)); - return CoderWs.layer.pipe(Layer.provide(rpcServices)); + // Coder: the gateway hub methods (helper protocol v3) share the runtime's CoderHub. + return Layer.mergeAll(CoderWs.layer, CoderHub.handlersLayer).pipe(Layer.provide(rpcServices)); }; diff --git a/apps/server/src/mcp/McpInvocationContext.ts b/apps/server/src/mcp/McpInvocationContext.ts index bb47e0cce0871..c64c5a6b8824f 100644 --- a/apps/server/src/mcp/McpInvocationContext.ts +++ b/apps/server/src/mcp/McpInvocationContext.ts @@ -34,6 +34,19 @@ export interface McpClientCaller { readonly sessionId: string; readonly label: string; readonly access: AuthMcpClientAccess; + /** + * Another T3 Code environment's peer link. What it starts here carries its + * session as `linkOrigin`, and it changes only that work (`linkOrigin.ts`). + */ + readonly linked?: boolean | undefined; + /** + * Narrower modes the client asked for on this request (`T3-Mode-Limit`): + * another environment passing on the limits of the agent it calls for. + * Coder: the gateway hub passes them with each linked call (`coder.hub.invoke`'s + * `limits`), so there is no `T3-Mode-Limit` header. They can only narrow (see + * `clientModeCeiling`). + */ + readonly narrowedTo?: ClientModes | undefined; } export interface ClientModes { @@ -41,18 +54,39 @@ export interface ClientModes { readonly interactionMode: ProviderInteractionMode; } +const runtimeModeRank: Record = { + "approval-required": 0, + "auto-accept-edits": 1, + auto: 2, + "full-access": 3, +}; +const interactionModeRank: Record = { plan: 0, default: 1 }; + /** * The modes a client caller's writes are capped at: what it was approved - * with. A read-only client never reaches a write (`McpToolAccess` refuses it - * first), so it maps to the lowest runtime mode rather than to nothing. - * Coder: no client narrows them per request; `T3-Mode-Limit` serves linked - * environments, which are not carried. + * with, narrowed by what it asked for on this request. A read-only client + * never reaches a write (`McpToolAccess` refuses it first), so it maps to the + * lowest runtime mode rather than to nothing. */ -export const clientModeCeiling = (client: McpClientCaller | undefined): ClientModes => ({ - runtimeMode: - client === undefined || client.access === "read-only" ? "approval-required" : client.access, - interactionMode: "default", -}); +export const clientModeCeiling = (client: McpClientCaller | undefined): ClientModes => { + const approved: ClientModes = { + runtimeMode: + client === undefined || client.access === "read-only" ? "approval-required" : client.access, + interactionMode: "default", + }; + const asked = client?.narrowedTo; + if (asked === undefined) return approved; + return { + runtimeMode: + runtimeModeRank[asked.runtimeMode] < runtimeModeRank[approved.runtimeMode] + ? asked.runtimeMode + : approved.runtimeMode, + interactionMode: + interactionModeRank[asked.interactionMode] < interactionModeRank[approved.interactionMode] + ? asked.interactionMode + : approved.interactionMode, + }; +}; /** Thread callers default to their own thread; client callers need thread for tools that act as the caller. */ export interface McpInvocationScope { @@ -62,6 +96,8 @@ export interface McpInvocationScope { readonly requestNamespace: string; readonly thread: McpThreadCaller | undefined; readonly client: McpClientCaller | undefined; + /** False while the Linked environments beta is off here; `/mcp` reads it per request. */ + readonly linkedEnvironments?: boolean; } export class McpInvocationContext extends Context.Service< @@ -79,6 +115,13 @@ export const hiddenFromSubagents = (): boolean => { return scope?.thread?.subagent !== true; }; +/** `McpSchema.EnabledWhen` for tools that only serve links, hidden while the beta is off. */ +export const hiddenWhileLinksOff = (): boolean => { + const fiber = Fiber.getCurrent(); + const scope = fiber && Context.getOrUndefined(fiber.context, McpInvocationContext); + return scope?.linkedEnvironments !== false; +}; + export type McpCapabilityError = C extends "preview" ? PreviewAutomationUnavailableError : McpCapabilityUnavailableError; diff --git a/apps/server/src/mcp/McpSessionRegistry.test.ts b/apps/server/src/mcp/McpSessionRegistry.test.ts index e3fa9adeb53a6..8920e592c57d7 100644 --- a/apps/server/src/mcp/McpSessionRegistry.test.ts +++ b/apps/server/src/mcp/McpSessionRegistry.test.ts @@ -34,7 +34,11 @@ const services = Layer.mergeAll( T3ToolDispatch.T3ToolDispatch, T3ToolDispatch.T3ToolDispatch.pipe( Effect.tap((tools) => - tools.bind({ catalog: [], dispatch: (scope) => Effect.succeed(scope.thread.threadId) }), + tools.bind({ + catalog: [], + dispatch: (scope) => Effect.succeed(scope.thread.threadId), + invoke: () => Effect.succeed(null), + }), ), ), ).pipe(Layer.provide(T3ToolDispatch.layer)), diff --git a/apps/server/src/mcp/McpToolAccess.ts b/apps/server/src/mcp/McpToolAccess.ts index 5a89a14981353..b82d9bb5ae59c 100644 --- a/apps/server/src/mcp/McpToolAccess.ts +++ b/apps/server/src/mcp/McpToolAccess.ts @@ -1,5 +1,6 @@ import { type EnvironmentId, + type OrchestrationV2LinkOrigin, OrchestratorMcpEnvironmentTarget, OrchestratorMcpFailure, type ProviderInteractionMode, @@ -7,6 +8,7 @@ import { type ThreadId, } from "@t3tools/contracts"; import * as Effect from "effect/Effect"; +import * as Option from "effect/Option"; import * as Predicate from "effect/Predicate"; import * as Ref from "effect/Ref"; import * as Struct from "effect/Struct"; @@ -18,6 +20,8 @@ import { DispatchModeLimit, type DispatchModeRefusal, } from "../orchestration-v2/DispatchModeLimit.ts"; +import * as PeerForwarding from "../peer/PeerForwarding.ts"; +import { assertNotLinked, assertSameLink, callerLinkOrigin } from "./linkOrigin.ts"; import * as McpInvocationContext from "./McpInvocationContext.ts"; import { resolveInteractionMode, resolveRuntimeMode } from "./delegatedTaskModes.ts"; import { @@ -41,8 +45,19 @@ const refuseOutsideConstruction = (token: symbol) => { let declare: ( handle: (params: P) => Effect.Effect, + remote: RemoteCheck

| undefined, ) => Declaration<(params: P) => Effect.Effect>; +/** + * What a call bound for a linked environment checks here before it goes: the + * caller, not the thread or project it names, which live there and are + * checked there. `undefined` for tools that act as the calling thread itself. + */ +type RemoteCheck

= ( + params: P, +) => Effect.Effect>; +let remoteCheckOf: (declaration: Declaration) => RemoteCheck | undefined; + type CheckedHandlerOf = D extends Declaration ? Handler : never; interface CheckedHandler extends Struct.Lambda { @@ -58,13 +73,20 @@ let handlersLayer: , EX, RX>( /** t3code/no-raw-mcp-registration confines Effect's unchecked registration API to McpHttpServer. */ export class Declaration { readonly #handle: Handler; - private constructor(token: typeof builtHere, handle: Handler) { + readonly #remote: RemoteCheck | undefined; + private constructor( + token: typeof builtHere, + handle: Handler, + remote: RemoteCheck | undefined, + ) { refuseOutsideConstruction(token); this.#handle = handle; + this.#remote = remote; } static { - declare = (handle) => new Declaration(builtHere, handle); + declare = (handle, remote) => new Declaration(builtHere, handle, remote); checkedHandler = Struct.lambda((declaration) => declaration.#handle); + remoteCheckOf = (declaration) => declaration.#remote; } } @@ -97,55 +119,92 @@ const requireThreadCaller = McpInvocationContext.McpInvocationContext.pipe( ); export const reads = (handle: (params: P) => Effect.Effect) => - declare((params: P) => handle(params)); + declare( + (params: P) => handle(params), + () => Effect.void, + ); export const readsAsCaller = (handle: (params: P) => Effect.Effect) => - declare((params: P) => requireThreadCaller.pipe(Effect.flatMap(() => handle(params)))); + declare((params: P) => requireThreadCaller.pipe(Effect.flatMap(() => handle(params))), undefined); export const actsAsCaller = (handle: (params: P) => Effect.Effect) => - declare((params: P) => - requireThreadCaller.pipe( - Effect.andThen(writingCaller), - Effect.flatMap(() => handle(params)), - ), + declare( + (params: P) => + requireThreadCaller.pipe( + Effect.andThen(writingCaller), + Effect.flatMap(() => handle(params)), + ), + undefined, ); -export const writes = (handle: (params: P) => Effect.Effect) => - declare((params: P) => orchestratingCaller.pipe(Effect.flatMap(() => handle(params)))); +/** + * Changes something that belongs to no thread, such as a pending upload or a + * scheduled task. Work a linked environment started may not: none of it + * carries the link's origin, so none of it is that link's. + */ +export const writes = ( + handle: (params: P) => Effect.Effect, + options?: { + /** Whether a linked caller may make it, as for uploads its own sends need. */ + readonly linkedCallers?: "allowed"; + }, +) => + declare( + (params: P) => + orchestratingCaller.pipe( + Effect.tap((caller) => + options?.linkedCallers === "allowed" + ? Effect.void + : assertNotLinked(caller, "change this environment's scheduled tasks"), + ), + Effect.flatMap(() => handle(params)), + ), + () => orchestratingCaller, + ); -/** Requires handler capability checks, not thread control. */ +/** Requires handler capability checks, not thread control; linked work is refused the same way. */ export const writesWithCapability = (handle: (params: P) => Effect.Effect) => - declare((params: P) => writingCaller.pipe(Effect.flatMap(() => handle(params)))); + declare( + (params: P) => + writingCaller.pipe( + Effect.tap((caller) => assertNotLinked(caller, "start work here that is not its link's")), + Effect.flatMap(() => handle(params)), + ), + () => writingCaller, + ); export const writesThreads = ( threads: (params: P) => ReadonlyArray, handle: (params: P) => Effect.Effect, ) => - declare((params: P) => - Effect.gen(function* () { - const caller = yield* writingCaller; - for (const threadId of threads(params)) { - if (threadId === undefined || threadId === caller.scope.thread?.threadId) continue; - const target = yield* caller.threads - .getThreadShell(threadId) - .pipe(Effect.mapError(unavailable)); - if (target !== null && target.deletedAt === null) { - yield* assertTargetWithinLimits(caller.limits, target); + declare( + (params: P) => + Effect.gen(function* () { + const caller = yield* writingCaller; + for (const threadId of threads(params)) { + if (threadId === undefined || threadId === caller.scope.thread?.threadId) continue; + const target = yield* caller.threads + .getThreadShell(threadId) + .pipe(Effect.mapError(unavailable)); + if (target !== null && target.deletedAt === null) { + yield* assertTargetWithinLimits(caller.limits, target); + yield* assertSameLink(caller, target); + } } - } - // Modes can rise after this check; the orchestrator rechecks under lock and records refusal before handlers wrap errors. - const refused = yield* Ref.make(undefined); - return yield* handle(params).pipe( - Effect.provideService(DispatchModeLimit, { ...caller.limits, refused }), - Effect.catch((error) => - Effect.flatMap(Ref.get(refused), (refusal) => - Effect.fail( - refusal === undefined ? error : escalationDenied(refusal), + // Modes can rise after this check; the orchestrator rechecks under lock and records refusal before handlers wrap errors. + const refused = yield* Ref.make(undefined); + return yield* handle(params).pipe( + Effect.provideService(DispatchModeLimit, { ...caller.limits, refused }), + Effect.catch((error) => + Effect.flatMap(Ref.get(refused), (refusal) => + Effect.fail( + refusal === undefined ? error : escalationDenied(refusal), + ), ), ), - ), - ); - }), + ); + }), + () => writingCaller, ); const escalationDenied = (refusal: DispatchModeRefusal) => @@ -160,39 +219,67 @@ const escalationDenied = (refusal: DispatchModeRefusal) => export interface StartedModes { readonly runtimeMode: RuntimeMode; readonly interactionMode: ProviderInteractionMode; + /** The linked environment the caller acts for. The thread must carry it. */ + readonly linkOrigin: OrchestrationV2LinkOrigin | undefined; } +/** + * Starts threads with the modes `modes` requests, which may not be broader + * than the caller's. `linked` says what a linked caller gets: threads stamped + * with its `linkOrigin`, or a refusal where the tool cannot carry one. + */ export const startsThreads = ( modes: (params: P) => { readonly runtimeMode?: RuntimeMode | undefined; readonly interactionMode?: ProviderInteractionMode | undefined; }, handle: (params: P, modes: StartedModes) => Effect.Effect, -) => - declare((params: P) => - Effect.gen(function* () { - const { limits } = yield* writingCaller; - const requested = modes(params); - const started: StartedModes = { - runtimeMode: yield* resolveRuntimeMode(limits.runtimeMode, requested.runtimeMode), - interactionMode: yield* resolveInteractionMode( - limits.interactionMode, - requested.interactionMode, - ), - }; - return yield* handle(params, started); - }), + linked: "stamped" | { readonly refused: string }, +) => { + const started = Effect.fn("McpToolAccess.started")(function* (caller: Caller, params: P) { + const requested = modes(params); + return { + runtimeMode: yield* resolveRuntimeMode(caller.limits.runtimeMode, requested.runtimeMode), + interactionMode: yield* resolveInteractionMode( + caller.limits.interactionMode, + requested.interactionMode, + ), + linkOrigin: callerLinkOrigin(caller), + } satisfies StartedModes; + }); + return declare( + (params: P) => + Effect.gen(function* () { + const caller = yield* writingCaller; + if (linked !== "stamped") yield* assertNotLinked(caller, linked.refused); + return yield* handle(params, yield* started(caller, params)); + }), + (params: P) => Effect.flatMap(writingCaller, (caller) => started(caller, params)), ); +}; /** One tool with two access rules, picked per call, such as create versus update. */ export const either = ( useFirst: (params: P) => boolean, first: Declaration<(params: P) => Effect.Effect>, second: Declaration<(params: P) => Effect.Effect>, -) => - declare((params: P): Effect.Effect => - useFirst(params) ? checkedHandler(first)(params) : checkedHandler(second)(params), +) => { + const remotes = [remoteCheckOf(first), remoteCheckOf(second)] as ReadonlyArray< + RemoteCheck

| undefined + >; + return declare( + (params: P): Effect.Effect => + useFirst(params) ? checkedHandler(first)(params) : checkedHandler(second)(params), + (params) => + remotes[useFirst(params) ? 0 : 1]?.(params) ?? + Effect.fail( + new OrchestratorMcpFailure({ + code: "invalid_request", + message: "This action acts as the calling thread, which is here. Omit environmentId.", + }), + ), ); +}; const fullAccessRequired = "Changing projects or environment settings needs a live full-access/default calling thread or a full-access client."; @@ -203,11 +290,30 @@ export const writesEnvironment = ( params: P, check: Effect.Effect, ) => Effect.Effect, + options?: { + /** + * Whether a linked caller may make it, as for adding a project: it leaves + * everything already here as it was. + */ + readonly linkedCallers?: "allowed"; + }, ) => { const check = orchestratingCaller.pipe( + Effect.tap((caller) => + options?.linkedCallers === "allowed" + ? Effect.void + : assertNotLinked(caller, "change projects or environment settings"), + ), Effect.tap((caller) => assertFullAccess(caller, fullAccessRequired)), ); - return declare((params: P) => check.pipe(Effect.flatMap(() => handle(params, check)))); + return declare( + (params: P) => check.pipe(Effect.flatMap(() => handle(params, check))), + // Linked work never reaches a link at all; that is checked as the call goes. + () => + orchestratingCaller.pipe( + Effect.tap((caller) => assertFullAccess(caller, fullAccessRequired)), + ), + ); }; type CheckServices = Effect.Services; @@ -264,41 +370,54 @@ const linksUnavailable = new OrchestratorMcpFailure({ }); /** - * Coder: peer links are not carried, so upstream's forwarding of these calls to - * a linked environment is replaced by its own refusal. A call naming this - * environment runs here; the handler never sees `environmentId`, as upstream's. + * Every tool that takes a linked environment runs there the same way: its + * declaration checks the caller here, and the same call goes to the other + * environment, which checks the rest. The handler here never sees + * `environmentId`, so it cannot leak into what it writes. */ -const refusingLinkedEnvironments = >( +const routed = Effect.fn("McpToolAccess.routed")(function* >( toolkit: Toolkit.Toolkit, + declarations: Handlers, checked: Toolkit.HandlersFrom, -): Toolkit.HandlersFrom => { +) { + // Optional so toolkits that never leave this environment build without it. + const forwarding = yield* Effect.serviceOption(PeerForwarding.PeerForwarding); const handlers: Record = { ...checked }; - for (const [name, tool] of Object.entries(toolkit.tools)) { - if (!takesLinkedEnvironment(tool)) continue; + for (const [name, declaration] of Object.entries>(declarations)) { + const tool = toolkit.tools[name]; + if (tool === undefined || !takesLinkedEnvironment(tool)) continue; + const remote = remoteCheckOf(declaration); + if (remote === undefined) + return yield* Effect.die( + `${name} takes a linked environment, but it acts as its calling thread, which is here.`, + ); const here = handlers[name] as ( params: object, ) => Effect.Effect>; handlers[name] = ({ environmentId, ...params }: { readonly environmentId?: EnvironmentId }) => Effect.gen(function* () { const scope = yield* McpInvocationContext.McpInvocationContext; - if (environmentId === undefined || environmentId === scope.environmentId) { - return yield* here(params); - } - return yield* linksUnavailable; + const target = PeerForwarding.remoteTarget(scope, environmentId); + if (target === undefined) return yield* here(params); + if (scope.linkedEnvironments === false) return yield* PeerForwarding.linkedEnvironmentsOff; + yield* (remote as RemoteCheck)(params); + if (Option.isNone(forwarding)) return yield* linksUnavailable; + return yield* forwarding.value.call(scope, tool, target, { ...params, environmentId }); }); } return handlers as Toolkit.HandlersFrom; -}; +}); export const toLayer = , EX = never, RX = never>( toolkit: Toolkit.Toolkit, build: Handlers | Effect.Effect, EX, RX>, ): HandlersLayer> => { + // Checked as soon as they are given, so a forged declaration fails here. const withDeclarations = (declarations: Handlers) => - refusingLinkedEnvironments(toolkit, checkedHandlers(declarations)); + routed(toolkit, declarations, checkedHandlers(declarations)); return handlersLayer( toolkit.toLayer( - Effect.isEffect(build) ? Effect.map(build, withDeclarations) : withDeclarations(build), + Effect.isEffect(build) ? Effect.flatMap(build, withDeclarations) : withDeclarations(build), ), ); }; diff --git a/apps/server/src/mcp/OrchestratorMcpService.activity.test.ts b/apps/server/src/mcp/OrchestratorMcpService.activity.test.ts index 353fb00fca97c..f3b664a4d0c2b 100644 --- a/apps/server/src/mcp/OrchestratorMcpService.activity.test.ts +++ b/apps/server/src/mcp/OrchestratorMcpService.activity.test.ts @@ -20,6 +20,7 @@ import * as ProviderAdapterRegistry from "../orchestration-v2/ProviderAdapterReg import * as ProviderRegistry from "../provider/ProviderRegistry.ts"; import * as ProjectService from "../project/ProjectService.ts"; import * as ScheduledTaskService from "../scheduledTasks/ScheduledTaskService.ts"; +import * as RemoteDelegation from "../peer/RemoteDelegation.ts"; import * as ServerSettings from "../serverSettings.ts"; import * as SecretRequests from "../secrets/SecretRequests.ts"; import * as ThreadLaunchService from "../orchestration-v2/ThreadLaunchService.ts"; @@ -162,6 +163,7 @@ it("readThread prefers activity-run status over a newer cancelled queued run", a } satisfies Partial), Layer.mock(ProjectService.ProjectService)({}), Layer.mock(SecretRequests.SecretRequests)({}), + Layer.mock(RemoteDelegation.RemoteDelegation)({}), Layer.mock(ScheduledTaskService.ScheduledTaskService)({ list: () => Effect.succeed({ tasks: [] }), } satisfies Partial), @@ -277,6 +279,7 @@ it("taskStatus returns task.providerInstanceId rather than the driver kind", asy } satisfies Partial), Layer.mock(ProjectService.ProjectService)({}), Layer.mock(SecretRequests.SecretRequests)({}), + Layer.mock(RemoteDelegation.RemoteDelegation)({}), Layer.mock(ScheduledTaskService.ScheduledTaskService)({ list: () => Effect.succeed({ tasks: [] }), } satisfies Partial), @@ -404,6 +407,7 @@ it("readThread and sendToThread reach threads in other projects", async () => { } satisfies Partial), Layer.mock(ProjectService.ProjectService)({}), Layer.mock(SecretRequests.SecretRequests)({}), + Layer.mock(RemoteDelegation.RemoteDelegation)({}), Layer.mock(ScheduledTaskService.ScheduledTaskService)({ list: () => Effect.succeed({ diff --git a/apps/server/src/mcp/OrchestratorMcpService.test.ts b/apps/server/src/mcp/OrchestratorMcpService.test.ts index 87eac6f88d511..156b52cfef1aa 100644 --- a/apps/server/src/mcp/OrchestratorMcpService.test.ts +++ b/apps/server/src/mcp/OrchestratorMcpService.test.ts @@ -55,6 +55,7 @@ import * as ProviderRegistry from "../provider/ProviderRegistry.ts"; import { buildUnavailableProviderSnapshot } from "../provider/unavailableProviderSnapshot.ts"; import * as ProjectService from "../project/ProjectService.ts"; import * as ScheduledTaskService from "../scheduledTasks/ScheduledTaskService.ts"; +import * as RemoteDelegation from "../peer/RemoteDelegation.ts"; import * as ServerSettings from "../serverSettings.ts"; import * as SecretRequests from "../secrets/SecretRequests.ts"; // Coder: no peer-link services to mock; `apps/server/src/peer` is not carried. @@ -167,6 +168,7 @@ describe("OrchestratorMcpService", () => { }), Layer.mock(ProjectService.ProjectService)({}), Layer.mock(SecretRequests.SecretRequests)({}), + Layer.mock(RemoteDelegation.RemoteDelegation)({}), Layer.mock(ScheduledTaskService.ScheduledTaskService)({}), ); const scope: McpInvocationScope = { @@ -267,6 +269,7 @@ describe("OrchestratorMcpService", () => { }), Layer.mock(ProjectService.ProjectService)({}), Layer.mock(SecretRequests.SecretRequests)({}), + Layer.mock(RemoteDelegation.RemoteDelegation)({}), Layer.mock(ScheduledTaskService.ScheduledTaskService)({}), ); const scope: McpInvocationScope = { @@ -367,6 +370,7 @@ describe("OrchestratorMcpService", () => { }), Layer.mock(ProjectService.ProjectService)({}), Layer.mock(SecretRequests.SecretRequests)({}), + Layer.mock(RemoteDelegation.RemoteDelegation)({}), Layer.mock(ScheduledTaskService.ScheduledTaskService)({}), ); const scope: McpInvocationScope = { @@ -459,6 +463,7 @@ describe("OrchestratorMcpService", () => { }), Layer.mock(ProjectService.ProjectService)({}), Layer.mock(SecretRequests.SecretRequests)({}), + Layer.mock(RemoteDelegation.RemoteDelegation)({}), Layer.mock(ScheduledTaskService.ScheduledTaskService)({}), ); const scope: McpInvocationScope = { @@ -555,6 +560,7 @@ describe("OrchestratorMcpService", () => { }), Layer.mock(ProjectService.ProjectService)({}), Layer.mock(SecretRequests.SecretRequests)({}), + Layer.mock(RemoteDelegation.RemoteDelegation)({}), Layer.mock(ScheduledTaskService.ScheduledTaskService)({}), ); const scope: McpInvocationScope = { @@ -646,6 +652,7 @@ describe("OrchestratorMcpService", () => { }), Layer.mock(ProjectService.ProjectService)({}), Layer.mock(SecretRequests.SecretRequests)({}), + Layer.mock(RemoteDelegation.RemoteDelegation)({}), Layer.mock(ScheduledTaskService.ScheduledTaskService)({}), ); const scope: McpInvocationScope = { @@ -731,6 +738,7 @@ describe("OrchestratorMcpService", () => { }), Layer.mock(ProjectService.ProjectService)({}), Layer.mock(SecretRequests.SecretRequests)({}), + Layer.mock(RemoteDelegation.RemoteDelegation)({}), Layer.mock(ScheduledTaskService.ScheduledTaskService)({}), ); const scope: McpInvocationScope = { @@ -817,6 +825,7 @@ describe("OrchestratorMcpService", () => { }), Layer.mock(ProjectService.ProjectService)({}), Layer.mock(SecretRequests.SecretRequests)({}), + Layer.mock(RemoteDelegation.RemoteDelegation)({}), Layer.mock(ScheduledTaskService.ScheduledTaskService)({}), ); const scope: McpInvocationScope = { @@ -950,6 +959,7 @@ describe("OrchestratorMcpService", () => { }), Layer.mock(ProjectService.ProjectService)({}), Layer.mock(SecretRequests.SecretRequests)({}), + Layer.mock(RemoteDelegation.RemoteDelegation)({}), Layer.mock(ScheduledTaskService.ScheduledTaskService)({}), ); const scope: McpInvocationScope = { @@ -1191,6 +1201,7 @@ describe("OrchestratorMcpService provider resolution", () => { ]), Layer.mock(ProjectService.ProjectService)({}), Layer.mock(SecretRequests.SecretRequests)({}), + Layer.mock(RemoteDelegation.RemoteDelegation)({}), Layer.mock(ScheduledTaskService.ScheduledTaskService)({}), ); @@ -1367,6 +1378,7 @@ describe("OrchestratorMcpService provider resolution", () => { adapterRegistryLayer([codexInstanceId, opencodeInstanceId]), Layer.mock(ProjectService.ProjectService)({}), Layer.mock(SecretRequests.SecretRequests)({}), + Layer.mock(RemoteDelegation.RemoteDelegation)({}), Layer.mock(ScheduledTaskService.ScheduledTaskService)({}), ), ), @@ -1471,6 +1483,7 @@ describe("OrchestratorMcpService provider resolution", () => { adapterRegistryLayer([codexInstanceId]), Layer.mock(ProjectService.ProjectService)({}), Layer.mock(SecretRequests.SecretRequests)({}), + Layer.mock(RemoteDelegation.RemoteDelegation)({}), Layer.mock(ScheduledTaskService.ScheduledTaskService)({}), ); @@ -1583,6 +1596,7 @@ describe("OrchestratorMcpService provider resolution", () => { adapterRegistryLayer([codexInstanceId, altInstanceId]), Layer.mock(ProjectService.ProjectService)({}), Layer.mock(SecretRequests.SecretRequests)({}), + Layer.mock(RemoteDelegation.RemoteDelegation)({}), Layer.mock(ScheduledTaskService.ScheduledTaskService)({}), ServerSettings.layerTest(), ); @@ -1691,6 +1705,7 @@ describe("OrchestratorMcpService provider resolution", () => { adapterRegistryLayer([codexInstanceId, altInstanceId]), Layer.mock(ProjectService.ProjectService)({}), Layer.mock(SecretRequests.SecretRequests)({}), + Layer.mock(RemoteDelegation.RemoteDelegation)({}), Layer.mock(ScheduledTaskService.ScheduledTaskService)({}), ServerSettings.layerTest(), ); @@ -1786,6 +1801,7 @@ describe("OrchestratorMcpService provider resolution", () => { ]), Layer.mock(ProjectService.ProjectService)({}), Layer.mock(SecretRequests.SecretRequests)({}), + Layer.mock(RemoteDelegation.RemoteDelegation)({}), Layer.mock(ScheduledTaskService.ScheduledTaskService)({}), ), ), @@ -2042,6 +2058,7 @@ describe("OrchestratorMcpService provider resolution", () => { ), Layer.mock(ProjectService.ProjectService)({}), Layer.mock(SecretRequests.SecretRequests)({}), + Layer.mock(RemoteDelegation.RemoteDelegation)({}), Layer.mock(ScheduledTaskService.ScheduledTaskService)({}), ); @@ -2206,6 +2223,7 @@ describe("OrchestratorMcpService provider resolution", () => { }), Layer.mock(ProjectService.ProjectService)({}), Layer.mock(SecretRequests.SecretRequests)({}), + Layer.mock(RemoteDelegation.RemoteDelegation)({}), Layer.mock(ScheduledTaskService.ScheduledTaskService)({ list: () => Effect.succeed({ tasks }), upsert: () => @@ -2276,6 +2294,7 @@ describe("OrchestratorMcpService provider resolution", () => { }), Layer.mock(ProjectService.ProjectService)({}), Layer.mock(SecretRequests.SecretRequests)({}), + Layer.mock(RemoteDelegation.RemoteDelegation)({}), Layer.mock(ScheduledTaskService.ScheduledTaskService)({ list: () => Effect.succeed({ tasks: [task({})] }), }), @@ -2364,6 +2383,7 @@ describe("OrchestratorMcpService provider resolution", () => { }), Layer.mock(ProjectService.ProjectService)({}), Layer.mock(SecretRequests.SecretRequests)({}), + Layer.mock(RemoteDelegation.RemoteDelegation)({}), Layer.mock(ScheduledTaskService.ScheduledTaskService)({ list: () => Effect.succeed({ tasks: [bound] }), upsert: () => @@ -2440,6 +2460,7 @@ describe("OrchestratorMcpService provider resolution", () => { adapterRegistryLayer([]), Layer.mock(ProjectService.ProjectService)({}), Layer.mock(SecretRequests.SecretRequests)({}), + Layer.mock(RemoteDelegation.RemoteDelegation)({}), Layer.mock(ScheduledTaskService.ScheduledTaskService)({}), ); yield* Effect.gen(function* () { @@ -2549,6 +2570,7 @@ describe("OrchestratorMcpService provider resolution", () => { adapterRegistryLayer([codexInstanceId, peerId]), Layer.mock(ProjectService.ProjectService)({}), Layer.mock(SecretRequests.SecretRequests)({}), + Layer.mock(RemoteDelegation.RemoteDelegation)({}), Layer.mock(ScheduledTaskService.ScheduledTaskService)({}), ); yield* Effect.gen(function* () { @@ -2625,6 +2647,7 @@ describe("OrchestratorMcpService thread lookup", () => { }), Layer.mock(ProjectService.ProjectService)({}), Layer.mock(SecretRequests.SecretRequests)({}), + Layer.mock(RemoteDelegation.RemoteDelegation)({}), Layer.mock(ScheduledTaskService.ScheduledTaskService)({}), ), ), @@ -2787,6 +2810,7 @@ describe("OrchestratorMcpService thread stop", () => { Layer.mock(ProviderRegistry.ProviderRegistry)({ getProviders: Effect.succeed([]) }), Layer.mock(ProjectService.ProjectService)({}), Layer.mock(SecretRequests.SecretRequests)({}), + Layer.mock(RemoteDelegation.RemoteDelegation)({}), Layer.mock(ScheduledTaskService.ScheduledTaskService)({}), ), ), diff --git a/apps/server/src/mcp/OrchestratorMcpService.ts b/apps/server/src/mcp/OrchestratorMcpService.ts index d0954ad582af2..f03ec0aecaf13 100644 --- a/apps/server/src/mcp/OrchestratorMcpService.ts +++ b/apps/server/src/mcp/OrchestratorMcpService.ts @@ -117,6 +117,8 @@ import { } from "./delegatedTaskModes.ts"; import { isLiveCallerShell, threadNotFound } from "./threadAccess.ts"; import * as SecretRequests from "../secrets/SecretRequests.ts"; +import * as PeerForwarding from "../peer/PeerForwarding.ts"; +import * as RemoteDelegation from "../peer/RemoteDelegation.ts"; const DEFAULT_WAIT_TIMEOUT_MS = 10 * 60 * 1_000; const MAX_WAIT_TIMEOUT_MS = 60 * 60 * 1_000; @@ -960,6 +962,7 @@ const make = Effect.gen(function* () { const threadLaunch = yield* ThreadLaunchService.ThreadLaunchService; const gitDriver = yield* GitVcsDriver.GitVcsDriver; const serverSettings = yield* ServerSettings.ServerSettingsService; + const remoteDelegation = yield* RemoteDelegation.RemoteDelegation; const requireProject = (projectId: ProjectId) => projects.getById(projectId).pipe( @@ -1397,14 +1400,15 @@ const make = Effect.gen(function* () { candidate.origin === "app_owned" && candidate.threadId === scope.thread.threadId, ); - // Coder: no task runs in a linked environment (peer links are not carried), so a task - // without a child here is unknown. - if (task === undefined || task.childThreadId === null) { + if (task === undefined || (task.childThreadId === null && task.remoteChild === undefined)) { return yield* failure( "task_not_found", `Delegated task ${taskId} does not belong to thread ${scope.thread.threadId}.`, ); } + if (task.childThreadId === null) { + return yield* readRemoteTask(scope, task, waitTimedOut, acknowledgeTerminal); + } const childControls = yield* threadManagement .getThreadRecords( task.childThreadId, @@ -1585,6 +1589,113 @@ const make = Effect.gen(function* () { return response; }); + /** `mode=wait` on a task already recorded, as `delegateTask` does for its own. */ + const awaitTask = Effect.fn("OrchestratorMcpService.awaitTask")(function* ( + scope: McpThreadInvocationScope, + taskId: NodeId, + requestedTimeoutMs: number | undefined, + ): Effect.fn.Return { + const timeoutMs = Math.min( + MAX_WAIT_TIMEOUT_MS, + Math.max(1, requestedTimeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS), + ); + const waited = yield* waitForTask(scope, taskId, timeoutMs); + if (Option.isSome(waited)) return waited.value; + // As for a local task: once the blocking wait ends, a later result wakes the parent. + yield* threadManagement + .dispatch({ + type: "delegated_task.wake-policy", + commandId: stableCommandId({ + scope, + requestKey: taskId, + operation: "delegate-task-wake-policy", + }), + parentThreadId: scope.thread.threadId, + taskId, + completionWake: "always", + }) + .pipe(Effect.ignoreCause({ log: true })); + return yield* readTask(scope, taskId, true, true); + }); + + /** + * A task that runs in a linked environment, answered from its row here: + * the follower records its result once its thread there ends. + */ + const readRemoteTask = Effect.fn("OrchestratorMcpService.readRemoteTask")(function* ( + scope: McpThreadInvocationScope, + task: OrchestrationV2Subagent, + waitTimedOut: boolean, + acknowledgeTerminal: boolean, + ): Effect.fn.Return { + const status: OrchestratorMcpDelegateTaskResult["status"] = + task.result === null + ? "running" + : task.status === "completed" || + task.status === "failed" || + task.status === "cancelled" || + task.status === "interrupted" + ? task.status + : "completed"; + const terminal = isTerminalTaskStatus(status); + if ( + acknowledgeTerminal && + terminal && + task.completionDelivery?.state !== "acknowledged" && + task.completionDelivery?.state !== "disposed" + ) { + const parentProjection = yield* loadProjection(scope.thread.threadId); + const observingRun = ThreadManagementService.latestActiveRun(parentProjection); + yield* threadManagement + .dispatch({ + type: "delegated_task.completion-delivery.acknowledge", + commandId: stableCommandId({ + scope, + requestKey: yield* requestKey(undefined), + operation: "task-status-acknowledge", + }), + parentThreadId: scope.thread.threadId, + taskId: task.id, + observedByRunId: + observingRun?.providerInstanceId === scope.thread.providerInstanceId + ? observingRun.id + : null, + }) + .pipe( + Effect.mapError((error) => + failure( + "orchestration_error", + `Unable to acknowledge delegated task ${task.id}: ${errorMessage(error)}`, + ), + ), + ); + } + return { + taskId: task.id, + childThreadId: null, + ...(task.remoteChild === undefined ? {} : { remoteChild: task.remoteChild }), + childRunId: null, + childNodeId: task.id, + status, + workState: terminal ? "result_available" : "working", + hasPendingChildRuns: false, + providerInstanceId: task.providerInstanceId, + model: task.model, + summary: task.result, + resultContextTransferId: null, + latestTerminalRunId: null, + latestTerminalStatus: terminal + ? (status as OrchestratorMcpDelegateTaskResult["latestTerminalStatus"]) + : null, + latestTerminalSummary: terminal ? task.result : null, + latestTerminalResultContextTransferId: null, + // Its questions and approvals are answered in the environment it runs in. + hasPendingQuestion: false, + pendingApproval: null, + waitTimedOut, + } satisfies OrchestratorMcpDelegateTaskResult; + }); + const waitForTask = Effect.fn("OrchestratorMcpService.waitForTask")( function* (scope: McpThreadInvocationScope, taskId: NodeId, _timeoutMs: number) { const streamError = (error: unknown) => @@ -2052,16 +2163,21 @@ const make = Effect.gen(function* () { }; }), delegateTask: Effect.fn("OrchestratorMcpService.delegateTask")(function* (callerScope, input) { - // Coder: peer links are not carried, so a task cannot run in another environment; naming - // this one runs it here, as upstream's remoteTarget does. - if ( - input.target?.environmentId !== undefined && - input.target.environmentId !== callerScope.environmentId - ) { - return yield* failure( - "invalid_request", - "This environment cannot reach linked environments.", - ); + const environmentId = + input.target === undefined + ? undefined + : PeerForwarding.remoteTarget(callerScope, input.target.environmentId); + if (input.target !== undefined && environmentId !== undefined) { + yield* requireCapability(callerScope); + const scope = yield* requireThreadScope(callerScope, "delegate_task"); + // The task's child runs as an ordinary thread there; this thread keeps the task. + const { taskId } = yield* remoteDelegation.delegate(scope, { + ...input, + target: { ...input.target, environmentId }, + }); + return yield* input.mode === "wait" + ? awaitTask(scope, taskId, input.timeoutMs) + : readTask(scope, taskId, false, true); } const { scope, parent } = yield* loadThreadCaller(callerScope, "delegate_task"); if ( @@ -2070,8 +2186,7 @@ const make = Effect.gen(function* () { ) { return yield* failure( "invalid_request", - // Coder: no linked environment's project to name instead. - "A task runs in this thread's project. Omit target.projectId.", + "A local task runs in this thread's project. Omit target.projectId, or pass target.environmentId to run it in that environment's project.", ); } const parentRun = parent.runs @@ -2254,12 +2369,22 @@ const make = Effect.gen(function* () { const scope = yield* requireThreadScope(callerScope, "task_cancel"); const current = yield* readTask(scope, input.taskId); const childThreadId = current.childThreadId; - // Coder: readTask rejects a task without a child here; no task runs in a linked environment. if (childThreadId === null) { - return yield* failure( - "task_not_found", - `Delegated task ${input.taskId} does not belong to thread ${scope.thread.threadId}.`, + // The task runs in a linked environment: its thread there is stopped through the link. + const { subagents } = yield* loadProjection(scope.thread.threadId); + const remoteTask = subagents.find( + (task) => + task.id === input.taskId && + task.origin === "app_owned" && + task.remoteChild !== undefined, ); + if (remoteTask === undefined) { + return yield* failure( + "task_not_found", + `Delegated task ${input.taskId} does not belong to thread ${scope.thread.threadId}.`, + ); + } + return yield* remoteDelegation.cancel(scope, remoteTask, input); } const key = yield* requestKey(input.clientRequestId); const parentProjection = yield* loadProjection(scope.thread.threadId); @@ -2534,6 +2659,9 @@ const make = Effect.gen(function* () { interactionMode, branch: parent.thread.branch, worktreePath: parent.thread.worktreePath, + ...(parent.thread.linkOrigin === undefined + ? {} + : { linkOrigin: parent.thread.linkOrigin }), }) .pipe( Effect.mapError((error) => @@ -2959,4 +3087,5 @@ export const layer: Layer.Layer< | ProjectService.ProjectService | SecretRequests.SecretRequests | ServerSettings.ServerSettingsService + | RemoteDelegation.RemoteDelegation > = Layer.effect(OrchestratorMcpService, make); diff --git a/apps/server/src/mcp/TaskCancelNativeSubagent.integration.test.ts b/apps/server/src/mcp/TaskCancelNativeSubagent.integration.test.ts index ba33c614ff0f8..c8b3f4ed3abf6 100644 --- a/apps/server/src/mcp/TaskCancelNativeSubagent.integration.test.ts +++ b/apps/server/src/mcp/TaskCancelNativeSubagent.integration.test.ts @@ -37,6 +37,7 @@ import * as SqlitePersistence from "../persistence/Sqlite.ts"; import * as ProjectService from "../project/ProjectService.ts"; import * as ProviderRegistry from "../provider/ProviderRegistry.ts"; import * as ScheduledTaskService from "../scheduledTasks/ScheduledTaskService.ts"; +import * as RemoteDelegation from "../peer/RemoteDelegation.ts"; import * as SecretRequests from "../secrets/SecretRequests.ts"; import type { McpInvocationScope } from "./McpInvocationContext.ts"; import * as OrchestratorMcpService from "./OrchestratorMcpService.ts"; @@ -157,6 +158,7 @@ it.effect("task_cancel ends a delegated child's background native subagent", () Layer.mock(ProjectService.ProjectService)({}), Layer.mock(SecretRequests.SecretRequests)({}), ServerSettings.layerTest(), + Layer.mock(RemoteDelegation.RemoteDelegation)({}), Layer.mock(ScheduledTaskService.ScheduledTaskService)({}), NodeServices.layer, ), diff --git a/apps/server/src/mcp/WorktreeMcpService.ts b/apps/server/src/mcp/WorktreeMcpService.ts index 8f02ee1546424..267df07f2432f 100644 --- a/apps/server/src/mcp/WorktreeMcpService.ts +++ b/apps/server/src/mcp/WorktreeMcpService.ts @@ -357,7 +357,9 @@ const make = Effect.gen(function* () { scriptName: result.scriptName, terminalId: result.terminalId, } - : { status: "no-script" }, + : result.status === "skipped-for-link" + ? { status: "skipped" } + : { status: "no-script" }, ), reportFailed("worktree handoff setup script failed"), ); diff --git a/apps/server/src/mcp/bridge/T3ToolBridge.test.ts b/apps/server/src/mcp/bridge/T3ToolBridge.test.ts index 5bdb4517a46d0..f6c9a7dee2145 100644 --- a/apps/server/src/mcp/bridge/T3ToolBridge.test.ts +++ b/apps/server/src/mcp/bridge/T3ToolBridge.test.ts @@ -28,6 +28,7 @@ import * as ProviderAdapterRegistry from "../../orchestration-v2/ProviderAdapter import * as ThreadLaunchService from "../../orchestration-v2/ThreadLaunchService.ts"; import * as ThreadManagementService from "../../orchestration-v2/ThreadManagementService.ts"; import * as ProviderRegistry from "../../provider/ProviderRegistry.ts"; +import * as RemoteDelegation from "../../peer/RemoteDelegation.ts"; import * as ScheduledTaskService from "../../scheduledTasks/ScheduledTaskService.ts"; import * as SecretRequests from "../../secrets/SecretRequests.ts"; import * as GitWorkflowService from "../../git/GitWorkflowService.ts"; @@ -136,6 +137,7 @@ const harness = (options: { Layer.mock(GitWorkflowService.GitWorkflowService)({}), Layer.mock(ProjectSetupScriptRunner.ProjectSetupScriptRunner)({}), Layer.mock(VcsStatusBroadcaster.VcsStatusBroadcaster)({}), + Layer.mock(RemoteDelegation.RemoteDelegation)({}), Layer.mock(ScheduledTaskService.ScheduledTaskService)({}), Layer.mock(SecretRequests.SecretRequests)({}), Layer.mock(ProviderRegistry.ProviderRegistry)({}), diff --git a/apps/server/src/mcp/bridge/T3ToolBridge.ts b/apps/server/src/mcp/bridge/T3ToolBridge.ts index 3d9439b62549b..b3acd1ddfb2c1 100644 --- a/apps/server/src/mcp/bridge/T3ToolBridge.ts +++ b/apps/server/src/mcp/bridge/T3ToolBridge.ts @@ -149,7 +149,7 @@ export const makeBindingWith = (options: { readonly inlineBudgetMs?: number } = const jobs = new Map(); const run = ( - scope: McpInvocationContext.McpThreadInvocationScope, + scope: McpInvocationContext.McpInvocationScope, request: FileBridgeRequest, ): Effect.Effect => ( @@ -247,7 +247,14 @@ export const makeBindingWith = (options: { readonly inlineBudgetMs?: number } = }; }); - return { catalog: T3_TOOL_CATALOG, dispatch } satisfies T3ToolBinding; + // A call another workspace forwards through the gateway hub runs inline as its caller; the + // hub waits for it, so it takes no task id. + const invoke: T3ToolBinding["invoke"] = (scope, request) => + T3_TOOL_CATALOG.some((entry) => entry.name === request.tool) + ? run(scope, request) + : failure("UnknownTool", "Unknown T3 tool."); + + return { catalog: T3_TOOL_CATALOG, dispatch, invoke } satisfies T3ToolBinding; }); export const makeBinding = makeBindingWith(); diff --git a/apps/server/src/mcp/bridge/T3ToolDispatch.ts b/apps/server/src/mcp/bridge/T3ToolDispatch.ts index 1a6676bc4ba0e..8cfc4e86a7e26 100644 --- a/apps/server/src/mcp/bridge/T3ToolDispatch.ts +++ b/apps/server/src/mcp/bridge/T3ToolDispatch.ts @@ -30,6 +30,11 @@ export interface T3ToolBinding { scope: McpInvocationContext.McpThreadInvocationScope, request: FileBridgeRequest, ) => Effect.Effect; + /** Runs a tool for a caller that is not one of this workspace's agents (the gateway hub). */ + readonly invoke: ( + scope: McpInvocationContext.McpInvocationScope, + request: FileBridgeRequest, + ) => Effect.Effect; } export class T3ToolDispatch extends Context.Service< diff --git a/apps/server/src/mcp/linkOrigin.ts b/apps/server/src/mcp/linkOrigin.ts new file mode 100644 index 0000000000000..7373fd51d2bd4 --- /dev/null +++ b/apps/server/src/mcp/linkOrigin.ts @@ -0,0 +1,60 @@ +import { + linkOriginIsFenced, + OrchestratorMcpFailure, + type OrchestrationV2LinkOrigin, + type OrchestrationV2ThreadShell, +} from "@t3tools/contracts"; +import * as Effect from "effect/Effect"; + +import type { Caller } from "./threadAccess.ts"; + +/** + * Below full access, work a link starts here (all of it carries that session in `linkOrigin`) + * may change only work from the same link: not the user's threads, projects or settings, nor + * this environment's links. Reads are not fenced. It is a routing rule for T3's tools; agents + * still run as this environment's user, so a full-access link is not fenced at all. + */ + +/** The link a caller acts for: its own session, or the link that started its thread. */ +export const callerLinkOrigin = ( + caller: Pick, +): OrchestrationV2LinkOrigin | undefined => + caller.caller?.linkOrigin ?? + (caller.scope.client?.linked === true + ? { + sessionId: caller.scope.client.sessionId, + label: caller.scope.client.label, + access: caller.scope.client.access, + } + : undefined); + +/** The link that fences a caller, if any: one paired below full access. */ +const fencingLinkOrigin = (caller: Pick) => { + const origin = callerLinkOrigin(caller); + return origin !== undefined && linkOriginIsFenced(origin) ? origin : undefined; +}; + +const outsideLink = (origin: OrchestrationV2LinkOrigin, message: string) => + new OrchestratorMcpFailure({ + code: "capability_denied", + message: `This work was started from ${origin.label} through a linked environment, so ${message} A link paired with full access is not limited this way.`, + }); + +/** A thread a fenced caller may change: one its own link started. */ +export const assertSameLink = ( + caller: Pick, + target: Pick, +) => { + const origin = fencingLinkOrigin(caller); + return origin === undefined || target.linkOrigin?.sessionId === origin.sessionId + ? Effect.void + : Effect.fail(outsideLink(origin, `it may change only threads that link started.`)); +}; + +/** Fenced work never changes what the environment already has: projects, settings, scheduled runs. */ +export const assertNotLinked = (caller: Pick, what: string) => { + const origin = fencingLinkOrigin(caller); + return origin === undefined + ? Effect.void + : Effect.fail(outsideLink(origin, `it cannot ${what}.`)); +}; diff --git a/apps/server/src/mcp/toolkits/orchestrator/handlers.ts b/apps/server/src/mcp/toolkits/orchestrator/handlers.ts index 2d829fe428e9a..5d26408314aae 100644 --- a/apps/server/src/mcp/toolkits/orchestrator/handlers.ts +++ b/apps/server/src/mcp/toolkits/orchestrator/handlers.ts @@ -2,6 +2,7 @@ import { OrchestratorMcpFailure } from "@t3tools/contracts"; import { OrchestratorToolkit } from "./tools.ts"; import * as Effect from "effect/Effect"; +import * as PeerForwarding from "../../../peer/PeerForwarding.ts"; import { readCaller } from "../../threadAccess.ts"; import * as McpInvocationContext from "../../McpInvocationContext.ts"; import * as McpToolAccess from "../../McpToolAccess.ts"; @@ -94,6 +95,8 @@ const handlers = { const service = yield* OrchestratorMcpService.OrchestratorMcpService; return yield* service.scheduleTask(scope, { ...input, prompt, schedule }); }), + // A scheduled run starts long after its caller, with nothing to carry the link. + { refused: "schedule tasks in this environment" }, ), McpToolAccess.writes( ({ scheduledTaskId, prompt, title, schedule, enabled, bindToCurrentThread }) => @@ -179,6 +182,13 @@ const handlers = { return yield* service.waitForThread(scope, input); }), ), + t3_environment_links: McpToolAccess.reads(() => + Effect.gen(function* () { + const scope = yield* McpInvocationContext.McpInvocationContext; + const forwarding = yield* PeerForwarding.PeerForwarding; + return yield* forwarding.links(scope); + }), + ), t3_thread_interrupt: McpToolAccess.writesThreads( (input) => [input.threadId], (input) => diff --git a/apps/server/src/mcp/toolkits/orchestrator/tools.ts b/apps/server/src/mcp/toolkits/orchestrator/tools.ts index 93a744c631aa4..0b1cf59685f00 100644 --- a/apps/server/src/mcp/toolkits/orchestrator/tools.ts +++ b/apps/server/src/mcp/toolkits/orchestrator/tools.ts @@ -2,6 +2,7 @@ import { OrchestratorMcpCapabilitiesInput, OrchestratorMcpCapabilitiesResult, OrchestrationV2StopWorkflowInput, + OrchestratorMcpEnvironmentLinksResult, OrchestratorMcpCreateThreadsInput, OrchestratorMcpCreateThreadsResult, OrchestratorMcpDelegateTaskInput, @@ -33,11 +34,12 @@ import { ThreadMetadataMcpUpdateResult, TrimmedNonEmptyString, } from "@t3tools/contracts"; -import { Tool, Toolkit } from "effect/ai"; +import { McpSchema, Tool, Toolkit } from "effect/ai"; import * as Schema from "effect/Schema"; import * as Struct from "effect/Struct"; import * as ThreadManagementService from "../../../orchestration-v2/ThreadManagementService.ts"; +import * as PeerForwarding from "../../../peer/PeerForwarding.ts"; import * as McpInvocationContext from "../../McpInvocationContext.ts"; import * as OrchestratorMcpService from "../../OrchestratorMcpService.ts"; import * as ThreadMetadataMcpService from "../../ThreadMetadataMcpService.ts"; @@ -47,6 +49,8 @@ const dependencies = [ ThreadManagementService.ThreadManagementService, OrchestratorMcpService.OrchestratorMcpService, ]; +/** Listing this environment's links. */ +const linkDependencies = [...dependencies, PeerForwarding.PeerForwarding]; const threadMetadataDependencies = [ McpInvocationContext.McpInvocationContext, ThreadManagementService.ThreadManagementService, @@ -289,8 +293,24 @@ const ThreadInterruptTool = Tool.make("t3_thread_interrupt", { .annotate(Tool.Title, "Interrupt a T3 thread") .annotate(Tool.Destructive, true); -// Coder: upstream's t3_environment_links, t3_environment_link, and t3_environment_unlink -// tools are not carried, since peer links are not. +const EnvironmentLinksTool = Tool.make("t3_environment_links", { + description: + // Coder: links are the user's workspace link rules in T3 Coder, not pairings an agent asks for. + "List linked environments (the user's other workspaces) and whether each answers now. Pass one's `environmentId` to a tool to act there; `delegate_task` takes `target.environmentId`.", + success: OrchestratorMcpEnvironmentLinksResult, + failure: OrchestratorMcpFailure, + failureMode: "return", + dependencies: linkDependencies, +}) + .annotate(Tool.Title, "List linked environments") + .annotate(Tool.Readonly, true) + .annotate(Tool.Destructive, false) + .annotate(Tool.Idempotent, true) + .annotate(McpSchema.EnabledWhen, McpInvocationContext.hiddenWhileLinksOff); + +// Coder: upstream's t3_environment_link and t3_environment_unlink, which pair and forget +// environments, are not carried; the user sets workspace link rules in T3 Coder. + export const OrchestratorToolkit = Toolkit.make( OrchestratorCapabilitiesTool, DelegateTaskTool, @@ -309,4 +329,5 @@ export const OrchestratorToolkit = Toolkit.make( ThreadSendTool, ThreadWaitTool, ThreadInterruptTool, + EnvironmentLinksTool, ); diff --git a/apps/server/src/mcp/toolkits/project/handlers.ts b/apps/server/src/mcp/toolkits/project/handlers.ts index fbc85fcf7f22b..f5a67ae025a85 100644 --- a/apps/server/src/mcp/toolkits/project/handlers.ts +++ b/apps/server/src/mcp/toolkits/project/handlers.ts @@ -76,7 +76,7 @@ const access = Effect.gen(function* () { export const layer = McpToolAccess.toLayer(ProjectToolkit, { t3_thread_launch: McpToolAccess.startsThreads( (input) => input, - (input, { runtimeMode, interactionMode }) => + (input, { runtimeMode, interactionMode, linkOrigin }) => Effect.gen(function* () { const scope = yield* McpInvocationContext.McpInvocationContext; const context = yield* readCaller(); @@ -216,6 +216,9 @@ export const layer = McpToolAccess.toLayer(ProjectToolkit, { }), createdBy: "agent", creationSource: "mcp", + ...(linkOrigin === undefined ? {} : { linkOrigin }), + // Kept only alongside linkOrigin: thread.create drops it otherwise. + ...(input.delegatedFrom === undefined ? {} : { delegatedFrom: input.delegatedFrom }), }).pipe( Effect.mapError((error) => { if (error._tag === "AttachmentClaimError") { @@ -244,6 +247,8 @@ export const layer = McpToolAccess.toLayer(ProjectToolkit, { status: run?.status ?? null, }; }), + // The launched thread carries the caller's link, if it has one. + "stamped", ), t3_project_list: McpToolAccess.reads((input) => Effect.gen(function* () { @@ -266,49 +271,53 @@ export const layer = McpToolAccess.toLayer(ProjectToolkit, { return result.value; }), ), - t3_project_create: McpToolAccess.writesEnvironment(({ workspaceRoot, ...input }) => - Effect.gen(function* () { - const projects = yield* Project.ProjectService; - if (workspaceRoot === undefined) { - // Only updates record model defaults; reject defaults that creation would silently drop. - if ( - input.scripts !== undefined || - input.createWorkspaceRootIfMissing !== undefined || - input.defaultModelSelection !== undefined - ) - return yield* new OrchestratorMcpFailure({ - code: "invalid_request", - message: - "A project started from its title takes only a title; set scripts or defaultModelSelection afterwards with t3_project_update.", - }); - const folders = yield* ManagedProjectFolders.ManagedProjectFolders; - const created = yield* folders.createNamedProject({ name: input.title }).pipe( - Effect.mapError( - (error) => - new OrchestratorMcpFailure({ - code: "orchestration_error", - message: error.message, - }), - ), - ); - const project = yield* projects - .getById(created.projectId) - .pipe( - Effect.mapError(unavailable), - Effect.flatMap( - Option.match({ onNone: () => Effect.fail(unavailable()), onSome: Effect.succeed }), + t3_project_create: McpToolAccess.writesEnvironment( + ({ workspaceRoot, ...input }) => + Effect.gen(function* () { + const projects = yield* Project.ProjectService; + if (workspaceRoot === undefined) { + // Only updates record model defaults; reject defaults that creation would silently drop. + if ( + input.scripts !== undefined || + input.createWorkspaceRootIfMissing !== undefined || + input.defaultModelSelection !== undefined + ) + return yield* new OrchestratorMcpFailure({ + code: "invalid_request", + message: + "A project started from its title takes only a title; set scripts or defaultModelSelection afterwards with t3_project_update.", + }); + const folders = yield* ManagedProjectFolders.ManagedProjectFolders; + const created = yield* folders.createNamedProject({ name: input.title }).pipe( + Effect.mapError( + (error) => + new OrchestratorMcpFailure({ + code: "orchestration_error", + message: error.message, + }), ), ); - return { - ...project, - ...(created.commitError === undefined ? {} : { commitError: created.commitError }), - }; - } - const commandId = yield* newCommandId(); - return yield* projects - .create({ ...input, workspaceRoot, commandId, projectId: ProjectId.make(commandId) }) - .pipe(Effect.mapError(projectFailure)); - }), + const project = yield* projects + .getById(created.projectId) + .pipe( + Effect.mapError(unavailable), + Effect.flatMap( + Option.match({ onNone: () => Effect.fail(unavailable()), onSome: Effect.succeed }), + ), + ); + return { + ...project, + ...(created.commitError === undefined ? {} : { commitError: created.commitError }), + }; + } + const commandId = yield* newCommandId(); + return yield* projects + .create({ ...input, workspaceRoot, commandId, projectId: ProjectId.make(commandId) }) + .pipe(Effect.mapError(projectFailure)); + }), + // Linked work may bring the repository it works in; an existing + // registered workspace is still refused. + { linkedCallers: "allowed" }, ), t3_project_update: McpToolAccess.writesEnvironment((input) => Effect.gen(function* () { @@ -326,18 +335,21 @@ export const layer = McpToolAccess.toLayer(ProjectToolkit, { .pipe(Effect.mapError(projectFailure)); }), ), - t3_project_clone: McpToolAccess.writesEnvironment((input) => - Effect.gen(function* () { - const repositories = yield* Repositories.SourceControlRepositoryService; - return yield* repositories.cloneRepository(input).pipe( - Effect.mapError( - (error) => - new OrchestratorMcpFailure({ - code: "orchestration_error", - message: error.detail, - }), - ), - ); - }), + t3_project_clone: McpToolAccess.writesEnvironment( + (input) => + Effect.gen(function* () { + const repositories = yield* Repositories.SourceControlRepositoryService; + return yield* repositories.cloneRepository(input).pipe( + Effect.mapError( + (error) => + new OrchestratorMcpFailure({ + code: "orchestration_error", + message: error.detail, + }), + ), + ); + }), + // An existing destination is never adopted. + { linkedCallers: "allowed" }, ), }); diff --git a/apps/server/src/mcp/toolkits/project/tools.ts b/apps/server/src/mcp/toolkits/project/tools.ts index 650e6ce3286f9..38931596868b4 100644 --- a/apps/server/src/mcp/toolkits/project/tools.ts +++ b/apps/server/src/mcp/toolkits/project/tools.ts @@ -5,6 +5,7 @@ import { TrimmedNonEmptyString, ThreadId, RunId, + OrchestrationV2DelegatedFrom, OrchestrationV2RunStatus, OrchestrationV2ThreadLaunchWorkspaceStrategy, RuntimeMode, @@ -146,7 +147,8 @@ const ThreadLaunchTool = Tool.make("t3_thread_launch", { ), attachments: Schema.optional(Schema.Array(McpAttachmentInput).check(Schema.isMaxLength(8))), clientRequestId: Schema.optional(OrchestratorMcpClientRequestId), - // Coder: upstream's `delegatedFrom`, set only by a linked environment, is not carried. + /** Set by a linked environment launching its agent's delegated task here; ignored otherwise. */ + delegatedFrom: Schema.optional(OrchestrationV2DelegatedFrom), }), success: Schema.Struct({ threadId: ThreadId, diff --git a/apps/server/src/orchestration-v2/ProjectionStore.ts b/apps/server/src/orchestration-v2/ProjectionStore.ts index e877d5d543abe..5636125ba0bb3 100644 --- a/apps/server/src/orchestration-v2/ProjectionStore.ts +++ b/apps/server/src/orchestration-v2/ProjectionStore.ts @@ -487,8 +487,15 @@ export interface ProjectionStoreV2Shape { ReadonlyArray<{ readonly threadId: ThreadId; readonly worktreePath: string }>, ProjectionStoreV2Error >; - // Coder: upstream's getOpenRemoteDelegatedTasks, read only by the linked-environment task - // follower, is not carried. + /** + * Delegated tasks in a linked environment with work left for this one: no + * result yet, or cancelled or stopped here without that stop reaching there, + * including a Stop after the task had its result. + */ + readonly getOpenRemoteDelegatedTasks: Effect.Effect< + ReadonlyArray<{ readonly parentThreadId: ThreadId; readonly taskId: NodeId }>, + ProjectionStoreV2Error + >; readonly getTurnStartContext: ( threadId: ThreadId, runId: RunId, @@ -6065,6 +6072,32 @@ export const layer: Layer.Layer = ) .pipe(Effect.mapError((cause) => new ProjectionStoreSetupError({ cause }))); + const getOpenRemoteDelegatedTasks: ProjectionStoreV2Shape["getOpenRemoteDelegatedTasks"] = sql<{ + readonly thread_id: string; + readonly subagent_id: string; + }>` + SELECT thread_id, subagent_id FROM orchestration_v2_projection_subagents + WHERE origin = 'app_owned' + AND child_thread_id IS NULL + AND json_type(payload_json, '$.remoteChild') = 'object' + AND ( + json_type(payload_json, '$.result') = 'null' + OR ( + json_extract(payload_json, '$.status') IN ('cancelled', 'interrupted') + AND json_type(payload_json, '$.remoteChild.stoppedThere') IS NOT 'true' + ) + OR json_type(payload_json, '$.remoteChild.stoppedThere') = 'false' + ) + `.pipe( + Effect.map((rows) => + rows.map((row) => ({ + parentThreadId: ThreadId.make(row.thread_id), + taskId: NodeId.make(row.subagent_id), + })), + ), + Effect.mapError((cause) => new ProjectionStoreSetupError({ cause })), + ); + const getThreadsWithPullRequests: ProjectionStoreV2Shape["getThreadsWithPullRequests"] = Effect.fn("ProjectionStore.getThreadsWithPullRequests")( function* (threadId) { @@ -6595,6 +6628,7 @@ export const layer: Layer.Layer = getSettlementCandidates: readOnReader(getSettlementCandidates), getThreadsWithPullRequests: readOnReader(getThreadsWithPullRequests), getThreadWorktreePaths: readOnReader(getThreadWorktreePaths), + getOpenRemoteDelegatedTasks: getOpenRemoteDelegatedTasks.pipe(NodeSqliteClient.readOnly), getThreadProjection, getTurnStartContext: readOnReader(getTurnStartContext), getTurnStartHistory: readOnReader(getTurnStartHistory), diff --git a/apps/server/src/orchestration-v2/ProviderSessionManager.test.ts b/apps/server/src/orchestration-v2/ProviderSessionManager.test.ts index 726ee561fa064..49115640f0378 100644 --- a/apps/server/src/orchestration-v2/ProviderSessionManager.test.ts +++ b/apps/server/src/orchestration-v2/ProviderSessionManager.test.ts @@ -586,7 +586,13 @@ const layerTestMcpRegistry = Layer.effect( Layer.effect( T3ToolDispatch.T3ToolDispatch, T3ToolDispatch.T3ToolDispatch.pipe( - Effect.tap((tools) => tools.bind({ catalog: [], dispatch: () => Effect.succeed(null) })), + Effect.tap((tools) => + tools.bind({ + catalog: [], + dispatch: () => Effect.succeed(null), + invoke: () => Effect.succeed(null), + }), + ), ), ).pipe(Layer.provide(T3ToolDispatch.layer)), ), diff --git a/apps/server/src/orchestration-v2/ProviderTurnControlService.test.ts b/apps/server/src/orchestration-v2/ProviderTurnControlService.test.ts index 3b2147da3b043..a39f6b7f036a6 100644 --- a/apps/server/src/orchestration-v2/ProviderTurnControlService.test.ts +++ b/apps/server/src/orchestration-v2/ProviderTurnControlService.test.ts @@ -210,7 +210,7 @@ it.effect( ProjectionStore.ProjectionStoreV2.of({ apply: () => Effect.void, getLimitRecoveryCandidates: () => Effect.die("unused getLimitRecoveryCandidates"), - // Coder: no getOpenRemoteDelegatedTasks; the linked-environment follower is not carried. + getOpenRemoteDelegatedTasks: Effect.die("unused getOpenRemoteDelegatedTasks"), getShellSnapshot: () => Effect.die("unused getShellSnapshot"), listActiveSubagentThreadIds: () => Effect.die("unused listActiveSubagentThreadIds"), listOlderSettledThreads: () => Effect.die("unused listOlderSettledThreads"), diff --git a/apps/server/src/orchestration-v2/RemoteDelegatedTask.test.ts b/apps/server/src/orchestration-v2/RemoteDelegatedTask.test.ts new file mode 100644 index 0000000000000..4bb8c103f6df7 --- /dev/null +++ b/apps/server/src/orchestration-v2/RemoteDelegatedTask.test.ts @@ -0,0 +1,411 @@ +import { assert, it } from "@effect/vitest"; +import { + CommandId, + EnvironmentId, + EventId, + MessageId, + NodeId, + ProjectId, + ProviderDriverKind, + ProviderInstanceId, + ProviderThreadId, + RunId, + ThreadId, +} from "@t3tools/contracts"; +import * as Context from "effect/Context"; +import * as DateTime from "effect/DateTime"; +import * as Effect from "effect/Effect"; +import * as Layer from "effect/Layer"; +import * as Ref from "effect/Ref"; + +import { CodexProviderCapabilitiesV2 } from "./Adapters/CodexAdapterV2.ts"; +import * as EventSink from "./EventSink.ts"; +import * as Orchestrator from "./Orchestrator.ts"; +import type * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter"; +import * as ProjectionStore from "./ProjectionStore.ts"; +import * as ProviderAdapterRegistry from "./ProviderAdapterRegistry.ts"; +import * as ProviderContinuationRequests from "@t3tools/provider-core/server/ProviderContinuationRequests"; +import * as ProviderReplayHarness from "./testkit/ProviderReplayHarness.ts"; +import * as SqlitePersistence from "../persistence/Sqlite.ts"; + +// A delegated task whose child runs in a linked environment is recorded on +// its parent without a child thread here, and completing it wakes the parent +// the way a local child's result does. + +const instanceId = ProviderInstanceId.make("codex"); +const driver = ProviderDriverKind.make("codex"); +const modelSelection = { instanceId, model: "gpt-5.4" }; +const adapter = { + instanceId, + driver, + getCapabilities: () => Effect.succeed(CodexProviderCapabilitiesV2), + planSelectionTransition: () => Effect.succeed({ type: "apply_on_next_turn" as const }), + openSession: () => Effect.die("No provider process needed for delegated task records"), +} as ProviderAdapter.ProviderAdapterV2["Service"]; + +/** Every parent wake the orchestrator offers, for the tests to read. */ +class Offers extends Context.Service< + Offers, + Ref.Ref> +>()("t3/orchestration-v2/RemoteDelegatedTask.test/Offers") {} +const layerOffers = Layer.effect( + Offers, + Ref.make>([]), +); +const layerDatabase = SqlitePersistence.layerMemory; +const layerTest = Layer.mergeAll( + layerDatabase, + ProjectionStore.layer.pipe(Layer.provide(layerDatabase)), + ProviderReplayHarness.layerWithRegistry( + { name: "remote-delegated-task" }, + ProviderAdapterRegistry.layerFromAdapters([adapter]), + { databaseLayer: layerDatabase, runEffectWorker: false }, + ), +).pipe( + Layer.provide( + Layer.effect( + ProviderContinuationRequests.ProviderContinuationRequests, + Offers.pipe( + Effect.map((offers) => ({ + offer: (request: ProviderContinuationRequests.ProviderContinuationRequest) => + Ref.update(offers, (seen) => [...seen, request]), + take: Effect.never, + })), + ), + ), + ), + Layer.provideMerge(layerOffers), +); + +/** A parent thread whose run is live, as when its agent calls delegate_task. */ +const seedLiveParent = (name: string) => + Effect.gen(function* () { + const orchestrator = yield* Orchestrator.OrchestratorV2; + const sink = yield* EventSink.EventSinkV2; + const now = yield* DateTime.now; + const threadId = ThreadId.make(`thread:${name}`); + const runId = RunId.make(`run:${name}`); + const rootNodeId = NodeId.make(`node:${name}:root`); + const providerThreadId = ProviderThreadId.make(`provider-thread:${name}`); + yield* orchestrator.dispatch({ + type: "thread.create", + createdBy: "user", + creationSource: "web", + commandId: CommandId.make(`command:create:${name}`), + threadId, + projectId: ProjectId.make("project:remote-delegated-task"), + title: "Parent", + modelSelection, + runtimeMode: "full-access", + interactionMode: "default", + branch: null, + worktreePath: null, + }); + yield* sink.write({ + commandId: CommandId.make(`command:seed:${name}`), + events: [ + { + id: EventId.make(`event:seed-provider-thread:${name}`), + type: "provider-thread.updated", + threadId, + driver, + providerInstanceId: instanceId, + occurredAt: now, + payload: { + id: providerThreadId, + driver, + providerInstanceId: instanceId, + providerSessionId: null, + appThreadId: threadId, + ownerNodeId: rootNodeId, + nativeThreadRef: { driver, nativeId: `native:${name}`, strength: "strong" }, + nativeConversationHeadRef: null, + status: "active", + firstRunOrdinal: 1, + lastRunOrdinal: 1, + handoffIds: [], + forkedFrom: null, + createdAt: now, + updatedAt: now, + }, + }, + { + id: EventId.make(`event:seed-node:${name}`), + type: "node.updated", + threadId, + runId, + nodeId: rootNodeId, + driver, + providerInstanceId: instanceId, + occurredAt: now, + payload: { + id: rootNodeId, + threadId, + runId, + parentNodeId: null, + rootNodeId, + kind: "root_turn", + status: "running", + countsForRun: true, + providerThreadId, + providerTurnId: null, + nativeItemRef: null, + runtimeRequestId: null, + checkpointScopeId: null, + startedAt: now, + completedAt: null, + }, + }, + { + id: EventId.make(`event:seed-run:${name}`), + type: "run.updated", + threadId, + runId, + nodeId: rootNodeId, + providerInstanceId: instanceId, + occurredAt: now, + payload: { + id: runId, + threadId, + ordinal: 1, + providerInstanceId: instanceId, + modelSelection, + providerThreadId, + userMessageId: MessageId.make(`message:seed-user:${name}`), + rootNodeId, + activeAttemptId: null, + status: "running", + requestedAt: now, + startedAt: now, + completedAt: null, + checkpointId: null, + contextHandoffId: null, + }, + }, + ], + }); + return { threadId, runId, rootNodeId }; + }); + +const remoteChild = { + environmentId: EnvironmentId.make("environment:box"), + threadId: ThreadId.make("thread:on-the-box"), + label: "Box", +}; + +it.layer(layerTest)("a delegated task in a linked environment", (it) => { + it.effect("is recorded on its parent without a child thread here, once", () => + Effect.gen(function* () { + const orchestrator = yield* Orchestrator.OrchestratorV2; + const parent = yield* seedLiveParent("records"); + const request = { + type: "delegated_task.remote.request" as const, + commandId: CommandId.make("command:remote-delegate:records"), + parentThreadId: parent.threadId, + parentRunId: parent.runId, + parentNodeId: parent.rootNodeId, + task: "Run the suite there.", + driver: ProviderDriverKind.make("remote"), + modelSelection, + remoteChild, + completionWake: "always" as const, + }; + yield* orchestrator.dispatch(request); + yield* orchestrator.dispatch(request); + const projection = yield* orchestrator.getThreadProjection(parent.threadId); + assert.equal(projection.subagents.length, 1); + const [task] = projection.subagents; + assert.equal(task?.childThreadId, null); + assert.deepEqual(task?.remoteChild, remoteChild); + assert.equal(task?.status, "running"); + const item = projection.turnItems.find((candidate) => candidate.type === "subagent"); + assert.deepEqual(item?.type === "subagent" ? item.remoteChild : undefined, remoteChild); + // No thread was created here for the child. + assert.equal(yield* orchestrator.getThreadShell(remoteChild.threadId), null); + }), + ); + + it.effect("keeps a newer stop recoverable after an older acknowledgement", () => + Effect.gen(function* () { + const orchestrator = yield* Orchestrator.OrchestratorV2; + const projections = yield* ProjectionStore.ProjectionStoreV2; + const parent = yield* seedLiveParent("stop-generation"); + yield* orchestrator.dispatch({ + type: "delegated_task.remote.request", + commandId: CommandId.make("command:remote-delegate:stop-generation"), + parentThreadId: parent.threadId, + parentRunId: parent.runId, + parentNodeId: parent.rootNodeId, + task: "Run a check.", + driver: ProviderDriverKind.make("remote"), + modelSelection, + remoteChild, + }); + const task = (yield* orchestrator.getThreadProjection(parent.threadId)).subagents[0]!; + const openFor = projections.getOpenRemoteDelegatedTasks.pipe( + Effect.map((open) => open.filter((entry) => entry.parentThreadId === parent.threadId)), + ); + const complete = { + type: "delegated_task.remote.complete" as const, + parentThreadId: parent.threadId, + taskId: task.id, + status: "completed" as const, + result: "Original result.", + }; + yield* orchestrator.dispatch({ + ...complete, + commandId: CommandId.make("command:result:stop-generation"), + stoppedThere: "ran-out", + }); + for (const count of [1, 2]) { + yield* orchestrator.dispatch({ + type: "delegated_task.remote.stop", + parentThreadId: parent.threadId, + taskId: task.id, + commandId: CommandId.make(`command:stop-generation:${count}`), + }); + } + // Reports from before generation tracking cannot clear a later numbered Stop either. + for (const stopCount of [undefined, 1]) { + const rejected = yield* orchestrator + .dispatch({ + ...complete, + commandId: CommandId.make(`command:stale-stop:${stopCount}`), + stoppedThere: "stopped", + ...(stopCount === undefined ? {} : { stopCount }), + }) + .pipe(Effect.flip); + assert.equal(rejected._tag, "OrchestratorDispatchError"); + assert.deepEqual(yield* openFor, [{ parentThreadId: parent.threadId, taskId: task.id }]); + } + yield* orchestrator.dispatch({ + ...complete, + commandId: CommandId.make("command:current-stop:2"), + stoppedThere: "stopped", + stopCount: 2, + }); + const settled = (yield* orchestrator.getThreadProjection(parent.threadId)).subagents[0]!; + assert.equal(settled.result, "Original result."); + assert.equal(settled.status, "completed"); + assert.equal(settled.remoteChild?.stoppedThere, true); + assert.deepEqual(yield* openFor, []); + }), + ); + + it.effect("owes a stop there for a Stop here that loses the race to its result", () => + Effect.gen(function* () { + const orchestrator = yield* Orchestrator.OrchestratorV2; + const projections = yield* ProjectionStore.ProjectionStoreV2; + const parent = yield* seedLiveParent("stop-after-result"); + yield* orchestrator.dispatch({ + type: "delegated_task.remote.request", + commandId: CommandId.make("command:remote-delegate:stop-after-result"), + parentThreadId: parent.threadId, + parentRunId: parent.runId, + parentNodeId: parent.rootNodeId, + task: "Run a check.", + driver: ProviderDriverKind.make("remote"), + modelSelection, + remoteChild, + }); + const task = (yield* orchestrator.getThreadProjection(parent.threadId)).subagents[0]!; + const complete = { + type: "delegated_task.remote.complete" as const, + parentThreadId: parent.threadId, + taskId: task.id, + }; + yield* orchestrator.dispatch({ + ...complete, + commandId: CommandId.make("command:result:stop-after-result"), + status: "completed", + result: "Done there.", + stoppedThere: "ran-out", + }); + // The parent's Stop read the task before its result landed. + yield* orchestrator.dispatch({ + ...complete, + commandId: CommandId.make("command:parent-stop:stop-after-result"), + status: "interrupted", + result: "Stopped with its parent.", + }); + + const stopped = (yield* orchestrator.getThreadProjection(parent.threadId)).subagents[0]!; + assert.equal(stopped.status, "completed"); + assert.equal(stopped.result, "Done there."); + assert.equal(stopped.remoteChild?.stoppedThere, false); + assert.equal(stopped.remoteChild?.stopCount, 1); + const open = yield* projections.getOpenRemoteDelegatedTasks; + assert.deepEqual( + open.filter((entry) => entry.parentThreadId === parent.threadId), + [{ parentThreadId: parent.threadId, taskId: task.id }], + ); + }), + ); + + it.effect("wakes its parent with the result when it completes there", () => + Effect.gen(function* () { + const orchestrator = yield* Orchestrator.OrchestratorV2; + const parent = yield* seedLiveParent("completes"); + const recorded = yield* orchestrator.dispatch({ + type: "delegated_task.remote.request", + commandId: CommandId.make("command:remote-delegate:completes"), + parentThreadId: parent.threadId, + parentRunId: parent.runId, + parentNodeId: parent.rootNodeId, + task: "Run the suite there.", + driver: ProviderDriverKind.make("remote"), + modelSelection, + remoteChild, + completionWake: "always", + }); + const taskEvent = recorded.storedEvents.find( + (stored) => stored.event.type === "subagent.updated", + ); + const taskId = + taskEvent?.event.type === "subagent.updated" ? taskEvent.event.payload.id : undefined; + assert.isDefined(taskId); + // Until it completes, it is open, and a restarted follower picks it up. + const projections = yield* ProjectionStore.ProjectionStoreV2; + const openFor = projections.getOpenRemoteDelegatedTasks.pipe( + Effect.map((open) => open.filter((task) => task.parentThreadId === parent.threadId)), + ); + assert.deepEqual(yield* openFor, [{ parentThreadId: parent.threadId, taskId: taskId! }]); + const offers = yield* Offers; + yield* Ref.set(offers, []); + const complete = (result: string) => + orchestrator.dispatch({ + type: "delegated_task.remote.complete", + commandId: CommandId.make(`command:remote-complete:${result}`), + parentThreadId: parent.threadId, + taskId: taskId!, + status: "completed", + result, + stoppedThere: "ran-out", + }); + yield* complete("All 412 tests pass on the box."); + // A second report is refused, so the first result stands. + const late = yield* complete("A late, different answer.").pipe(Effect.flip); + assert.equal(late._tag, "OrchestratorDispatchError"); + + const projection = yield* orchestrator.getThreadProjection(parent.threadId); + const task = projection.subagents.find((candidate) => candidate.id === taskId); + assert.equal(task?.status, "completed"); + assert.equal(task?.result, "All 412 tests pass on the box."); + // The live parent run claimed it, so task_status acknowledges it as for a local child. + assert.equal(task?.completionDelivery?.state, "claimed"); + // Nothing is left for the follower to pick up after a restart. + assert.deepEqual(yield* openFor, []); + const item = projection.turnItems.find( + (candidate) => candidate.type === "subagent" && candidate.subagentId === taskId, + ); + assert.equal(item?.status, "completed"); + // The parent's live run is offered the delivery, as for a local child. + const delivery = projection.runs.find((run) => run.id === parent.runId)?.delegatedCompletion + ?.delivery; + assert.deepEqual(delivery?.taskIds, [taskId]); + const offered = yield* Ref.get(offers); + assert.equal(offered.length, 1); + assert.equal(offered[0]?.threadId, parent.threadId); + }), + ); +}); diff --git a/apps/server/src/orchestration-v2/ThreadLaunchService.ts b/apps/server/src/orchestration-v2/ThreadLaunchService.ts index fb80b972f7ebe..289df535c12ea 100644 --- a/apps/server/src/orchestration-v2/ThreadLaunchService.ts +++ b/apps/server/src/orchestration-v2/ThreadLaunchService.ts @@ -9,6 +9,8 @@ import { type ModelSelection, type OrchestrationV2Actor, type OrchestrationV2CreationSource, + type OrchestrationV2DelegatedFrom, + type OrchestrationV2LinkOrigin, type OrchestrationV2ProviderThreadNativeMetadata, type OrchestrationV2ThreadProjection, type ProviderDriverKind, @@ -97,8 +99,10 @@ export interface ThreadLaunchInput { }; readonly createdBy: OrchestrationV2Actor; readonly creationSource: OrchestrationV2CreationSource; - // Coder: upstream's `linkOrigin` and `delegatedFrom`, which only a linked environment's - // launch sets, are not carried. + /** The linked environment this launch is for, if one asked for it. */ + readonly linkOrigin?: OrchestrationV2LinkOrigin; + /** The parent there, when that environment's agent delegated this as a task. */ + readonly delegatedFrom?: OrchestrationV2DelegatedFrom; } type PreparationInput = Pick< @@ -914,6 +918,10 @@ const make = Effect.gen(function* () { ...(input.importedNativeThread === undefined ? {} : { importedNativeThread: input.importedNativeThread }), + ...(input.linkOrigin === undefined ? {} : { linkOrigin: input.linkOrigin }), + ...(input.delegatedFrom === undefined + ? {} + : { delegatedFrom: input.delegatedFrom }), createdBy: input.createdBy, creationSource: input.creationSource, }); diff --git a/apps/server/src/orchestration-v2/ThreadManagementService.ts b/apps/server/src/orchestration-v2/ThreadManagementService.ts index e011d441ef8c4..fefee454c0e7e 100644 --- a/apps/server/src/orchestration-v2/ThreadManagementService.ts +++ b/apps/server/src/orchestration-v2/ThreadManagementService.ts @@ -1204,9 +1204,42 @@ const make = Effect.gen(function* () { > = []; const stoppedChildThreadIds = new Set(); for (const task of subagents) { - // Coder: no task runs in a linked environment, so a task without a child here has - // nothing to stop (upstream stops a remote task through its follower). - if (task.origin !== "app_owned" || task.childThreadId === null) continue; + if (task.origin !== "app_owned") continue; + if (task.childThreadId === null) { + // A task in a linked environment ends here; its follower then stops it there. + // One with its result keeps it, but its thread there may run follow-up work. + if (task.remoteChild === undefined) continue; + const commandId = CommandId.make(`${input.commandId}:stop:${task.id}`); + yield* dispatch( + task.result === null + ? { + type: "delegated_task.remote.complete", + commandId, + parentThreadId: input.threadId, + taskId: task.id, + status: "interrupted", + result: + input.reason === undefined + ? "Stopped with its parent." + : `Stopped with its parent: ${input.reason}`, + } + : { + type: "delegated_task.remote.stop", + commandId, + parentThreadId: input.threadId, + taskId: task.id, + }, + ).pipe( + Effect.catch((error) => + Effect.logWarning("Unable to stop a delegated task", { + parentThreadId: input.threadId, + taskId: task.id, + error, + }).pipe(Effect.andThen(Effect.sync(() => failures.push(error)))), + ), + ); + continue; + } const threadId = task.childThreadId; // Follow-up tasks reuse a child thread; walk its subtree only once. if (stoppedChildThreadIds.has(threadId)) continue; diff --git a/apps/server/src/peer/PeerForwarding.ts b/apps/server/src/peer/PeerForwarding.ts new file mode 100644 index 0000000000000..587a19f649986 --- /dev/null +++ b/apps/server/src/peer/PeerForwarding.ts @@ -0,0 +1,277 @@ +import { + type EnvironmentId, + OrchestratorMcpFailure, + type OrchestratorMcpEnvironmentLinksResult, + OrchestratorMcpThreadInterruptInput, + OrchestratorMcpThreadInterruptResult, + OrchestratorMcpThreadReadInput, + OrchestratorMcpThreadReadResult, + OrchestratorMcpThreadWaitInput, + OrchestratorMcpThreadWaitResult, +} from "@t3tools/contracts"; +import * as Context from "effect/Context"; +import * as Crypto from "effect/Crypto"; +import * as DateTime from "effect/DateTime"; +import * as Effect from "effect/Effect"; +import * as Hex from "effect/encoding/Hex"; +import * as Layer from "effect/Layer"; +import * as Schema from "effect/Schema"; +import type * as Tool from "effect/ai/Tool"; + +import { assertNotLinked } from "../mcp/linkOrigin.ts"; +import * as McpInvocationContext from "../mcp/McpInvocationContext.ts"; +import { readCaller, unavailable } from "../mcp/threadAccess.ts"; +import * as ThreadManagement from "../orchestration-v2/ThreadManagementService.ts"; +import * as PeerLinks from "./PeerLinks.ts"; +import * as PeerMcpClient from "./PeerMcpClient.ts"; + +/** + * A peer's `/mcp` holds a wait open for its whole timeout without sending + * anything, and T3 Connect's edge drops a request idle for about 100 s, so a + * forwarded wait goes out in pieces no longer than this. + */ +export const FORWARDED_WAIT_CHUNK_MS = 50_000; +const DEFAULT_WAIT_TIMEOUT_MS = 10 * 60 * 1_000; +const MAX_WAIT_TIMEOUT_MS = 60 * 60 * 1_000; + +type Scope = McpInvocationContext.McpInvocationScope; + +/** + * Runs T3 MCP tools in a linked environment for an agent here. The tool's own + * declaration checks the agent here first; the linked environment then holds + * the call to the link's access, narrowed to the agent's modes, which every + * forwarded call carries. + */ +export class PeerForwarding extends Context.Service< + PeerForwarding, + { + /** + * Runs `tool` in the linked environment `environmentId` with `params`. A + * `t3_thread_wait` goes in pieces short enough to survive any route. + */ + readonly call: ( + scope: Scope, + tool: T, + environmentId: EnvironmentId, + params: Tool.Parameters, + ) => Effect.Effect, OrchestratorMcpFailure>; + /** `t3_thread_read` there. */ + readonly readThread: ( + scope: Scope, + environmentId: EnvironmentId, + input: OrchestratorMcpThreadReadInput, + ) => Effect.Effect; + /** `t3_thread_interrupt` there. */ + readonly interruptThread: ( + scope: Scope, + environmentId: EnvironmentId, + input: OrchestratorMcpThreadInterruptInput, + ) => Effect.Effect; + /** `t3_thread_wait` there, in pieces short enough to survive any route. */ + readonly waitForThread: ( + scope: Scope, + environmentId: EnvironmentId, + input: OrchestratorMcpThreadWaitInput, + ) => Effect.Effect; + /** The environments this one links to, as an agent sees them. */ + readonly links: ( + scope: Scope, + ) => Effect.Effect; + } +>()("t3/peer/PeerForwarding") {} + +/** What an agent hears when it names another machine while the beta is off here. */ +export const linkedEnvironmentsOff = new OrchestratorMcpFailure({ + code: "capability_denied", + message: + "Linked environments is off on this machine, so no tool can act on another machine. Leave out environmentId to work here; the user can turn it on in Settings → Labs.", +}); + +/** The linked environment a call names, or nothing when it names this one. */ +export const remoteTarget = (scope: Scope, environmentId: EnvironmentId | undefined) => + environmentId === scope.environmentId ? undefined : environmentId; + +const make = Effect.gen(function* () { + const peers = yield* PeerMcpClient.PeerMcpClient; + const links = yield* PeerLinks.PeerLinks; + const crypto = yield* Crypto.Crypto; + const threads = yield* ThreadManagement.ThreadManagementService; + + /** + * The caller's own limits, which travel with every forwarded call: the peer sees only the + * link's credential, so a caller that may not control threads here is refused here. Work a + * link started never uses this environment's links, since the peer would see this + * environment's session instead of that link, and its fence could not hold. + */ + const callerLimits = (scope: Scope) => + readCaller().pipe( + Effect.tap((caller) => assertNotLinked(caller, "use this environment's links")), + Effect.map((caller) => caller.limits), + Effect.provideService(McpInvocationContext.McpInvocationContext, scope), + Effect.provideService(ThreadManagement.ThreadManagementService, threads), + ); + + /** + * Every caller here reaches the peer as the one link session, so a retry + * key is scoped to its caller before it leaves: two agents here reusing a + * key never collide there, and one agent retrying gets its first result. + */ + const scopedRequestId = (namespace: string, clientRequestId: string) => + crypto.digest("SHA-256", new TextEncoder().encode(`${namespace}\n${clientRequestId}`)).pipe( + Effect.map((digest) => `fwd:${Hex.encode(digest)}`), + Effect.orDie, + ); + + /** Tool and contract schemas are plain data: they encode and decode without services. */ + const forward = Effect.fn("PeerForwarding.forward")(function* ( + scope: Scope, + toolName: string, + parameters: Schema.Top, + success: Schema.Top, + environmentId: EnvironmentId, + params: unknown, + ) { + const limits = yield* callerLimits(scope); + const encoded = (yield* Schema.encodeUnknownEffect(parameters as Schema.Encoder)( + params, + ).pipe(Effect.mapError(unavailable))) as Record; + const { environmentId: _target, ...args } = encoded; + // A pending upload lives here, so it cannot go with the call. + if (Array.isArray(args.attachments) && args.attachments.length > 0) { + return yield* new OrchestratorMcpFailure({ + code: "invalid_request", + message: "A launch in a linked environment cannot carry attachments yet.", + }); + } + if (typeof args.clientRequestId === "string") { + args.clientRequestId = yield* scopedRequestId(scope.requestNamespace, args.clientRequestId); + } + return yield* peers.call({ + environmentId, + tool: toolName, + arguments: args, + limits, + success: success as Schema.Decoder, + }); + }); + + const readThread: PeerForwarding["Service"]["readThread"] = (scope, environmentId, input) => + forward( + scope, + "t3_thread_read", + OrchestratorMcpThreadReadInput, + OrchestratorMcpThreadReadResult, + environmentId, + input, + ); + + const interruptThread: PeerForwarding["Service"]["interruptThread"] = ( + scope, + environmentId, + input, + ) => + forward( + scope, + "t3_thread_interrupt", + OrchestratorMcpThreadInterruptInput, + OrchestratorMcpThreadInterruptResult, + environmentId, + input, + ); + + const waitForThread: PeerForwarding["Service"]["waitForThread"] = Effect.fn( + "PeerForwarding.waitForThread", + )(function* (scope, environmentId, input) { + let remaining = Math.min( + MAX_WAIT_TIMEOUT_MS, + Math.max(1, input.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS), + ); + let runId = input.runId; + while (true) { + const chunk = Math.min(remaining, FORWARDED_WAIT_CHUNK_MS); + const result = yield* forward( + scope, + "t3_thread_wait", + OrchestratorMcpThreadWaitInput, + OrchestratorMcpThreadWaitResult, + environmentId, + { + threadId: input.threadId, + ...(runId === undefined ? {} : { runId }), + timeoutMs: chunk, + ...(input.untilDelegatedWorkSettled === undefined + ? {} + : { untilDelegatedWorkSettled: input.untilDelegatedWorkSettled }), + }, + ); + remaining -= chunk; + if (!result.timedOut || remaining <= 0) return result; + // Later pieces wait for the run the first one picked, not a newer one. + runId = result.runId ?? undefined; + } + }); + + // While the beta is off, agents start nothing over links. Tasks already running there keep + // following through readThread, waitForThread and interruptThread, so they still finish. + const requireEnabled = links.enabled.pipe( + Effect.flatMap((enabled) => (enabled ? Effect.void : Effect.fail(linkedEnvironmentsOff))), + ); + + const call: PeerForwarding["Service"]["call"] = (scope, tool, environmentId, params) => { + const forwarded: Effect.Effect< + Tool.Success, + OrchestratorMcpFailure + > = tool.name === "t3_thread_wait" + ? (waitForThread( + scope, + environmentId, + params as OrchestratorMcpThreadWaitInput, + ) as Effect.Effect, OrchestratorMcpFailure>) + : forward(scope, tool.name, tool.parametersSchema, tool.successSchema, environmentId, params); + return Effect.andThen(requireEnabled, forwarded); + }; + + /** + * The next step for an agent whose machine is not linked: without it, an + * empty list reads as a dead end and agents go looking elsewhere. + */ + // Coder: the user links workspaces in T3 Coder's workspace Links settings; there is no + // t3_environment_link pairing card. + const NOT_LISTED = + "Not listed: not linked yet. Ask the user to link that workspace in T3 Coder's workspace Links settings."; + + const listLinks: PeerForwarding["Service"]["links"] = Effect.fn("PeerForwarding.listLinks")( + function* (scope) { + yield* callerLimits(scope); + yield* requireEnabled; + const listed = yield* links.list.pipe( + Effect.mapError( + (error) => + new OrchestratorMcpFailure({ code: "orchestration_error", message: error.message }), + ), + ); + return { + environmentId: scope.environmentId, + links: listed.map((link) => ({ + environmentId: link.environmentId, + label: link.label, + status: link.status, + access: link.access, + expiresAt: DateTime.formatIso(link.expiresAt), + lastError: link.lastError, + })), + notListed: NOT_LISTED, + }; + }, + ); + + return PeerForwarding.of({ + call, + readThread, + interruptThread, + waitForThread, + links: listLinks, + }); +}); + +export const layer = Layer.effect(PeerForwarding, make); diff --git a/apps/server/src/peer/PeerLinks.ts b/apps/server/src/peer/PeerLinks.ts new file mode 100644 index 0000000000000..a8e225b406914 --- /dev/null +++ b/apps/server/src/peer/PeerLinks.ts @@ -0,0 +1,84 @@ +/** + * Coder: upstream's PeerLinks pairs with other environments over MCP OAuth and stores their + * session tokens. Here the user sets workspace link rules in T3 Coder's gateway, which knows + * whether each linked workspace is connected; this service reads them through the gateway hub + * (`coderHub.ts`). It keeps upstream's service tag and the members `PeerForwarding` and + * `RemoteDelegation` read, so both stay upstream's. Nothing is stored here. + * + * @module peer/PeerLinks + */ +import { + type EnvironmentId, + type PeerLink, + PeerLinkError, + type PeerLinkSummary, +} from "@t3tools/contracts"; +import * as Context from "effect/Context"; +import * as DateTime from "effect/DateTime"; +import * as Effect from "effect/Effect"; +import * as Layer from "effect/Layer"; +import * as Option from "effect/Option"; + +import type { CoderHubLink } from "@t3tools/coder-cli/rpc"; +import * as CoderHub from "../coderHub.ts"; +import * as ServerSettings from "../serverSettings.ts"; + +/** Link rules do not expire and record no linking time; these stand in for upstream's fields. */ +const LINK_RULE_LINKED_AT = DateTime.makeUnsafe("1970-01-01T00:00:00.000Z"); +const LINK_RULE_EXPIRES_AT = DateTime.makeUnsafe("9999-12-31T00:00:00.000Z"); + +export class PeerLinks extends Context.Service< + PeerLinks, + { + /** Whether the Linked environments beta (Settings → Labs) is on here. */ + readonly enabled: Effect.Effect; + readonly list: Effect.Effect, PeerLinkError>; + /** The link rule to `environmentId`, without asking whether it answers. */ + readonly get: ( + environmentId: EnvironmentId, + ) => Effect.Effect, PeerLinkError>; + } +>()("t3/peer/PeerLinks") {} + +const toSummary = (link: CoderHubLink): PeerLinkSummary => ({ + environmentId: link.environmentId, + label: link.label, + urls: [], + access: link.access, + linkedAt: LINK_RULE_LINKED_AT, + expiresAt: LINK_RULE_EXPIRES_AT, + lastReachedAt: null, + lastError: link.connected ? null : "That workspace is not connected in T3 Coder.", + status: link.connected ? "reachable" : "unreachable", +}); + +const make = Effect.gen(function* () { + const hub = yield* CoderHub.CoderHub; + const serverSettings = yield* ServerSettings.ServerSettingsService; + + const enabled = serverSettings.getSettings.pipe( + Effect.map((settings) => settings.linkedEnvironmentsEnabled), + Effect.orElseSucceed(() => false), + ); + + const list: PeerLinks["Service"]["list"] = hub.listLinks.pipe( + Effect.map((links) => links.map(toSummary)), + Effect.mapError( + (failure) => new PeerLinkError({ reason: "unreachable", message: failure.message }), + ), + ); + + return PeerLinks.of({ + enabled, + list, + get: (environmentId) => + list.pipe( + Effect.map((links) => + Option.fromNullishOr(links.find((link) => link.environmentId === environmentId)), + ), + Effect.map(Option.map(({ status: _status, ...link }): PeerLink => link)), + ), + }); +}); + +export const layer = Layer.effect(PeerLinks, make); diff --git a/apps/server/src/peer/PeerMcpClient.ts b/apps/server/src/peer/PeerMcpClient.ts new file mode 100644 index 0000000000000..03d1674416754 --- /dev/null +++ b/apps/server/src/peer/PeerMcpClient.ts @@ -0,0 +1,79 @@ +/** + * Coder: upstream's PeerMcpClient calls a linked environment's `/mcp` over HTTP with an OAuth + * session. Here the call goes through the gateway hub instead (`coderHub.ts`): the laptop + * gateway runs it on the other workspace's helper as that link's caller, which applies the + * same access and fence. The service tag and `call` are upstream's, so `PeerForwarding` and + * `RemoteDelegation` stay upstream's. + * + * @module peer/PeerMcpClient + */ +import { + type EnvironmentId, + OrchestratorMcpFailure, + type ProviderInteractionMode, + type RuntimeMode, +} from "@t3tools/contracts"; +import * as Context from "effect/Context"; +import * as Effect from "effect/Effect"; +import * as Layer from "effect/Layer"; +import * as Schema from "effect/Schema"; + +import * as CoderHub from "../coderHub.ts"; + +/** The limits a call carries to the peer: the calling agent's modes here. */ +export interface PeerCallLimits { + readonly runtimeMode: RuntimeMode; + readonly interactionMode: ProviderInteractionMode; +} + +/** + * Calls a linked workspace's T3 tools for an agent here. Each call carries the calling + * agent's limits, so the other workspace enforces the narrower of those and the link's access. + */ +export class PeerMcpClient extends Context.Service< + PeerMcpClient, + { + /** Calls `tool` on the peer and decodes its result with `success`. */ + readonly call: >(input: { + readonly environmentId: EnvironmentId; + readonly tool: string; + readonly arguments: Record; + readonly limits: PeerCallLimits; + readonly success: S; + }) => Effect.Effect; + } +>()("t3/peer/PeerMcpClient") {} + +const make = Effect.gen(function* () { + const hub = yield* CoderHub.CoderHub; + + const call: PeerMcpClient["Service"]["call"] = (input) => + hub + .call({ + environmentId: input.environmentId, + tool: input.tool, + arguments: input.arguments, + limits: input.limits, + }) + .pipe( + Effect.flatMap((outcome) => + outcome._tag === "Failure" + ? Effect.fail(outcome.failure) + : Schema.decodeUnknownEffect(input.success)(outcome.value).pipe( + Effect.mapError( + () => + new OrchestratorMcpFailure({ + code: "orchestration_error", + message: + "The linked workspace's answer did not match this version. Reconnect both workspaces so they run the same helper.", + }), + ), + ), + ), + Effect.withSpan("PeerMcpClient.call"), + ); + + return PeerMcpClient.of({ call }); +}); + +export const layer = Layer.effect(PeerMcpClient, make); diff --git a/apps/server/src/peer/RemoteDelegation.ts b/apps/server/src/peer/RemoteDelegation.ts new file mode 100644 index 0000000000000..e789bfb228301 --- /dev/null +++ b/apps/server/src/peer/RemoteDelegation.ts @@ -0,0 +1,802 @@ +import { + CommandId, + type EnvironmentId, + NodeId, + OrchestratorMcpFailure, + type OrchestratorMcpDelegateTaskInput, + type OrchestratorMcpTaskCancelResult, + type OrchestratorMcpThreadTimelineItem, + type OrchestrationV2RemoteTaskChild, + type OrchestrationV2Subagent, + type ProjectId, + type ProviderInstanceId, + ProviderDriverKind, + type RunId, + type ThreadId, +} from "@t3tools/contracts"; +import * as Context from "effect/Context"; +import * as Crypto from "effect/Crypto"; +import * as Duration from "effect/Duration"; +import * as Effect from "effect/Effect"; +import * as Layer from "effect/Layer"; +import * as Option from "effect/Option"; +import * as Schedule from "effect/Schedule"; +import * as Scope from "effect/Scope"; +import * as Stream from "effect/Stream"; +import type * as Tool from "effect/ai/Tool"; + +import type * as McpInvocationContext from "../mcp/McpInvocationContext.ts"; +import { ProjectToolkit } from "../mcp/toolkits/project/tools.ts"; +import { + resolveInteractionMode, + resolveRuntimeMode, + taskPrompt, +} from "../mcp/delegatedTaskModes.ts"; +import * as ProjectionStore from "../orchestration-v2/ProjectionStore.ts"; +import * as ThreadManagement from "../orchestration-v2/ThreadManagementService.ts"; +// Coder: the identity service lives in `coderEnvironment.ts`; `environment/` is not carried. +import * as ServerEnvironment from "../coderEnvironment.ts"; +import * as ProjectService from "../project/ProjectService.ts"; +import * as RepositoryIdentityResolver from "../project/RepositoryIdentityResolver.ts"; +import { forkParked } from "../serverActivation.ts"; +import * as PeerForwarding from "./PeerForwarding.ts"; +import * as PeerLinks from "./PeerLinks.ts"; + +/** How long one follow of a remote task waits on its thread there before checking again. */ +const FOLLOW_WAIT_MS = 10 * 60 * 1_000; +/** A linked environment that stops answering is retried, backing off to this. */ +const FOLLOW_MAX_BACKOFF = Duration.minutes(5); +/** How a follower retries; tests step it by hand. */ +export const FollowRetrySchedule = Context.Reference>( + "t3/peer/RemoteDelegation/FollowRetrySchedule", + { + defaultValue: () => + Schedule.exponential(Duration.seconds(2)).pipe( + Schedule.modifyDelay(({ duration }) => + Effect.succeed(Duration.min(duration, FOLLOW_MAX_BACKOFF)), + ), + ), + }, +); + +type ThreadScope = McpInvocationContext.McpThreadInvocationScope; + +/** + * `delegate_task` to a linked environment. The task's child is an ordinary + * thread there, launched through the link; the parent here records the task + * like a local one, without a child thread, and a follower completes it when + * the thread there ends, so the parent wakes as it would for a local child. + */ +export class RemoteDelegation extends Context.Service< + RemoteDelegation, + { + readonly delegate: ( + scope: ThreadScope, + input: OrchestratorMcpDelegateTaskInput & { + readonly target: NonNullable & { + readonly environmentId: EnvironmentId; + }; + }, + ) => Effect.Effect<{ readonly taskId: NodeId }, OrchestratorMcpFailure>; + /** + * Stops the task's thread there, then completes it here as cancelled. A + * task that already has its result keeps it; its thread there is still + * stopped, as cancelling a local task stops follow-up work on its child. + */ + readonly cancel: ( + scope: ThreadScope, + task: OrchestrationV2Subagent, + input: { + readonly reason?: string | undefined; + readonly clientRequestId?: string | undefined; + }, + ) => Effect.Effect; + /** + * Follows every open remote task until it ends, including after a + * restart, and a finished one again when a Stop here owes it a stop there. + */ + readonly start: () => Effect.Effect; + } +>()("t3/peer/RemoteDelegation") {} + +/** The other side refused because the thread there runs above this caller's modes. */ +const isModeRefusal = (error: OrchestratorMcpFailure) => + error.code === "runtime_mode_escalation_denied" || + error.code === "interaction_mode_escalation_denied"; + +/** + * Refusals that following again cannot change: the link was revoked, expired + * or forgotten, or the thread or run there is gone. Anything else (the other + * machine asleep, a dropped route) is worth retrying. + */ +const isFinal = (error: OrchestratorMcpFailure) => + error.code === "capability_denied" || + error.code === "thread_not_found" || + error.code === "run_not_found"; + +const make = Effect.gen(function* () { + const followRetry = yield* FollowRetrySchedule; + const forwarding = yield* PeerForwarding.PeerForwarding; + const links = yield* PeerLinks.PeerLinks; + const threads = yield* ThreadManagement.ThreadManagementService; + const projections = yield* ProjectionStore.ProjectionStoreV2; + const projects = yield* ProjectService.ProjectService; + const repositoryIdentities = yield* RepositoryIdentityResolver.RepositoryIdentityResolver; + const crypto = yield* Crypto.Crypto; + const hereId = yield* ServerEnvironment.ServerEnvironmentIdentity.pipe( + Effect.flatMap((environment) => environment.getEnvironmentId), + ); + // Followers live as long as this service, so shutting down stops them. + const followers = yield* Scope.Scope; + + // One follower runs per open task and holds what it read across a wait of + // up to FOLLOW_WAIT_MS, so it reads its own task, never the parent's whole + // task list: a parent with thousands of tasks made every restart decode + // that list once per open task at the same time and ran out of heap. + const readTask = (parentThreadId: ThreadId, taskId: NodeId) => + threads + .getThreadRecords(parentThreadId, ["subagents"], { subagentIds: [taskId] }) + .pipe(Effect.map(({ thread, subagents }) => ({ thread, task: subagents[0] }))); + + /** The peer's project with this thread's repository, or the one the caller named. */ + const resolveRemoteProject = Effect.fn("RemoteDelegation.resolveRemoteProject")(function* ( + scope: ThreadScope, + environmentId: EnvironmentId, + parentProjectId: ProjectId, + requested: ProjectId | undefined, + ) { + if (requested !== undefined) return requested; + const here = yield* projects.getById(parentProjectId).pipe( + Effect.map(Option.getOrUndefined), + Effect.orElseSucceed(() => undefined), + ); + // The project's own identity is a one-minute cache that reads blank when + // cold, so resolve it here, as the other side's t3_project_list does. + const key = + here === undefined + ? undefined + : (yield* repositoryIdentities.resolve(here.workspaceRoot))?.canonicalKey; + if (key === undefined) { + return yield* new OrchestratorMcpFailure({ + code: "target_required", + message: "Pass target.projectId: this thread's project has no repository to match there.", + }); + } + const matches: Array<{ readonly id: ProjectId; readonly title: string }> = []; + let cursor: number | null = 0; + while (cursor !== null) { + const listed: Tool.Success = + yield* forwarding.call(scope, ProjectToolkit.tools.t3_project_list, environmentId, { + cursor, + limit: 100, + }); + matches.push( + ...listed.projects.filter((project) => project.repositoryIdentity?.canonicalKey === key), + ); + cursor = listed.nextCursor; + } + if (matches.length === 1) return matches[0]!.id; + return yield* new OrchestratorMcpFailure({ + code: "invalid_request", + message: + matches.length === 0 + ? `No project there has this repository (${key}). Pass target.projectId; t3_project_list with this environmentId lists them. To bring the repository there, use t3_project_clone and then t3_project_create with this environmentId.` + : `Several projects there have this repository: ${matches.map((project) => `${project.title} (${project.id})`).join(", ")}. Pass target.projectId.`, + }); + }); + + const delegate: RemoteDelegation["Service"]["delegate"] = Effect.fn("RemoteDelegation.delegate")( + function* (scope, input) { + const parent = yield* threads.getThreadRecords(scope.thread.threadId, ["runs"]).pipe( + Effect.mapError( + () => + new OrchestratorMcpFailure({ + code: "thread_not_found", + message: "The calling thread was not found.", + }), + ), + ); + const parentRun = parent.runs + .filter(ThreadManagement.isActiveRun) + .toSorted((left, right) => right.ordinal - left.ordinal)[0]; + if ( + parentRun === undefined || + parentRun.rootNodeId === null || + parentRun.providerInstanceId !== scope.thread.providerInstanceId + ) { + return yield* new OrchestratorMcpFailure({ + code: "parent_not_active", + message: "Delegated tasks require an active run owned by this MCP provider session.", + }); + } + const parentNodeId = parentRun.rootNodeId; + const { target } = input; + // A worktree there would branch from a commit this checkout has and the + // other may not, so a remote task runs in that project's checkout. + if (input.isolation === "worktree") { + return yield* new OrchestratorMcpFailure({ + code: "invalid_request", + message: + 'A task in a linked environment runs in that project\'s checkout; isolation "worktree" is not supported there. Omit isolation, or use t3_thread_launch with environmentId and a worktree workspaceStrategy.', + }); + } + // The provider and model inherit as they do for a task here. Another + // provider there has no model to inherit, so the caller names one. + const inherited = parent.thread.modelSelection; + const instanceId = target.providerInstanceId ?? inherited.instanceId; + const model = + target.model ?? (instanceId === inherited.instanceId ? inherited.model : undefined); + if (model === undefined) { + return yield* new OrchestratorMcpFailure({ + code: "target_required", + message: "Pass target.model from orchestrator_capabilities with this environmentId.", + }); + } + const options = + target.options ?? + (instanceId === inherited.instanceId && model === inherited.model + ? inherited.options + : undefined); + // Modes asked for are checked against this thread. Omitted ones are left + // to the other side, which inherits this thread's modes capped by the + // link's access, so a narrower link still takes the task. + const runtimeMode = + input.runtimeMode === undefined || input.runtimeMode === "inherit" + ? undefined + : yield* resolveRuntimeMode(parent.thread.runtimeMode, input.runtimeMode); + const interactionMode = + input.interactionMode === undefined || input.interactionMode === "inherit" + ? undefined + : yield* resolveInteractionMode(parent.thread.interactionMode, input.interactionMode); + const projectId = yield* resolveRemoteProject( + scope, + target.environmentId, + parent.thread.projectId, + target.projectId, + ); + // One key for the launch there and the record here, so a retry finds both. + // Both are scoped to the provider session, as every key a caller passes is: + // the forwarder scopes the launch's, and the record's names it. + const key = input.clientRequestId ?? (yield* crypto.randomUUIDv4().pipe(Effect.orDie)); + const task = taskPrompt(input); + const launched = yield* forwarding.call( + scope, + ProjectToolkit.tools.t3_thread_launch, + target.environmentId, + { + projectId, + title: input.title ?? parent.thread.title, + modelSelection: { instanceId, model, ...(options === undefined ? {} : { options }) }, + ...(runtimeMode === undefined ? {} : { runtimeMode }), + ...(interactionMode === undefined ? {} : { interactionMode }), + message: task, + clientRequestId: `delegate:${scope.thread.threadId}:${key}`, + // The thread there shows it is this thread's subagent, with a way back. + delegatedFrom: { + environmentId: hereId, + threadId: parent.thread.id, + title: parent.thread.title, + }, + }, + ); + const link = yield* links.get(target.environmentId).pipe( + Effect.map(Option.getOrUndefined), + Effect.orElseSucceed(() => undefined), + ); + const commandId = CommandId.make( + `command:mcp:${encodeURIComponent(scope.requestNamespace)}:remote-delegate:${encodeURIComponent(key)}`, + ); + const remoteChild: OrchestrationV2RemoteTaskChild = { + environmentId: target.environmentId, + threadId: launched.threadId, + label: link?.label ?? target.environmentId, + ...(launched.runId === null ? {} : { runId: launched.runId }), + }; + const recorded = yield* threads + .dispatch({ + type: "delegated_task.remote.request", + commandId, + parentThreadId: scope.thread.threadId, + parentRunId: parentRun.id, + parentNodeId, + task, + ...(input.title === undefined ? {} : { title: input.title }), + // The driver runs there; this side only labels the task with it. + driver: ProviderDriverKind.make("remote"), + modelSelection: launched.modelSelection, + remoteChild, + completionWake: input.mode === "wait" ? "settled_only" : "always", + }) + .pipe( + // The cause goes to the log; the caller learns only that recording failed. + Effect.tapError((cause) => + Effect.logWarning("remote-delegation.record-failed", { + parentThreadId: scope.thread.threadId, + cause, + }), + ), + Effect.mapError( + () => + new OrchestratorMcpFailure({ + code: "orchestration_error", + message: "Unable to record the delegated task.", + }), + ), + // Nothing here follows a thread the task was never recorded for, so stop it there. + // A crash between the launch and this record still leaves it running there + // until a retry with the same clientRequestId records it. + Effect.tapError(() => + stopThere(followScope(scope.thread, remoteChild), remoteChild, "stop").pipe( + Effect.ignoreCause({ log: true }), + ), + ), + ); + const taskEvent = recorded.storedEvents.find( + (stored) => stored.event.type === "subagent.updated", + ); + const taskId = + taskEvent?.event.type === "subagent.updated" + ? taskEvent.event.payload.id + : // A replayed request recorded the task the first time. + yield* threads.getThreadRecords(scope.thread.threadId, ["subagents"]).pipe( + Effect.map( + ({ subagents }) => + subagents.find((task) => task.remoteChild?.threadId === launched.threadId)?.id, + ), + Effect.orElseSucceed(() => undefined), + ); + if (taskId === undefined) { + return yield* new OrchestratorMcpFailure({ + code: "orchestration_error", + message: "The delegated task was not recorded.", + }); + } + yield* followOne(scope.thread.threadId, taskId).pipe(Effect.forkIn(followers)); + return { taskId }; + }, + ); + + /** + * Completes `task` here with its thread there's final state. Each attempt is its own + * command, so a failed one never blocks the next; a report refused because the task already + * has its result (a cancel, a Stop or an earlier report) is done. `stoppedThere` records that + * nothing is left to stop there, even on a task that already has its result. + */ + const complete = Effect.fn("RemoteDelegation.complete")(function* ( + parentThreadId: ThreadId, + taskId: NodeId, + status: "completed" | "failed" | "cancelled" | "interrupted", + result: string, + stoppedThere: "ran-out" | "stopped" | undefined, + stopCount?: number, + ) { + const attempt = yield* crypto.randomUUIDv4().pipe(Effect.orDie); + yield* threads + .dispatch({ + type: "delegated_task.remote.complete", + commandId: CommandId.make(`command:remote-task-complete:${taskId}:${attempt}`), + parentThreadId, + taskId, + status, + result, + ...(stoppedThere === undefined ? {} : { stoppedThere }), + ...(stopCount === undefined ? {} : { stopCount }), + }) + .pipe( + Effect.catch((error) => + readTask(parentThreadId, taskId).pipe( + Effect.flatMap(({ task }) => (task?.result != null ? Effect.void : Effect.fail(error))), + ), + ), + ); + }); + + /** + * How this environment reaches a task's thread there: as the parent + * thread, under one namespace per parent, so a stop sent again after a + * restart or a dropped route is recorded there once. + */ + const followScope = ( + parent: { readonly threadId: ThreadId; readonly providerInstanceId: ProviderInstanceId }, + remote: OrchestrationV2RemoteTaskChild, + ): ThreadScope => ({ + environmentId: hereId, + requestNamespace: `remote-task:${parent.threadId}`, + thread: { + threadId: parent.threadId, + providerSessionId: `remote-task:${remote.threadId}`, + providerInstanceId: parent.providerInstanceId, + }, + client: undefined, + capabilities: new Set(["orchestration"]), + issuedAt: 0, + }); + + /** + * Stops the task's own thread there as its Stop button does: its running turn, queued + * messages, pull request watches and delegated tasks. `key` names the stop (the follower + * sends one, each cancel its own), and each is recorded there once however often it is sent. + */ + const stopThere = ( + scope: ThreadScope, + remote: OrchestrationV2RemoteTaskChild, + key: string, + reason?: string, + ) => + forwarding + .interruptThread(scope, remote.environmentId, { + threadId: remote.threadId, + stop: true, + ...(reason === undefined ? {} : { reason }), + clientRequestId: `${key}:${remote.threadId}`, + }) + .pipe(Effect.asVoid); + + /** + * The last reply `runId` gave on the task's thread there, which is its + * result, read whole however long it is. A failed run prefers its error + * from the activity view over an earlier reply, without taking another run's. + */ + const lastReply = Effect.fn("RemoteDelegation.lastReply")(function* ( + scope: ThreadScope, + remote: OrchestrationV2RemoteTaskChild, + runId: RunId | null, + failed = false, + ) { + let reply: OrchestratorMcpThreadTimelineItem | undefined; + let error: OrchestratorMcpThreadTimelineItem | undefined; + let afterPosition: number | undefined; + while (true) { + const read = yield* forwarding.readThread(scope, remote.environmentId, { + threadId: remote.threadId, + view: failed ? "activity" : "messages", + limit: 100, + ...(afterPosition === undefined ? {} : { afterPosition }), + }); + reply = + read.items.findLast( + (item) => item.type === "assistant_message" && (runId === null || item.runId === runId), + ) ?? reply; + if (failed) { + error = + read.items.findLast( + (item) => item.type === "error" && (runId === null || item.runId === runId), + ) ?? error; + } + if (!read.hasMore || read.nextPosition === null) break; + afterPosition = read.nextPosition; + } + reply = error ?? reply; + if (reply === undefined) return undefined; + let text = reply.text ?? ""; + let textOffset = reply.textTruncated ? (reply.nextTextOffset ?? null) : null; + while (textOffset !== null) { + const rest = yield* forwarding.readThread(scope, remote.environmentId, { + threadId: remote.threadId, + itemId: reply.itemId, + textOffset, + maxCharsPerItem: 50_000, + }); + const part = rest.items[0]; + if (part === undefined) break; + text += part.text ?? ""; + textOffset = part.textTruncated ? (part.nextTextOffset ?? null) : null; + } + return text; + }); + + /** + * Why following a task can never succeed, if that is what `error` means. + * The far side's message already says what was refused and what to do; a + * link forgotten here only reads as a bad request, so it is named. + */ + const finalReason = Effect.fn("RemoteDelegation.finalReason")( + function* (parentThreadId: ThreadId, taskId: NodeId, error: OrchestratorMcpFailure) { + if (isFinal(error)) return error.message; + if (error.code !== "invalid_request") return undefined; + const { task } = yield* readTask(parentThreadId, taskId); + const environmentId = task?.remoteChild?.environmentId; + if (environmentId === undefined) return error.message; + const link = yield* links.get(environmentId); + return Option.isSome(link) ? undefined : error.message; + }, + Effect.orElseSucceed(() => undefined), + ); + + /** A task's thread there that ended without a reply. */ + const noReply = "(The thread in the linked environment ended without a reply.)"; + + /** + * Waits for the task's run there to end, completes the task here, and stops it there if it + * ended here first. A revoked, expired or forgotten link, or a thread or run gone there, + * fails the task with nothing left to stop; anything else (the other machine asleep, a + * dropped route) is retried with back-off, and so is completing. + */ + const follow = (parentThreadId: ThreadId, taskId: NodeId): Effect.Effect => + followOnce(parentThreadId, taskId).pipe( + // `false` means it is still running there: follow again straight away. + Effect.repeat({ while: (done) => !done }), + Effect.catchTags({ + OrchestratorMcpFailure: Effect.fn("RemoteDelegation.followFailed")(function* (error) { + const reason = yield* finalReason(parentThreadId, taskId, error); + if (reason === undefined) return yield* error; + // Gone there, or no link to reach it by: nothing left to stop there. + const { task } = yield* readTask(parentThreadId, taskId); + const stopCount = task?.remoteChild?.stopCount; + yield* complete(parentThreadId, taskId, "failed", reason, "stopped", stopCount); + }), + }), + Effect.retry(followRetry), + Effect.ignoreCause({ log: true }), + ); + + /** + * One wait on the task's thread there; true once the task here is done. + * A task completed here first (cancelled, or its parent stopped) is + * stopped there, and done once that stop is recorded here. + */ + const followOnce = Effect.fn("RemoteDelegation.followOnce")(function* ( + parentThreadId: ThreadId, + taskId: NodeId, + ) { + const sequence = yield* threads.getThreadEventSequence(parentThreadId); + const { thread, task } = yield* readTask(parentThreadId, taskId); + if (task?.remoteChild === undefined) return true; + const remote = task.remoteChild; + const scope = followScope( + { threadId: parentThreadId, providerInstanceId: thread.providerInstanceId }, + remote, + ); + // Ended here, maybe while this follower backed off from an unreachable + // machine or before a restart: it still has to be stopped there. So + // does one its parent here was stopped after, for what followed there. + if (task.result !== null) { + if ( + remote.stoppedThere === false || + ((task.status === "cancelled" || task.status === "interrupted") && + remote.stoppedThere !== true) + ) { + const key = remote.stopCount === undefined ? "stop" : `stop-${remote.stopCount}`; + yield* stopThere(scope, remote, key).pipe( + // Its thread there now runs above what this side may touch, say + // because the parent here was lowered since; no retry changes that. + Effect.catchIf(isModeRefusal, (error) => + Effect.logWarning("A linked environment refused to stop a delegated task", { + taskId, + reason: error.message, + }), + ), + ); + yield* complete( + parentThreadId, + taskId, + terminalStatus(task.status), + task.result, + "stopped", + remote.stopCount, + ); + return yield* settled(parentThreadId, taskId); + } + return true; + } + const endedHere = threads + .streamStoredEventsFrom({ + threadId: parentThreadId, + afterSequence: sequence, + eventType: "subagent.updated", + }) + .pipe( + Stream.filter( + (stored) => + stored.event.type === "subagent.updated" && + stored.event.payload.id === taskId && + stored.event.payload.result !== null, + ), + Stream.runHead, + Effect.flatMap((ended) => + Option.isSome(ended) ? Effect.succeed({ endedHere: true } as const) : Effect.never, + ), + ); + const waited = yield* forwarding + .waitForThread(scope, remote.environmentId, { + threadId: remote.threadId, + ...(remote.runId === undefined ? {} : { runId: remote.runId }), + timeoutMs: FOLLOW_WAIT_MS, + // A thread there whose run ended may still be waiting on its own + // tasks to wake it for the answer, which a task here waits for too. + // An older peer ignores this and reports the run alone. + untilDelegatedWorkSettled: true, + }) + .pipe(Effect.raceFirst(endedHere)); + // The next look reads the result and stops it there. + if ("endedHere" in waited) return false; + if (waited.timedOut) return false; + // A task recorded without its run waits on the thread's latest; a + // thread there with none has nothing left to wait for. + if (waited.runId === null) { + const reply = yield* lastReply(scope, remote, null); + yield* complete( + parentThreadId, + taskId, + reply === undefined ? "failed" : "completed", + reply ?? "The thread in the linked environment has no run to follow.", + "ran-out", + ); + return yield* settled(parentThreadId, taskId); + } + if (!isTerminal(waited.status)) return false; + const resultRun = waited.resultRun ?? { + runId: remote.runId ?? waited.runId, + status: waited.status, + }; + const result = yield* lastReply(scope, remote, resultRun.runId, resultRun.status === "failed"); + yield* complete( + parentThreadId, + taskId, + terminalStatus(resultRun.status), + result ?? noReply, + "ran-out", + ); + return yield* settled(parentThreadId, taskId); + }); + + /** + * Whether the task is done here after the follower reported its run ran + * out there. A cancel or Stop that landed while the reply was read keeps + * its result, and still owes a stop there for what may follow the run; + * the next look sends it. + */ + const settled = (parentThreadId: ThreadId, taskId: NodeId) => + readTask(parentThreadId, taskId).pipe( + Effect.map(({ task }) => task?.remoteChild?.stoppedThere === true), + ); + + const following = new Map(); + + /** + * `follow`, at most once per task. Asked again while it runs, say by a + * Stop here on a task that already has its result, it looks once more + * before it ends, so that stop is not missed. + */ + const followOne = (parentThreadId: ThreadId, taskId: NodeId) => + Effect.suspend(() => { + const running = following.get(taskId); + if (running !== undefined) { + running.again = true; + return Effect.void; + } + const state = { again: false }; + following.set(taskId, state); + return follow(parentThreadId, taskId).pipe( + // Checked and released in one step, so a request between them is never lost. + Effect.repeat({ + while: () => { + if (state.again) { + state.again = false; + return true; + } + following.delete(taskId); + return false; + }, + }), + Effect.ensuring( + Effect.sync(() => { + if (following.get(taskId) === state) following.delete(taskId); + }), + ), + ); + }); + + const cancel: RemoteDelegation["Service"]["cancel"] = Effect.fn("RemoteDelegation.cancel")( + function* (scope, task, input) { + const remote = task.remoteChild; + if (remote === undefined) { + return yield* new OrchestratorMcpFailure({ + code: "task_not_found", + message: `Delegated task ${task.id} is not remote.`, + }); + } + const { reason } = input; + const there = followScope(scope.thread, remote); + // A later cancel stops what started there since; a retry of this one, nothing new. + const key = `cancel:${encodeURIComponent(scope.requestNamespace)}:${ + input.clientRequestId ?? (yield* crypto.randomUUIDv4().pipe(Effect.orDie)) + }`; + if (task.result !== null) { + // Best effort: the result stands whether or not the stop gets there. + yield* stopThere(there, remote, key, reason).pipe( + Effect.andThen( + complete( + task.threadId, + task.id, + terminalStatus(task.status), + task.result, + "stopped", + remote.stopCount, + ), + ), + Effect.ignoreCause({ log: true }), + ); + return { + taskId: task.id, + status: + task.status === "completed" || task.status === "failed" || task.status === "interrupted" + ? task.status + : "cancelled", + } satisfies OrchestratorMcpTaskCancelResult; + } + // A link that is gone or a machine that is down still cancels the task + // here; its follower keeps trying to stop it there, across restarts. + const unstopped = yield* stopThere(there, remote, key, reason).pipe( + Effect.as(undefined), + Effect.catch((error) => Effect.succeed(error.message)), + ); + const cancelled = reason === undefined ? "Cancelled." : `Cancelled: ${reason}`; + yield* complete( + task.threadId, + task.id, + "cancelled", + unstopped === undefined + ? cancelled + : `${cancelled} It could not be stopped in ${remote.label} and may still run there: ${unstopped}`, + unstopped === undefined ? "stopped" : undefined, + remote.stopCount, + ).pipe( + Effect.tapError((cause) => + Effect.logWarning("remote-delegation.cancel-record-failed", { taskId: task.id, cause }), + ), + Effect.mapError( + () => + new OrchestratorMcpFailure({ + code: "orchestration_error", + message: "Unable to record the cancellation.", + }), + ), + ); + return { + taskId: task.id, + status: "cancel_requested", + } satisfies OrchestratorMcpTaskCancelResult; + }, + ); + + const start: RemoteDelegation["Service"]["start"] = () => + forkParked( + Effect.gen(function* () { + // A finished task's follower has ended, so a Stop here that owes its + // thread there a stop starts it again. Started before the scan below; + // a Stop that slips between the two stays owed for the next start. + yield* Stream.runForEach(threads.streamDomainEvents, (event) => + event.type === "subagent.updated" && event.payload.remoteChild?.stoppedThere === false + ? followOne(event.threadId, event.payload.id).pipe(Effect.forkIn(followers)) + : Effect.void, + ).pipe( + Effect.ignoreCause({ log: true }), + Effect.forkIn(followers, { startImmediately: true }), + ); + const open = yield* projections.getOpenRemoteDelegatedTasks; + yield* Effect.forEach( + open, + ({ parentThreadId, taskId }) => followOne(parentThreadId, taskId), + { + concurrency: "unbounded", + discard: true, + }, + ); + }).pipe(Effect.ignoreCause({ log: true })), + ); + + return RemoteDelegation.of({ delegate, cancel, start }); +}); + +const isTerminal = (status: string) => + status === "completed" || + status === "failed" || + status === "cancelled" || + status === "interrupted" || + status === "rolled_back"; + +const terminalStatus = (status: string): "completed" | "failed" | "cancelled" | "interrupted" => + status === "completed" || status === "failed" || status === "interrupted" ? status : "cancelled"; + +export const layer = Layer.effect(RemoteDelegation, make); diff --git a/apps/server/src/project/ProjectSetupScriptRunner.test.ts b/apps/server/src/project/ProjectSetupScriptRunner.test.ts index c295a06ac39ac..29a15a6f0715b 100644 --- a/apps/server/src/project/ProjectSetupScriptRunner.test.ts +++ b/apps/server/src/project/ProjectSetupScriptRunner.test.ts @@ -11,6 +11,7 @@ import { TestClock } from "effect/testing"; import * as ServerSettings from "../serverSettings.ts"; import * as TerminalManager from "../terminal/Manager.ts"; +import * as ProjectionStore from "../orchestration-v2/ProjectionStore.ts"; import * as ProjectService from "./ProjectService.ts"; import * as ProjectSetupScriptRunner from "./ProjectSetupScriptRunner.ts"; @@ -58,6 +59,9 @@ const makeHarness = Effect.fn(function* (options: { Layer.mergeAll( terminals, Layer.mock(ProjectService.ProjectService)({}), + Layer.mock(ProjectionStore.ProjectionStoreV2)({ + getThreadShell: () => Effect.succeed(null), + }), ServerSettings.layerTest(), NodeCrypto.layer, ), diff --git a/apps/server/src/project/ProjectSetupScriptRunner.ts b/apps/server/src/project/ProjectSetupScriptRunner.ts index 25a2d57392cb8..095f20938c8b0 100644 --- a/apps/server/src/project/ProjectSetupScriptRunner.ts +++ b/apps/server/src/project/ProjectSetupScriptRunner.ts @@ -1,4 +1,4 @@ -import { ProjectId, type ProjectScript } from "@t3tools/contracts"; +import { linkOriginIsFenced, ProjectId, type ProjectScript, ThreadId } from "@t3tools/contracts"; import * as HostProcess from "@t3tools/shared/HostProcess"; import { projectScriptRuntimeEnv, @@ -17,6 +17,7 @@ import * as Layer from "effect/Layer"; import * as Option from "effect/Option"; import * as Schema from "effect/Schema"; +import * as ProjectionStore from "../orchestration-v2/ProjectionStore.ts"; import * as ServerSettings from "../serverSettings.ts"; import * as TerminalManager from "../terminal/Manager.ts"; import * as ProjectService from "./ProjectService.ts"; @@ -46,10 +47,18 @@ export interface ProjectSetupScriptOutputLine { readonly line: string; } -// Coder: upstream's `skipped-for-link` result, for threads a fenced peer link started, is not -// carried; peer links are not. +/** + * A thread a link below full access started does not run this project's setup + * script: the script is the user's own code, and such a link only grants T3's + * tools (see `mcp/linkOrigin.ts`). + */ +export interface ProjectSetupScriptRunnerResultSkippedForLink { + readonly status: "skipped-for-link"; +} + export type ProjectSetupScriptRunnerResult = | ProjectSetupScriptRunnerResultNoScript + | ProjectSetupScriptRunnerResultSkippedForLink | ProjectSetupScriptRunnerResultStarted; export interface ProjectSetupScriptRunnerInput { @@ -75,7 +84,7 @@ export class ProjectSetupScriptOperationError extends Schema.TaggedError + new ProjectSetupScriptOperationError({ + ...errorContext, + operation: "readThread", + cause, + }), + ), + ); + if (thread?.linkOrigin !== undefined && linkOriginIsFenced(thread.linkOrigin)) + return { status: "skipped-for-link" } as const; const suppliedProject = input.project; const projectById = suppliedProject ?? diff --git a/knip.jsonc b/knip.jsonc index 87fd7c6a4a011..05b350aec50c3 100644 --- a/knip.jsonc +++ b/knip.jsonc @@ -50,6 +50,8 @@ "nsExports", ], "apps/server/src/os-jank.ts": ["exports", "nsExports"], + "apps/server/src/peer/PeerForwarding.ts": ["exports", "nsExports"], + "apps/server/src/peer/RemoteDelegation.ts": ["exports", "nsExports"], "apps/server/src/project/RepositoryIdentityResolver.ts": ["exports", "nsExports"], "apps/server/src/provider/CodexProvider.ts": ["exports", "nsExports"], "apps/server/src/scheduledTasks/ScheduledTaskService.ts": ["exports", "nsExports"], diff --git a/packages/client-runtime/src/t3ToolSummary.ts b/packages/client-runtime/src/t3ToolSummary.ts index 3d420f5f0da8f..037d1a7a59929 100644 --- a/packages/client-runtime/src/t3ToolSummary.ts +++ b/packages/client-runtime/src/t3ToolSummary.ts @@ -336,6 +336,9 @@ export function summarizeT3ToolCalls( case "environment-update": label = phrase("Updated", "update", `environment preferences ${times}`); break; + case "environment-links": + label = phrase("Listed", "list", `linked environments ${times}`); + break; case "attachment-prepare": label = phrase( "Prepared", diff --git a/packages/provider-core/src/server/orchestrationInstructions.ts b/packages/provider-core/src/server/orchestrationInstructions.ts index 8914c1798086e..d32f74c40cdda 100644 --- a/packages/provider-core/src/server/orchestrationInstructions.ts +++ b/packages/provider-core/src/server/orchestrationInstructions.ts @@ -1,7 +1,7 @@ import type { ProviderInteractionMode } from "@t3tools/contracts"; -// Coder: the linked-machine lines (`t3_environment_links`, `t3_environment_link`) are not -// carried, since peer links are not. +// Coder: a workspace not linked is linked by the user in T3 Coder's workspace Links settings; +// there is no `t3_environment_link` pairing card. // Codex truncates entries over 4,000 bytes; keep each section self-contained and below that limit. export const T3_CODE_ORCHESTRATION_SECTIONS: ReadonlyArray = [ `## T3 Code orchestration @@ -15,7 +15,9 @@ Ordinary coding tasks need no T3 tools. - If you are a subagent or child, do the work yourself. Start no subagents unless your task says to.`, `- \`t3_thread_launch\` and \`create_threads\` make new top-level threads, only when the user asks for a new thread. "Subagent", "delegate", and "parallel" never mean one. Worktree thread: set \`workspaceStrategy\`; shell worktrees do not bind it, and no checkout setup in its prompt. No \`workspaceStrategy\`: project root, not your worktree. - Given a thread id, \`t3_thread_read\` it before you answer about it. -- In your reply, a thread's first mention is its \`link\` verbatim. No \`link\`: \`[title](t3-thread://v1/)\`. Never a plain title or bare id. +- Another machine: \`t3_environment_links\` lists linked ones. Pass its \`environmentId\` to a T3 tool to act there. Ids are then that machine's, so pass \`threadId\`. +- A machine the user names that is not linked: tell them to link its workspace in T3 Coder's workspace Links settings. +- In your reply, a thread's first mention is its \`link\` verbatim. No \`link\`: \`[title](t3-thread://v1/)\`. Never a plain title or bare id. A thread on a linked machine: its title and machine, not its link. - A secret: call \`request_secret\` yourself. Pass its \`secretRef\` to a T3 tool, or use \`delivery: "file"\` for a shell command. Never ask in chat or invent one. When asked only to schedule, \`schedule_task\` without running its prompt. - T3 tools may load late. Try the name once before you call it absent.`, `### Visuals and preview diff --git a/packages/shared/src/t3McpToolPresentation.ts b/packages/shared/src/t3McpToolPresentation.ts index 474d991f84518..33afbe3b11b17 100644 --- a/packages/shared/src/t3McpToolPresentation.ts +++ b/packages/shared/src/t3McpToolPresentation.ts @@ -51,6 +51,7 @@ export type T3McpToolSummaryAction = | "project-delete" | "project-clone" | "environment-read" + | "environment-links" | "environment-update" | "attachment-prepare" | "attachment-discard" @@ -321,8 +322,12 @@ const T3_MCP_TOOLS: Readonly> = { ["Read", "Reading", "Read", "environment preferences"], "environment-read", ), - // Coder: no t3_environment_links, t3_environment_link, or t3_environment_unlink; linked - // environments are not carried. + t3_environment_links: tool( + ["List", "Listing", "Listed", "linked environments"], + "environment-links", + ), + // Coder: no t3_environment_link or t3_environment_unlink; the user sets workspace link + // rules in T3 Coder instead of pairing. t3_environment_preferences_update: tool( ["Update", "Updating", "Updated", "environment preferences"], "environment-update", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 3522b72138334..9aef92d50446f 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -334,6 +334,9 @@ importers: '@ff-labs/fff-node': specifier: 0.11.0 version: 0.11.0(patch_hash=765c192f75289d2a65d54011f65e3c9397603298eefb7203e7e05260352e47c8) + '@t3tools/coder-cli': + specifier: workspace:* + version: link:../../packages/coder-cli '@t3tools/provider-acp': specifier: workspace:* version: link:../../packages/provider-acp From fbbc0a67aa8010ce1e53ec40f5106f6f3a11946b Mon Sep 17 00:00:00 2001 From: Henry Chu Date: Wed, 28 Oct 2026 07:57:01 -0400 Subject: [PATCH 3/4] Add Linked workspaces settings and restore the Labs switch Connections gains a Linked workspaces section that edits the gateway's link rules; removing a workspace drops its rules. Labs' Beta section carries upstream's Linked environments switch (still no guest links). Co-Authored-By: Claude Opus 5.5 --- apps/web/src/coder/api.ts | 1 + .../settings/CoderWorkspaceSettings.tsx | 8 + .../components/settings/LabsSettingsPanel.tsx | 45 ++- .../settings/WorkspaceLinkSettings.tsx | 268 ++++++++++++++++++ .../src/components/settings/settingsSearch.ts | 15 + .../src/routes/_chat.settings.connections.tsx | 4 +- 6 files changed, 337 insertions(+), 4 deletions(-) create mode 100644 apps/web/src/components/settings/WorkspaceLinkSettings.tsx diff --git a/apps/web/src/coder/api.ts b/apps/web/src/coder/api.ts index 3d1f513eb7c56..e1250b62a23f1 100644 --- a/apps/web/src/coder/api.ts +++ b/apps/web/src/coder/api.ts @@ -14,6 +14,7 @@ export type { CoderDeploymentProfile, CoderWorkspaceProfile, CoderPortForwardProfile, + CoderWorkspaceLinkProfile, CoderProfileConfig, CoderPortForwardRuntimeStatus, DiscoveredCoderWorkspace, diff --git a/apps/web/src/components/settings/CoderWorkspaceSettings.tsx b/apps/web/src/components/settings/CoderWorkspaceSettings.tsx index 8d9c89d4250cc..a6e908c053b6d 100644 --- a/apps/web/src/components/settings/CoderWorkspaceSettings.tsx +++ b/apps/web/src/components/settings/CoderWorkspaceSettings.tsx @@ -235,6 +235,14 @@ function CoderWorkspaceRow({ (entry) => entry.workspaceId !== workspace.id, ), }), + // Coder: a link to or from a removed workspace goes with it. + ...(current.workspaceLinks === undefined + ? {} + : { + workspaceLinks: current.workspaceLinks.filter( + (entry) => entry.from !== workspace.id && entry.to !== workspace.id, + ), + }), })); }); diff --git a/apps/web/src/components/settings/LabsSettingsPanel.tsx b/apps/web/src/components/settings/LabsSettingsPanel.tsx index a198c464e12d2..aef61caa7f7e6 100644 --- a/apps/web/src/components/settings/LabsSettingsPanel.tsx +++ b/apps/web/src/components/settings/LabsSettingsPanel.tsx @@ -1,13 +1,52 @@ -import { SettingsPageContainer } from "./settingsLayout"; +import { Link } from "@tanstack/react-router"; + +import { ScopedSwitch } from "./ScopedSwitch"; +import { SettingsPageContainer, SettingsRow, SettingsSection } from "./settingsLayout"; +import { searchableSetting } from "./settingsSearch"; import { LegacyFeaturesSection } from "./SettingsPanels"; +import { useScopedSettings, useUpdateScopedSettings } from "./useScopedSettings"; /** Features still settling in, and legacy behavior kept for people who rely on it. */ export function LabsSettingsPanel() { return ( - {/* Coder: no Beta section. Guest links need T3 Connect, and linked environments pair - servers over /mcp; neither is carried. */} + + {/* Coder: no guest links row; guest links need T3 Connect, which is not carried. */} + + ); } + +function LinkedEnvironmentsRow() { + const settings = useScopedSettings(); + const updateSettings = useUpdateScopedSettings(); + return ( + + Let agents here work on your other machines, and theirs here. Turn it on for each machine, + then link them in{" "} + + Connections + + . While it is off, nothing new starts over a link; tasks already running finish. + + } + control={ + + updateSettings({ linkedEnvironmentsEnabled: Boolean(checked) }) + } + aria-label="Linked environments" + /> + } + /> + ); +} diff --git a/apps/web/src/components/settings/WorkspaceLinkSettings.tsx b/apps/web/src/components/settings/WorkspaceLinkSettings.tsx new file mode 100644 index 0000000000000..470c2fe2b394d --- /dev/null +++ b/apps/web/src/components/settings/WorkspaceLinkSettings.tsx @@ -0,0 +1,268 @@ +import { AuthMcpClientAccess } from "@t3tools/contracts"; +import { EyeIcon, type LucideIcon, MoreHorizontalIcon, PlusIcon } from "lucide-react"; +import { useId, useState } from "react"; + +import type { + CoderProfileConfig, + CoderWorkspaceLinkProfile, + CoderWorkspaceProfile, +} from "../../coder/api"; +import { randomUUID } from "../../lib/utils"; +import { runtimeModeConfig } from "../chat/runtimeModeConfig"; +import { Button } from "../ui/button"; +import { Menu, MenuItem, MenuPopup, MenuTrigger } from "../ui/menu"; +import { SettingsSection } from "./settingsLayout"; +import { SettingsSelect } from "./settingsSelect"; +import { + SettingsField, + SettingsResource, + SettingsResourceDialog, + SettingsResourceEmpty, + SettingsResourceError, +} from "./SettingsResource"; +import type { UpdateCoderSettingsConfig } from "./useCoderSettingsConfig"; +import { useSettingsOperation } from "./useSettingsOperation"; + +const EMPTY_LINKS: readonly CoderWorkspaceLinkProfile[] = []; + +/** Upstream's link access labels (`ConnectAgentSurface.tsx`'s `accessConfig`, not carried). */ +export const workspaceLinkAccessConfig: Record< + AuthMcpClientAccess, + { readonly label: string; readonly description: string; readonly icon: LucideIcon } +> = { + "read-only": { + label: "Read only", + description: "Read projects and threads. Cannot start, message or change anything.", + icon: EyeIcon, + }, + ...runtimeModeConfig, +}; + +/** + * Coder: link rules replace upstream's pairing. A rule lets agents in one workspace act in + * another through the gateway while both are connected, capped at the rule's access. + */ +export function WorkspaceLinkSettings({ + config, + updateConfig, +}: { + config: CoderProfileConfig; + updateConfig: UpdateCoderSettingsConfig; +}) { + const links = config.workspaceLinks ?? EMPTY_LINKS; + const [editing, setEditing] = useState(null); + const operation = useSettingsOperation(); + return ( + <> + setEditing("new")} + > + + Add link + + } + > + {links.length === 0 ? ( + + {config.workspaces.length < 2 + ? "Connect two workspaces before linking them." + : "No workspaces are linked yet."} + + ) : ( + links.map((link) => { + const from = config.workspaces.find((entry) => entry.id === link.from); + const to = config.workspaces.find((entry) => entry.id === link.to); + if (!from || !to) return null; + return ( + + + + + } + /> + + setEditing(link)}>Edit link + + void operation.run(link.id, "Could not remove link", () => + updateConfig((current) => ({ + ...current, + workspaceLinks: (current.workspaceLinks ?? []).filter( + (entry) => entry.id !== link.id, + ), + })), + ) + } + > + Remove link + + + + } + > + + + ); + }) + )} + + {editing !== null ? ( + setEditing(null)} + /> + ) : null} + + ); +} + +export function WorkspaceLinkEditor({ + link, + existingLinks, + workspaces, + updateConfig, + onClose, +}: { + link: CoderWorkspaceLinkProfile | null; + existingLinks: readonly CoderWorkspaceLinkProfile[]; + workspaces: readonly CoderWorkspaceProfile[]; + updateConfig: UpdateCoderSettingsConfig; + onClose: () => void; +}) { + const [from, setFrom] = useState(link?.from ?? workspaces[0]?.id ?? ""); + const [to, setTo] = useState(link?.to ?? workspaces[1]?.id ?? ""); + const [access, setAccess] = useState(link?.access ?? "approval-required"); + const operation = useSettingsOperation(); + const fromFieldId = useId(); + const toFieldId = useId(); + const accessFieldId = useId(); + const sameWorkspace = from === to; + const duplicate = existingLinks.some( + (candidate) => candidate.from === from && candidate.to === to && candidate.id !== link?.id, + ); + const known = (id: string) => workspaces.some((workspace) => workspace.id === id); + return ( + { + event.preventDefault(); + if (!known(from) || !known(to) || sameWorkspace || duplicate) return; + void operation + .run("save", "Could not save link", () => + updateConfig((current) => { + const next: CoderWorkspaceLinkProfile = { + id: link?.id ?? `workspace-link-${randomUUID()}`, + from, + to, + access, + }; + const rules = current.workspaceLinks ?? []; + if (link && !rules.some((entry) => entry.id === link.id)) + throw new Error("This link was removed. Close the editor and add it again."); + return { + ...current, + workspaceLinks: link + ? rules.map((entry) => (entry.id === link.id ? next : entry)) + : [...rules, next], + }; + }), + ) + .then((saved) => { + if (saved) onClose(); + }); + }} + > +

+ + ); +} diff --git a/apps/web/src/components/settings/settingsSearch.ts b/apps/web/src/components/settings/settingsSearch.ts index a9616a5015600..fe652a02cbb1d 100644 --- a/apps/web/src/components/settings/settingsSearch.ts +++ b/apps/web/src/components/settings/settingsSearch.ts @@ -398,6 +398,14 @@ export const SETTINGS_SEARCH_ITEMS = [ to: "/settings/general", searchTerms: ["hide fold running monitoring threads inbox sidebar shelf"], }, + // Coder: no guest links entry; guest links are not carried. + { + id: "linked-environments-beta", + title: "Linked environments", + to: "/settings/labs", + scope: "environment", + searchTerms: ["beta link another machine vps peer agents work there delegate"], + }, { id: "auto-settle-inactive-threads", title: "Auto-settle inactive threads", @@ -785,6 +793,13 @@ export const SETTINGS_SEARCH_ITEMS = [ to: "/settings/connections", searchTerms: ["ports tcp udp localhost loopback forward local remote restart"], }, + { + id: "workspace-links", + scope: "connections", + title: "Linked workspaces", + to: "/settings/connections", + searchTerms: ["link linked environments another workspace agents work there delegate access"], + }, { id: "archive", title: "Archived threads", diff --git a/apps/web/src/routes/_chat.settings.connections.tsx b/apps/web/src/routes/_chat.settings.connections.tsx index 73aa89efbcd26..339669094b27a 100644 --- a/apps/web/src/routes/_chat.settings.connections.tsx +++ b/apps/web/src/routes/_chat.settings.connections.tsx @@ -6,8 +6,9 @@ import { CoderWorkspaceSettings } from "../components/settings/CoderWorkspaceSet import { PortForwardSettings } from "../components/settings/PortForwardSettings"; import { SettingsPageContainer } from "../components/settings/settingsLayout"; import { useCoderSettingsConfig } from "../components/settings/useCoderSettingsConfig"; +import { WorkspaceLinkSettings } from "../components/settings/WorkspaceLinkSettings"; -/** Upstream's Connections page, where Coder connects deployments, workspaces, and forwards. */ +/** Upstream's Connections page, where Coder connects deployments, workspaces, forwards, and links. */ function CoderConnectionsSettings() { const { config, saveConfig, workspaceRuntime } = useCoder(); const updateConfig = useCoderSettingsConfig(config, saveConfig); @@ -20,6 +21,7 @@ function CoderConnectionsSettings() { workspaceRuntime={workspaceRuntime} updateConfig={updateConfig} /> + ); } From bb48dc4ea5f366e65c2273938703127c07b6be0b Mon Sep 17 00:00:00 2001 From: Henry Chu Date: Wed, 28 Oct 2026 07:57:01 -0400 Subject: [PATCH 4/4] Document linked workspaces and the gateway hub boundaries AGENTS.md boundaries 3, 6, and 9 cover routing between two local helper connections and the non-secret link rules; the user guide explains links, access modes, and what a disconnect does; the seams doc describes the hub transport seam. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 11 +++-- docs/internals/coder-only.md | 96 +++++++++++++++++++----------------- docs/user/workspaces.md | 17 +++++++ 3 files changed, 74 insertions(+), 50 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 48e56b1b55a63..abb089322bac9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,14 +29,17 @@ runtime boundary or syncing upstream. 3. No relay, Tailscale, Cloudflare, OAuth, Electron, mobile, hosted web, auto-update, T3-owned telemetry or trace export, WSL, generic user-facing SSH, reverse forwarding, or arbitrary tunnels. The web client contacts no service of its own; linked content (Markdown images and videos, link - favicons, GitLab avatars) loads from its own host as on upstream. + favicons, GitLab avatars) loads from its own host as on upstream. The gateway may route a T3 + tool call between two workspace helpers it holds; that is local stdio-to-stdio routing, not a + relay. 4. Port forwards are foreground `coder port-forward` processes bound to `127.0.0.1`, built from structured fields only; stop only the exact child process captured at spawn. 5. Coder owns authentication: never ask for, read, copy, log, or persist Coder tokens. GitLab and provider credentials stay in the workspace. Upstream's agent secret request card stays as is. 6. The workspace helper runs in the foreground over `coder ssh` and speaks newline-delimited RPC over stdio. T3 tools reach agents over the workspace file bridge, never an MCP server, because - work Claude Code and Codex policies block custom MCP servers. + work Claude Code and Codex policies block custom MCP servers. The gateway subscribes to each + helper's hub outbox and forwards calls between connected helpers per workspace link rules. 7. Codex, Claude Code, Pi, and Kilo Code are the only providers; they exist only in the workspace, and T3 never probes for or launches a local provider. Kilo Code runs through upstream's ACP Registry driver from its local `kilo acp` command only: no registry index, installs, or agent @@ -44,8 +47,8 @@ runtime boundary or syncing upstream. 8. No provider binary is bundled on the laptop; the Anthropic Agent SDK stays type-only. 9. Durable application state stays in the workspace, which remains the source of truth. Local persistence outside the browser is limited to non-secret deployment URLs, Coder executable - paths, workspace targets, port-forward rules, and the last gateway port. The browser may store - and cache what upstream does, but never credentials. + paths, workspace targets, port-forward rules, workspace link rules, and the last gateway port. + The browser may store and cache what upstream does, but never credentials. 10. GitLab is the only hosted source-control provider; Git and `glab` run only in the workspace. 11. The branch policy below is part of the boundary. diff --git a/docs/internals/coder-only.md b/docs/internals/coder-only.md index 91ec3dda0030d..6219dc6662555 100644 --- a/docs/internals/coder-only.md +++ b/docs/internals/coder-only.md @@ -68,7 +68,8 @@ Restored data stays in `synchronizing` state until the marker arrives, except fo resume behavior: a recently viewed live thread renders its retained snapshot immediately and only shows synchronization progress if replay changes its contents. The marker follows buffered live events accumulated during snapshot or replay loading. The browser and helper are built from the -same checkout; helper protocol version 2 remains the transport compatibility fence. +same checkout; helper protocol version 3 remains the transport compatibility fence (version 3 adds +the gateway hub methods; see the linked-environments entry). Live shell and thread subscriptions are bounded (`LiveStreamBudget.ts`), including batches awaiting an RPC acknowledgement; overflow detaches that live source, and reconnect uses the existing @@ -492,7 +493,7 @@ listed here is drift to remove rather than fork behavior to keep. older-settled-thread reads (`WsOrchestrationV2GetThreadFamilyRpc`, `WsOrchestrationV2GetWorktreeThreadIdsRpc`, `WsOrchestrationV2GetOlderSettledThreadsRpc`) are served as upstream's handlers; `WsGuestShareCreateRpc` is omitted (see the guest-sharing cut), - as are the four `WsPeerLinks*` RPCs (see the linked-environments cut), + as are the four `WsPeerLinks*` RPCs (see the linked-environments entry), `WsServerPrepareTriageRpc` (see the triage cut), and `WsPreviewStopLocalServerRpc` (see the dev-servers cut). - Guest thread sharing (#24104) is not carried: guests reach a share over upstream's server HTTP @@ -508,50 +509,53 @@ listed here is drift to remove rather than fork behavior to keep. orchestration-v2 guest decider, commands, and projection columns stay, because the contract unions need them (`knip.jsonc` ignores their unused exports); with no service nothing creates a share, so the sidebar `"request"` status and its notification title never fire. - - Linked environments (peer links, #16653–#17130) are not carried: upstream links two servers - with pairing and OAuth and forwards T3 tool calls over server-to-server HTTP `/mcp`, which - breaks `AGENTS.md` boundaries 2, 3, and 6. Cut on the server: `apps/server/src/peer/**` - (`PeerLinks`, `PeerMcpClient`, `PeerForwarding`, `PeerLinkRequests`, `RemoteDelegation`) and - its layers in `server.ts`, the `WsPeerLinks*` handlers, `mcp/linkOrigin.ts` and its fence - (`McpToolAccess`'s `linkedCallers`/`linked` options, `ProjectSetupScriptRunner`'s - `skipped-for-link`, `WorktreeMcpService`'s `skipped` status), `McpInvocationContext`'s - `T3-Mode-Limit` narrowing and `hiddenWhileLinksOff`, the `t3_environment_links`, - `t3_environment_link`, and `t3_environment_unlink` tools, the linked-machine lines of - provider-core's `orchestrationInstructions.ts`, `t3_thread_launch`'s `delegatedFrom` parameter, - `ThreadLaunchService`'s `linkOrigin`/`delegatedFrom` inputs, `OrchestratorMcpService`'s remote - task read, wait, delegate, and cancel paths, `ThreadManagementService`'s remote task stop, and - `ProjectionStore`'s `getOpenRemoteDelegatedTasks`. `McpToolAccess.toLayer` refuses any tool - call whose `environmentId` names another environment with upstream's "This environment - cannot reach linked environments." error, and `delegate_task` refuses a `target.environmentId` - naming another environment the same way. Migrations 070 and 071 keep their IDs and create nothing; 072's index stays, - because `ProjectionStore`'s waiting-card reads name it. `peerLinks`, `mcpModeLimitHeader`, and - `linkFence` are in `CODER_OMITTED_CAPABILITIES`. The contracts (`peerLink.ts`, the - `environmentId` tool fields the bridge advertises, `remoteChild`, `linkOrigin`, - `delegatedFrom`, the `link_request` turn item, and the `delegated_task.remote.*` and - `link_request.record` commands), the orchestration-v2 decider cases for them, their projection - decoding and shell fields, `ThreadManagementService`'s client provenance strip, and - `ProviderRuntimeRecoveryService`'s remote-task and link-card checks stay, because the contract - unions need them; with no peer service nothing creates a remote task or a link card. Cut in - the clients: web `EnvironmentContextChip.tsx`, `chat/LinkRequestCard.tsx`, - `settings/LinkAccessPicker.tsx`, `LinkMachineSelect.tsx`, `LinkedEnvironmentsSettings.tsx`, - `state/peerLinks.ts`, `state/peerPairingCode.ts`; client-runtime `linkRequest.ts`, - `state/peerLinks.ts`, `state/peerPairingCode.ts` and their exports; Labs' linked-environments - row (`LabsSettingsPanel.tsx` has no Beta section) and its settings-search entries; the `@` - machine menu items and machine chips in the composer and drafts (`useComposerMenuItems.ts`, - `ComposerCommandMenu.tsx`, `composerThreadItems.ts`, `composerDraftStore.ts`, - `composerContextRecords.ts`, `composerContextPresentation.tsx`, `useComposerSend.ts`, - `chatViewSend.ts`, `useQueuedRunEdit.ts`); the link-request timeline card - (`TimelineV2EventRow.tsx`, `session-logic.ts`); remote-task lineage from `remoteChild` and - `delegatedFrom` (`ThreadRelationshipsControl.tsx`, `V2LifecycleRow.tsx`, `MessagesTimeline.tsx`, - `ChatView.tsx`'s parent link, `ChatHeader.tsx`'s "From" badge, `Sidebar.logic.ts`, - `Sidebar.tsx`, `routeReveal.ts`, `useSidebarProjectGroups.ts`, + - Linked environments (#16653–#17130) are carried between Coder workspaces through the gateway + hub instead of server-to-server HTTP `/mcp` and pairing, which would break `AGENTS.md` + boundaries 2, 3, and 6. Upstream's `peer/PeerForwarding.ts` and `peer/RemoteDelegation.ts`, + `mcp/linkOrigin.ts` and its fence, `McpToolAccess`'s forwarding of every tool that takes + `environmentId`, `McpInvocationContext`'s linked caller, `delegate_task`'s remote branch, + `ThreadLaunchService`'s `linkOrigin`/`delegatedFrom`, `ThreadManagementService`'s remote stop, + `ProjectionStore`'s `getOpenRemoteDelegatedTasks`, `t3_environment_links`, the Labs + "Linked environments" switch, and the linked-machine orchestration instructions are upstream's. + The transport is one seam: `peer/PeerMcpClient.ts` and `peer/PeerLinks.ts` keep upstream's + service tags but send calls and read links through `coderHub.ts`, the helper's side of the hub + (helper protocol v3: `coder.hub.outbox`, `coder.hub.reply`, `coder.hub.invoke` in + `packages/coder-cli/src/rpc.ts`). The gateway (`apps/coder-gateway/src/hub.ts`) holds each + v3 helper's outbox open, checks the requester's workspace link rule (`workspaceLinks` in the + gateway config, edited in Connections' "Linked workspaces" section, + `WorkspaceLinkSettings.tsx`), runs the call on the target workspace's helper with + `coder.hub.invoke` as that link's caller (`sessionId` `coder-link:`, the rule's access, + the calling agent's modes as `narrowedTo`), and replies; the browser bridge refuses the hub + methods. A workspace that is not connected is unreachable, and upstream's follower retries. + Differences, each marked `Coder:`: no `T3-Mode-Limit` header (the hub carries the limits); + `PeerLinks` has no pairing, storage, or expiry (`expiresAt` is a fixed far-future value); + `t3_environment_link`, `t3_environment_unlink`, `PeerLinkRequests`, the link-request card, and + the `WsPeerLinks*` handlers are not carried, so `t3_environment_links`' `notListed` and the + orchestration instructions point to the Links settings; `coder.hub.invoke` refuses calls while + Labs' switch is off, as upstream's `/mcp` does; `T3ToolBridge`'s binding gains `invoke` for a + linked caller; and upstream's peer tests (`PeerForwarding.test.ts`, `RemoteDelegation.test.ts`, + `linkOrigin.test.ts`, `PeerLinks.testkit.ts`) are not carried because they pair two HTTP + servers; `coderHub.test.ts` and the gateway's `hub.test.ts` test the transport. Migrations 070 + and 071 keep their IDs and create nothing; 072's index stays. `peerLinks` and `linkFence` are + advertised; `mcpModeLimitHeader` is in `CODER_OMITTED_CAPABILITIES`. Still cut in the + clients, and restored by the lineage follow-up: web `EnvironmentContextChip.tsx`, + `chat/LinkRequestCard.tsx`, `settings/LinkAccessPicker.tsx`, `LinkMachineSelect.tsx`, + `LinkedEnvironmentsSettings.tsx`, `state/peerLinks.ts`, `state/peerPairingCode.ts`; + client-runtime `linkRequest.ts`, `state/peerLinks.ts`, `state/peerPairingCode.ts` and their + exports; the `@` machine menu items and machine chips in the composer and drafts + (`useComposerMenuItems.ts`, `ComposerCommandMenu.tsx`, `composerThreadItems.ts`, + `composerDraftStore.ts`, `composerContextRecords.ts`, `composerContextPresentation.tsx`, + `useComposerSend.ts`, `chatViewSend.ts`, `useQueuedRunEdit.ts`); the link-request timeline + card (`TimelineV2EventRow.tsx`, `session-logic.ts`); remote-task lineage from `remoteChild` + and `delegatedFrom` (`ThreadRelationshipsControl.tsx`, `V2LifecycleRow.tsx`, + `MessagesTimeline.tsx`, `ChatView.tsx`'s parent link, `ChatHeader.tsx`'s "From" badge, + `Sidebar.logic.ts`, `Sidebar.tsx`, `routeReveal.ts`, `useSidebarProjectGroups.ts`, `ThreadNotificationCoordinator.tsx`, `state/entities.ts`, client-runtime `threadShell.ts` and - `models.ts`); and the `t3_environment_*` tool presentations (`t3McpToolPresentation.ts`, - `t3ToolSummary.ts`). The contract's `environment` record kind keeps upstream's definition in - `contextPresentationRegistry.ts` and an unavailable-chip handler in - `UserMessageContextChips.tsx`, because both registries require every contract kind; shared - `composerContextReferences.ts` parses it as upstream does. The planned gateway-hub delegation - follow-up restores `RemoteDelegation` and the lineage UI over the gateway instead of HTTP. + `models.ts`); and the `t3_environment_link`/`unlink` tool presentations + (`t3McpToolPresentation.ts`, `t3ToolSummary.ts`). The contract's `environment` record kind + keeps upstream's definition in `contextPresentationRegistry.ts` and an unavailable-chip + handler in `UserMessageContextChips.tsx`, because both registries require every contract kind; + shared `composerContextReferences.ts` parses it as upstream does. - In-app triage (#22753) is not carried: it clones upstream T3 Code's source into the server's cache and starts an agent to help file an upstream issue, which T3 Coder bugs are not. `apps/server/src/triage/**`, its layer in `server.ts`, and the `server.prepareTriage` handler @@ -1192,7 +1196,7 @@ listed here is drift to remove rather than fork behavior to keep. - **Settings.** Upstream's layout, pages (#25651), navigation, and search, with Coder's Connections ("Environments"), Providers, GitLab, and background-activity panels. The access, browser, devices, SnapShot, and diagnostics pages are not carried, and `movedSettingsPath` never points at - them; Labs has no Beta (guest links) section; About has no mobile app row or privacy policy link; + them; Labs' Beta section has only the Linked environments switch (no guest links); About has no mobile app row or privacy policy link; storage cleanup lives on Maintenance and Worktrees as upstream's. `hooks/useEnvironmentDisconnectDelay.ts` keeps only upstream's `useEnvironmentStateHeldFor`. No Integrations, SnapShot, desktop, diagnostics, pairing, mobile app links (`MobileAppSettingsRow`), or `keybindings.json` editor. Settings diff --git a/docs/user/workspaces.md b/docs/user/workspaces.md index 5856938773c1c..fca846118db8a 100644 --- a/docs/user/workspaces.md +++ b/docs/user/workspaces.md @@ -64,6 +64,23 @@ network. Each rule runs its own forward process, reports its state (**Starting** **Stopped**), and can be restarted or removed individually. Saved rules start again when the gateway starts; a rule that failed stays stopped until you restart it or change its configuration. +## Linked workspaces + +A link lets agents in one workspace delegate tasks to another workspace and work on its threads. +It works only while T3 Coder is connected to both workspaces; nothing else connects them. + +1. In each workspace, turn on **Linked environments** under **Settings → Labs**. +2. Under **Settings → Environments → Linked workspaces**, choose **Add link**, then pick the + workspace whose agents act, the workspace they may work in, and an access mode. + +A link goes one way. The access mode caps what those agents may do in the other workspace, from +**Read only** to **Full access**; below full access they can change only the work they started +there. An agent lists linked workspaces with `t3_environment_links` and delegates with +`delegate_task`, setting `target.environmentId` to the other workspace. Its task appears in its +own thread, and the work runs as an ordinary thread in the other workspace. Disconnecting that +workspace stops its helper and the work running there; the task waits and reports how that work +ended once the workspace is connected again. + ## Data ownership Repositories, prompts, responses, provider sessions, terminals, checkpoints, project records, and