Skip to content
Source
Sign inSign up
Open History to see the last commit

orchestratorMcp.ts

963 lines38.4 KB

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