lael-labs/t3code

apps/server/src/mcp/OrchestratorMcpToolkit.integration.test.ts+21−0

@@ -668,6 +668,27 @@ describe("orchestrator MCP toolkit", () => { · 667 unmodified lines
668	});	668	});
669	expect(yield* Ref.get(scheduledStore)).toHaveLength(0);	669	expect(yield* Ref.get(scheduledStore)).toHaveLength(0);
670		670
		671	// OpenCode 1.15 has emitted this exact nested-object-as-JSON-string
		672	// shape. Decode it at the MCP boundary rather than failing a task
		673	// the model otherwise specified correctly.
		674	const serializedScheduleCall = yield* invoke("schedule_task", {
		675	prompt: "check for new pull requests",
		676	schedule: '{"type":"interval","everyMs":3600000}',
		677	clientRequestId: "schedule-opencode-compat-1",
		678	});
		679	expect(serializedScheduleCall.isError).toBe(false);
		680	expect(serializedScheduleCall.structuredContent).toMatchObject({
		681	schedule: { type: "interval", everyMs: 3_600_000 },
		682	boundThreadId: parentThreadId,
		683	});
		684	const serializedScheduledTaskId = (
		685	serializedScheduleCall.structuredContent as { scheduledTaskId: string }
		686	).scheduledTaskId;
		687	yield* invoke("delete_scheduled_task", {
		688	scheduledTaskId: serializedScheduledTaskId,
		689	});
		690	expect(yield* Ref.get(scheduledStore)).toHaveLength(0);
		691
