The best way to control Claude Code, Codex and more from any computer or phone

main
ts 287 lines 10.8 KB
Raw
1 import {
2 type AuthMcpClientAccess,
3 type EnvironmentId,
4 McpCapabilityUnavailableError,
5 OrchestratorMcpFailure,
6 PreviewAutomationUnavailableError,
7 type ProviderInstanceId,
8 type ProviderInteractionMode,
9 type OrchestrationV2LinkedSender,
10 type RuntimeMode,
11 type ThreadId,
12 } from "@t3tools/contracts";
13 import * as Context from "effect/Context";
14 import type * as DateTime from "effect/DateTime";
15 import * as Effect from "effect/Effect";
16 import * as Fiber from "effect/Fiber";
17 import { formatThreadLink, hostedThreadLink } from "@t3tools/shared/threadLinks";
18
19 const ALL_MCP_CAPABILITIES = [
20 "preview",
21 "orchestration",
22 "worktree",
23 "device",
24 "pull-requests",
25 "issues",
26 "background-wait",
27 ] as const;
28 export type McpCapability = (typeof ALL_MCP_CAPABILITIES)[number];
29
30 export interface McpThreadCaller {
31 readonly threadId: ThreadId;
32 readonly providerSessionId: string;
33 readonly providerInstanceId: ProviderInstanceId;
34 /** A delegated child task; its parent owns the work it hands back. */
35 readonly subagent?: boolean;
36 }
37
38 export interface McpClientCaller {
39 readonly sessionId: string;
40 readonly label: string;
41 readonly access: AuthMcpClientAccess;
42 /**
43 * Another T3 Code environment's peer link. What it starts here carries its
44 * session as `linkOrigin`, and it changes only that work (`linkOrigin.ts`).
45 */
46 readonly linked?: boolean | undefined;
47 /** When a peer link's session ends unless it is used again, answered as `T3-Link-Expires-At`. */
48 readonly linkExpiresAt?: DateTime.Utc | undefined;
49 /**
50 * Narrower modes the client asked for on this request (`T3-Mode-Limit`):
51 * another environment passing on the limits of the agent it calls for.
52 */
53 readonly narrowedTo?: ClientModes | undefined;
54 /** A linked environment's thread this request is made for (`T3-Sender-Thread`). */
55 readonly senderThread?: OrchestrationV2LinkedSender | undefined;
56 /** An outside client's thread links go through this hosted app, as Copy thread's do. */
57 readonly hostedAppUrl?: string | undefined;
58 }
59
60 /**
61 * `T3-Mode-Limit: <runtimeMode>/<interactionMode>` lets an OAuth client cap
62 * a request below what it was approved with: another environment passes on
63 * the limits of the agent it calls for. It can only narrow (see
64 * `clientModeCeiling`), so a client gains nothing by sending a broad one.
65 */
66 export const MODE_LIMIT_HEADER = "t3-mode-limit";
67
68 /**
69 * `T3-Link-Expires-At: <ISO time>` answers a peer link's request with when its
70 * session now ends. Using a link renews it, so the linking side keeps this.
71 */
72 export const LINK_EXPIRES_AT_HEADER = "t3-link-expires-at";
73
74 /**
75 * `T3-Sender-Thread: <environmentId>/<threadId>/<title>`, each URI-encoded: the
76 * thread another environment makes a request for, so what it sends here can name
77 * it. Read only from a linked client.
78 */
79 export const SENDER_THREAD_HEADER = "t3-sender-thread";
80
81 export interface ClientModes {
82 readonly runtimeMode: RuntimeMode;
83 readonly interactionMode: ProviderInteractionMode;
84 }
85
86 const runtimeModeRank: Record<RuntimeMode, number> = {
87 "approval-required": 0,
88 "auto-accept-edits": 1,
89 auto: 2,
90 "full-access": 3,
91 };
92 const interactionModeRank: Record<ProviderInteractionMode, number> = { plan: 0, default: 1 };
93
94 /**
95 * The modes a client caller's writes are capped at: what it was approved
96 * with, narrowed by what it asked for on this request. A read-only client
97 * never reaches a write (`McpToolAccess` refuses it first), so it maps to the
98 * lowest runtime mode rather than to nothing.
99 */
100 export const clientModeCeiling = (client: McpClientCaller | undefined): ClientModes => {
101 const approved: ClientModes = {
102 runtimeMode:
103 client === undefined || client.access === "read-only" ? "approval-required" : client.access,
104 interactionMode: "default",
105 };
106 const asked = client?.narrowedTo;
107 if (asked === undefined) return approved;
108 return {
109 runtimeMode:
110 runtimeModeRank[asked.runtimeMode] < runtimeModeRank[approved.runtimeMode]
111 ? asked.runtimeMode
112 : approved.runtimeMode,
113 interactionMode:
114 interactionModeRank[asked.interactionMode] < interactionModeRank[approved.interactionMode]
115 ? asked.interactionMode
116 : approved.interactionMode,
117 };
118 };
119
120 /**
121 * A client approved above an administrator's runtime-mode ceiling acts as if it had narrowed
122 * itself to the ceiling, so what it starts and schedules is not refused for a mode it never chose.
123 */
124 export const withRuntimeModeCeiling = (
125 scope: McpInvocationScope,
126 ceiling: RuntimeMode | undefined,
127 ): McpInvocationScope => {
128 if (ceiling === undefined || scope.client === undefined) return scope;
129 const asked = scope.client.narrowedTo;
130 return {
131 ...scope,
132 client: {
133 ...scope.client,
134 narrowedTo: {
135 runtimeMode:
136 asked !== undefined && runtimeModeRank[asked.runtimeMode] < runtimeModeRank[ceiling]
137 ? asked.runtimeMode
138 : ceiling,
139 interactionMode: asked?.interactionMode ?? "default",
140 },
141 },
142 };
143 };
144
145 /** Thread callers default to their own thread; client callers need thread for tools that act as the caller. */
146 export interface McpInvocationScope {
147 readonly environmentId: EnvironmentId;
148 readonly capabilities: ReadonlySet<McpCapability>;
149 readonly issuedAt: number;
150 readonly requestNamespace: string;
151 readonly thread: McpThreadCaller | undefined;
152 readonly client: McpClientCaller | undefined;
153 /** False while the Linked environments beta is off here; `/mcp` reads it per request. */
154 readonly linkedEnvironments?: boolean;
155 /**
156 * The origin this `/mcp` request reached, e.g. a T3 Connect tunnel. Hosted clients cannot
157 * see the URL they were configured with, so links they must fetch carry it. Unset in-process.
158 */
159 readonly origin?: string | undefined;
160 /** False when the calling thread's project is on no forge T3 reads; `/mcp` reads it per request. */
161 readonly forge?: boolean;
162 }
163
164 /**
165 * T3 Code renders `t3-thread://` links as thread chips. Other MCP clients cannot open them, so
166 * they get the hosted link Copy thread copies, which opens the thread in either app or a browser.
167 * A known `title` labels the chip for clients that cannot load this environment's threads.
168 */
169 export const threadLinkFor = (
170 scope: Pick<McpInvocationScope, "environmentId" | "client">,
171 threadId: ThreadId,
172 title?: string,
173 ): string => {
174 const hostedAppUrl = scope.client?.hostedAppUrl;
175 const ref = { environmentId: scope.environmentId, threadId };
176 return hostedAppUrl === undefined
177 ? formatThreadLink(ref, title)
178 : hostedThreadLink(ref, hostedAppUrl);
179 };
180
181 export class McpInvocationContext extends Context.Service<
182 McpInvocationContext,
183 McpInvocationScope
184 >()("t3/mcp/McpInvocationContext") {}
185
186 /**
187 * `McpSchema.EnabledWhen` for tools a delegated child must not see or call.
188 * EnabledWhen only receives the MCP client profile, so read the T3 caller from the request fiber.
189 */
190 export const hiddenFromSubagents = (): boolean => {
191 const fiber = Fiber.getCurrent();
192 const scope = fiber && Context.getOrUndefined(fiber.context, McpInvocationContext);
193 return scope?.thread?.subagent !== true;
194 };
195
196 /**
197 * `McpSchema.EnabledWhen` for tools that act as the calling thread: a client
198 * from outside has none. Discovery only; `McpToolAccess` still refuses the
199 * call, and `toLayer` requires this on every thread-bound declaration.
200 */
201 export const hiddenFromOutsideClients = (): boolean => {
202 const fiber = Fiber.getCurrent();
203 const scope = fiber && Context.getOrUndefined(fiber.context, McpInvocationContext);
204 return scope === undefined || scope.thread !== undefined;
205 };
206
207 /** `hiddenFromOutsideClients`, and hidden from a thread whose provider cannot hold for background work. */
208 export const hiddenWithoutBackgroundWait = (): boolean => {
209 const fiber = Fiber.getCurrent();
210 const scope = fiber && Context.getOrUndefined(fiber.context, McpInvocationContext);
211 return (
212 scope === undefined || (scope.thread !== undefined && scope.capabilities.has("background-wait"))
213 );
214 };
215
216 /** `McpSchema.EnabledWhen` for tools that only serve links, hidden while the beta is off. */
217 export const hiddenWhileLinksOff = (): boolean => {
218 const fiber = Fiber.getCurrent();
219 const scope = fiber && Context.getOrUndefined(fiber.context, McpInvocationContext);
220 return scope?.linkedEnvironments !== false;
221 };
222
223 /** `McpSchema.EnabledWhen` for tools that act on the thread's forge, hidden where it has none. */
224 export const hiddenWithoutForge = (): boolean => {
225 const fiber = Fiber.getCurrent();
226 const scope = fiber && Context.getOrUndefined(fiber.context, McpInvocationContext);
227 return scope?.forge !== false;
228 };
229
230 export type McpCapabilityError<C extends McpCapability> = C extends "preview"
231 ? PreviewAutomationUnavailableError
232 : McpCapabilityUnavailableError;
233
234 const missingCapability = (
235 invocation: McpInvocationScope,
236 capability: McpCapability,
237 ): PreviewAutomationUnavailableError | McpCapabilityUnavailableError => {
238 const fields = {
239 environmentId: invocation.environmentId,
240 ...(invocation.thread === undefined
241 ? {}
242 : {
243 threadId: invocation.thread.threadId,
244 providerSessionId: invocation.thread.providerSessionId,
245 providerInstanceId: invocation.thread.providerInstanceId,
246 }),
247 };
248 return capability === "preview"
249 ? new PreviewAutomationUnavailableError({ capability, ...fields })
250 : new McpCapabilityUnavailableError({ capability, ...fields });
251 };
252
253 export const requireMcpCapability = <const C extends McpCapability>(
254 capability: C,
255 ): Effect.Effect<McpInvocationScope, McpCapabilityError<C>, McpInvocationContext> =>
256 McpInvocationContext.pipe(
257 Effect.filterOrFail(
258 (invocation) => invocation.capabilities.has(capability),
259 (invocation) => missingCapability(invocation, capability) as McpCapabilityError<C>,
260 ),
261 Effect.withSpan("mcp.requireCapability"),
262 );
263
264 export const requireThreadMcpCapability = <const C extends "preview" | "device">(
265 capability: C,
266 ): Effect.Effect<McpThreadInvocationScope, McpCapabilityError<C>, McpInvocationContext> =>
267 McpInvocationContext.pipe(
268 Effect.filterOrFail(
269 (invocation): invocation is McpThreadInvocationScope =>
270 invocation.capabilities.has(capability) && invocation.thread !== undefined,
271 (invocation) => missingCapability(invocation, capability) as McpCapabilityError<C>,
272 ),
273 Effect.withSpan("mcp.requireCapability"),
274 );
275
276 const threadCallerRequired = (operation: string) =>
277 new OrchestratorMcpFailure({
278 code: "thread_credential_required",
279 message: `${operation} acts as the calling T3 thread, so it needs an agent running inside T3 Code. This MCP client signed in from outside a thread.`,
280 });
281
282 export type McpThreadInvocationScope = McpInvocationScope & { readonly thread: McpThreadCaller };
283
284 export const requireThreadScope = (scope: McpInvocationScope, operation: string) =>
285 scope.thread === undefined
286 ? Effect.fail(threadCallerRequired(operation))
287 : Effect.succeed(scope as McpThreadInvocationScope);