From 7f19f71cee3cf261da313bad9ebb3ef6469d98d1 Mon Sep 17 00:00:00 2001 From: nullStack65 <112618179+nullStack65@users.noreply.github.com> Date: Thu, 19 Nov 2026 19:51:57 +0000 Subject: [PATCH 1/2] fix(mcp): older linked environments can route threads to a founder inbox A linked environment on a release from before `inboxRouting.reason` has no such field in its tool schema, so its agent cannot send one. The server rejected every founder or shared route from it for a missing reason: a dead end. Peers now announce `T3-Peer-Features: inbox-reason`. A linked caller without the header gets its reason-less route filed as `fyi`, which is how lanes filed before reasons already show. Current peers still must give one. Co-Authored-By: Claude Opus 5.5 --- apps/server/src/mcp/McpHttpServer.ts | 20 ++++++- apps/server/src/mcp/McpInvocationContext.ts | 18 +++++++ .../src/mcp/ThreadMetadataMcpService.ts | 7 ++- .../src/mcp/toolkits/project/handlers.ts | 10 +++- apps/server/src/peer/PeerMcpClient.test.ts | 52 +++++++++++++++++++ apps/server/src/peer/PeerMcpClient.ts | 2 + packages/contracts/src/threadInbox.test.ts | 37 +++++++++++++ packages/contracts/src/threadInbox.ts | 24 +++++++++ 8 files changed, 165 insertions(+), 5 deletions(-) diff --git a/apps/server/src/mcp/McpHttpServer.ts b/apps/server/src/mcp/McpHttpServer.ts index 752702e390a2f..9784f84303590 100644 --- a/apps/server/src/mcp/McpHttpServer.ts +++ b/apps/server/src/mcp/McpHttpServer.ts @@ -225,6 +225,21 @@ const withSenderThread = ( : { ...invocation, client: { ...invocation.client, senderThread: decoded.value } }; }; +/** Records what a linked environment's tools support; anything malformed reads as none. */ +const withPeerFeatures = ( + invocation: McpInvocationContext.McpInvocationScope, + request: HttpServerRequest.HttpServerRequest, +): McpInvocationContext.McpInvocationScope => { + const header = request.headers[McpInvocationContext.PEER_FEATURES_HEADER]; + if (header === undefined || invocation.client?.linked !== true) return invocation; + const peerFeatures = header + .split(",") + .map((feature) => feature.trim()) + .filter((feature) => /^[a-z0-9-]{1,64}$/.test(feature)) + .slice(0, 32); + return { ...invocation, client: { ...invocation.client, peerFeatures } }; +}; + // The Linked environments beta is off here: links wait until it is on again. const linkedEnvironmentsOff = HttpServerResponse.jsonUnsafe( { @@ -270,7 +285,10 @@ const makeMcpAuthMiddleware = Effect.gen(function* () { offerOAuth: Option.isSome(clients) && !looksLikeProviderToken(token), }); } - const asked = withModeLimit(withSenderThread(invocation, request), request); + const asked = withModeLimit( + withPeerFeatures(withSenderThread(invocation, request), request), + request, + ); if (asked === undefined) return invalidModeLimit; const limited = McpInvocationContext.withRuntimeModeCeiling(asked, runtimeModeCeiling); const linkedEnvironments = yield* linksEnabled; diff --git a/apps/server/src/mcp/McpInvocationContext.ts b/apps/server/src/mcp/McpInvocationContext.ts index 8cca204209e86..81c3d43b44c08 100644 --- a/apps/server/src/mcp/McpInvocationContext.ts +++ b/apps/server/src/mcp/McpInvocationContext.ts @@ -3,6 +3,7 @@ import { type EnvironmentId, McpCapabilityUnavailableError, OrchestratorMcpFailure, + PEER_FEATURE_INBOX_REASON, PreviewAutomationUnavailableError, type ProviderInstanceId, type ProviderInteractionMode, @@ -48,6 +49,8 @@ export interface McpClientCaller { readonly narrowedTo?: ClientModes | undefined; /** A linked environment's thread this request is made for (`T3-Sender-Thread`). */ readonly senderThread?: OrchestrationV2LinkedSender | undefined; + /** What a linked environment says its tools support (`T3-Peer-Features`); none from older ones. */ + readonly peerFeatures?: ReadonlyArray | undefined; /** An outside client's thread links go through this hosted app, as Copy thread's do. */ readonly hostedAppUrl?: string | undefined; } @@ -67,6 +70,21 @@ export const MODE_LIMIT_HEADER = "t3-mode-limit"; */ export const SENDER_THREAD_HEADER = "t3-sender-thread"; +/** + * `T3-Peer-Features: ,`: what a linked environment's tools support, so this + * side can tell an older release from a current one (its `clientInfo` version never changes). + * Read only from a linked client. A missing header means a release from before it. + */ +export const PEER_FEATURES_HEADER = "t3-peer-features"; + +/** Features this release's peer client announces on every call. */ +export const PEER_FEATURES: ReadonlyArray = [PEER_FEATURE_INBOX_REASON]; + +/** A linked environment whose tools cannot send `inboxRouting.reason`. */ +export const isLegacyInboxPeer = (scope: Pick): boolean => + scope.client?.linked === true && + !(scope.client.peerFeatures ?? []).includes(PEER_FEATURE_INBOX_REASON); + export interface ClientModes { readonly runtimeMode: RuntimeMode; readonly interactionMode: ProviderInteractionMode; diff --git a/apps/server/src/mcp/ThreadMetadataMcpService.ts b/apps/server/src/mcp/ThreadMetadataMcpService.ts index 350d0b9da4858..19667572dd20f 100644 --- a/apps/server/src/mcp/ThreadMetadataMcpService.ts +++ b/apps/server/src/mcp/ThreadMetadataMcpService.ts @@ -10,6 +10,7 @@ import { type ThreadMetadataMcpUpdateResult, ThreadId, routeThreadInbox, + withLegacyPeerInboxReason, } from "@t3tools/contracts"; import * as Context from "effect/Context"; import * as SecureRandom from "effect/crypto/SecureRandom"; @@ -18,7 +19,7 @@ import * as Effect from "effect/Effect"; import * as Layer from "effect/Layer"; import * as ThreadManagementService from "../orchestration-v2/ThreadManagementService.ts"; -import type { McpInvocationScope } from "./McpInvocationContext.ts"; +import { isLegacyInboxPeer, type McpInvocationScope } from "./McpInvocationContext.ts"; import { threadNotFound } from "./threadAccess.ts"; export class ThreadMetadataMcpService extends Context.Service< @@ -151,8 +152,10 @@ const make = Effect.gen(function* () { const update = Effect.fn("ThreadMetadataMcpService.update")(function* ( scope: McpInvocationScope, - input: ThreadMetadataMcpUpdateInput, + requested: ThreadMetadataMcpUpdateInput, ) { + // An older linked environment cannot send a reason; file its route as FYI, not a dead end. + const input = withLegacyPeerInboxReason(requested, isLegacyInboxPeer(scope)); if (!scope.capabilities.has("orchestration")) { return yield* failure( "capability_denied", diff --git a/apps/server/src/mcp/toolkits/project/handlers.ts b/apps/server/src/mcp/toolkits/project/handlers.ts index f116e1d7da6d9..d4adf8ca86f3f 100644 --- a/apps/server/src/mcp/toolkits/project/handlers.ts +++ b/apps/server/src/mcp/toolkits/project/handlers.ts @@ -1,6 +1,7 @@ import { agentLaunchInboxError, agentLaunchInboxRouting, + withLegacyPeerInboxReason, CommandId, type EnvironmentId, MessageId, @@ -261,6 +262,11 @@ export const layer = McpToolAccess.toLayer(ProjectToolkit, { const scope = yield* McpInvocationContext.McpInvocationContext; const context = yield* readCaller(); const { caller } = context; + // An older linked environment cannot send a reason; file its launch as FYI, not a dead end. + const filed = withLegacyPeerInboxReason( + input, + McpInvocationContext.isLegacyInboxPeer(scope), + ); // A retry with the same key replays the first launch: the ids derive // from the caller and the key, and the launch service replays a // command it already accepted. @@ -271,7 +277,7 @@ export const layer = McpToolAccess.toLayer(ProjectToolkit, { const threadId = ThreadId.make(commandId); const messageId = MessageId.make(commandId); const attachments = input.attachments ?? []; - const inboxError = agentLaunchInboxError(input); + const inboxError = agentLaunchInboxError(filed); if (inboxError !== null) return yield* new OrchestratorMcpFailure({ code: "invalid_request", @@ -434,7 +440,7 @@ export const layer = McpToolAccess.toLayer(ProjectToolkit, { } const result = yield* ThreadMessageIntake.launchThread({ inboxOrigin: { kind: "agent", id: caller?.id ?? "agent" }, - inboxRouting: agentLaunchInboxRouting(input), + inboxRouting: agentLaunchInboxRouting(filed), commandId, threadId, projectId, diff --git a/apps/server/src/peer/PeerMcpClient.test.ts b/apps/server/src/peer/PeerMcpClient.test.ts index 3dcf0697afae6..c47ed35ca8d46 100644 --- a/apps/server/src/peer/PeerMcpClient.test.ts +++ b/apps/server/src/peer/PeerMcpClient.test.ts @@ -150,6 +150,58 @@ it.effect("tells the peer which thread a call is made for", () => ).pipe(Effect.provide(NodeHttpServer.layerTest)), ); +const featuresToolkit = Toolkit.make( + Tool.make("features", { + description: "Returns what the calling peer says it supports.", + success: Schema.Struct({ legacy: Schema.Boolean, features: Schema.Array(Schema.String) }), + dependencies: [McpInvocationContext.McpInvocationContext], + }), +); + +it.effect("announces this release's peer features, so the peer can tell it from an older one", () => + Effect.scoped( + Effect.gen(function* () { + const handlers = McpToolAccess.toLayer(featuresToolkit, { + features: McpToolAccess.reads(() => + McpInvocationContext.McpInvocationContext.pipe( + Effect.map((scope) => ({ + legacy: McpInvocationContext.isLegacyInboxPeer(scope), + features: [...(scope.client?.peerFeatures ?? [])], + })), + ), + ), + }); + const box = descriptorOf("environment-box", "Box"); + const b = yield* servePeer(box, McpHttpServer.toolkitRegistration(featuresToolkit, handlers)); + const context = yield* Layer.build( + layerLinkingEnvironment(descriptorOf("environment-a", "A")), + ); + const links = Context.get(context, PeerLinks.PeerLinks); + const client = Context.get(context, PeerMcpClient.PeerMcpClient); + yield* linkTo(links, b); + const seen = yield* client.call({ + environmentId: box.environmentId, + tool: "features", + arguments: {}, + limits: { runtimeMode: "full-access", interactionMode: "default" }, + success: Schema.Struct({ legacy: Schema.Boolean, features: Schema.Array(Schema.String) }), + }); + // A current peer must still give inboxRouting.reason; only one without the header is legacy. + expect(seen).toEqual({ legacy: false, features: ["inbox-reason"] }); + expect( + McpInvocationContext.isLegacyInboxPeer({ + client: { sessionId: "s", label: "old desktop", access: "full-access", linked: true }, + }), + ).toBe(true); + expect( + McpInvocationContext.isLegacyInboxPeer({ + client: { sessionId: "s", label: "browser", access: "full-access" }, + }), + ).toBe(false); + }), + ).pipe(Effect.provide(NodeHttpServer.layerTest)), +); + it.effect.each([false, true])( "reuses an initialized session before its first call finishes (cancelled: %s)", (cancelFirst) => diff --git a/apps/server/src/peer/PeerMcpClient.ts b/apps/server/src/peer/PeerMcpClient.ts index 6e920f8bfad52..07ddf93c9750d 100644 --- a/apps/server/src/peer/PeerMcpClient.ts +++ b/apps/server/src/peer/PeerMcpClient.ts @@ -215,6 +215,8 @@ const make = Effect.gen(function* () { { ...limitHeader, ...senderHeader, + [McpInvocationContext.PEER_FEATURES_HEADER]: + McpInvocationContext.PEER_FEATURES.join(","), "mcp-session-id": sessionId, "mcp-protocol-version": PROTOCOL_VERSION, }, diff --git a/packages/contracts/src/threadInbox.test.ts b/packages/contracts/src/threadInbox.test.ts index 53ade33321004..7041319402357 100644 --- a/packages/contracts/src/threadInbox.test.ts +++ b/packages/contracts/src/threadInbox.test.ts @@ -18,6 +18,7 @@ import { projectThreadInbox, inboxRoutingFor, primaryInbox, + withLegacyPeerInboxReason, type ThreadInboxRoutingPatch, } from "./threadInbox.ts"; const kameron = { kind: "human", id: "kameron" } as const; @@ -146,6 +147,42 @@ describe("shared fleet organizational inbox", () => { expect(visibleIn(quieter)).toEqual(["kameron", "agents"]); expect(founderInboxLane(quieter, "kameron")).toBe("FYI"); }); + + it("files an older linked environment's reason-less founder routes as FYI instead of failing", () => { + // A peer from before `inboxRouting.reason` has no such field in its tools: rejecting the + // route for a missing reason left its agent no way to succeed. + const toKameron = { assignee: kameron } as const; + const routed = (routing: ThreadInboxRoutingPatch) => + routeThreadInbox(makeThreadInbox({ actor: bot }), routing); + expect(agentInboxRoutingError(routed(toKameron), toKameron)).toContain("inboxRouting.reason"); + + const legacy = withLegacyPeerInboxReason({ inboxRouting: toKameron }, true); + expect(legacy.inboxRouting).toEqual({ assignee: kameron, reason: "fyi" }); + expect(agentInboxRoutingError(routed(legacy.inboxRouting), legacy.inboxRouting)).toBeNull(); + expect(founderInboxLane(routed(legacy.inboxRouting), "kameron")).toBe("FYI"); + + const launch = withLegacyPeerInboxReason({ inbox: "kameron" as const }, true); + expect(agentLaunchInboxError(launch)).toBeNull(); + expect( + founderInboxLane( + makeThreadInbox({ actor: bot, routing: agentLaunchInboxRouting(launch) }), + "kameron", + ), + ).toBe("FYI"); + + // A current peer announces the feature and still must give a reason. + expect(withLegacyPeerInboxReason({ inboxRouting: toKameron }, false).inboxRouting).toEqual( + toKameron, + ); + expect( + agentLaunchInboxError(withLegacyPeerInboxReason({ inbox: "kameron" as const }, false)), + ).toContain("inboxRouting.reason"); + // A reason the older peer did send, and a launch that names no inbox, are left alone. + const reviewed = { inboxRouting: { assignee: kameron, reason: "review" as const } }; + expect(withLegacyPeerInboxReason(reviewed, true)).toBe(reviewed); + const plain = { title: "x", inboxRouting: undefined }; + expect(withLegacyPeerInboxReason(plain, true)).toBe(plain); + }); it("shows reason-less agent lanes only to the founder they were routed to, as FYI", () => { const people = [null, kameron, jeff] as const; const patches: ThreadInboxRoutingPatch[] = [{}]; diff --git a/packages/contracts/src/threadInbox.ts b/packages/contracts/src/threadInbox.ts index e96a6b175eb5f..0a7f4675d4534 100644 --- a/packages/contracts/src/threadInbox.ts +++ b/packages/contracts/src/threadInbox.ts @@ -187,6 +187,30 @@ export function agentInboxRoutingError( return "Agent work files into the Agents inbox and reports one final result there. Put a thread in a founder's or the shared inbox only when they will converse in it, review, decide or approve: pass inboxRouting.reason ('conversation', 'review', 'decision', 'approval' or 'fyi'). To ask a founder something on a thread, use t3_thread_update action:'request_decision' and also write the question in the thread, where they read it. If the answer reaches you another way, such as a relayed approval, call action:'resolve_decision'."; } +/** + * What a linked environment sends in `T3-Peer-Features` once its tools forward + * `inboxRouting.reason`. Releases before it have no such field in their tool schema, so their + * agents cannot give a reason at all. + */ +export const PEER_FEATURE_INBOX_REASON = "inbox-reason" as const; + +/** + * Files a reason-less route from an older linked environment as `fyi` instead of rejecting it: + * that agent's tools cannot send a reason, so the rejection would be a dead end. `fyi` is what + * lanes filed before reasons existed already show as (see `founderInboxLane`). Routes that + * carry a reason, and routes that touch no inbox, are returned unchanged. + */ +export function withLegacyPeerInboxReason< + T extends { + readonly inbox?: InboxChoice | undefined; + readonly inboxRouting?: ThreadInboxRoutingPatch | undefined; + }, +>(input: T, legacyPeer: boolean): T { + if (!legacyPeer || input.inboxRouting?.reason !== undefined) return input; + if (input.inbox === undefined && input.inboxRouting === undefined) return input; + return { ...input, inboxRouting: { ...input.inboxRouting, reason: "fyi" } }; +} + /** The rejection for an agent launch filed by `agentLaunchInboxRouting`, or null. */ export const agentLaunchInboxError = (input: Parameters[0]) => { const routing = agentLaunchInboxRouting(input); From ec1d14219067a0918046126dc010ec6eb81d0c07 Mon Sep 17 00:00:00 2001 From: nullStack65 <112618179+nullStack65@users.noreply.github.com> Date: Thu, 19 Nov 2026 22:21:46 +0000 Subject: [PATCH 2/2] fix(mcp): cover create_threads for older peers; stamp fyi only on founder routes Review round fixes: - create_threads files a reason-less founder route from an older linked environment as FYI, like t3_thread_update and t3_thread_launch already do. - withLegacyPeerInboxReason stamps `fyi` only on a route the strict guard would reject (one that reaches a founder or the shared inbox); a route that stays in Agents keeps no reason. - A launch placed on another environment forwards the filed route. Co-Authored-By: Claude Opus 5.5 --- apps/server/src/mcp/OrchestratorMcpService.ts | 13 ++++++++++--- apps/server/src/mcp/toolkits/project/handlers.ts | 2 +- packages/contracts/src/threadInbox.test.ts | 11 +++++++++++ packages/contracts/src/threadInbox.ts | 4 +++- 4 files changed, 25 insertions(+), 5 deletions(-) diff --git a/apps/server/src/mcp/OrchestratorMcpService.ts b/apps/server/src/mcp/OrchestratorMcpService.ts index 8698aa87b82b7..4dc6caa655906 100644 --- a/apps/server/src/mcp/OrchestratorMcpService.ts +++ b/apps/server/src/mcp/OrchestratorMcpService.ts @@ -68,6 +68,7 @@ import { SECRET_REQUEST_UNSAVED_NOTE, agentLaunchInboxError, agentLaunchInboxRouting, + withLegacyPeerInboxReason, } from "@t3tools/contracts"; import { getProviderOptionCurrentValue, withLegacyUltracodeEffort } from "@t3tools/shared/model"; import { backgroundWorkHoldsCompletion } from "@t3tools/shared/orchestrationV2PendingBackgroundWork"; @@ -127,6 +128,7 @@ import * as ScheduledTaskService from "../scheduledTasks/ScheduledTaskService.ts import * as ServerSettings from "../serverSettings.ts"; import { clientModeCeiling, + isLegacyInboxPeer, type McpInvocationScope, type McpThreadInvocationScope, requireThreadScope, @@ -3126,12 +3128,17 @@ const make = Effect.gen(function* () { createThreads: Effect.fn("OrchestratorMcpService.createThreads")( function* (callerScope, input) { const { scope, parent } = yield* loadThreadCaller(callerScope, "create_threads"); - for (const request of input.threads) { + // An older linked environment cannot send a reason; file its threads as FYI, not a dead end. + const legacyPeer = isLegacyInboxPeer(callerScope); + const threads = input.threads.map((request) => + withLegacyPeerInboxReason(request, legacyPeer), + ); + for (const request of threads) { const inboxError = agentLaunchInboxError(request); if (inboxError !== null) return yield* failure("invalid_request", inboxError); } // Each thread shares this thread's checkout, so another environment cannot take it. - for (const request of input.threads) { + for (const request of threads) { yield* admitPlacement( chooseThreadPlacement( { @@ -3160,7 +3167,7 @@ const make = Effect.gen(function* () { const providers = yield* loadProviders; const key = yield* requestKey(input.clientRequestId); const created = yield* Effect.forEach( - input.threads, + threads, (request, index) => Effect.gen(function* () { const commandId = stableCommandId({ diff --git a/apps/server/src/mcp/toolkits/project/handlers.ts b/apps/server/src/mcp/toolkits/project/handlers.ts index d4adf8ca86f3f..6bd5b14690d74 100644 --- a/apps/server/src/mcp/toolkits/project/handlers.ts +++ b/apps/server/src/mcp/toolkits/project/handlers.ts @@ -372,7 +372,7 @@ export const layer = McpToolAccess.toLayer(ProjectToolkit, { // A launch already made here replays here. Any other is placed, or reaches the // environment its key was placed in, before anything only this checkout checks. if (!replaying) { - const placedThere = yield* launchPlacedThere(scope, input, { + const placedThere = yield* launchPlacedThere(scope, filed, { projectId, threadId, strategy, diff --git a/packages/contracts/src/threadInbox.test.ts b/packages/contracts/src/threadInbox.test.ts index 7041319402357..97fb266ed09e7 100644 --- a/packages/contracts/src/threadInbox.test.ts +++ b/packages/contracts/src/threadInbox.test.ts @@ -182,6 +182,17 @@ describe("shared fleet organizational inbox", () => { expect(withLegacyPeerInboxReason(reviewed, true)).toBe(reviewed); const plain = { title: "x", inboxRouting: undefined }; expect(withLegacyPeerInboxReason(plain, true)).toBe(plain); + // A route that stays in Agents gets no reason stamped on it. + for (const agentsOnly of [ + { inboxRouting: {} }, + { inboxRouting: { assignee: null } }, + { inbox: "agents" as const }, + ]) + expect(withLegacyPeerInboxReason(agentsOnly, true)).toBe(agentsOnly); + // The shared inbox is a founder inbox too: filed as FYI, not rejected. + expect( + agentLaunchInboxError(withLegacyPeerInboxReason({ inbox: "shared" as const }, true)), + ).toBeNull(); }); it("shows reason-less agent lanes only to the founder they were routed to, as FYI", () => { const people = [null, kameron, jeff] as const; diff --git a/packages/contracts/src/threadInbox.ts b/packages/contracts/src/threadInbox.ts index 0a7f4675d4534..c13d8c0ea84c8 100644 --- a/packages/contracts/src/threadInbox.ts +++ b/packages/contracts/src/threadInbox.ts @@ -207,7 +207,9 @@ export function withLegacyPeerInboxReason< }, >(input: T, legacyPeer: boolean): T { if (!legacyPeer || input.inboxRouting?.reason !== undefined) return input; - if (input.inbox === undefined && input.inboxRouting === undefined) return input; + // Only a route the strict guard would reject: one that reaches a founder or the shared inbox. + // A route that stays in Agents keeps no reason. + if (agentLaunchInboxError(input) === null) return input; return { ...input, inboxRouting: { ...input.inboxRouting, reason: "fyi" } }; }