671	const delegatedCall = yield* invoke("delegate_task", {	692	const delegatedCall = yield* invoke("delegate_task", {
672	task: delegatedPrompt,	693	task: delegatedPrompt,
673	target: {	694	target: {

apps/server/src/mcp/toolkits/orchestrator/tools.test.ts+28−0

@@ -0,0 +1,28 @@
	1	import { assert, describe, it } from "@effect/vitest";
	2	import { Tool } from "effect/unstable/ai";
	3
	4	import { CreateThreadsTool, DelegateTaskTool, ScheduleTaskTool } from "./tools.ts";
	5
	6	describe("orchestrator MCP tool guidance", () => {
	7	it("directs subagent requests to delegation instead of ordinary threads", () => {
	8	assert.include(DelegateTaskTool.description ?? "", "child agent/subagent");
	9	assert.include(DelegateTaskTool.description ?? "", "cross-provider");
	10	assert.include(CreateThreadsTool.description ?? "", "not delegation");
	11	assert.include(CreateThreadsTool.description ?? "", "call delegate_task");
	12	});
	13
	14	it("publishes an actionable schedule schema and compatibility string branch", () => {
	15	const schema = Tool.getJsonSchema(ScheduleTaskTool) as {
	16	readonly type?: unknown;
	17	readonly properties?: Readonly<
	18	Record<string, { readonly description?: unknown; readonly anyOf?: ReadonlyArray<unknown> }>
	19	>;
	20	};
	21
	22	assert.equal(schema.type, "object");
	23	assert.isString(schema.properties?.schedule?.description);
	24	assert.isAtLeast(schema.properties?.schedule?.anyOf?.length ?? 0, 2);
	25	assert.include(ScheduleTaskTool.description ?? "", "STRUCTURED OBJECT");
	26	assert.include(ScheduleTaskTool.description ?? "", "nextRunAt");
	27	});
	28	});

apps/server/src/mcp/toolkits/orchestrator/tools.ts+4−4

apps/server/src/orchestration-v2/Adapters/AcpAdapterV2.ts+8−2

   AcpSessionRuntimeStartResult,
 } from "../../provider/acp/AcpSessionRuntime.ts";
 import * as AcpSessionRuntime from "../../provider/acp/AcpSessionRuntime.ts";
+import { t3OrchestrationPromptForFirstRun } from "../../provider/T3OrchestrationInstructions.ts";
 import { IdAllocatorV2, type IdAllocatorV2Shape } from "../IdAllocator.ts";
 import { type ProviderContinuationRequest } from "../ProviderContinuationRequests.ts";
 import { makeProviderFailure } from "../ProviderFailure.ts";
           turnInput: ProviderAdapterV2TurnInput,
         ) {
           const prompt: Array<EffectAcpSchema.ContentBlock> = [];
-          if (turnInput.message.text.length > 0) {
+          const text = t3OrchestrationPromptForFirstRun({
-            prompt.push({ type: "text", text: turnInput.message.text });
+            prompt: turnInput.message.text,
+            runOrdinal: turnInput.runOrdinal,
+            hasT3Mcp: acpMcpServers(turnInput.threadId).length > 0,
+          });
+          if (text.length > 0) {
+            prompt.push({ type: "text", text });
           }
           if (turnInput.message.attachments.length > 0 && !supportsImagePrompts) {
             return yield* new ProviderAdapterProtocolError({

apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts+9−0

@@ -519,6 +519,15 @@ describe("ClaudeAdapterV2 native protocol logging", () => { · 518 unmodified lines
519	cwd: "/workspace",	519	cwd: "/workspace",
520	...overrides,	520	...overrides,
521	});	521	});
		522	assert.isObject(options.systemPrompt);
		523	const systemPrompt = options.systemPrompt as {
		524	readonly type: string;
		525	readonly preset: string;
		526	readonly append?: string;
		527	};
		528	assert.equal(systemPrompt.type, "preset");
		529	assert.equal(systemPrompt.preset, "claude_code");
		530	assert.include(systemPrompt.append ?? "", "use `delegate_task`");
522	const logged = loggedClaudeQueryOptions(options);	531	const logged = loggedClaudeQueryOptions(options);
523	assert.equal(logged.hasMcpServers, true);	532	assert.equal(logged.hasMcpServers, true);
524	assert.notInclude(JSON.stringify(logged), "secret-claude-token");	533	assert.notInclude(JSON.stringify(logged), "secret-claude-token");

apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts+10−0

   makeEventNdjsonLogger,
 } from "../../provider/Layers/EventNdjsonLogger.ts";
 import { mergeProviderInstanceEnvironment } from "../../provider/ProviderInstanceEnvironment.ts";
+import { T3_CODE_ORCHESTRATION_INSTRUCTIONS } from "../../provider/T3OrchestrationInstructions.ts";
 import * as McpProviderSession from "../../mcp/McpProviderSession.ts";
 import { IdAllocatorV2, type IdAllocatorV2Shape } from "../IdAllocator.ts";
 import { makeProviderFailure } from "../ProviderFailure.ts";
       : {}),
     ...(input.environment === undefined ? {} : { env: input.environment }),
     ...(input.mcpServers === undefined ? {} : { mcpServers: input.mcpServers }),
+    ...(input.mcpServers === undefined
+      ? {}
+      : {
+          systemPrompt: {
+            type: "preset" as const,
+            preset: "claude_code" as const,
+            append: T3_CODE_ORCHESTRATION_INSTRUCTIONS,
+          },
+        }),
     ...(Object.keys(extraArgs).length === 0 ? {} : { extraArgs }),
   };
   return input.cwd === null ? options : { ...options, cwd: input.cwd };

apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.test.ts+29−0

@@ -244,6 +244,35 @@ describe("CodexAdapterV2 runtime policy", () => { · 243 unmodified lines
244	}),	244	}),
245	);	245	);
246		246
		247	it.effect("adds default-mode developer instructions when the T3 MCP server is attached", () =>
		248	Effect.gen(function* () {
		249	const params = yield* buildCodexTurnStartParams({
		250	nativeThreadId: "native-orchestration-instructions",
		251	codexInput: [{ type: "text", text: "delegate this task" }],
		252	runtimePolicy: {
		253	runtimeMode: "full-access",
		254	interactionMode: "default",
		255	cwd: null,
		256	},
		257	modelSelection: {
		258	instanceId: ProviderInstanceId.make("codex"),
		259	model: "gpt-5.4",
		260	},
		261	hasT3Mcp: true,
		262	});
		263
		264	assert.equal(params.collaborationMode?.mode, "default");
		265	assert.include(
		266	params.collaborationMode?.settings.developer_instructions ?? "",
		267	"use `delegate_task`",
		268	);
		269	assert.include(
		270	params.collaborationMode?.settings.developer_instructions ?? "",
		271	"structured object, never as JSON text",
		272	);
		273	}),
		274	);
		275
