@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 03:37 UTC

main
ts 1,009 lines 40.1 KB
Raw
1 import * as Effect from "effect/Effect";
2 import * as Schema from "effect/Schema";
3 import * as SchemaTransformation from "effect/SchemaTransformation";
4
5 import { AuthMcpClientAccess } from "./auth.ts";
6 import {
7 ContextTransferId,
8 EnvironmentId,
9 IsoDateTime,
10 MessageId,
11 NodeId,
12 NonNegativeInt,
13 PositiveInt,
14 ProjectId,
15 RunId,
16 RuntimeRequestId,
17 ScheduledTaskId,
18 SecretRef,
19 ThreadId,
20 TrimmedNonEmptyString,
21 TurnItemId,
22 } from "./baseSchemas.ts";
23 import {
24 ScheduledTaskRunStatus,
25 ScheduledTaskSchedule,
26 ScheduledTaskUpsertSchedule,
27 } from "./scheduledTask.ts";
28 import { ProviderInteractionMode, ProviderRequestKind, RuntimeMode } from "./providerPolicy.ts";
29 import { PullRequestState } from "./pullRequest.ts";
30 import {
31 ThreadLinkedPullRequest,
32 ThreadPullRequestKey,
33 ThreadPullRequestLinkSource,
34 } from "./threadPullRequest.ts";
35 import { secretRequestPageUrl } from "./secretRequest.ts";
36 import { hasOnlyPairedSurrogates } from "./threadMetadataMcp.ts";
37 import { LastThreadTitleRegeneration, ThreadTitleRegeneration } from "./threadTitle.ts";
38 import {
39 OrchestrationV2Actor,
40 OrchestrationV2CreationSource,
41 OrchestrationV2DelegatedFrom,
42 OrchestrationV2RunStatus,
43 OrchestrationV2TurnItemStatus,
44 } from "./orchestrationV2.ts";
45 import { ProviderOptionSelection, ProviderOptionSelectionValue } from "./model.ts";
46 import { ProviderDriverKind, ProviderInstanceId } from "./providerInstance.ts";
47
48 const OrchestratorMcpPrompt = TrimmedNonEmptyString.check(Schema.isMaxLength(120_000));
49 const OrchestratorMcpTitle = TrimmedNonEmptyString.check(Schema.isMaxLength(512));
50 export const OrchestratorMcpClientRequestId = TrimmedNonEmptyString.check(Schema.isMaxLength(256))
51 .check(
52 Schema.makeFilter((value) =>
53 hasOnlyPairedSurrogates(value)
54 ? true
55 : "clientRequestId must contain valid paired Unicode surrogates.",
56 ),
57 )
58 .annotate({ description: "Reuse it to retry the same call. A new call gets a new key." });
59
60 // OpenCode 1.15 serializes nested MCP union objects as JSON strings; decode that form at the boundary.
61 const OrchestratorMcpScheduleFromJsonString = Schema.fromJsonString(
62 ScheduledTaskUpsertSchedule,
63 ).annotate({
64 description: "JSON-text schedule. Prefer the object form.",
65 });
66
67 const OrchestratorMcpSchedule = Schema.Union([
68 ScheduledTaskUpsertSchedule,
69 OrchestratorMcpScheduleFromJsonString,
70 ]).annotate({
71 description:
72 "Trigger: {type:'interval',everyMs}, {type:'fixed_time',timeOfDay,weekdays?}, {type:'once',runAt}, or {type:'webhook'}.",
73 });
74
75 const OrchestratorMcpTargetOptionsFromRecord = Schema.Record(
76 Schema.String,
77 ProviderOptionSelectionValue,
78 ).pipe(
79 Schema.decodeTo(
80 Schema.Array(ProviderOptionSelection),
81 SchemaTransformation.transformEffect({
82 decode: (record) =>
83 Effect.succeed(Object.entries(record).map(([id, value]) => ({ id, value }))),
84 encode: (selections: ReadonlyArray<ProviderOptionSelection>) =>
85 Effect.succeed(
86 Object.fromEntries(selections.map((selection) => [selection.id, selection.value])),
87 ),
88 }),
89 ),
90 );
91
92 export const OrchestratorMcpTargetOptions = Schema.Union([
93 Schema.Array(ProviderOptionSelection),
94 OrchestratorMcpTargetOptionsFromRecord,
95 ]);
96 export type OrchestratorMcpTargetOptions = typeof OrchestratorMcpTargetOptions.Type;
97
98 export const OrchestratorMcpTarget = Schema.Struct({
99 providerInstanceId: Schema.optional(
100 ProviderInstanceId.annotate({
101 description: "Provider instance id from `orchestrator_capabilities`.",
102 }),
103 ),
104 driverKind: Schema.optional(
105 ProviderDriverKind.annotate({
106 description: "Prefer `providerInstanceId`.",
107 }),
108 ),
109 model: Schema.optional(TrimmedNonEmptyString),
110 options: Schema.optional(
111 OrchestratorMcpTargetOptions.annotate({
112 description:
113 "Options from `orchestrator_capabilities`, such as {effort:'max'}. Given values override inherited. [] or {} clears.",
114 }),
115 ),
116 environmentId: Schema.optional(
117 EnvironmentId.annotate({
118 description:
119 "Linked environment to run in. Provider and model default to yours; others come from `orchestrator_capabilities` with this `environmentId`.",
120 }),
121 ),
122 projectId: Schema.optional(
123 ProjectId.annotate({
124 description:
125 "With `environmentId`: its project to run in. Default: the one with this project's repository.",
126 }),
127 ),
128 });
129 export type OrchestratorMcpTarget = typeof OrchestratorMcpTarget.Type;
130
131 export const OrchestratorMcpRuntimeMode = Schema.Union([Schema.Literal("inherit"), RuntimeMode]);
132 export type OrchestratorMcpRuntimeMode = typeof OrchestratorMcpRuntimeMode.Type;
133
134 export const OrchestratorMcpInteractionMode = Schema.Union([
135 Schema.Literal("inherit"),
136 ProviderInteractionMode,
137 ]);
138 export type OrchestratorMcpInteractionMode = typeof OrchestratorMcpInteractionMode.Type;
139
140 export const OrchestratorMcpTaskRole = Schema.Literals([
141 "implementation",
142 "research",
143 "review",
144 "design",
145 "test",
146 "general",
147 ]);
148 export type OrchestratorMcpTaskRole = typeof OrchestratorMcpTaskRole.Type;
149
150 export const OrchestratorMcpDelegatedTaskStatus = Schema.Literals([
151 "queued",
152 "starting",
153 "running",
154 "waiting",
155 "completed",
156 "failed",
157 "cancelled",
158 "interrupted",
159 ]);
160 export type OrchestratorMcpDelegatedTaskStatus = typeof OrchestratorMcpDelegatedTaskStatus.Type;
161
162 export const OrchestratorMcpTerminalDelegatedTaskStatus = Schema.Literals([
163 "completed",
164 "failed",
165 "cancelled",
166 "interrupted",
167 ]);
168 export type OrchestratorMcpTerminalDelegatedTaskStatus =
169 typeof OrchestratorMcpTerminalDelegatedTaskStatus.Type;
170
171 export const OrchestratorMcpDelegateTaskInput = Schema.Struct({
172 task: OrchestratorMcpPrompt,
173 // Some providers send the whole target object as JSON text.
174 target: Schema.optional(
175 Schema.Union([OrchestratorMcpTarget, Schema.fromJsonString(OrchestratorMcpTarget)]),
176 ),
177 title: Schema.optional(OrchestratorMcpTitle),
178 role: Schema.optional(OrchestratorMcpTaskRole),
179 isolation: Schema.optional(
180 Schema.Literals(["shared", "worktree"]).annotate({
181 description:
182 "'shared' (default): parent checkout. 'worktree': new prepared checkout from the parent commit, for a separate checkout or PR per child. Uncommitted edits stay out.",
183 }),
184 ),
185 mode: Schema.optional(
186 Schema.Literals(["async", "wait"]).annotate({
187 description:
188 "Default 'async'. 'wait' only if this turn needs the result. A question or approval ends the wait.",
189 }),
190 ),
191 timeoutMs: Schema.optional(Schema.Finite).annotate({
192 description: "Mode 'wait' only. At most 45 s. A timeout does not cancel the child.",
193 }),
194 clientRequestId: Schema.optional(OrchestratorMcpClientRequestId),
195 runtimeMode: Schema.optional(
196 OrchestratorMcpRuntimeMode.annotate({
197 description:
198 "Omit unless the user asks for a supervised child. Narrow modes pause for human approval, not read-only. Above yours is rejected.",
199 }),
200 ),
201 interactionMode: Schema.optional(OrchestratorMcpInteractionMode),
202 });
203 export type OrchestratorMcpDelegateTaskInput = typeof OrchestratorMcpDelegateTaskInput.Type;
204
205 // Set only on results for still-running tasks whose completion will wake the parent.
206 export const ORCHESTRATOR_MCP_RUNNING_TASK_NEXT =
207 "Completion wakes this thread. Do not wait on it or poll it. Continue other work, and end your turn when none is left.";
208 // A string, not a literal: linked environments on other versions send their own wording.
209 const OrchestratorMcpRunningTaskNext = Schema.String;
210
211 // Optional: linked environments on older versions omit it.
212 const OrchestratorMcpExecutedModel = Schema.NullOr(Schema.String).annotate({
213 description:
214 "Model the provider reported running, or null when unavailable. Can differ from the requested `model`.",
215 });
216
217 export const OrchestratorMcpDelegateTaskResult = Schema.Struct({
218 taskId: NodeId,
219 /** Null for a task that runs in a linked environment; see `remoteChild`. */
220 childThreadId: Schema.NullOr(ThreadId),
221 /** The linked environment and thread a remote task runs as. */
222 remoteChild: Schema.optional(
223 Schema.Struct({ environmentId: EnvironmentId, threadId: ThreadId, label: Schema.String }),
224 ),
225 link: Schema.optional(Schema.String),
226 childRunId: Schema.NullOr(RunId),
227 childNodeId: NodeId,
228 status: OrchestratorMcpDelegatedTaskStatus.annotate({
229 description:
230 "starting means the child's provider has not started its turn yet, so no work has begun.",
231 }),
232 workState: Schema.Literals(["working", "waiting_for_children", "result_available"]),
233 hasPendingChildRuns: Schema.Boolean,
234 latestTerminalRunId: Schema.NullOr(RunId),
235 latestTerminalStatus: Schema.NullOr(OrchestratorMcpTerminalDelegatedTaskStatus),
236 latestTerminalSummary: Schema.NullOr(Schema.String),
237 latestTerminalResultContextTransferId: Schema.NullOr(ContextTransferId),
238 providerInstanceId: ProviderInstanceId,
239 model: Schema.NullOr(Schema.String),
240 executedModel: Schema.optional(OrchestratorMcpExecutedModel),
241 options: Schema.optional(Schema.Array(ProviderOptionSelection)),
242 summary: Schema.NullOr(Schema.String),
243 resultContextTransferId: Schema.NullOr(ContextTransferId),
244 hasPendingQuestion: Schema.Boolean.annotate({
245 description:
246 "A question blocks the child and ends a wait. Answer via `t3_pending_request` on `childThreadId`, or the user does.",
247 }),
248 pendingApproval: Schema.NullOr(
249 Schema.Struct({ requestId: RuntimeRequestId, kind: ProviderRequestKind, runId: RunId }),
250 ).annotate({
251 description: "Oldest pending approval, or null. Ends a wait. Grants no approval rights.",
252 }),
253 waitTimedOut: Schema.Boolean.annotate({
254 description: "True only on the timed-out wait call. The child keeps running.",
255 }),
256 next: Schema.optional(OrchestratorMcpRunningTaskNext),
257 });
258 export type OrchestratorMcpDelegateTaskResult = typeof OrchestratorMcpDelegateTaskResult.Type;
259
260 export const OrchestratorMcpTaskStatusInput = Schema.Struct({
261 taskId: NodeId,
262 });
263 export type OrchestratorMcpTaskStatusInput = typeof OrchestratorMcpTaskStatusInput.Type;
264
265 export const OrchestratorMcpTaskCancelInput = Schema.Struct({
266 taskId: NodeId,
267 reason: Schema.optional(Schema.String.check(Schema.isMaxLength(2_000))),
268 clientRequestId: Schema.optional(OrchestratorMcpClientRequestId),
269 });
270 export type OrchestratorMcpTaskCancelInput = typeof OrchestratorMcpTaskCancelInput.Type;
271
272 export const OrchestratorMcpTaskCancelResult = Schema.Struct({
273 taskId: NodeId,
274 status: Schema.Literals(["cancel_requested", "completed", "failed", "cancelled", "interrupted"]),
275 });
276 export type OrchestratorMcpTaskCancelResult = typeof OrchestratorMcpTaskCancelResult.Type;
277
278 export const OrchestratorMcpCreateThreadRequest = Schema.Struct({
279 prompt: Schema.optional(OrchestratorMcpPrompt),
280 title: Schema.optional(OrchestratorMcpTitle),
281 target: Schema.optional(OrchestratorMcpTarget),
282 runtimeMode: Schema.optional(OrchestratorMcpRuntimeMode),
283 interactionMode: Schema.optional(OrchestratorMcpInteractionMode),
284 });
285 export type OrchestratorMcpCreateThreadRequest = typeof OrchestratorMcpCreateThreadRequest.Type;
286
287 export const OrchestratorMcpCreateThreadsInput = Schema.Struct({
288 threads: Schema.Array(OrchestratorMcpCreateThreadRequest).check(
289 Schema.isMinLength(1),
290 Schema.isMaxLength(20),
291 ),
292 clientRequestId: Schema.optional(OrchestratorMcpClientRequestId),
293 });
294 export type OrchestratorMcpCreateThreadsInput = typeof OrchestratorMcpCreateThreadsInput.Type;
295
296 export const OrchestratorMcpCreatedThreadStatus = Schema.Union([
297 Schema.Literal("idle"),
298 Schema.Literal("preparing"),
299 OrchestratorMcpDelegatedTaskStatus,
300 Schema.Literal("rolled_back"),
301 ]);
302 export type OrchestratorMcpCreatedThreadStatus = typeof OrchestratorMcpCreatedThreadStatus.Type;
303
304 export const OrchestratorMcpCreatedThread = Schema.Struct({
305 threadId: ThreadId,
306 link: Schema.optional(Schema.String),
307 runId: Schema.NullOr(RunId),
308 status: OrchestratorMcpCreatedThreadStatus,
309 title: Schema.String,
310 createdBy: OrchestrationV2Actor,
311 creationSource: OrchestrationV2CreationSource,
312 providerInstanceId: ProviderInstanceId,
313 model: Schema.String,
314 });
315 export type OrchestratorMcpCreatedThread = typeof OrchestratorMcpCreatedThread.Type;
316
317 export const OrchestratorMcpCreateThreadsResult = Schema.Struct({
318 threads: Schema.Array(OrchestratorMcpCreatedThread),
319 });
320 export type OrchestratorMcpCreateThreadsResult = typeof OrchestratorMcpCreateThreadsResult.Type;
321
322 export const OrchestratorMcpThreadStatus = Schema.Union([
323 Schema.Literal("idle"),
324 OrchestrationV2RunStatus,
325 ]);
326 export type OrchestratorMcpThreadStatus = typeof OrchestratorMcpThreadStatus.Type;
327
328 const OrchestratorMcpProjectTarget = Schema.optional(
329 ProjectId.annotate({
330 description: "Project to use. Default: your thread's project. Required outside a thread.",
331 }),
332 );
333
334 /**
335 * A linked environment to act in instead of this one. The tools that take it
336 * forward the call there, where the link's access and the caller's own modes
337 * both apply.
338 */
339 export const OrchestratorMcpEnvironmentTarget = Schema.optional(
340 EnvironmentId.annotate({
341 description:
342 "Linked environment to act in. Omit for this one. Ids are then that environment's.",
343 }),
344 );
345
346 // Codex hides `minimum` and `maximum` from the model, so a value above the maximum clamps on
347 // decode instead of failing the call; pagination returns the rest. Values below 1 still fail:
348 // 0 asks for nothing, and answering it with one item would be a different request.
349 export const clampedPositiveInt = (maximum: number) =>
350 PositiveInt.pipe(
351 Schema.decodeTo(
352 PositiveInt.check(Schema.isLessThanOrEqualTo(maximum)),
353 SchemaTransformation.transform({
354 decode: (value) => Math.min(value, maximum),
355 encode: (value) => value,
356 }),
357 ),
358 );
359
360 export const OrchestratorMcpThreadListInput = Schema.Struct({
361 environmentId: OrchestratorMcpEnvironmentTarget,
362 projectId: OrchestratorMcpProjectTarget,
363 allProjects: Schema.optional(Schema.Boolean),
364 statuses: Schema.optional(
365 Schema.Array(OrchestratorMcpThreadStatus).check(Schema.isMaxLength(10)),
366 ),
367 titleContains: Schema.optional(TrimmedNonEmptyString.check(Schema.isMaxLength(256))),
368 settled: Schema.optional(Schema.Boolean),
369 snoozed: Schema.optional(Schema.Boolean),
370 includeSubagents: Schema.optional(Schema.Boolean),
371 cursor: Schema.optional(NonNegativeInt),
372 limit: Schema.optional(clampedPositiveInt(100)),
373 });
374 export type OrchestratorMcpThreadListInput = typeof OrchestratorMcpThreadListInput.Type;
375
376 /** state is null until the host is read. */
377 export const OrchestratorMcpThreadPullRequest = Schema.Struct({
378 ...ThreadPullRequestKey.fields,
379 url: TrimmedNonEmptyString,
380 source: ThreadPullRequestLinkSource,
381 state: Schema.NullOr(PullRequestState),
382 watching: Schema.Boolean,
383 watchStartedAt: Schema.NullOr(IsoDateTime),
384 });
385 export type OrchestratorMcpThreadPullRequest = typeof OrchestratorMcpThreadPullRequest.Type;
386
387 /** Background work still open on the thread, as its provider reported it. */
388 export const OrchestratorMcpThreadBackgroundTask = Schema.Struct({
389 taskId: TrimmedNonEmptyString,
390 kind: Schema.Literals(["subagent", "command", "monitor", "background_task"]),
391 description: Schema.optional(TrimmedNonEmptyString),
392 /** The agent waits on this command or monitor. Other kinds always hold the thread. */
393 awaited: Schema.optional(Schema.Literal(true)),
394 childThreadId: Schema.optional(ThreadId),
395 });
396 export type OrchestratorMcpThreadBackgroundTask = typeof OrchestratorMcpThreadBackgroundTask.Type;
397
398 export const OrchestratorMcpThreadListItem = Schema.Struct({
399 threadId: ThreadId,
400 projectId: ProjectId,
401 title: Schema.String,
402 link: Schema.optional(Schema.String),
403 createdBy: OrchestrationV2Actor,
404 creationSource: OrchestrationV2CreationSource,
405 status: OrchestratorMcpThreadStatus,
406 latestRunId: Schema.NullOr(RunId),
407 providerInstanceId: ProviderInstanceId,
408 model: Schema.String,
409 runtimeMode: RuntimeMode,
410 interactionMode: ProviderInteractionMode,
411 linkedPullRequest: Schema.NullOr(ThreadLinkedPullRequest),
412 /** Up to 5 open linked pull requests, watched first; list_thread_pull_requests pages all of them. */
413 pullRequests: Schema.optional(Schema.Array(OrchestratorMcpThreadPullRequest)),
414 pullRequestCount: Schema.optional(NonNegativeInt),
415 openPullRequestCount: Schema.optional(NonNegativeInt),
416 settled: Schema.Boolean,
417 settledAt: Schema.NullOr(IsoDateTime),
418 snoozed: Schema.Boolean,
419 snoozedUntil: Schema.NullOr(IsoDateTime),
420 /** Absent from linked environments that predate it. */
421 pinned: Schema.optional(Schema.Boolean),
422 /** Absent from linked environments that predate it. */
423 blockedOnThreadWait: Schema.optional(Schema.Boolean),
424 /** Absent from linked environments that predate it. */
425 pendingBackgroundTasks: Schema.optional(Schema.Array(OrchestratorMcpThreadBackgroundTask)),
426 parentThreadId: Schema.NullOr(ThreadId),
427 relationshipToParent: Schema.NullOr(Schema.Literals(["fork", "subagent"])),
428 /** The linked environment's thread that delegated this one; absent otherwise. */
429 delegatedFrom: Schema.optional(OrchestrationV2DelegatedFrom),
430 itemCount: NonNegativeInt,
431 createdAt: IsoDateTime,
432 updatedAt: IsoDateTime,
433 });
434 export type OrchestratorMcpThreadListItem = typeof OrchestratorMcpThreadListItem.Type;
435
436 export const OrchestratorMcpThreadListResult = Schema.Struct({
437 /** null with `allProjects`. */
438 projectId: Schema.NullOr(ProjectId),
439 currentThreadId: Schema.NullOr(ThreadId),
440 threads: Schema.Array(OrchestratorMcpThreadListItem),
441 nextCursor: Schema.NullOr(NonNegativeInt),
442 total: NonNegativeInt,
443 });
444 export type OrchestratorMcpThreadListResult = typeof OrchestratorMcpThreadListResult.Type;
445
446 export const OrchestratorMcpThreadReadInput = Schema.Struct({
447 environmentId: OrchestratorMcpEnvironmentTarget,
448 threadId: ThreadId,
449 itemId: Schema.optional(TurnItemId),
450 textOffset: Schema.optional(NonNegativeInt),
451 view: Schema.optional(Schema.Literals(["messages", "activity"])),
452 afterPosition: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(-1))),
453 beforePosition: Schema.optional(NonNegativeInt),
454 limit: Schema.optional(clampedPositiveInt(100)).annotate({ description: "Max 100." }),
455 runLimit: Schema.optional(clampedPositiveInt(50)).annotate({ description: "Max 50." }),
456 maxCharsPerItem: Schema.optional(clampedPositiveInt(20_000)).annotate({
457 description: "Max 20000.",
458 }),
459 });
460 export type OrchestratorMcpThreadReadInput = typeof OrchestratorMcpThreadReadInput.Type;
461
462 export const OrchestratorMcpThreadDetail = Schema.Struct({
463 threadId: ThreadId,
464 projectId: ProjectId,
465 title: Schema.String,
466 link: Schema.optional(Schema.String),
467 createdBy: OrchestrationV2Actor,
468 creationSource: OrchestrationV2CreationSource,
469 status: OrchestratorMcpThreadStatus,
470 latestRunId: Schema.NullOr(RunId),
471 activeRunId: Schema.NullOr(RunId),
472 providerInstanceId: ProviderInstanceId,
473 model: Schema.String,
474 runtimeMode: RuntimeMode,
475 interactionMode: ProviderInteractionMode,
476 linkedPullRequest: Schema.NullOr(ThreadLinkedPullRequest),
477 /** Up to 5 open linked pull requests, watched first, on the first page only; list_thread_pull_requests pages all of them. */
478 pullRequests: Schema.optional(Schema.Array(OrchestratorMcpThreadPullRequest)),
479 pullRequestCount: Schema.optional(NonNegativeInt),
480 openPullRequestCount: Schema.optional(NonNegativeInt),
481 titleRegeneration: Schema.NullOr(ThreadTitleRegeneration),
482 lastTitleRegeneration: Schema.optional(Schema.NullOr(LastThreadTitleRegeneration)),
483 branch: Schema.NullOr(Schema.String),
484 worktreePath: Schema.NullOr(Schema.String),
485 parentThreadId: Schema.NullOr(ThreadId),
486 relationshipToParent: Schema.NullOr(Schema.Literals(["fork", "subagent"])),
487 /** The linked environment's thread that delegated this one; absent otherwise. */
488 delegatedFrom: Schema.optional(OrchestrationV2DelegatedFrom),
489 runCount: NonNegativeInt,
490 itemCount: NonNegativeInt,
491 pendingRequestCount: NonNegativeInt,
492 archived: Schema.Boolean,
493 settled: Schema.Boolean,
494 settledAt: Schema.NullOr(IsoDateTime),
495 snoozed: Schema.Boolean,
496 snoozedUntil: Schema.NullOr(IsoDateTime),
497 /** Absent from linked environments that predate it. */
498 pinned: Schema.optional(Schema.Boolean),
499 /** Absent from linked environments that predate it. */
500 blockedOnThreadWait: Schema.optional(Schema.Boolean),
501 /** Absent from linked environments that predate it. */
502 pendingBackgroundTasks: Schema.optional(Schema.Array(OrchestratorMcpThreadBackgroundTask)),
503 createdAt: IsoDateTime,
504 updatedAt: IsoDateTime,
505 });
506 export type OrchestratorMcpThreadDetail = typeof OrchestratorMcpThreadDetail.Type;
507
508 export const OrchestratorMcpThreadRun = Schema.Struct({
509 runId: RunId,
510 ordinal: PositiveInt,
511 status: OrchestrationV2RunStatus,
512 providerInstanceId: ProviderInstanceId,
513 model: Schema.String,
514 executedModel: Schema.optional(OrchestratorMcpExecutedModel),
515 requestedAt: IsoDateTime,
516 startedAt: Schema.NullOr(IsoDateTime),
517 completedAt: Schema.NullOr(IsoDateTime),
518 });
519 export type OrchestratorMcpThreadRun = typeof OrchestratorMcpThreadRun.Type;
520
521 export const OrchestratorMcpThreadTimelineItem = Schema.Struct({
522 position: NonNegativeInt,
523 visibility: Schema.Literals(["local", "inherited", "synthetic"]),
524 sourceThreadId: ThreadId,
525 itemId: TurnItemId,
526 subagentId: Schema.optional(NodeId),
527 runId: Schema.NullOr(RunId),
528 messageId: Schema.NullOr(MessageId),
529 createdBy: Schema.NullOr(OrchestrationV2Actor),
530 creationSource: Schema.NullOr(OrchestrationV2CreationSource),
531 senderThreadId: Schema.optional(ThreadId),
532 type: Schema.String,
533 status: OrchestrationV2TurnItemStatus,
534 title: Schema.NullOr(Schema.String),
535 text: Schema.NullOr(Schema.String),
536 textTruncated: Schema.Boolean,
537 nextTextOffset: Schema.optional(Schema.NullOr(NonNegativeInt)),
538 updatedAt: IsoDateTime,
539 });
540 export type OrchestratorMcpThreadTimelineItem = typeof OrchestratorMcpThreadTimelineItem.Type;
541
542 export const OrchestratorMcpThreadReadResult = Schema.Struct({
543 thread: OrchestratorMcpThreadDetail,
544 recentRuns: Schema.Array(OrchestratorMcpThreadRun),
545 items: Schema.Array(OrchestratorMcpThreadTimelineItem),
546 nextPosition: Schema.NullOr(NonNegativeInt),
547 hasMore: Schema.Boolean,
548 /** null when nothing is older than the page. Missing from peers that only read forward. */
549 earlierPosition: Schema.optional(Schema.NullOr(NonNegativeInt)),
550 });
551 export type OrchestratorMcpThreadReadResult = typeof OrchestratorMcpThreadReadResult.Type;
552
553 export const OrchestratorMcpThreadSendInput = Schema.Struct({
554 environmentId: OrchestratorMcpEnvironmentTarget,
555 threadId: ThreadId,
556 message: OrchestratorMcpPrompt,
557 mode: Schema.optional(Schema.Literals(["auto", "queue", "steer", "restart"])),
558 freshContext: Schema.optional(
559 Schema.Boolean.annotate({
560 description:
561 "Start a new provider session without the thread's earlier context, like /clear. Never steers.",
562 }),
563 ),
564 outputSchema: Schema.optional(
565 Schema.Record(Schema.String, Schema.Json).annotate({
566 description:
567 "JSON Schema for a result the turn must return as data, read back as `output` from `t3_thread_wait`. Never steers.",
568 }),
569 ),
570 clientRequestId: Schema.optional(OrchestratorMcpClientRequestId),
571 });
572 export type OrchestratorMcpThreadSendInput = typeof OrchestratorMcpThreadSendInput.Type;
573
574 export const OrchestratorMcpThreadSendResult = Schema.Struct({
575 threadId: ThreadId,
576 link: Schema.optional(Schema.String),
577 messageId: MessageId,
578 runId: RunId,
579 taskId: Schema.optional(NodeId),
580 status: OrchestrationV2RunStatus,
581 delivery: Schema.Literals(["started", "queued", "steered", "restarted"]),
582 });
583 export type OrchestratorMcpThreadSendResult = typeof OrchestratorMcpThreadSendResult.Type;
584
585 export const OrchestratorMcpThreadWaitInput = Schema.Struct({
586 environmentId: OrchestratorMcpEnvironmentTarget,
587 threadId: ThreadId,
588 runId: Schema.optional(RunId),
589 timeoutMs: Schema.optional(Schema.Finite),
590 untilDelegatedWorkSettled: Schema.optional(
591 Schema.Boolean.annotate({
592 description:
593 "Also wait for its delegated and background tasks and their completions to settle. `resultRun` then names the run with its final answer.",
594 }),
595 ),
596 untilOutput: Schema.optional(
597 Schema.Boolean.annotate({
598 description:
599 "Also wait for the `output` the run was asked for, which a later turn may submit.",
600 }),
601 ),
602 });
603 export type OrchestratorMcpThreadWaitInput = typeof OrchestratorMcpThreadWaitInput.Type;
604
605 export const OrchestratorMcpThreadWaitResult = Schema.Struct({
606 threadId: ThreadId,
607 runId: Schema.NullOr(RunId),
608 status: OrchestratorMcpThreadStatus,
609 timedOut: Schema.Boolean,
610 next: Schema.optional(OrchestratorMcpRunningTaskNext),
611 /** With untilDelegatedWorkSettled, once settled: the run whose reply is the thread's result. */
612 resultRun: Schema.optional(Schema.Struct({ runId: RunId, status: OrchestrationV2RunStatus })),
613 /** What the run returned against the `outputSchema` it was sent with. Absent until submitted. */
614 output: Schema.optional(Schema.Json),
615 });
616 export type OrchestratorMcpThreadWaitResult = typeof OrchestratorMcpThreadWaitResult.Type;
617
618 export const OrchestratorMcpThreadInterruptInput = Schema.Struct({
619 environmentId: OrchestratorMcpEnvironmentTarget,
620 threadId: ThreadId,
621 runId: Schema.optional(RunId),
622 reason: Schema.optional(Schema.String.check(Schema.isMaxLength(2_000))),
623 /**
624 * Stop the thread as its Stop button does instead: interrupt its running
625 * turn whichever run that is, hold its queued messages, end its pull request
626 * watches and stop every task it delegated. `runId` is then not used.
627 */
628 stop: Schema.optional(Schema.Boolean),
629 clientRequestId: Schema.optional(OrchestratorMcpClientRequestId),
630 });
631 export type OrchestratorMcpThreadInterruptInput = typeof OrchestratorMcpThreadInterruptInput.Type;
632
633 export const OrchestratorMcpThreadInterruptResult = Schema.Struct({
634 threadId: ThreadId,
635 runId: Schema.NullOr(RunId),
636 status: Schema.Union([
637 Schema.Literal("interrupt_requested"),
638 Schema.Literal("no_active_run"),
639 Schema.Literals(["completed", "failed", "cancelled", "interrupted", "rolled_back"]),
640 ]),
641 });
642 export type OrchestratorMcpThreadInterruptResult = typeof OrchestratorMcpThreadInterruptResult.Type;
643
644 export const OrchestratorMcpCapabilitiesInput = Schema.Struct({
645 environmentId: OrchestratorMcpEnvironmentTarget,
646 search: Schema.optional(
647 TrimmedNonEmptyString.check(Schema.isMaxLength(200)).annotate({
648 description: "Match model ids and labels. Replaces the short list.",
649 }),
650 ),
651 });
652 export type OrchestratorMcpCapabilitiesInput = typeof OrchestratorMcpCapabilitiesInput.Type;
653
654 export const OrchestratorMcpModelOption = Schema.Struct({
655 id: Schema.String,
656 values: Schema.Array(ProviderOptionSelectionValue),
657 default: Schema.optional(ProviderOptionSelectionValue),
658 });
659 export type OrchestratorMcpModelOption = typeof OrchestratorMcpModelOption.Type;
660
661 export const OrchestratorMcpProviderCapability = Schema.Struct({
662 providerInstanceId: ProviderInstanceId,
663 driverKind: ProviderDriverKind,
664 displayName: Schema.NullOr(Schema.String),
665 models: Schema.Array(
666 Schema.Struct({
667 id: Schema.String,
668 /** Omitted when it only restates the id. */
669 label: Schema.optional(Schema.String),
670 options: Schema.optional(Schema.Array(OrchestratorMcpModelOption)),
671 }),
672 ),
673 /** Models left out of `models`: unlisted visible models, or matches past the cap with `search`. */
674 omittedModels: Schema.optional(NonNegativeInt),
675 runtimeModes: Schema.optional(Schema.Array(RuntimeMode)),
676 canRunChildTask: Schema.Boolean,
677 canRunCrossProviderChildTask: Schema.Boolean,
678 constraints: Schema.Array(Schema.String),
679 });
680 export type OrchestratorMcpProviderCapability = typeof OrchestratorMcpProviderCapability.Type;
681
682 export const OrchestratorMcpEnvironmentLink = Schema.Struct({
683 environmentId: EnvironmentId,
684 label: Schema.String,
685 /** Whether it answered just now. An expired link must be linked again there. */
686 status: Schema.Literals(["reachable", "unreachable", "expired"]),
687 /** The most the linked environment lets this one's agents do there. */
688 access: AuthMcpClientAccess,
689 expiresAt: IsoDateTime,
690 lastError: Schema.NullOr(Schema.String),
691 });
692 export type OrchestratorMcpEnvironmentLink = typeof OrchestratorMcpEnvironmentLink.Type;
693
694 export const OrchestratorMcpEnvironmentLinksResult = Schema.Struct({
695 environmentId: EnvironmentId,
696 links: Schema.Array(OrchestratorMcpEnvironmentLink),
697 /** What to do when the machine the user means is not among `links`. */
698 notListed: Schema.String,
699 });
700 export type OrchestratorMcpEnvironmentLinksResult =
701 typeof OrchestratorMcpEnvironmentLinksResult.Type;
702
703 export const OrchestratorMcpCapabilitiesResult = Schema.Struct({
704 parentThreadId: Schema.NullOr(ThreadId),
705 inheritedProviderInstanceId: Schema.NullOr(ProviderInstanceId),
706 inheritedModel: Schema.NullOr(Schema.String),
707 inheritedOptions: Schema.optional(Schema.Array(ProviderOptionSelection)),
708 runtimeMode: RuntimeMode,
709 interactionMode: ProviderInteractionMode,
710 providers: Schema.Array(OrchestratorMcpProviderCapability),
711 features: Schema.Struct({
712 appOwnedSubagents: Schema.Boolean,
713 asyncPolling: Schema.Boolean,
714 cancellation: Schema.Boolean,
715 batchThreadCreation: Schema.Boolean,
716 threadManagement: Schema.Boolean,
717 incrementalThreadRead: Schema.Boolean,
718 scheduledTasks: Schema.Boolean,
719 maxBatchThreads: Schema.Number,
720 }),
721 });
722 export type OrchestratorMcpCapabilitiesResult = typeof OrchestratorMcpCapabilitiesResult.Type;
723
724 export const OrchestratorMcpScheduleTaskInput = Schema.Struct({
725 environmentId: OrchestratorMcpEnvironmentTarget,
726 projectId: OrchestratorMcpProjectTarget,
727 prompt: OrchestratorMcpPrompt,
728 schedule: OrchestratorMcpSchedule,
729 title: Schema.optional(OrchestratorMcpTitle),
730 enabled: Schema.optional(Schema.Boolean.annotate({ description: "Default true." })),
731 bindToCurrentThread: Schema.optional(
732 Schema.Boolean.annotate({
733 description:
734 "Post here, else new thread per run. Unset: true in own project, else false; updates keep it.",
735 }),
736 ),
737 freshSession: Schema.optional(
738 Schema.Boolean.annotate({
739 description:
740 "Runs share one thread but each starts a fresh session. Unbound: the first run makes the thread.",
741 }),
742 ),
743 clientRequestId: Schema.optional(OrchestratorMcpClientRequestId),
744 });
745 export type OrchestratorMcpScheduleTaskInput = typeof OrchestratorMcpScheduleTaskInput.Type;
746
747 /** `schedule_task` creates a task, or updates one when `scheduledTaskId` is given. */
748 export const OrchestratorMcpSaveScheduledTaskInput = Schema.Struct({
749 ...OrchestratorMcpScheduleTaskInput.fields,
750 scheduledTaskId: Schema.optional(ScheduledTaskId),
751 prompt: Schema.optional(OrchestratorMcpPrompt),
752 schedule: Schema.optional(OrchestratorMcpSchedule),
753 });
754 export type OrchestratorMcpSaveScheduledTaskInput =
755 typeof OrchestratorMcpSaveScheduledTaskInput.Type;
756
757 export const OrchestratorMcpScheduledTask = Schema.Struct({
758 scheduledTaskId: ScheduledTaskId,
759 title: Schema.String,
760 prompt: Schema.String,
761 enabled: Schema.Boolean,
762 projectId: ProjectId,
763 boundThreadId: Schema.NullOr(ThreadId),
764 freshSession: Schema.Boolean,
765 schedule: ScheduledTaskSchedule,
766 nextRunAt: Schema.NullOr(IsoDateTime),
767 lastRunStatus: ScheduledTaskRunStatus,
768 webhookUrl: Schema.optional(Schema.String).annotate({
769 description:
770 "Webhook bearer URL, returned only on task creation to callers allowed to run it. Lists and updates omit it; the user can copy it from Settings. Creation may omit it without T3 Connect remote access or run permission.",
771 }),
772 webhookSignature: Schema.optional(Schema.Literals(["none", "set"])),
773 blockedByPolicy: Schema.optional(Schema.String).annotate({
774 description: "Present when an administrator's policy stops this task from running.",
775 }),
776 });
777 export type OrchestratorMcpScheduledTask = typeof OrchestratorMcpScheduledTask.Type;
778
779 export const OrchestratorMcpScheduleTaskResult = OrchestratorMcpScheduledTask;
780 export type OrchestratorMcpScheduleTaskResult = typeof OrchestratorMcpScheduleTaskResult.Type;
781
782 export const OrchestratorMcpListScheduledTasksInput = Schema.Struct({
783 environmentId: OrchestratorMcpEnvironmentTarget,
784 projectId: Schema.optional(
785 ProjectId.annotate({
786 description: "Default: your thread's project, or all outside a thread.",
787 }),
788 ),
789 scheduledTaskId: Schema.optional(ScheduledTaskId),
790 });
791 export type OrchestratorMcpListScheduledTasksInput =
792 typeof OrchestratorMcpListScheduledTasksInput.Type;
793
794 export const OrchestratorMcpListScheduledTasksResult = Schema.Struct({
795 tasks: Schema.Array(OrchestratorMcpScheduledTask),
796 });
797 export type OrchestratorMcpListScheduledTasksResult =
798 typeof OrchestratorMcpListScheduledTasksResult.Type;
799
800 export const OrchestratorMcpUpdateScheduledTaskInput = Schema.Struct({
801 environmentId: OrchestratorMcpEnvironmentTarget,
802 scheduledTaskId: ScheduledTaskId,
803 prompt: Schema.optional(OrchestratorMcpPrompt),
804 title: Schema.optional(OrchestratorMcpTitle),
805 schedule: Schema.optional(OrchestratorMcpSchedule),
806 enabled: Schema.optional(Schema.Boolean),
807 bindToCurrentThread: Schema.optional(Schema.Boolean),
808 freshSession: Schema.optional(Schema.Boolean),
809 });
810 export type OrchestratorMcpUpdateScheduledTaskInput =
811 typeof OrchestratorMcpUpdateScheduledTaskInput.Type;
812
813 // Not trimmed: whitespace in a password matters. The check stays out of the advertised schema.
814 const PastedSecretValue = Schema.String.check(
815 Schema.makeFilter((value: string) => value.length > 0, { expected: "a non-empty string" }),
816 );
817
818 const RequestSecretFields = Schema.Array(
819 Schema.Struct({
820 name: TrimmedNonEmptyString.check(Schema.isPattern(/^[A-Za-z][A-Za-z0-9_]{0,31}$/)),
821 label: TrimmedNonEmptyString,
822 placeholder: Schema.optional(TrimmedNonEmptyString),
823 secret: Schema.optional(Schema.Boolean).annotate({
824 description: "false shows the typed value, e.g. an email.",
825 }),
826 }),
827 )
828 .check(Schema.isMinLength(1), Schema.isMaxLength(8))
829 .check(
830 Schema.makeFilter((fields) =>
831 new Set(fields.map((field) => field.name)).size === fields.length
832 ? true
833 : "Field names must be unique.",
834 ),
835 );
836
837 export const OrchestratorMcpRequestSecretInput = Schema.Struct({
838 label: TrimmedNonEmptyString.annotate({
839 description: "Card title, such as 'GitHub webhook secret'.",
840 }),
841 reason: TrimmedNonEmptyString.annotate({
842 description: "What it is for and where to get it. A link goes in `url`.",
843 }),
844 url: Schema.optional(
845 TrimmedNonEmptyString.check(
846 Schema.makeFilter((value) => secretRequestPageUrl(value) !== null, {
847 expected: "an http(s) URL",
848 }),
849 ),
850 ).annotate({
851 description: "Sign-in or setup page for the value. Shown as a button.",
852 }),
853 placeholder: Schema.optional(TrimmedNonEmptyString),
854 delivery: Schema.optional(Schema.Literals(["secretRef", "file"])).annotate({
855 description: "secretRef (default) for a T3 tool; file for a command.",
856 }),
857 fields: Schema.optional(RequestSecretFields).annotate({
858 description:
859 'Values only the user has, in one card, e.g. email + password, with delivery "file". Returns `files` by name.',
860 }),
861 value: Schema.optional(PastedSecretValue).annotate({
862 description: "Pasted in this thread; no card.",
863 }),
864 /** Default 10 minutes. */
865 timeoutMs: Schema.optional(
866 Schema.Int.check(Schema.isBetween({ minimum: 1_000, maximum: 60 * 60 * 1_000 })),
867 ),
868 clientRequestId: Schema.optional(OrchestratorMcpClientRequestId).annotate({
869 description: "Retry key.",
870 }),
871 });
872 export type OrchestratorMcpRequestSecretInput = typeof OrchestratorMcpRequestSecretInput.Type;
873
874 export const OrchestratorMcpRequestSecretResult = Schema.Union([
875 Schema.Struct({
876 status: Schema.Literal("saved"),
877 secretRef: SecretRef.annotate({
878 description: "One-use. Pass to a tool that accepts a secretRef. You never see the value.",
879 }),
880 }),
881 Schema.Struct({
882 status: Schema.Literal("saved").annotate({ description: "file holds the value." }),
883 file: Schema.String.annotate({
884 description:
885 "Owner-only file with the value. Read it inside commands and never print it. Deleted after 24 hours.",
886 }),
887 }),
888 Schema.Struct({
889 status: Schema.Literal("saved"),
890 files: Schema.Record(Schema.String, Schema.String).annotate({
891 description: "One file per field name, used like `file`.",
892 }),
893 }),
894 Schema.Struct({
895 status: Schema.Literals(["declined", "cancelled", "timed_out"]).annotate({
896 description:
897 "declined: user chose not to; don't ask again. cancelled: ended with the run. timed_out: no answer in time. After cancelled or timed_out, ask again with a new `clientRequestId` only if still needed.",
898 }),
899 note: Schema.optional(Schema.String).annotate({ description: "What to do next." }),
900 }),
901 ]);
902 export type OrchestratorMcpRequestSecretResult = typeof OrchestratorMcpRequestSecretResult.Type;
903
904 export const OrchestratorMcpEnvironmentLinkInput = Schema.Struct({
905 environmentId: Schema.optional(EnvironmentId).annotate({
906 description:
907 "The machine, when known, e.g. from a mentioned machine. Otherwise the user picks it in the card.",
908 }),
909 url: Schema.optional(TrimmedNonEmptyString).annotate({
910 description:
911 "Only an address the user gave: https, Tailscale, LAN or loopback. Never guess one.",
912 }),
913 hint: Schema.optional(TrimmedNonEmptyString).annotate({
914 description: 'The user\'s words for the machine, e.g. "vps". Preselects it in the card.',
915 }),
916 reason: Schema.optional(TrimmedNonEmptyString).annotate({
917 description: "One sentence for the card.",
918 }),
919 requestedAccess: Schema.optional(AuthMcpClientAccess).annotate({
920 description: "Suggested access. The user picks; default approval-required.",
921 }),
922 clientRequestId: Schema.optional(OrchestratorMcpClientRequestId),
923 });
924 export type OrchestratorMcpEnvironmentLinkInput = typeof OrchestratorMcpEnvironmentLinkInput.Type;
925
926 export const OrchestratorMcpEnvironmentLinkResult = Schema.Union([
927 Schema.Struct({
928 status: Schema.Literal("pending").annotate({
929 description:
930 "The card is waiting for the user. Their answer arrives as a message in this thread.",
931 }),
932 turnItemId: TurnItemId,
933 }),
934 Schema.Struct({
935 status: Schema.Literal("linked"),
936 environmentId: EnvironmentId.annotate({
937 description: "Pass it as environmentId to act there; t3_environment_links lists it.",
938 }),
939 label: Schema.String,
940 access: AuthMcpClientAccess.annotate({ description: "The access the user chose." }),
941 }),
942 Schema.Struct({
943 status: Schema.Literals(["declined", "cancelled"]).annotate({
944 description:
945 "declined: the user chose not to. cancelled: the card closed unanswered, when the thread was stopped or archived.",
946 }),
947 }),
948 Schema.Struct({
949 status: Schema.Literal("failed"),
950 message: Schema.String.annotate({
951 description: "Why the other environment refused the link, as the user saw it.",
952 }),
953 }),
954 ]);
955 export type OrchestratorMcpEnvironmentLinkResult = typeof OrchestratorMcpEnvironmentLinkResult.Type;
956
957 export const OrchestratorMcpEnvironmentUnlinkInput = Schema.Struct({
958 environmentId: EnvironmentId.annotate({
959 description: "The linked environment to forget, from t3_environment_links.",
960 }),
961 });
962 export type OrchestratorMcpEnvironmentUnlinkInput =
963 typeof OrchestratorMcpEnvironmentUnlinkInput.Type;
964
965 export const OrchestratorMcpEnvironmentUnlinkResult = Schema.Struct({
966 environmentId: EnvironmentId,
967 removed: Schema.Boolean,
968 });
969 export type OrchestratorMcpEnvironmentUnlinkResult =
970 typeof OrchestratorMcpEnvironmentUnlinkResult.Type;
971
972 export const OrchestratorMcpDeleteScheduledTaskInput = Schema.Struct({
973 environmentId: OrchestratorMcpEnvironmentTarget,
974 scheduledTaskId: ScheduledTaskId,
975 });
976 export type OrchestratorMcpDeleteScheduledTaskInput =
977 typeof OrchestratorMcpDeleteScheduledTaskInput.Type;
978
979 export const OrchestratorMcpDeleteScheduledTaskResult = Schema.Struct({
980 scheduledTaskId: ScheduledTaskId,
981 deleted: Schema.Boolean,
982 });
983 export type OrchestratorMcpDeleteScheduledTaskResult =
984 typeof OrchestratorMcpDeleteScheduledTaskResult.Type;
985
986 export class OrchestratorMcpFailure extends Schema.TaggedError<OrchestratorMcpFailure>()(
987 "OrchestratorMcpFailure",
988 {
989 code: Schema.Literals([
990 "capability_denied",
991 "parent_not_active",
992 "provider_unavailable",
993 "model_unavailable",
994 "runtime_mode_escalation_denied",
995 "interaction_mode_escalation_denied",
996 "task_not_found",
997 "task_not_cancellable",
998 "thread_not_found",
999 "run_not_found",
1000 "thread_not_sendable",
1001 "thread_not_interruptible",
1002 "invalid_request",
1003 "orchestration_error",
1004 "thread_credential_required",
1005 "target_required",
1006 ]),
1007 message: Schema.String,
1008 },
1009 ) {}