fix(server): delegate_task and create_threads say where a target's providerInstanceId comes from

apps/server/src/mcp/toolkits/orchestrator/tools.test.ts

@@ -3,6 +3,7 @@ import * as Exit from "effect/Exit";
 import * as Schema from "effect/Schema";
 import { Tool } from "effect/ai";
 
+import { advertisedJsonSchema } from "../../advertisedJsonSchema.ts";
 import { OrchestratorToolkit } from "./tools.ts";
 
 // Oversized page sizes clamp on decode, so the schema has no `maximum`; Codex also drops
@@ -27,3 +28,22 @@ it("refuses a t3_thread_update whose fields do not fit its action", () => {
     true,
   );
 });
+
+it("tells agents where a target's providerInstanceId comes from", () => {
+  type Schema = {
+    readonly properties?: Record<string, Schema>;
+    readonly items?: Schema;
+    readonly description?: string;
+  };
+  const { delegate_task, create_threads } = OrchestratorToolkit.tools;
+  const delegate = advertisedJsonSchema(delegate_task) as Schema;
+  const threads = advertisedJsonSchema(create_threads) as Schema;
+  for (const target of [
+    delegate.properties?.target,
+    threads.properties?.threads?.items?.properties?.target,
+  ]) {
+    expect(target?.properties?.providerInstanceId?.description).toBe(
+      "From orchestrator_capabilities.",
+    );
+  }
+});

apps/server/src/provider/agentContextBudget.json

@@ -1,5 +1,5 @@
 {
   "claudeSystemAppendBytes": 5547,
   "codexAdditionalContextBytes": 7277,
-  "mcpToolListJsonBytes": 48217
+  "mcpToolListJsonBytes": 48213
 }

packages/contracts/src/orchestratorMcp.ts

@@ -96,9 +96,10 @@ export type OrchestratorMcpTargetOptions = typeof OrchestratorMcpTargetOptions.T
 
 export const OrchestratorMcpTarget = Schema.Struct({
   providerInstanceId: Schema.optional(
-    ProviderInstanceId.annotate({
-      description: "Provider instance id from `orchestrator_capabilities`.",
-    }),
+    // JSON Schema shows a transform's encoded side, so `.annotate` would never reach tools/list.
+    ProviderInstanceId.pipe(
+      Schema.annotateEncoded({ description: "From orchestrator_capabilities." }),
+    ),
   ),
   driverKind: Schema.optional(
     ProviderDriverKind.annotate({
@@ -108,8 +109,7 @@ export const OrchestratorMcpTarget = Schema.Struct({
   model: Schema.optional(TrimmedNonEmptyString),
   options: Schema.optional(
     OrchestratorMcpTargetOptions.annotate({
-      description:
-        "Options from `orchestrator_capabilities`, such as {effort:'max'}. Given values override inherited. [] or {} clears.",
+      description: "From orchestrator_capabilities. Overrides inherited; []/{} clear.",
     }),
   ),
   environmentId: Schema.optional(