247	it.effect("compiles per-turn Codex model options and cwd from their owning inputs", () =>	276	it.effect("compiles per-turn Codex model options and cwd from their owning inputs", () =>
248	Effect.gen(function* () {	277	Effect.gen(function* () {
249	const params = yield* buildCodexTurnStartParams({	278	const params = yield* buildCodexTurnStartParams({

apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts+19−7

 import { resolveAttachmentPath } from "../../attachmentStore.ts";
 import { getCodexServiceTierOptionValue } from "../../codexModelOptions.ts";
 import { ServerConfig } from "../../config.ts";
-import { CODEX_PLAN_MODE_DEVELOPER_INSTRUCTIONS } from "../../provider/CodexDeveloperInstructions.ts";
+import {
+  CODEX_DEFAULT_MODE_DEVELOPER_INSTRUCTIONS,
+  CODEX_PLAN_MODE_DEVELOPER_INSTRUCTIONS,
+} from "../../provider/CodexDeveloperInstructions.ts";
 import {
   materializeCodexShadowHome,
   resolveCodexHomeLayout,
   readonly codexInput: ReadonlyArray<CodexSchema.V2TurnStartParams__UserInput>;
   readonly runtimePolicy: ProviderAdapterV2RuntimePolicy;
   readonly modelSelection: ModelSelection;
+  readonly hasT3Mcp?: boolean;
 }) {
   return Effect.gen(function* () {
     const runtimeModeDefaults = codexRuntimeModeTurnDefaults(input.runtimePolicy.runtimeMode);
     const effort =
       selectedEffort === undefined ? undefined : yield* decodeTurnReasoningEffort(selectedEffort);
     const serviceTier = getCodexServiceTierOptionValue(input.modelSelection);
-    const collaborationMode: CodexSchema.ClientRequest__CollaborationMode | undefined =
+    const developerInstructions =
       input.runtimePolicy.interactionMode === "plan"
-        ? {
+        ? CODEX_PLAN_MODE_DEVELOPER_INSTRUCTIONS
-            mode: "plan",
+        : input.hasT3Mcp === true
+          ? CODEX_DEFAULT_MODE_DEVELOPER_INSTRUCTIONS
+          : undefined;
+    const collaborationMode: CodexSchema.ClientRequest__CollaborationMode | undefined =
+      developerInstructions === undefined
+        ? undefined
+        : {
+            mode: input.runtimePolicy.interactionMode === "plan" ? "plan" : "default",
             settings: {
               model: input.modelSelection.model,
               reasoning_effort: effort ?? "medium",
-              developer_instructions: CODEX_PLAN_MODE_DEVELOPER_INSTRUCTIONS,
+              developer_instructions: developerInstructions,
             },
-          }
+          };
-        : undefined;
     return yield* decodeCodexTurnStartParamsWithCollaborationMode({
       threadId: input.nativeThreadId,
                 codexInput,
                 runtimePolicy: turnInput.runtimePolicy,
                 modelSelection: turnInput.modelSelection,
+                hasT3Mcp:
+                  McpProviderSession.readMcpProviderSession(turnInput.threadId) !== undefined,
               });
               yield* Ref.update(pendingRootTurns, (current) => {
                 const updated = new Map(current);

apps/server/src/orchestration-v2/Adapters/CursorAdapterV2.ts+8−2

 import * as McpProviderSession from "../../mcp/McpProviderSession.ts";
 import { cursorSdkModelSelection } from "../../provider/cursorSdkModel.ts";
 import { mergeProviderInstanceEnvironment } from "../../provider/ProviderInstanceEnvironment.ts";
+import { t3OrchestrationPromptForFirstRun } from "../../provider/T3OrchestrationInstructions.ts";
 import { IdAllocatorV2, type IdAllocatorV2Shape } from "../IdAllocator.ts";
 import { makeProviderFailure } from "../ProviderFailure.ts";
 import { turnScopedSelectionTransition } from "../ProviderSelectionTransition.ts";
         const resolveUserMessage = Effect.fnUntraced(function* (
           turnInput: ProviderAdapterV2TurnInput,
         ) {
+          const text = t3OrchestrationPromptForFirstRun({
+            prompt: turnInput.message.text,
+            runOrdinal: turnInput.runOrdinal,
+            hasT3Mcp: cursorMcpServers(turnInput.threadId) !== undefined,
+          });
           const images = yield* Effect.forEach(
             turnInput.message.attachments,
             (attachment: ChatAttachment) =>
             });
           }
           return images.length === 0
-            ? turnInput.message.text
+            ? text
             : ({
-                text: turnInput.message.text,
+                text,
                 images,
               } satisfies SDKUserMessage);
         });

apps/server/src/orchestration-v2/Adapters/OpenCodeAdapterV2.ts+10−1

   summarizeNativeProtocolPayload,
 } from "../../provider/NativeProtocolLogging.ts";
 import { mergeProviderInstanceEnvironment } from "../../provider/ProviderInstanceEnvironment.ts";
+import { t3OrchestrationSystemPrompt } from "../../provider/T3OrchestrationInstructions.ts";
 import {
   OpenCodeRuntime,
   OpenCodeRuntimeError,
         });
         const mcpSession = McpProviderSession.readMcpProviderSession(input.threadId);
-        if (mcpSession !== undefined && !connection.external) {
+        const hasT3Mcp = mcpSession !== undefined && !connection.external;
+        const orchestrationSystemPrompt = t3OrchestrationSystemPrompt(hasT3Mcp);
+        if (hasT3Mcp) {
           yield* runOpenCodeSdk("mcp.add", () =>
             client.mcp.add({
               name: "t3-code",
                   model: parsedModel,
                   ...(agent === undefined ? {} : { agent }),
                   ...(variant === undefined ? {} : { variant }),
+                  ...(orchestrationSystemPrompt === undefined
+                    ? {}
+                    : { system: orchestrationSystemPrompt }),
                   parts,
                 },
                 () =>
                     model: parsedModel,
                     ...(agent === undefined ? {} : { agent }),
                     ...(variant === undefined ? {} : { variant }),
+                    ...(orchestrationSystemPrompt === undefined
+                      ? {}
+                      : { system: orchestrationSystemPrompt }),
                     parts,
                   }),
               ).pipe(

apps/server/src/provider/CodexDeveloperInstructions.ts+5−10

 import type { ProviderInteractionMode } from "@t3tools/contracts";
 import { buildRuntimeInstructions } from "./RuntimeInstructions.ts";
+import { T3_CODE_ORCHESTRATION_INSTRUCTIONS } from "./T3OrchestrationInstructions.ts";
+import { T3_CODE_ORCHESTRATION_INSTRUCTIONS } from "./T3OrchestrationInstructions.ts";
 const T3_CODE_BROWSER_TOOL_INSTRUCTIONS = `
 ## T3 Code collaborative browser
 Do not switch to global browser skills, Chrome, Node REPL browser automation, standalone Playwright, or agent-browser merely because the preview is initially closed or a first call fails. Use an alternative browser system only when the T3 preview tools are absent, the user explicitly requests another browser, or \`preview_open\` returns an explicit unsupported/unavailable error. A failed T3 preview tool call should be inspected and retried with corrected arguments when the error is actionable.
 `;
-const T3_CODE_THREAD_ORCHESTRATION_INSTRUCTIONS = `
-## T3 Code thread orchestration
-When the \`t3-code\` MCP server exposes \`t3_thread_*\` tools, you can run a bounded orchestration loop without asking the user to relay updates. Start independent work with \`t3_thread_start\` (or \`create_threads\` for a batch), retain the returned thread/run IDs, wait with \`t3_thread_wait\`, and collect durable output with \`t3_thread_read\`. Use \`t3_thread_send\` for follow-up or steering and \`t3_thread_interrupt\` when work is no longer needed. Use stable \`clientRequestId\` values when retrying mutating calls, and use \`t3_thread_list\` to recover IDs after context loss.
-Keep loops bounded by an explicit completion condition and timeout. A wait timeout does not stop the target thread. Do not repeatedly start equivalent threads or send duplicate work when a durable run is already active.
-`;
 /**
  * The browser block is omitted entirely when the preview tools aren't attached.
  * Describing `preview_*` tools that aren't in the turn's tool list would be
 In Default mode, strongly prefer making reasonable assumptions and executing the user's request rather than stopping to ask questions. If you absolutely must ask a question because the answer cannot be discovered from local context and a reasonable assumption would be risky, ask the user directly with a concise plain-text question. Never write a multiple choice question as a textual assistant message.
 ${browserToolInstructions(browserToolsAvailable)}
-${T3_CODE_THREAD_ORCHESTRATION_INSTRUCTIONS}
+${T3_CODE_ORCHESTRATION_INSTRUCTIONS}
 </collaboration_mode>`;
 export interface CodexRuntimeInfo {

apps/server/src/provider/T3OrchestrationInstructions.test.ts+47−0

@@ -0,0 +1,47 @@
	1	import { assert, describe, it } from "@effect/vitest";
	2
	3	import {
	4	T3_CODE_ORCHESTRATION_INSTRUCTIONS,
	5	t3OrchestrationPromptForFirstRun,
	6	t3OrchestrationSystemPrompt,
	7	} from "./T3OrchestrationInstructions.ts";
	8
	9	describe("T3 orchestration provider instructions", () => {
	10	it("distinguishes delegated subagents from ordinary top-level threads", () => {
	11	assert.include(T3_CODE_ORCHESTRATION_INSTRUCTIONS, "use `delegate_task`");
	12	assert.include(T3_CODE_ORCHESTRATION_INSTRUCTIONS, "ordinary top-level T3 conversations");
	13	assert.include(T3_CODE_ORCHESTRATION_INSTRUCTIONS, "Never use them merely");
	14	assert.include(T3_CODE_ORCHESTRATION_INSTRUCTIONS, "different provider");
	15	});
	16
	17	it("documents structured schedules instead of JSON strings", () => {
	18	assert.include(T3_CODE_ORCHESTRATION_INSTRUCTIONS, "structured object, never as JSON text");
	19	assert.include(T3_CODE_ORCHESTRATION_INSTRUCTIONS, '"everyMs":3600000');
	20	assert.include(T3_CODE_ORCHESTRATION_INSTRUCTIONS, "bindToCurrentThread=false");
	21	});
	22
	23	it("injects prompt fallback only for an MCP-enabled first run", () => {
	24	const prompt = "Inspect the repository.";
	25	const injected = t3OrchestrationPromptForFirstRun({
	26	prompt,
	27	runOrdinal: 1,
	28	hasT3Mcp: true,
	29	});
	30
	31	assert.include(injected, "<t3_code_orchestration_instructions>");
	32	assert.include(injected, `<user_request>\n${prompt}\n</user_request>`);
	33	assert.equal(
	34	t3OrchestrationPromptForFirstRun({ prompt, runOrdinal: 2, hasT3Mcp: true }),
	35	prompt,
	36	);
	37	assert.equal(
	38	t3OrchestrationPromptForFirstRun({ prompt, runOrdinal: 1, hasT3Mcp: false }),
	39	prompt,
	40	);
	41	});
	42
	43	it("only exposes the system prompt when the T3 MCP server is attached", () => {
	44	assert.equal(t3OrchestrationSystemPrompt(false), undefined);
	45	assert.equal(t3OrchestrationSystemPrompt(true), T3_CODE_ORCHESTRATION_INSTRUCTIONS);
	46	});
	47	});

apps/server/src/provider/T3OrchestrationInstructions.ts+35−0

@@ -0,0 +1,35 @@
	1	export const T3_CODE_ORCHESTRATION_INSTRUCTIONS = `
	2
	3	## T3 Code orchestration
	4
	5	The \`t3-code\` MCP server provides app-owned orchestration. Treat these concepts distinctly:
	6
	7	- A delegated task/subagent is child work owned by the current thread. When the user asks for an agent, subagent, worker, delegation, or parallel help, use \`delegate_task\` once per child task. This remains true when targeting a different provider. Use \`orchestrator_capabilities\` to discover provider/model IDs, retain each returned \`taskId\`, and use \`task_status\` or \`task_cancel\` to manage it. The returned \`childThreadId\` is backing storage for the subagent; do not replace delegation with ordinary thread creation.
	8	- \`create_threads\` and \`t3_thread_start\` create ordinary top-level T3 conversations. Use them only when the user explicitly asks for separate/new/top-level threads or conversations. Never use them merely because the user said "subagent" or requested parallel delegated work.
	9	- \`schedule_task\` creates persistent recurring work in the app scheduler. Pass \`schedule\` as a structured object, never as JSON text: \`{"type":"interval","everyMs":3600000}\` for an interval, or \`{"type":"fixed_time","timeOfDay":"09:00","weekdays":[1,2,3,4,5]}\` for a wall-clock schedule. By default runs return to the current thread; set \`bindToCurrentThread=false\` only when the user wants a fresh thread for every run. After scheduling, report the returned cadence and next run time.
	10
	11	Tool names may include an MCP prefix (for example \`mcp__t3-code__delegate_task\`); the semantics are the same. Keep polling/wait loops bounded, do not duplicate active work, and use stable \`clientRequestId\` values when retrying mutations.
	12	`;
	13
	14	/**
	15	* Providers without a system/developer-instruction channel receive this
	16	* context in the first prompt. Keep the wrapper explicit so it cannot be
	17	* mistaken for text authored by the user.
	18	*/
	19	export function prependT3OrchestrationInstructions(prompt: string): string {
	20	return `<t3_code_orchestration_instructions>${T3_CODE_ORCHESTRATION_INSTRUCTIONS.trim()}</t3_code_orchestration_instructions>\n\n<user_request>\n${prompt}\n</user_request>`;
	21	}
	22
	23	export function t3OrchestrationPromptForFirstRun(input: {
	24	readonly prompt: string;
	25	readonly runOrdinal: number;
	26	readonly hasT3Mcp: boolean;
	27	}): string {
	28	return input.runOrdinal === 1 && input.hasT3Mcp
	29	? prependT3OrchestrationInstructions(input.prompt)
	30	: input.prompt;
	31	}
	32
	33	export function t3OrchestrationSystemPrompt(hasT3Mcp: boolean): string \| undefined {
	34	return hasT3Mcp ? T3_CODE_ORCHESTRATION_INSTRUCTIONS : undefined;
	35	}

packages/contracts/src/orchestratorMcp.ts+66−13

 } from "./model.ts";
 import { ProviderDriverKind, ProviderInstanceId } from "./providerInstance.ts";
-const OrchestratorMcpPrompt = TrimmedNonEmptyString.check(Schema.isMaxLength(120_000));
+const OrchestratorMcpPrompt = TrimmedNonEmptyString.check(Schema.isMaxLength(120_000)).annotate({
-const OrchestratorMcpTitle = TrimmedNonEmptyString.check(Schema.isMaxLength(512));
+  description: "Complete task or message text for the target agent.",
-const OrchestratorMcpClientRequestId = TrimmedNonEmptyString.check(Schema.isMaxLength(256));
+});
+const OrchestratorMcpTitle = TrimmedNonEmptyString.check(Schema.isMaxLength(512)).annotate({
+  description: "Optional concise display title.",
+});
+const OrchestratorMcpClientRequestId = TrimmedNonEmptyString.check(
+  Schema.isMaxLength(256),
+).annotate({ description: "Stable idempotency key to reuse when retrying this mutation." });
+/**
+ * OpenCode 1.15 has been observed serializing nested MCP union objects as JSON
+ * strings. Keep the structured object as the documented form while accepting
+ * that compatibility shape at the tool boundary and decoding it immediately.
+ */
+const OrchestratorMcpScheduleFromJsonString = Schema.fromJsonString(ScheduledTaskSchedule).annotate(
+  {
+    description:
+      "Compatibility-only JSON encoding of the schedule object. Prefer a structured object.",
+  },
+);
+const OrchestratorMcpSchedule = Schema.Union([
+  ScheduledTaskSchedule,
+  OrchestratorMcpScheduleFromJsonString,
+]).annotate({
+  description:
+    "Recurring schedule object: {type:'interval', everyMs} or {type:'fixed_time', timeOfDay, weekdays?}. Never stringify it unless the provider requires the compatibility form.",
+});
 /**
  * Shorthand `{ id: value }` record form for target model options. Unlike the
 export type OrchestratorMcpTargetOptions = typeof OrchestratorMcpTargetOptions.Type;
 export const OrchestratorMcpTarget = Schema.Struct({
-  providerInstanceId: Schema.optional(ProviderInstanceId),
+  providerInstanceId: Schema.optional(
-  driverKind: Schema.optional(ProviderDriverKind),
+    ProviderInstanceId.annotate({
-  model: Schema.optional(TrimmedNonEmptyString),
+      description: "Configured provider instance id from orchestrator_capabilities.",
+    }),
+  ),
+  driverKind: Schema.optional(
+    ProviderDriverKind.annotate({
+      description: "Provider driver kind; prefer providerInstanceId when available.",
+    }),
+  ),
+  model: Schema.optional(
+    TrimmedNonEmptyString.annotate({
+      description: "Model id advertised for the selected provider instance.",
+    }),
+  ),
   /**
    * Model option selections for the child (for example reasoning effort).
    * Accepts the canonical `[{ id, value }]` array or the shorthand
    * advertised by orchestrator_capabilities. When omitted, options inherit
    * from the parent only when the child runs the parent's provider and model.
    */
-  options: Schema.optional(OrchestratorMcpTargetOptions),
+  options: Schema.optional(
+    OrchestratorMcpTargetOptions.annotate({
+      description: "Model option selections advertised by orchestrator_capabilities.",
+    }),
+  ),
 });
 export type OrchestratorMcpTarget = typeof OrchestratorMcpTarget.Type;
 export type OrchestratorMcpDelegatedTaskStatus = typeof OrchestratorMcpDelegatedTaskStatus.Type;
 export const OrchestratorMcpDelegateTaskInput = Schema.Struct({
-  task: OrchestratorMcpPrompt,
+  task: OrchestratorMcpPrompt.annotate({
+    description: "Self-contained task for one delegated child agent/subagent.",
+  }),
   target: Schema.optional(OrchestratorMcpTarget),
   title: Schema.optional(OrchestratorMcpTitle),
   role: Schema.optional(OrchestratorMcpTaskRole),
 export type OrchestratorMcpCapabilitiesResult = typeof OrchestratorMcpCapabilitiesResult.Type;
 export const OrchestratorMcpScheduleTaskInput = Schema.Struct({
-  prompt: OrchestratorMcpPrompt,
+  prompt: OrchestratorMcpPrompt.annotate({
-  schedule: ScheduledTaskSchedule,
+    description: "Prompt executed on every scheduled run.",
+  }),
+  schedule: OrchestratorMcpSchedule,
   title: Schema.optional(OrchestratorMcpTitle),
-  enabled: Schema.optional(Schema.Boolean),
+  enabled: Schema.optional(
+    Schema.Boolean.annotate({ description: "Whether the schedule starts enabled; defaults true." }),
+  ),
   /**
    * When true (the default), the scheduled task fires into the calling thread
    * on each run instead of launching a fresh thread. This is the recurring
    * "wake up in this thread" behaviour reserved for agent-created tasks.
    */
-  bindToCurrentThread: Schema.optional(Schema.Boolean),
+  bindToCurrentThread: Schema.optional(
+    Schema.Boolean.annotate({
+      description:
+        "True (default) posts each run into this thread; false creates a fresh top-level thread per run.",
+    }),
+  ),
   clientRequestId: Schema.optional(OrchestratorMcpClientRequestId),
 });
 export type OrchestratorMcpScheduleTaskInput = typeof OrchestratorMcpScheduleTaskInput.Type;
   scheduledTaskId: ScheduledTaskId,
   prompt: Schema.optional(OrchestratorMcpPrompt),
   title: Schema.optional(OrchestratorMcpTitle),
-  schedule: Schema.optional(ScheduledTaskSchedule),
+  schedule: Schema.optional(OrchestratorMcpSchedule),
   enabled: Schema.optional(Schema.Boolean),
   bindToCurrentThread: Schema.optional(Schema.Boolean),
 });

packages/contracts/src/scheduledTask.ts+27−6

 import { ProviderInteractionMode, RuntimeMode } from "./providerPolicy.ts";
 /** 24-hour "HH:MM" wall-clock time. Mirrors `parseTimeOfDay` on the server. */
-const TimeOfDay = TrimmedNonEmptyString.check(Schema.isPattern(/^([01]?\d|2[0-3]):([0-5]\d)$/));
+const TimeOfDay = TrimmedNonEmptyString.check(
+  Schema.isPattern(/^([01]?\d|2[0-3]):([0-5]\d)$/),
+).annotate({ description: "Local wall-clock time in 24-hour HH:MM form, such as 09:30." });
 export const ScheduledTaskSchedule = Schema.Union([
   Schema.Struct({
-    type: Schema.Literal("interval"),
+    type: Schema.Literal("interval").annotate({
-    everyMs: PositiveInt,
+      description: "Select interval scheduling.",
+    }),
+    everyMs: PositiveInt.annotate({
+      description: "Positive interval in milliseconds; 3600000 means every hour.",
+    }),
+  }).annotate({
+    description: "Run repeatedly after a fixed number of milliseconds.",
   }),
   Schema.Struct({
-    type: Schema.Literal("fixed_time"),
+    type: Schema.Literal("fixed_time").annotate({
+      description: "Select a fixed local wall-clock time.",
+    }),
     timeOfDay: TimeOfDay,
     weekdays: Schema.optional(
-      Schema.Array(Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 6 }))),
+      Schema.Array(
+        Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 6 })).annotate({
+          description: "Weekday number where 0 is Sunday and 6 is Saturday.",
+        }),
+      ).annotate({
+        description: "Optional weekdays; omit to run every day.",
+      }),
     ),
+  }).annotate({
+    description: "Run at a fixed local wall-clock time on selected weekdays.",
   }),
-]);
+]).annotate({
+  description:
+    "Structured recurring schedule. Pass an object with type 'interval' or 'fixed_time'.",
+});
 export type ScheduledTaskSchedule = typeof ScheduledTaskSchedule.Type;
 export const ScheduledTaskRunStatus = Schema.Literals(["never", "running", "succeeded", "failed"]);

fix(orchestration): clarify agent delegation and scheduling

Keyboard shortcuts

General

Issues and pull requests

Issues, pull requests and Inbox

Repository code

@@ -49,7 +49,7 @@ export const OrchestratorCapabilitiesTool = Tool.make("orchestrator_capabilities · 48 unmodified lines
49		49
50	export const DelegateTaskTool = Tool.make("delegate_task", {	50	export const DelegateTaskTool = Tool.make("delegate_task", {
51	description:	51	description:
52	"Create a T3-owned child agent thread and run it with only the supplied task prompt, without copying parent conversation history. Provider, model, model options (e.g. reasoning effort — see orchestrator_capabilities for valid ids), runtime mode, and interaction mode inherit from the parent unless overridden via target. Prefer mode='async' and poll task_status for long work; mode='wait' blocks until completion or timeout.",	52	"Delegate one task to a T3-owned child agent/subagent of THIS thread and run it with only the supplied task prompt, without copying parent conversation history. Use this whenever the user asks for an agent, subagent, worker, delegated task, or parallel help—including cross-provider work. The childThreadId is backing storage, not an ordinary top-level thread. Provider, model, model options (see orchestrator_capabilities), runtime mode, and interaction mode inherit unless target overrides them. Prefer mode='async' and poll task_status for long work; mode='wait' blocks until completion or timeout.",
53	parameters: OrchestratorMcpDelegateTaskInput,	53	parameters: OrchestratorMcpDelegateTaskInput,
54	success: OrchestratorMcpDelegateTaskResult,	54	success: OrchestratorMcpDelegateTaskResult,
55	failure: OrchestratorMcpFailure,	55	failure: OrchestratorMcpFailure,
@@ -88,7 +88,7 @@ export const TaskCancelTool = Tool.make("task_cancel", { · 32 unmodified lines
88		88
89	export const ScheduleTaskTool = Tool.make("schedule_task", {	89	export const ScheduleTaskTool = Tool.make("schedule_task", {
90	description:	90	description:
91	"Create a recurring scheduled task that automatically runs a prompt on a schedule. Use this to set up autonomous recurring work — the app's scheduler fires it even when no turn is active. By default (bindToCurrentThread=true) each run posts into THIS thread, which is how you 'wake up' and continue here on an interval or at a fixed time; set bindToCurrentThread=false to launch a fresh thread each run instead. Provider, model, and runtime settings inherit from the calling thread. Schedule is either {type:'interval', everyMs} (e.g. everyMs=60000 for every minute) or {type:'fixed_time', timeOfDay:'HH:MM', weekdays?:[0-6] where 0=Sunday}.",	91	"Create persistent recurring work in the app scheduler, which runs even when no turn is active. Pass schedule as a STRUCTURED OBJECT, never JSON text: {type:'interval', everyMs:3600000} means hourly; {type:'fixed_time', timeOfDay:'09:00', weekdays:[1,2,3,4,5]} means weekday mornings. By default (bindToCurrentThread=true) each run posts into THIS thread; use false only when the user wants a fresh top-level thread per run. Provider, model, and runtime settings inherit from this thread. Report the returned schedule and nextRunAt after success.",
92	parameters: OrchestratorMcpScheduleTaskInput,	92	parameters: OrchestratorMcpScheduleTaskInput,
93	success: OrchestratorMcpScheduleTaskResult,	93	success: OrchestratorMcpScheduleTaskResult,
94	failure: OrchestratorMcpFailure,	94	failure: OrchestratorMcpFailure,
@@ -138,7 +138,7 @@ export const DeleteScheduledTaskTool = Tool.make("delete_scheduled_task", { · 43 unmodified lines
138		138
139	export const CreateThreadsTool = Tool.make("create_threads", {	139	export const CreateThreadsTool = Tool.make("create_threads", {
140	description:	140	description:
141	"Create one or more ordinary top-level T3 V2 threads. Each entry may have its own prompt, title, provider instance or driver, model, model options (e.g. reasoning effort), runtime mode, and interaction mode. Omitted provider/model/settings inherit from the calling thread; entries without prompts create empty threads.",	141	"Create one or more ORDINARY TOP-LEVEL T3 conversations. This is not delegation and does not create child agents/subagents. If the user asks for agents, subagents, workers, delegation, or parallel help, call delegate_task once per child instead—even when selecting different providers. Use create_threads only when the user explicitly asks for separate/new/top-level threads or conversations. Each entry may override provider, model, options, runtime mode, and interaction mode; omitted settings inherit.",
142	parameters: OrchestratorMcpCreateThreadsInput,	142	parameters: OrchestratorMcpCreateThreadsInput,
143	success: OrchestratorMcpCreateThreadsResult,	143	success: OrchestratorMcpCreateThreadsResult,
144	failure: OrchestratorMcpFailure,	144	failure: OrchestratorMcpFailure,
@@ -151,7 +151,7 @@ export const CreateThreadsTool = Tool.make("create_threads", { · 6 unmodified lines
151		151
152	export const ThreadStartTool = Tool.make("t3_thread_start", {	152	export const ThreadStartTool = Tool.make("t3_thread_start", {
153	description:	153	description:
154	"Create an ordinary top-level T3 thread and immediately start its first turn. The new thread inherits this thread's project, checkout, provider, model, and runtime settings unless overridden. Use t3_thread_wait and t3_thread_read to collect its result.",	154	"Create an ordinary TOP-LEVEL T3 conversation and immediately start its first turn. This is not a child agent/subagent; use delegate_task for delegated work. The new thread inherits this thread's project, checkout, provider, model, and runtime settings unless overridden. Use t3_thread_wait and t3_thread_read to collect its result.",
155	parameters: OrchestratorMcpThreadStartInput,	155	parameters: OrchestratorMcpThreadStartInput,
156	success: OrchestratorMcpCreatedThread,	156	success: OrchestratorMcpCreatedThread,
157	failure: OrchestratorMcpFailure,	157	failure: OrchestratorMcpFailure,