From 57f771d446f05256c80a49592385c0892d84ae2d Mon Sep 17 00:00:00 2001 From: Chris OHearn Date: Thu, 12 Nov 2026 19:27:56 -0700 Subject: [PATCH 01/14] feat(mcp): t3_thread_result and t3_thread_read accept links and bare mcp: uuids 18 of Jarvis's 27 thread_not_found results were bare uuids of mcp: threads, likely from hosted links that escape mcp: as mcp%3A. Reads now resolve t3-thread:// v1 and v2 links, hosted links and bare uuids, say when a thread was deleted, and name the closest ids otherwise. Co-Authored-By: Claude Opus 5.5 --- .../src/mcp/OrchestratorMcpService.test.ts | 17 ++- apps/server/src/mcp/OrchestratorMcpService.ts | 45 ++++---- apps/server/src/mcp/threadReference.test.ts | 79 +++++++++++++ apps/server/src/mcp/threadReference.ts | 107 ++++++++++++++++++ 4 files changed, 218 insertions(+), 30 deletions(-) create mode 100644 apps/server/src/mcp/threadReference.test.ts create mode 100644 apps/server/src/mcp/threadReference.ts diff --git a/apps/server/src/mcp/OrchestratorMcpService.test.ts b/apps/server/src/mcp/OrchestratorMcpService.test.ts index e428fe9e0602b..ac5330fd34df5 100644 --- a/apps/server/src/mcp/OrchestratorMcpService.test.ts +++ b/apps/server/src/mcp/OrchestratorMcpService.test.ts @@ -3943,6 +3943,7 @@ describe("OrchestratorMcpService thread lookup", () => { Layer.mock(ThreadManagementService.ThreadManagementService)({ getThreadShell: (threadId) => Effect.succeed(shells.find((shell) => shell.id === threadId) ?? null), + listActiveShellIndex: () => Effect.succeed([]), sendToThread: () => Ref.update(sent, (count) => count + 1).pipe(Effect.as({} as never)), ...overrides, }), @@ -3963,7 +3964,11 @@ describe("OrchestratorMcpService thread lookup", () => { const sent = yield* Ref.make(0); return yield* Effect.gen(function* () { const mcp = yield* OrchestratorMcpService.OrchestratorMcpService; - const read = yield* mcp.readThread(client, { threadId: bareId }).pipe(Effect.flip); + // Reads resolve a bare uuid to its mcp: thread, so only a miss fails. + const read = yield* mcp.readThread(client, { threadId: bareId }).pipe( + Effect.match({ onFailure: (error) => error, onSuccess: () => null }), + Effect.catchDefect(() => Effect.succeed(null)), + ); const send = yield* mcp .sendToThread(client, { threadId: bareId, message: "hello" }) .pipe(Effect.flip); @@ -4238,8 +4243,8 @@ describe("OrchestratorMcpService thread lookup", () => { it.effect("points a bare uuid at the mcp: thread it belongs to", () => Effect.gen(function* () { - const { read, send, wait, sends } = yield* failuresFor([launched]); - for (const error of [read, send, wait]) { + const { send, wait, sends } = yield* failuresFor([launched]); + for (const error of [send, wait]) { assert.equal(error.code, "thread_not_found"); assert.include(error.message, `mcp:${bareId}`); } @@ -4250,8 +4255,8 @@ describe("OrchestratorMcpService thread lookup", () => { it.effect("keeps the plain message for an id that matches nothing", () => Effect.gen(function* () { const { read, send, wait } = yield* failuresFor([]); - assert.equal(read.code, "thread_not_found"); - assert.equal(read.message, `Thread ${bareId} is no longer available.`); + assert.equal(read?.code, "thread_not_found"); + assert.include(read?.message, `No thread ${bareId} in this environment`); assert.equal(send.code, "thread_not_found"); assert.equal(send.message, `Thread ${bareId} was not found.`); assert.equal(wait.code, "thread_not_found"); @@ -4262,7 +4267,7 @@ describe("OrchestratorMcpService thread lookup", () => { it.effect("does not name an mcp: thread that was deleted", () => Effect.gen(function* () { const { read, send, wait } = yield* failuresFor([deletedLaunched]); - assert.equal(read.message, `Thread ${bareId} is no longer available.`); + assert.equal(read?.message, `Thread mcp:${bareId} was deleted.`); assert.equal(send.message, `Thread ${bareId} was not found.`); assert.equal(wait.message, send.message); }), diff --git a/apps/server/src/mcp/OrchestratorMcpService.ts b/apps/server/src/mcp/OrchestratorMcpService.ts index 59442dc012c60..2ebfa5379bb9b 100644 --- a/apps/server/src/mcp/OrchestratorMcpService.ts +++ b/apps/server/src/mcp/OrchestratorMcpService.ts @@ -140,6 +140,7 @@ import { taskPrompt, } from "./delegatedTaskModes.ts"; import { isLiveCallerShell, threadNotFound } from "./threadAccess.ts"; +import { resolveReadableThread } from "./threadReference.ts"; import * as SecretRequests from "../secrets/SecretRequests.ts"; import * as PeerForwarding from "../peer/PeerForwarding.ts"; import * as RemoteDelegation from "../peer/RemoteDelegation.ts"; @@ -1279,19 +1280,14 @@ const make = Effect.gen(function* () { const loadReadableThread = Effect.fn("OrchestratorMcpService.loadReadableThread")(function* ( scope: McpInvocationScope, - threadId: ThreadId, + reference: ThreadId, ) { const { parent } = yield* loadCaller(scope, []); - const shell = yield* threadManagement - .getThreadShell(threadId) - .pipe(Effect.mapError(threadManagementFailure)); - if (shell === null || shell.deletedAt !== null) { - return yield* threadNotFound( - threadManagement, - threadId, - `Thread ${threadId} is no longer available.`, - ); - } + const { threadId, shell } = yield* resolveReadableThread( + threadManagement, + scope.environmentId, + reference, + ); const revision = yield* threadManagement .getThreadEventSequence(threadId) .pipe(Effect.mapError(threadManagementFailure)); @@ -1309,7 +1305,7 @@ const make = Effect.gen(function* () { "contextTransfers", ]); const target = yield* records.pipe(Effect.mapError(threadManagementFailure)); - return { parent, target, shell, revision } as const; + return { parent, target, shell, revision, threadId } as const; }); const loadProviders = providerRegistry.getProviders; @@ -3118,17 +3114,14 @@ const make = Effect.gen(function* () { total: filtered.length, } satisfies OrchestratorMcpThreadListResult; }), - threadResult: Effect.fn("OrchestratorMcpService.threadResult")(function* (scope, input) { + threadResult: Effect.fn("OrchestratorMcpService.threadResult")(function* (scope, request) { yield* loadCaller(scope, []); - const shell = yield* threadManagement - .getThreadShell(input.threadId) - .pipe(Effect.mapError(threadManagementFailure)); - if (shell === null || shell.deletedAt !== null) - return yield* threadNotFound( - threadManagement, - input.threadId, - `Thread ${input.threadId} is no longer available.`, - ); + const { threadId, shell } = yield* resolveReadableThread( + threadManagement, + scope.environmentId, + request.threadId, + ); + const input = { ...request, threadId }; const revision = yield* threadManagement .getThreadEventSequence(input.threadId) .pipe(Effect.mapError(threadManagementFailure)); @@ -3209,8 +3202,12 @@ const make = Effect.gen(function* () { revision, }; }), - readThread: Effect.fn("OrchestratorMcpService.readThread")(function* (scope, input) { - const { parent, target, shell, revision } = yield* loadReadableThread(scope, input.threadId); + readThread: Effect.fn("OrchestratorMcpService.readThread")(function* (scope, request) { + const { parent, target, shell, revision, threadId } = yield* loadReadableThread( + scope, + request.threadId, + ); + const input = { ...request, threadId }; const view = input.view ?? "messages"; const afterPosition = input.afterPosition ?? -1; const limit = input.limit ?? DEFAULT_THREAD_READ_LIMIT; diff --git a/apps/server/src/mcp/threadReference.test.ts b/apps/server/src/mcp/threadReference.test.ts new file mode 100644 index 0000000000000..a5d27dadcc0f8 --- /dev/null +++ b/apps/server/src/mcp/threadReference.test.ts @@ -0,0 +1,79 @@ +import { describe, expect, it } from "@effect/vitest"; +import { EnvironmentId, ThreadId } from "@t3tools/contracts"; +import * as DateTime from "effect/DateTime"; +import * as Effect from "effect/Effect"; + +import type { ActiveShellIndexEntry } from "../orchestration-v2/ProjectionStore.ts"; +import { liveThreadShell } from "./McpToolAccess.testkit.ts"; +import { resolveReadableThread } from "./threadReference.ts"; + +const here = EnvironmentId.make("environment-here"); +const uuid = "5d0b4a3e-8c1f-4a52-9d37-2f6c7e1b9a04"; +const mcpThread = ThreadId.make(`mcp:${uuid}`); +const launchThread = ThreadId.make(`mcp:launch:${"be52150e".repeat(8)}`); +const nativeThread = ThreadId.make("7e56b504-8739-4f3f-80e7-298410d87ec0"); +const deletedThread = ThreadId.make("mcp:0dd09096-12e3-4179-87d5-42fa45c77d5e"); + +const threads = { + getThreadShell: (threadId: ThreadId) => + Effect.succeed( + threadId === deletedThread + ? { ...liveThreadShell(threadId), deletedAt: DateTime.makeUnsafe(0) } + : [mcpThread, launchThread, nativeThread].includes(threadId) + ? liveThreadShell(threadId) + : null, + ), + listActiveShellIndex: () => + Effect.succeed( + [mcpThread, launchThread, nativeThread].map( + (id) => ({ id }) as unknown as ActiveShellIndexEntry, + ), + ), +}; + +const resolve = (reference: string) => + resolveReadableThread(threads, here, ThreadId.make(reference)).pipe( + Effect.map(({ threadId }) => threadId), + ); +const refuse = (reference: string) => resolve(reference).pipe(Effect.flip); + +describe("resolveReadableThread", () => { + it.effect("reads each reference shape agents pass as the thread it names", () => + Effect.gen(function* () { + for (const [reference, expected] of [ + [mcpThread, mcpThread], + [uuid, mcpThread], + [launchThread, launchThread], + [nativeThread, nativeThread], + [`t3-thread://v1/${mcpThread}`, mcpThread], + [`t3-thread://v1/${uuid}`, mcpThread], + [`t3-thread://v2/${here}/${launchThread}`, launchThread], + [`t3-thread://v1/mcp%3A${uuid}`, mcpThread], + [`https://app.t3.codes/threads/${here}/mcp%3A${uuid}`, mcpThread], + ] as const) { + expect(yield* resolve(reference), reference).toBe(expected); + } + }), + ); + + it.effect("sends a link for another environment there instead of reading a local thread", () => + Effect.gen(function* () { + const error = yield* refuse(`t3-thread://v2/environment-there/${mcpThread}`); + expect(error.code).toBe("invalid_request"); + expect(error.message).toContain(`Pass environmentId: "environment-there"`); + }), + ); + + it.effect("says a thread was deleted, and names the closest ids for one never here", () => + Effect.gen(function* () { + expect((yield* refuse(deletedThread)).message).toBe(`Thread ${deletedThread} was deleted.`); + + const typo = yield* refuse("mcp:5d0b4a3e-0000-4000-8000-000000000000"); + expect(typo.code).toBe("thread_not_found"); + expect(typo.message).toContain(`Closest: \`${mcpThread}\``); + + const unknown = yield* refuse("mcp:11111111-2222-4333-8444-555555555555"); + expect(unknown.message).toContain("pass its environmentId"); + }), + ); +}); diff --git a/apps/server/src/mcp/threadReference.ts b/apps/server/src/mcp/threadReference.ts new file mode 100644 index 0000000000000..224856e49f272 --- /dev/null +++ b/apps/server/src/mcp/threadReference.ts @@ -0,0 +1,107 @@ +import { + type EnvironmentId, + OrchestratorMcpFailure, + type OrchestrationV2ThreadShell, + ThreadId, +} from "@t3tools/contracts"; +import { parseThreadLinkHref, threadLinkCandidates } from "@t3tools/shared/threadLinks"; +import * as Effect from "effect/Effect"; + +import type * as ThreadManagement from "../orchestration-v2/ThreadManagementService.ts"; + +type Threads = Pick< + ThreadManagement.ThreadManagementService["Service"], + "getThreadShell" | "listActiveShellIndex" +>; + +const unavailable = () => + new OrchestratorMcpFailure({ + code: "orchestration_error", + message: "The operation could not be completed.", + }); + +const LINK_PREFIXES = ["t3-thread://", "https://", "http://"]; +const MAX_SUGGESTIONS = 3; + +/** The id-like core of a reference, without `mcp:`, `mcp:launch:` or a uuid's dashes. */ +const idCore = (threadId: string) => + threadId + .replace(/^mcp:(launch:)?/, "") + .replaceAll("-", "") + .toLowerCase(); + +/** + * Outside clients get hosted links that escape `mcp:` as `mcp%3A`, and models often drop it and + * pass the bare uuid. Reads have no per-thread grant, so the id is resolved here instead of + * hinted; write tools keep their exact-id checks. + */ +const variants = (threadId: ThreadId): ReadonlyArray => { + if (threadId.startsWith("mcp:launch:")) return [threadId]; + if (threadId.startsWith("mcp:")) return [threadId, ThreadId.make(threadId.slice(4))]; + return [threadId, ThreadId.make(`mcp:${threadId}`)]; +}; + +const closestMatches = Effect.fn("mcp.threadReference.closestMatches")(function* ( + threads: Threads, + reference: ThreadId, +) { + const core = idCore(reference); + if (core.length < 6) return []; + const prefix = core.slice(0, 8); + const index = yield* threads.listActiveShellIndex().pipe(Effect.orElseSucceed(() => [])); + return index + .map((entry) => entry.id) + .filter((id) => idCore(id).startsWith(prefix)) + .slice(0, MAX_SUGGESTIONS); +}); + +/** + * Resolves what an agent passed as a thread to read: a thread id, a `t3-thread://` v1 or v2 link, + * a hosted thread link, a bare uuid of an `mcp:` thread, or an `mcp:launch:` id. + */ +export const resolveReadableThread = Effect.fn("mcp.resolveReadableThread")(function* ( + threads: Threads, + environmentId: EnvironmentId, + reference: ThreadId, +) { + let candidates: ReadonlyArray = [reference]; + if (LINK_PREFIXES.some((prefix) => reference.startsWith(prefix))) { + const link = parseThreadLinkHref(reference); + if (link === null) { + return yield* new OrchestratorMcpFailure({ + code: "invalid_request", + message: `threadId ${reference} is not a thread link. Pass a thread id such as \`mcp:\`, a t3-thread:// link, or a hosted /threads// link.`, + }); + } + if (link.environmentId !== null && link.environmentId !== environmentId) { + return yield* new OrchestratorMcpFailure({ + code: "invalid_request", + message: `That link names environment ${link.environmentId}, not this one (${environmentId}). Pass environmentId: "${link.environmentId}" and threadId: "${link.threadId}".`, + }); + } + candidates = threadLinkCandidates(link, environmentId).map((ref) => ref.threadId); + } + let deleted: ThreadId | undefined; + for (const candidate of candidates.flatMap(variants)) { + const shell: OrchestrationV2ThreadShell | null = yield* threads + .getThreadShell(candidate) + .pipe(Effect.mapError(unavailable)); + if (shell === null) continue; + if (shell.deletedAt === null) return { threadId: candidate, shell }; + deleted ??= candidate; + } + if (deleted !== undefined) { + return yield* new OrchestratorMcpFailure({ + code: "thread_not_found", + message: `Thread ${deleted} was deleted.`, + }); + } + const matches = yield* closestMatches(threads, candidates[0] ?? reference); + return yield* new OrchestratorMcpFailure({ + code: "thread_not_found", + message: + matches.length > 0 + ? `No thread ${reference} in this environment. Closest: ${matches.map((id) => `\`${id}\``).join(", ")}.` + : `No thread ${reference} in this environment (${environmentId}). For a linked environment's thread, pass its environmentId (t3_environment_links); t3_thread_search finds threads by title.`, + }); +}); From 5fc94a9c22478842aad6e55e0e269e8318282de1 Mon Sep 17 00:00:00 2001 From: Chris OHearn Date: Thu, 12 Nov 2026 19:29:31 -0700 Subject: [PATCH 02/14] feat(mcp): t3_thread_send reports where a queued message waits A send that queues behind a busy run now returns its queue position, the messages ahead of it, the active run and its age, and whether the queue is held. Same-thread waits run 17 to 49 minutes, and senders had no way to see why. Co-Authored-By: Claude Opus 5.5 --- apps/server/src/mcp/OrchestratorMcpService.ts | 20 +++++ apps/server/src/mcp/queueStanding.test.ts | 73 +++++++++++++++++++ apps/server/src/mcp/queueStanding.ts | 38 ++++++++++ packages/contracts/src/orchestratorMcp.ts | 11 +++ 4 files changed, 142 insertions(+) create mode 100644 apps/server/src/mcp/queueStanding.test.ts create mode 100644 apps/server/src/mcp/queueStanding.ts diff --git a/apps/server/src/mcp/OrchestratorMcpService.ts b/apps/server/src/mcp/OrchestratorMcpService.ts index 2ebfa5379bb9b..652d4c776b255 100644 --- a/apps/server/src/mcp/OrchestratorMcpService.ts +++ b/apps/server/src/mcp/OrchestratorMcpService.ts @@ -141,6 +141,7 @@ import { } from "./delegatedTaskModes.ts"; import { isLiveCallerShell, threadNotFound } from "./threadAccess.ts"; import { resolveReadableThread } from "./threadReference.ts"; +import { queuedRunMessageIds, queueStanding } from "./queueStanding.ts"; import * as SecretRequests from "../secrets/SecretRequests.ts"; import * as PeerForwarding from "../peer/PeerForwarding.ts"; import * as RemoteDelegation from "../peer/RemoteDelegation.ts"; @@ -1310,6 +1311,20 @@ const make = Effect.gen(function* () { const loadProviders = providerRegistry.getProviders; + // Best effort: the message is already queued, so a failed read only omits the standing. + const readQueueStanding = Effect.fn("OrchestratorMcpService.readQueueStanding")( + function* (threadId: ThreadId, runId: RunId) { + const { runs } = yield* threadManagement.getThreadRecords(threadId, ["runs"], { + runStatuses: [...ThreadManagementService.ACTIVE_RUN_STATUSES, "queued"], + }); + const { messages } = yield* threadManagement.getThreadRecords(threadId, ["messages"], { + messageIds: queuedRunMessageIds(runs), + }); + return queueStanding({ runs, messages }, runId, yield* Clock.currentTimeMillis); + }, + Effect.orElseSucceed(() => undefined), + ); + const loadOrchestrationCapableInstanceIds = () => providerAdapters.list().pipe(Effect.map((instanceIds) => new Set(instanceIds))); @@ -3470,8 +3485,13 @@ const make = Effect.gen(function* () { result.run.id, input.clientRequestId, ).pipe(Effect.provideService(Invocation.McpInvocationContext, scope)); + const queue = + result.delivery === "queued" + ? yield* readQueueStanding(input.threadId, result.run.id) + : undefined; return { ...(notify === undefined ? {} : { notify }), + ...(queue === undefined ? {} : { queue }), threadId: input.threadId, link: threadLinkFor(scope, input.threadId, target.thread.title), messageId, diff --git a/apps/server/src/mcp/queueStanding.test.ts b/apps/server/src/mcp/queueStanding.test.ts new file mode 100644 index 0000000000000..e7a87c4da600c --- /dev/null +++ b/apps/server/src/mcp/queueStanding.test.ts @@ -0,0 +1,73 @@ +import { RunId } from "@t3tools/contracts"; +import * as DateTime from "effect/DateTime"; +import { describe, expect, it } from "vite-plus/test"; + +import { queueStanding } from "./queueStanding.ts"; + +const at = (iso: string) => DateTime.makeUnsafe(iso); +const now = DateTime.toEpochMillis(at("2026-11-12T10:20:00Z")); + +const projection = (runs: ReadonlyArray, messages: ReadonlyArray = []) => + ({ runs, messages }) as never; + +describe("queueStanding", () => { + it("counts the messages that start first and the age of the run it waits on", () => { + const runs = [ + { + id: "run:active", + ordinal: 1, + status: "running", + requestedAt: at("2026-11-12T10:00:00Z"), + startedAt: at("2026-11-12T10:02:30Z"), + }, + { id: "run:mine", ordinal: 4, queuePosition: 3, status: "queued", userMessageId: "m:mine" }, + { id: "run:first", ordinal: 2, queuePosition: 1, status: "queued", userMessageId: "m:first" }, + { id: "run:second", ordinal: 3, queuePosition: 2, status: "queued", userMessageId: "m:2" }, + { id: "run:later", ordinal: 5, queuePosition: 4, status: "queued", userMessageId: "m:later" }, + ]; + + expect(queueStanding(projection(runs), RunId.make("run:mine"), now)).toEqual({ + position: 3, + messagesAhead: 2, + activeRunId: "run:active", + activeRunAgeSeconds: 1050, + }); + }); + + it("puts automatic task completions ahead and reports a held queue without an active run", () => { + const runs = [ + { + id: "run:mine", + ordinal: 2, + queuePosition: 1, + queueHeld: true, + status: "queued", + userMessageId: "m:mine", + }, + { + id: "run:completion", + ordinal: 3, + queuePosition: 2, + queueHeld: true, + status: "queued", + userMessageId: "m:completion", + }, + ]; + const messages = [ + { id: "m:mine" }, + { + id: "m:completion", + delegatedCompletion: { parentRunId: "run:p", generation: 1, taskIds: [] }, + }, + ]; + + expect(queueStanding(projection(runs, messages), RunId.make("run:mine"), now)).toEqual({ + position: 2, + messagesAhead: 1, + activeRunId: null, + activeRunAgeSeconds: null, + held: true, + }); + expect(queueStanding(projection(runs, messages), RunId.make("run:gone"), now)).toBeUndefined(); + }); +}); diff --git a/apps/server/src/mcp/queueStanding.ts b/apps/server/src/mcp/queueStanding.ts new file mode 100644 index 0000000000000..4ce4bab93ed1f --- /dev/null +++ b/apps/server/src/mcp/queueStanding.ts @@ -0,0 +1,38 @@ +import type { + OrchestrationV2Run, + OrchestrationV2ThreadProjection, + OrchestratorMcpQueueStanding, + RunId, +} from "@t3tools/contracts"; +import * as DateTime from "effect/DateTime"; + +import { isActiveRun } from "../orchestration-v2/ThreadManagementService.ts"; +import { queuedRunsInDeliveryOrder } from "../orchestration-v2/QueuedRunOrder.ts"; + +/** Where a queued run waits: what starts before it, and how long the run it waits on has run. */ +export function queueStanding( + projection: Pick, + runId: RunId, + nowMs: number, +): OrchestratorMcpQueueStanding | undefined { + const queued = queuedRunsInDeliveryOrder(projection); + const index = queued.findIndex((run) => run.id === runId); + if (index < 0) return undefined; + const active = projection.runs + .filter(isActiveRun) + .toSorted((left, right) => right.ordinal - left.ordinal)[0]; + const since = active === undefined ? undefined : (active.startedAt ?? active.requestedAt); + return { + position: index + 1, + messagesAhead: index, + activeRunId: active?.id ?? null, + activeRunAgeSeconds: + since === undefined + ? null + : Math.max(0, Math.floor((nowMs - DateTime.toEpochMillis(since)) / 1000)), + ...(queued[index]?.queueHeld === true ? { held: true } : {}), + }; +} + +export const queuedRunMessageIds = (runs: ReadonlyArray) => + runs.filter((run) => run.status === "queued").map((run) => run.userMessageId); diff --git a/packages/contracts/src/orchestratorMcp.ts b/packages/contracts/src/orchestratorMcp.ts index 4a2706f09d4cf..9573f82c09552 100644 --- a/packages/contracts/src/orchestratorMcp.ts +++ b/packages/contracts/src/orchestratorMcp.ts @@ -600,6 +600,16 @@ export const OrchestratorMcpThreadSendInput = Schema.Struct({ }); export type OrchestratorMcpThreadSendInput = typeof OrchestratorMcpThreadSendInput.Type; +/** Set when a send queues: `position` 1 starts next. `held` waits for a resume. */ +export const OrchestratorMcpQueueStanding = Schema.Struct({ + position: PositiveInt, + messagesAhead: NonNegativeInt, + activeRunId: Schema.NullOr(RunId), + activeRunAgeSeconds: Schema.NullOr(NonNegativeInt), + held: Schema.optional(Schema.Boolean), +}); +export type OrchestratorMcpQueueStanding = typeof OrchestratorMcpQueueStanding.Type; + export const OrchestratorMcpThreadSendResult = Schema.Struct({ notify: Schema.optional(McpThreadNotifyResult), threadId: ThreadId, @@ -609,6 +619,7 @@ export const OrchestratorMcpThreadSendResult = Schema.Struct({ taskId: Schema.optional(NodeId), status: OrchestrationV2RunStatus, delivery: Schema.Literals(["started", "queued", "steered", "restarted"]), + queue: Schema.optional(OrchestratorMcpQueueStanding), }); export type OrchestratorMcpThreadSendResult = typeof OrchestratorMcpThreadSendResult.Type; From fd1d74af5fc8a995d760666c68775dfbf92eee12 Mon Sep 17 00:00:00 2001 From: Chris OHearn Date: Thu, 12 Nov 2026 19:31:13 -0700 Subject: [PATCH 03/14] fix(mcp): delegate_task errors name the field and the valid choices Three of six delegate_task failures in two days were a cross-project target.projectId, whose error never said that t3_thread_launch with projectId starts work in another project. That error now does, and the provider, driver, model, worktree and linked-project errors name the field at fault and list what is accepted. Co-Authored-By: Claude Opus 5.5 --- .../src/mcp/OrchestratorMcpService.test.ts | 18 ++++++++++++++++-- apps/server/src/mcp/OrchestratorMcpService.ts | 19 +++++++++++++------ apps/server/src/mcp/providerModels.ts | 14 +++++++++++++- .../src/mcp/toolkits/project/handlers.test.ts | 6 +++++- apps/server/src/peer/RemoteDelegation.ts | 2 +- 5 files changed, 48 insertions(+), 11 deletions(-) diff --git a/apps/server/src/mcp/OrchestratorMcpService.test.ts b/apps/server/src/mcp/OrchestratorMcpService.test.ts index ac5330fd34df5..0c4e05c8d687c 100644 --- a/apps/server/src/mcp/OrchestratorMcpService.test.ts +++ b/apps/server/src/mcp/OrchestratorMcpService.test.ts @@ -1985,8 +1985,22 @@ describe("OrchestratorMcpService provider resolution", () => { }) .pipe(Effect.flip); assert.equal(byDriver.code, "provider_unavailable"); - assert.isTrue( - byDriver.message.includes("No V2 provider adapter is registered for driver forkOnly."), + assert.include( + byDriver.message, + "No V2 provider adapter is registered for target.driverKind forkOnly. Drivers here: ", + ); + + const elsewhere = yield* service + .delegateTask(scope, { + task: "Summarize the diff.", + target: { projectId: ProjectId.make("project:elsewhere") }, + mode: "async", + }) + .pipe(Effect.flip); + assert.equal(elsewhere.code, "invalid_request"); + assert.include( + elsewhere.message, + 'use t3_thread_launch with projectId: "project:elsewhere"', ); }).pipe(Effect.provide(layerOrchestratorService.pipe(Layer.provide(layerDependencies)))); }), diff --git a/apps/server/src/mcp/OrchestratorMcpService.ts b/apps/server/src/mcp/OrchestratorMcpService.ts index 652d4c776b255..1f92feb22899b 100644 --- a/apps/server/src/mcp/OrchestratorMcpService.ts +++ b/apps/server/src/mcp/OrchestratorMcpService.ts @@ -1,6 +1,6 @@ import * as JarvisPlaybook from "./JarvisPlaybook.ts"; import * as WorkLedger from "../persistence/WorkLedger.ts"; -import { advertisedModel, requireAdvertisedModel } from "./providerModels.ts"; +import { advertisedModel, listChoices, requireAdvertisedModel } from "./providerModels.ts"; import { hasGitEntry } from "./gitEntryProbe.ts"; import * as Invocation from "./McpInvocationContext.ts"; import * as ThreadNotifications from "./ThreadNotifications.ts"; @@ -1371,6 +1371,10 @@ const make = Effect.gen(function* () { const requestedInstanceId = input.target?.providerInstanceId; const requestedDriver = input.target?.driverKind; const orchestrationCapableInstanceIds = yield* loadOrchestrationCapableInstanceIds(); + const capableProviders = () => + input.providers.filter((provider) => + orchestrationCapableInstanceIds.has(provider.instanceId), + ); let instanceId = requestedInstanceId; if (instanceId === undefined && requestedDriver !== undefined) { @@ -1382,7 +1386,7 @@ const make = Effect.gen(function* () { if (candidates.length === 0) { return yield* failure( "provider_unavailable", - `No V2 provider adapter is registered for driver ${requestedDriver}.`, + `No V2 provider adapter is registered for target.driverKind ${requestedDriver}. Drivers here: ${listChoices(capableProviders().map((provider) => provider.driver))}.`, ); } const healthyCandidates = candidates.filter( @@ -1422,13 +1426,13 @@ const make = Effect.gen(function* () { if (provider === undefined) { return yield* failure( "provider_unavailable", - `Provider instance ${instanceId} is not registered.`, + `${requestedInstanceId === undefined ? "This thread's provider instance" : "target.providerInstanceId"} ${instanceId} is not registered. Pass target.providerInstanceId, one of: ${listChoices(capableProviders().map((provider) => provider.instanceId))}.`, ); } if (requestedDriver !== undefined && provider.driver !== requestedDriver) { return yield* failure( "invalid_request", - `Provider instance ${instanceId} uses driver ${provider.driver}, not ${requestedDriver}.`, + `target.providerInstanceId ${instanceId} uses driver ${provider.driver}, not target.driverKind ${requestedDriver}. Pass only one of them.`, ); } const constraints = providerConstraints( @@ -2508,7 +2512,7 @@ const make = Effect.gen(function* () { ) { return yield* failure( "invalid_request", - "A local task runs in this thread's project. Omit target.projectId, or pass target.environmentId to run it in that environment's project.", + `target.projectId ${input.target.projectId} is not this thread's project (${parent.thread.projectId}), and a local task always runs here. To start work in that project, use t3_thread_launch with projectId: "${input.target.projectId}". Otherwise omit target.projectId, or add target.environmentId to run in a linked environment's project.`, ); } const parentRun = parent.runs @@ -2557,7 +2561,10 @@ const make = Effect.gen(function* () { }) .pipe( Effect.mapError(() => - failure("invalid_request", "Unable to resolve the parent checkout commit."), + failure( + "invalid_request", + `isolation "worktree" needs a commit in the parent checkout (${parent.thread.worktreePath ?? project.workspaceRoot}), and none resolved. Use isolation "shared", or commit first.`, + ), ), ); // Launch preparation creates the worktree from the project root, so a diff --git a/apps/server/src/mcp/providerModels.ts b/apps/server/src/mcp/providerModels.ts index af4f9e84203f0..454c223801fd8 100644 --- a/apps/server/src/mcp/providerModels.ts +++ b/apps/server/src/mcp/providerModels.ts @@ -13,7 +13,19 @@ export const requireAdvertisedModel = (provider: ServerProvider, model: string) ? Effect.fail( new OrchestratorMcpFailure({ code: "model_unavailable", - message: `Model ${model} is not advertised by provider ${provider.instanceId}.`, + message: `Model ${model} is not advertised by provider ${provider.instanceId}. Use one of: ${listChoices(provider.models.map((candidate) => candidate.slug))}.`, }), ) : Effect.void; + +const MAX_LISTED_CHOICES = 12; + +/** Valid values for an error message, capped so a large catalog stays readable. */ +export const listChoices = (values: Iterable) => { + const all = [...new Set(values)]; + if (all.length === 0) return "none"; + const shown = all.slice(0, MAX_LISTED_CHOICES).join(", "); + return all.length > MAX_LISTED_CHOICES + ? `${shown}, and ${all.length - MAX_LISTED_CHOICES} more in orchestrator_capabilities` + : shown; +}; diff --git a/apps/server/src/mcp/toolkits/project/handlers.test.ts b/apps/server/src/mcp/toolkits/project/handlers.test.ts index d7693b2d348e8..96d9e6b9ec403 100644 --- a/apps/server/src/mcp/toolkits/project/handlers.test.ts +++ b/apps/server/src/mcp/toolkits/project/handlers.test.ts @@ -412,7 +412,11 @@ it.effect("a launch with a model its provider does not advertise creates no thre ] as const) { expect(yield* launchWith(instanceId, model)).toMatchObject({ code: "model_unavailable", - message: `Model ${model} is not advertised by provider ${instanceId}.`, + message: expect.stringMatching( + new RegExp( + `^Model ${model} is not advertised by provider ${instanceId}\\. Use one of: \\S`, + ), + ), }); } expect(launched).toHaveLength(0); diff --git a/apps/server/src/peer/RemoteDelegation.ts b/apps/server/src/peer/RemoteDelegation.ts index a5790332ebc64..2001e502d4bd1 100644 --- a/apps/server/src/peer/RemoteDelegation.ts +++ b/apps/server/src/peer/RemoteDelegation.ts @@ -186,7 +186,7 @@ const make = Effect.gen(function* () { if (key === undefined) { return yield* new OrchestratorMcpFailure({ code: "target_required", - message: "Pass target.projectId: this thread's project has no repository to match there.", + message: `Pass target.projectId: this thread's project has no repository to match in environment ${environmentId}. t3_project_list with environmentId: "${environmentId}" lists its projects.`, }); } const matches: Array<{ readonly id: ProjectId; readonly title: string }> = []; From d1a23b5950c93b1c610568743a45b6f3968ca791 Mon Sep 17 00:00:00 2001 From: Chris OHearn Date: Thu, 12 Nov 2026 19:46:10 -0700 Subject: [PATCH 04/14] feat(mcp): t3_thread_configure can schedule a model change on a busy thread The Jarvis inbox always has a run going, so every effort change was refused as busy. With applyAt: "next_turn", the change is stored on the thread and the next turn starts with it. Messages queued before it start with it too, the way messages queued before a failover follow the thread. It clears once none of those wait. Reading the configuration shows the pending change, and scheduling the current model cancels it. Provider instance switches and runtime mode changes still need an idle thread. Co-Authored-By: Claude Opus 5.5 --- apps/server/src/mcp/toolkits/core.test.ts | 76 ++++++++++++ .../src/mcp/toolkits/thread/handlers.ts | 40 +++++- apps/server/src/mcp/toolkits/thread/tools.ts | 20 ++- .../Orchestrator.control-reads.test.ts | 34 +++++- .../src/orchestration-v2/Orchestrator.ts | 114 +++++++++++++++--- .../src/orchestration-v2/runtimeLayer.test.ts | 87 +++++++++++++ .../src/provider/agentContextBudget.json | 2 +- packages/contracts/src/orchestrationV2.ts | 15 +++ 8 files changed, 361 insertions(+), 27 deletions(-) diff --git a/apps/server/src/mcp/toolkits/core.test.ts b/apps/server/src/mcp/toolkits/core.test.ts index 1edac9c9b1e79..43af61ed3afb6 100644 --- a/apps/server/src/mcp/toolkits/core.test.ts +++ b/apps/server/src/mcp/toolkits/core.test.ts @@ -1266,6 +1266,82 @@ it.effect("a read-only client reads threads and is refused every write before it ); const dispatched: Array = []; +it.effect("schedules a model change on a busy thread and shows it until it applies", () => { + const commands: Array = []; + const busyThread = { + id: ThreadId.make("busy-inbox"), + projectId: "other-project", + providerInstanceId: "codex", + modelSelection: { instanceId: "codex", model: "gpt-5" }, + runtimeMode: "full-access", + interactionMode: "default", + deletedAt: null, + }; + const scheduled = { + modelSelection: { instanceId: "codex", model: "gpt-6" }, + afterRunId: "run:busy", + }; + return Effect.gen(function* () { + const server = yield* McpServer.McpServer; + const call = (args: Record) => + server + .callTool({ name: "t3_thread_configure", arguments: { threadId: busyThread.id, ...args } }) + .pipe( + Effect.provideService( + McpInvocationContext.McpInvocationContext, + clientScope("full-access"), + ), + Effect.provideService(McpSchema.McpServerClient, client), + ); + + const result = yield* call({ modelSelection: scheduled.modelSelection, applyAt: "next_turn" }); + expect(result.structuredContent).toEqual({ + status: "scheduled", + afterRunId: "run:busy", + sequence: 7, + }); + expect(commands).toEqual([ + expect.objectContaining({ type: "thread.model-selection.set", applyAt: "next_turn" }), + ]); + expect((yield* call({})).structuredContent).toMatchObject({ + modelSelection: busyThread.modelSelection, + scheduledModelSelection: scheduled, + }); + + for (const refused of [ + { runtimeMode: "approval-required", applyAt: "next_turn" }, + { modelSelection: { instanceId: "claudeAgent", model: "opus" }, applyAt: "next_turn" }, + ]) { + expect(declaredFailure(yield* call(refused))).toMatchObject({ code: "invalid_request" }); + } + expect(commands).toHaveLength(1); + }).pipe( + Effect.provide( + layerThreadToolkit.pipe( + Layer.provideMerge(McpHttpServer.layerInProcessMcpServer), + Layer.provide(NodeCrypto.layer), + Layer.provide( + Layer.mock(ThreadManagement.ThreadManagementService)({ + getThreadShell: () => Effect.succeed(busyThread as never), + getProjectThreadRecords: () => + Effect.succeed({ + thread: { + ...busyThread, + ...(commands.length === 0 ? {} : { scheduledModelSelection: scheduled }), + }, + } as never), + dispatch: (command) => + Effect.sync(() => { + commands.push(command); + return { sequence: 7 } as never; + }), + }), + ), + ), + ), + ); +}); + it.effect("refuses act-as-caller tools to a client caller", () => Effect.gen(function* () { const server = yield* McpServer.McpServer; diff --git a/apps/server/src/mcp/toolkits/thread/handlers.ts b/apps/server/src/mcp/toolkits/thread/handlers.ts index a0955869db3b3..185883e871e6c 100644 --- a/apps/server/src/mcp/toolkits/thread/handlers.ts +++ b/apps/server/src/mcp/toolkits/thread/handlers.ts @@ -232,6 +232,14 @@ export const layer = McpToolAccess.toLayer(ThreadToolkit, { return { threadId: thread.id, modelSelection: thread.modelSelection, + ...(thread.scheduledModelSelection == null + ? {} + : { + scheduledModelSelection: { + modelSelection: thread.scheduledModelSelection.modelSelection, + afterRunId: thread.scheduledModelSelection.afterRunId, + }, + }), runtimeMode: thread.runtimeMode, interactionMode: thread.interactionMode, }; @@ -250,6 +258,13 @@ export const layer = McpToolAccess.toLayer(ThreadToolkit, { message: "Set runtimeMode separately from modelSelection.", }); } + if (input.applyAt !== undefined) { + return yield* new OrchestratorMcpFailure({ + code: "invalid_request", + message: + "applyAt schedules a modelSelection; runtimeMode changes only on an idle thread.", + }); + } const scope = yield* McpInvocationContext.McpInvocationContext; const actor = scope.thread !== undefined @@ -272,10 +287,31 @@ export const layer = McpToolAccess.toLayer(ThreadToolkit, { } const modelSelection = yield* required(input.modelSelection, "modelSelection"); const type = modelSelectionCommandType(thread.providerInstanceId, modelSelection); + if (input.applyAt !== undefined && type === "provider.switch") { + return yield* new OrchestratorMcpFailure({ + code: "invalid_request", + message: `applyAt schedules a model or option change on this thread's provider instance (${thread.providerInstanceId}). Switch to ${modelSelection.instanceId} while the thread is idle.`, + }); + } + const applyAt = input.applyAt; const result = yield* threads - .dispatch({ type, threadId: thread.id, commandId: yield* newCommandId(), modelSelection }) + .dispatch({ + type, + threadId: thread.id, + commandId: yield* newCommandId(), + modelSelection, + ...(applyAt === undefined ? {} : { applyAt }), + }) .pipe(Effect.mapError(dispatchFailure)); - return { sequence: result.sequence }; + if (applyAt === undefined) return { sequence: result.sequence }; + const scheduled = (yield* readThread(thread.id)).projection.thread.scheduledModelSelection; + return scheduled == null + ? { sequence: result.sequence } + : { + status: "scheduled" as const, + afterRunId: scheduled.afterRunId, + sequence: result.sequence, + }; }), ), ), diff --git a/apps/server/src/mcp/toolkits/thread/tools.ts b/apps/server/src/mcp/toolkits/thread/tools.ts index 9e815956cd4da..8ebccd91d00a6 100644 --- a/apps/server/src/mcp/toolkits/thread/tools.ts +++ b/apps/server/src/mcp/toolkits/thread/tools.ts @@ -187,6 +187,9 @@ const ApprovalLogTool = Tool.make("t3_approval_log", { const threadConfiguration = Schema.Struct({ threadId: ThreadId, modelSelection: ModelSelection, + scheduledModelSelection: Schema.optional( + Schema.Struct({ modelSelection: ModelSelection, afterRunId: RunId }), + ), runtimeMode: RuntimeMode, interactionMode: ProviderInteractionMode, }); @@ -198,9 +201,24 @@ const ThreadConfigureTool = Tool.make("t3_thread_configure", { environmentId: OrchestratorMcpEnvironmentTarget, threadId: Schema.optional(ThreadId), modelSelection: Schema.optional(ModelSelection), + applyAt: Schema.optional( + Schema.Literal("next_turn").annotate({ + description: + "Busy thread: apply modelSelection from the next turn, queued messages included.", + }), + ), runtimeMode: Schema.optional(RuntimeMode), }), - success: Schema.Union([threadConfiguration, OrchestrationV2DispatchCommandResult]), + // The scheduled result goes before the plain one, which would match it and drop its fields. + success: Schema.Union([ + threadConfiguration, + Schema.Struct({ + status: Schema.Literal("scheduled"), + afterRunId: RunId, + sequence: OrchestrationV2DispatchCommandResult.fields.sequence, + }), + OrchestrationV2DispatchCommandResult, + ]), }).annotate(Tool.Destructive, true); const ThreadTransferTool = Tool.make("t3_thread_transfer", { diff --git a/apps/server/src/orchestration-v2/Orchestrator.control-reads.test.ts b/apps/server/src/orchestration-v2/Orchestrator.control-reads.test.ts index 150277023dc03..53f5ddd267cae 100644 --- a/apps/server/src/orchestration-v2/Orchestrator.control-reads.test.ts +++ b/apps/server/src/orchestration-v2/Orchestrator.control-reads.test.ts @@ -71,16 +71,24 @@ const layerTest = Layer.mergeAll( ), ); -it.effect.each( - (["provider.switch", "thread.model-selection.set"] as const).flatMap((type) => +it.effect.each([ + ...(["provider.switch", "thread.model-selection.set"] as const).flatMap((type) => [ { active: true, selectionChange: "instance" }, { active: false, selectionChange: "instance" }, { active: true, selectionChange: "next-turn" }, { active: true, selectionChange: "restart" }, - ].map((scenario) => ({ type, ...scenario })), + ].map((scenario) => ({ type, ...scenario, applyAt: undefined })), + ), + ...(["instance", "restart"] as const).flatMap((selectionChange) => + [true, false].map((active) => ({ + type: "thread.model-selection.set" as const, + active, + selectionChange, + applyAt: "next_turn" as const, + })), ), -)("$type $selectionChange ($active)", ({ type, active, selectionChange }) => +])("$type $selectionChange ($active) $applyAt", ({ type, active, selectionChange, applyAt }) => Effect.gen(function* () { const orchestrator = yield* Orchestrator.OrchestratorV2; const projections = yield* ProjectionStore.ProjectionStoreV2; @@ -208,10 +216,26 @@ it.effect.each( commandId, threadId, modelSelection: target, + ...(applyAt === undefined ? {} : { applyAt }), }) .pipe(Effect.result); const after = yield* projections.getThreadProjection(threadId); - if (active && selectionChange !== "next-turn") { + if (active && applyAt === "next_turn") { + assert.ok(Result.isSuccess(outcome)); + assert.deepEqual(after.thread.modelSelection, before.thread.modelSelection); + assert.deepEqual(after.thread.scheduledModelSelection, { + modelSelection: target, + afterRunId: runId, + queuedThroughOrdinal: 1, + }); + assert.deepEqual(after.runs, before.runs); + assert.deepEqual(after.providerSessions, before.providerSessions); + assert.deepEqual( + yield* outbox.listByCommandId(commandId), + [], + "a scheduled switch must not touch the running session", + ); + } else if (active && selectionChange !== "next-turn") { assert.deepEqual( after, before, diff --git a/apps/server/src/orchestration-v2/Orchestrator.ts b/apps/server/src/orchestration-v2/Orchestrator.ts index 8e1b677fd60ed..e2ba4d522bfa9 100644 --- a/apps/server/src/orchestration-v2/Orchestrator.ts +++ b/apps/server/src/orchestration-v2/Orchestrator.ts @@ -54,6 +54,7 @@ import { type OrchestrationV2RemoteTaskChild, type OrchestrationV2ModelSwitch, type OrchestrationV2Run, + type OrchestrationV2ScheduledModelSelection, type OrchestrationV2RunAttempt, type OrchestrationV2ThreadShell, type OrchestrationV2ThreadShellSnapshot, @@ -952,12 +953,51 @@ function queuedBeforeFailoverFrom( }); } +/** The selection a new turn starts with: a change scheduled behind a busy run, else the thread's. */ +function nextTurnModelSelection( + thread: Pick< + OrchestrationV2ThreadProjection["thread"], + "modelSelection" | "scheduledModelSelection" + >, +): ModelSelection { + return thread.scheduledModelSelection?.modelSelection ?? thread.modelSelection; +} + +/** A run queued before a scheduled change starts with it, as one queued before a failover does. */ +function queuedBeforeScheduledSelection( + projection: Pick, + run: OrchestrationV2Run, +): boolean { + const scheduled = projection.thread.scheduledModelSelection; + return scheduled != null && run.ordinal <= scheduled.queuedThroughOrdinal; +} + +/** Drops a scheduled change once the run starting now leaves no run queued before it. */ +function threadAtRunStart( + projection: Pick, + startingRunId: OrchestrationV2Run["id"] | null, +): OrchestrationV2ThreadProjection["thread"] { + const scheduled = projection.thread.scheduledModelSelection; + if (scheduled == null) return projection.thread; + const waiting = projection.runs.some( + (run) => + run.id !== startingRunId && + run.status === "queued" && + run.ordinal <= scheduled.queuedThroughOrdinal, + ); + return waiting ? projection.thread : { ...projection.thread, scheduledModelSelection: null }; +} + function queuedRunFollowsThread( - projection: Pick, + projection: Pick, run: OrchestrationV2Run, ): boolean { const message = projection.messages.find((candidate) => candidate.id === run.userMessageId); - return followsCurrentConversation(message) || queuedBeforeFailoverFrom(projection, run, message); + return ( + followsCurrentConversation(message) || + queuedBeforeFailoverFrom(projection, run, message) || + queuedBeforeScheduledSelection(projection, run) + ); } function queuedRunModelSelection( @@ -965,7 +1005,7 @@ function queuedRunModelSelection( run: OrchestrationV2Run, ): ModelSelection { return queuedRunFollowsThread(projection, run) - ? projection.thread.modelSelection + ? nextTurnModelSelection(projection.thread) : run.modelSelection; } @@ -976,7 +1016,7 @@ function queueTailModelSelection( return ( queuedRunsInDeliveryOrder(projection).findLast( (run) => !queuedRunFollowsThread(projection, run), - )?.modelSelection ?? projection.thread.modelSelection + )?.modelSelection ?? nextTurnModelSelection(projection.thread) ); } @@ -2485,6 +2525,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio projection.thread.modelSelection, queuedRun.modelSelection, ); + const threadAtStart = threadAtRunStart(projection, queuedRun.id); // The picker may already have moved ahead of the native conversation. const switchFromActiveProvider = followsCurrent && @@ -2953,18 +2994,19 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio : "Provider or model selection changed."; yield* writeSystemEvents( [ - ...(selectionChanged + ...(selectionChanged || threadAtStart !== projection.thread ? [ { - type: - queuedRun.providerInstanceId === projection.thread.providerInstanceId + type: !selectionChanged + ? ("thread.metadata-updated" as const) + : queuedRun.providerInstanceId === projection.thread.providerInstanceId ? ("thread.model-selection-updated" as const) : ("thread.provider-switched" as const), threadId, providerInstanceId: queuedRun.providerInstanceId, occurredAt: now, payload: { - ...projection.thread, + ...threadAtStart, providerInstanceId: queuedRun.providerInstanceId, modelSelection: queuedRun.modelSelection, updatedAt: now, @@ -4384,6 +4426,25 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio targetModelSelection: command.modelSelection, }) .pipe(mapDispatchError(command)); + if (command.type === "thread.model-selection.set" && command.applyAt === "next_turn") { + const { runs } = yield* loadProjectionForCommand(command, ["runs"], { + turnItemTypes: [], + }); + const activeRun = runs + .filter(isActiveRun) + .toSorted((left, right) => right.ordinal - left.ordinal)[0]; + if (activeRun !== undefined) { + const scheduled: OrchestrationV2ScheduledModelSelection | null = + modelSelectionsEqual(thread.modelSelection, command.modelSelection) + ? null + : { + modelSelection: command.modelSelection, + afterRunId: activeRun.id, + queuedThroughOrdinal: Math.max(...runs.map((run) => run.ordinal)), + }; + return { ...plan, releaseProviderSessionIds: [], scheduled }; + } + } if (plan.instanceChanged || plan.releaseProviderSessionIds.length > 0) { const projection = yield* loadProjectionForCommand(command, ["runs"], { turnItemTypes: [], @@ -4395,7 +4456,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio }); } } - return plan; + return { ...plan, scheduled: undefined }; }) : null; @@ -4998,10 +5059,18 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio return { ...thread, interactionMode: command.interactionMode, updatedAt: now }; case "thread.model-selection.set": case "provider.switch": + if (providerSwitchPlan !== null && providerSwitchPlan.scheduled !== undefined) { + return { + ...thread, + scheduledModelSelection: providerSwitchPlan.scheduled, + updatedAt: now, + }; + } return { ...thread, providerInstanceId: command.modelSelection.instanceId, modelSelection: command.modelSelection, + ...(thread.scheduledModelSelection == null ? {} : { scheduledModelSelection: null }), updatedAt: now, }; } @@ -5068,9 +5137,11 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio case "thread.interaction-mode.set": return "thread.interaction-mode-updated" as const; case "thread.model-selection.set": - return thread.providerInstanceId === command.modelSelection.instanceId - ? ("thread.model-selection-updated" as const) - : ("thread.provider-switched" as const); + return providerSwitchPlan !== null && providerSwitchPlan.scheduled !== undefined + ? ("thread.metadata-updated" as const) + : thread.providerInstanceId === command.modelSelection.instanceId + ? ("thread.model-selection-updated" as const) + : ("thread.provider-switched" as const); case "provider.switch": return "thread.provider-switched" as const; } @@ -5121,6 +5192,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio if ( command.type === "thread.model-selection.set" && providerSwitchPlan !== null && + providerSwitchPlan.scheduled === undefined && !providerSwitchPlan.instanceChanged && providerSwitchPlan.releaseProviderSessionIds.length === 0 ) { @@ -7388,6 +7460,10 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio return; } + // A new turn, unlike a steer, starts with a change scheduled behind the run before it. + if (command.modelSelection === undefined) { + modelSelection = nextTurnModelSelection(projection.thread); + } const activeProviderThread = projection.providerThreads.find( (candidate) => candidate.id === projection.thread.activeProviderThreadId, ); @@ -7825,23 +7901,25 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio (transfer) => transfer.id !== pendingMergeBackTransfer?.id, ); const now = yield* DateTime.now; - if ( + const selectionChanged = !modelSelectionsEqual(projection.thread.modelSelection, modelSelection) || - projection.thread.providerInstanceId !== modelSelection.instanceId - ) { + projection.thread.providerInstanceId !== modelSelection.instanceId; + const threadAtStart = threadAtRunStart(projection, null); + if (selectionChanged || threadAtStart !== projection.thread) { yield* emit( events, command, )({ - type: - projection.thread.providerInstanceId === modelSelection.instanceId + type: !selectionChanged + ? "thread.metadata-updated" + : projection.thread.providerInstanceId === modelSelection.instanceId ? "thread.model-selection-updated" : "thread.provider-switched", threadId: command.threadId, providerInstanceId: modelSelection.instanceId, occurredAt: now, payload: { - ...projection.thread, + ...threadAtStart, providerInstanceId: modelSelection.instanceId, modelSelection, updatedAt: now, diff --git a/apps/server/src/orchestration-v2/runtimeLayer.test.ts b/apps/server/src/orchestration-v2/runtimeLayer.test.ts index cafdf068dc8e6..ba06a7b381c2f 100644 --- a/apps/server/src/orchestration-v2/runtimeLayer.test.ts +++ b/apps/server/src/orchestration-v2/runtimeLayer.test.ts @@ -8602,6 +8602,93 @@ it.layer(layerTest)("OrchestrationV2LayerLive lifecycle", (it) => { }), ); + it.effect("starts every message queued behind a scheduled model change with it", () => + Effect.gen(function* () { + const orchestrator = yield* Orchestrator.OrchestratorV2; + const eventSink = yield* EventSink.EventSinkV2; + const threadId = ThreadId.make("runtime-layer-scheduled-model-change"); + const scheduledSelection = { ...modelSelection, model: "gpt-5.5" }; + yield* orchestrator.dispatch({ + type: "thread.create", + commandId: CommandId.make(`${threadId}:create`), + threadId, + projectId: ProjectId.make(`${threadId}:project`), + createdBy: "user", + creationSource: "web", + title: "Scheduled model change", + modelSelection, + runtimeMode: "full-access", + interactionMode: "default", + branch: null, + worktreePath: process.cwd(), + }); + const send = (key: string) => + orchestrator.dispatch({ + type: "message.dispatch", + commandId: CommandId.make(`${threadId}:${key}`), + threadId, + messageId: MessageId.make(`${threadId}:${key}`), + text: key, + attachments: [], + dispatchMode: { type: key === "active" ? "start_immediately" : "queue_after_active" }, + createdBy: "agent", + creationSource: "mcp", + }); + for (const key of ["active", "before-1", "before-2"]) yield* send(key); + yield* orchestrator.dispatch({ + type: "thread.model-selection.set", + commandId: CommandId.make(`${threadId}:schedule`), + threadId, + modelSelection: scheduledSelection, + applyAt: "next_turn", + }); + yield* send("after"); + const scheduled = yield* orchestrator.getThreadProjection(threadId); + assert.deepEqual(scheduled.thread.modelSelection, modelSelection); + assert.deepEqual( + scheduled.thread.scheduledModelSelection?.modelSelection, + scheduledSelection, + ); + const [active, before1, before2, after] = scheduled.runs; + assert.deepEqual(after?.modelSelection, scheduledSelection); + + const complete = (runId: RunId) => + Effect.gen(function* () { + const current = yield* orchestrator.getThreadProjection(threadId); + yield* eventSink.write({ + events: [ + { + id: EventId.make(`${runId}:completed`), + type: "run.updated", + threadId, + runId, + occurredAt: yield* DateTime.now, + payload: { + ...current.runs.find((run) => run.id === runId)!, + status: "completed", + completedAt: yield* DateTime.now, + }, + }, + ], + }); + yield* orchestrator.resumeQueuedRuns; + return yield* orchestrator.getThreadProjection(threadId); + }); + const firstBoundary = yield* complete(active!.id); + const started1 = firstBoundary.runs.find((run) => run.id === before1!.id)!; + assert.equal(started1.status, "starting"); + assert.deepEqual(started1.modelSelection, scheduledSelection); + assert.deepEqual(firstBoundary.thread.modelSelection, scheduledSelection); + assert.isNotNull(firstBoundary.thread.scheduledModelSelection ?? null); + + const secondBoundary = yield* complete(before1!.id); + const started2 = secondBoundary.runs.find((run) => run.id === before2!.id)!; + assert.equal(started2.status, "starting"); + assert.deepEqual(started2.modelSelection, scheduledSelection); + assert.isNull(secondBoundary.thread.scheduledModelSelection ?? null); + }), + ); + it.effect("keeps a buffered provider wake on its own provider behind a queued pick", () => Effect.gen(function* () { const orchestrator = yield* Orchestrator.OrchestratorV2; diff --git a/apps/server/src/provider/agentContextBudget.json b/apps/server/src/provider/agentContextBudget.json index ce6d27233f0ef..011b10cc25633 100644 --- a/apps/server/src/provider/agentContextBudget.json +++ b/apps/server/src/provider/agentContextBudget.json @@ -1,5 +1,5 @@ { "claudeSystemAppendBytes": 5597, "codexAdditionalContextBytes": 7327, - "mcpToolListJsonBytes": 57258 + "mcpToolListJsonBytes": 56571 } diff --git a/packages/contracts/src/orchestrationV2.ts b/packages/contracts/src/orchestrationV2.ts index 5e2cc81d19d1b..caa83bd11992c 100644 --- a/packages/contracts/src/orchestrationV2.ts +++ b/packages/contracts/src/orchestrationV2.ts @@ -456,6 +456,18 @@ const LenientThreadOpens = Schema.NullOr(OrchestrationV2ThreadOpens).pipe( Schema.catchDecoding(() => Effect.succeedSome(null)), ); +/** + * A model change asked for while a run was active. Runs queued through `queuedThroughOrdinal` + * and every later turn start with it; the first start that leaves none of those queued clears it. + */ +export const OrchestrationV2ScheduledModelSelection = Schema.Struct({ + modelSelection: ModelSelection, + afterRunId: RunId, + queuedThroughOrdinal: NonNegativeInt, +}); +export type OrchestrationV2ScheduledModelSelection = + typeof OrchestrationV2ScheduledModelSelection.Type; + export const OrchestrationV2AppThread = Schema.Struct({ ...OrchestrationV2CreationFields, id: ThreadId, @@ -463,6 +475,7 @@ export const OrchestrationV2AppThread = Schema.Struct({ title: TrimmedNonEmptyString, providerInstanceId: ProviderInstanceId, modelSelection: ModelSelection, + scheduledModelSelection: Schema.optional(Schema.NullOr(OrchestrationV2ScheduledModelSelection)), runtimeMode: RuntimeMode, interactionMode: ProviderInteractionMode, branch: Schema.NullOr(TrimmedNonEmptyString), @@ -3333,6 +3346,8 @@ export const OrchestrationV2Command = Schema.Union([ commandId: CommandId, threadId: ThreadId, modelSelection: ModelSelection, + /** While a run is active, schedule the change for the next turn start instead of refusing. */ + applyAt: Schema.optional(Schema.Literal("next_turn")), }), Schema.Struct({ type: Schema.Literal("provider-session.detach"), From 751bdd39ff3b98ed3288c3a58778076d376de14e Mon Sep 17 00:00:00 2001 From: Chris OHearn Date: Thu, 12 Nov 2026 19:46:44 -0700 Subject: [PATCH 05/14] docs(user): scheduled model changes, queue standing and thread links for outside agents Co-Authored-By: Claude Opus 5.5 --- docs/user/outside-agents.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/user/outside-agents.md b/docs/user/outside-agents.md index 767ef72a7e779..fe13d72ec37ce 100644 --- a/docs/user/outside-agents.md +++ b/docs/user/outside-agents.md @@ -99,6 +99,14 @@ T3 Code. `runtimeMode` alone. It cannot raise permissions or change them during an active run, and the thread must be within the calling agent's permission limits. The change and caller appear in thread activity. +- To change a busy thread's model or options, such as an inbox thread's effort, + call `t3_thread_configure` with `modelSelection` and `applyAt: "next_turn"`. + The next turn starts with it, and so do messages already queued. Reading the + configuration shows the pending change; scheduling the current model cancels + it. Switching to another provider instance still needs an idle thread. +- When `t3_thread_send` queues behind a busy run, its `queue` result gives the + message's position, the messages ahead of it, and how long the active run has + been going. ## Claude Code @@ -136,7 +144,7 @@ Add the environment as a custom MCP app in ChatGPT's apps settings: ### Check results and decisions Use `t3_thread_result` for a thread's latest run, or pass `runId` for a specific -run. It returns status, the last assistant reply, pending request IDs, linked +run. `threadId` also accepts a thread link, including the hosted links T3 returns. It returns status, the last assistant reply, pending request IDs, linked pull requests, and a revision. `latestMessage` also returns the thread’s most recent message, including inbox posts without a run. Replies default to 4,000 characters. Increase `maxChars` up to 50,000 when `truncated` is true. This read does not acknowledge From 5aeeda9cd4adf328a77c11720051525861ddd635 Mon Sep 17 00:00:00 2001 From: Chris OHearn Date: Thu, 12 Nov 2026 19:59:57 -0700 Subject: [PATCH 06/14] fix(mcp): check a scheduled model up front and refuse applyAt alone A scheduled model or option that the provider rejects would fail each queued message in turn, so configure now checks it before scheduling. applyAt without modelSelection is now an error instead of a silent read. Also tests the queue standing a queued send returns. Co-Authored-By: Claude Opus 5.5 --- .../src/mcp/OrchestratorMcpService.test.ts | 52 +++++++++++++++++++ apps/server/src/mcp/OrchestratorMcpService.ts | 2 +- apps/server/src/mcp/toolkits/core.test.ts | 27 ++++++++-- .../src/mcp/toolkits/thread/handlers.ts | 34 +++++++++++- 4 files changed, 107 insertions(+), 8 deletions(-) diff --git a/apps/server/src/mcp/OrchestratorMcpService.test.ts b/apps/server/src/mcp/OrchestratorMcpService.test.ts index 0c4e05c8d687c..3a2391a031d7d 100644 --- a/apps/server/src/mcp/OrchestratorMcpService.test.ts +++ b/apps/server/src/mcp/OrchestratorMcpService.test.ts @@ -4141,6 +4141,58 @@ describe("OrchestratorMcpService thread lookup", () => { }), ); + it.effect("reports where a queued send waits behind the active run", () => + Effect.gen(function* () { + const sent = yield* Ref.make(0); + const startedAt = DateTime.makeUnsafe(0); + const runs = [ + { + id: RunId.make("run:active"), + ordinal: 1, + status: "running", + requestedAt: startedAt, + startedAt, + }, + { id: RunId.make("run:ahead"), ordinal: 2, status: "queued", userMessageId: "m:ahead" }, + { id: RunId.make("run:mine"), ordinal: 3, status: "queued", userMessageId: "m:mine" }, + ]; + const filters: Array = []; + yield* TestClock.adjust("90 seconds"); + const result = yield* Effect.gen(function* () { + const mcp = yield* OrchestratorMcpService.OrchestratorMcpService; + return yield* mcp.sendToThread(client, { threadId: launched.id, message: "hello" }); + }).pipe( + Effect.provide( + service([launched], sent, { + getProjectThreadRecords: () => Effect.succeed(idleThreadProjection(launched)), + sendToThread: () => + Effect.succeed({ + delivery: "queued", + run: { id: RunId.make("run:mine"), status: "queued" }, + } as never), + getThreadRecords: (_threadId, _fields, filter) => { + filters.push(filter); + return Effect.succeed({ + runs, + messages: [{ id: "m:ahead" }, { id: "m:mine" }], + } as unknown as OrchestrationV2ThreadProjection); + }, + }), + ), + ); + assert.deepEqual(result.queue, { + position: 2, + messagesAhead: 1, + activeRunId: RunId.make("run:active"), + activeRunAgeSeconds: 90, + }); + assert.deepEqual(filters, [ + { runStatuses: ["preparing", "starting", "running", "waiting", "queued"] }, + { messageIds: ["m:ahead", "m:mine"] }, + ]); + }), + ); + it.effect( "seeds coordinator rollover while leaving ordinary sends and clean resets unchanged", () => diff --git a/apps/server/src/mcp/OrchestratorMcpService.ts b/apps/server/src/mcp/OrchestratorMcpService.ts index 1f92feb22899b..0b069dde60fce 100644 --- a/apps/server/src/mcp/OrchestratorMcpService.ts +++ b/apps/server/src/mcp/OrchestratorMcpService.ts @@ -413,7 +413,7 @@ function knownOptions( } /** Skip checks without descriptors; reject duplicate IDs because consumers disagree on precedence. */ -function invalidOptionSelections( +export function invalidOptionSelections( selections: ReadonlyArray, descriptors: ReadonlyArray | undefined, ): ReadonlyArray { diff --git a/apps/server/src/mcp/toolkits/core.test.ts b/apps/server/src/mcp/toolkits/core.test.ts index 43af61ed3afb6..b2d85cf25417c 100644 --- a/apps/server/src/mcp/toolkits/core.test.ts +++ b/apps/server/src/mcp/toolkits/core.test.ts @@ -1308,11 +1308,21 @@ it.effect("schedules a model change on a busy thread and shows it until it appli scheduledModelSelection: scheduled, }); - for (const refused of [ - { runtimeMode: "approval-required", applyAt: "next_turn" }, - { modelSelection: { instanceId: "claudeAgent", model: "opus" }, applyAt: "next_turn" }, - ]) { - expect(declaredFailure(yield* call(refused))).toMatchObject({ code: "invalid_request" }); + for (const [refused, code] of [ + [{ runtimeMode: "approval-required", applyAt: "next_turn" }, "invalid_request"], + [{ applyAt: "next_turn" }, "invalid_request"], + [ + { modelSelection: { instanceId: "claudeAgent", model: "opus" }, applyAt: "next_turn" }, + "invalid_request", + ], + [ + { modelSelection: { instanceId: "codex", model: "gpt-9" }, applyAt: "next_turn" }, + "model_unavailable", + ], + ] as const) { + expect(declaredFailure(yield* call(refused)), JSON.stringify(refused)).toMatchObject({ + code, + }); } expect(commands).toHaveLength(1); }).pipe( @@ -1337,6 +1347,13 @@ it.effect("schedules a model change on a busy thread and shows it until it appli }), }), ), + Layer.provide( + Layer.mock(ProviderRegistry.ProviderRegistry)({ + getProviders: Effect.succeed([ + { instanceId: "codex", models: [{ slug: "gpt-5" }, { slug: "gpt-6" }] } as never, + ]), + }), + ), ), ), ); diff --git a/apps/server/src/mcp/toolkits/thread/handlers.ts b/apps/server/src/mcp/toolkits/thread/handlers.ts index 185883e871e6c..b182cafe20f97 100644 --- a/apps/server/src/mcp/toolkits/thread/handlers.ts +++ b/apps/server/src/mcp/toolkits/thread/handlers.ts @@ -13,7 +13,12 @@ import { } from "@t3tools/contracts"; import * as Effect from "effect/Effect"; import * as Schema from "effect/Schema"; -import { modelSelectionCommandType } from "@t3tools/shared/model"; +import * as Option from "effect/Option"; +import { modelSelectionCommandType, withLegacyUltracodeEffort } from "@t3tools/shared/model"; + +import * as ProviderRegistry from "../../../provider/ProviderRegistry.ts"; +import { invalidOptionSelections } from "../../OrchestratorMcpService.ts"; +import { advertisedModel, requireAdvertisedModel } from "../../providerModels.ts"; import * as McpInvocationContext from "../../McpInvocationContext.ts"; import * as McpToolAccess from "../../McpToolAccess.ts"; @@ -223,7 +228,10 @@ export const layer = McpToolAccess.toLayer(ThreadToolkit, { ), ), t3_thread_configure: McpToolAccess.either( - (input) => input.modelSelection === undefined && input.runtimeMode === undefined, + (input) => + input.modelSelection === undefined && + input.runtimeMode === undefined && + input.applyAt === undefined, McpToolAccess.reads((input) => Effect.gen(function* () { const { @@ -294,6 +302,28 @@ export const layer = McpToolAccess.toLayer(ThreadToolkit, { }); } const applyAt = input.applyAt; + // A scheduled selection is checked now: a bad one would fail each queued message in turn. + const registry = yield* Effect.serviceOption(ProviderRegistry.ProviderRegistry); + if (applyAt !== undefined && Option.isSome(registry)) { + const provider = (yield* registry.value.getProviders).find( + (candidate) => candidate.instanceId === modelSelection.instanceId, + ); + if (provider !== undefined) { + yield* requireAdvertisedModel(provider, modelSelection.model); + const descriptors = advertisedModel(provider, modelSelection.model)?.capabilities + ?.optionDescriptors; + const invalid = invalidOptionSelections( + withLegacyUltracodeEffort(descriptors, modelSelection.options) ?? [], + descriptors, + ); + if (invalid.length > 0) { + return yield* new OrchestratorMcpFailure({ + code: "invalid_request", + message: `modelSelection.options rejected: ${invalid.join(" ")}`, + }); + } + } + } const result = yield* threads .dispatch({ type, From 41ca4c9da57b0ac6328846463d5498bf67fe3562 Mon Sep 17 00:00:00 2001 From: Chris OHearn Date: Thu, 12 Nov 2026 20:00:15 -0700 Subject: [PATCH 07/14] docs(user): say that app messages keep the composer's model over a scheduled change Co-Authored-By: Claude Opus 5.5 --- docs/user/outside-agents.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/user/outside-agents.md b/docs/user/outside-agents.md index fe13d72ec37ce..2f391d671bf0f 100644 --- a/docs/user/outside-agents.md +++ b/docs/user/outside-agents.md @@ -101,9 +101,11 @@ T3 Code. change and caller appear in thread activity. - To change a busy thread's model or options, such as an inbox thread's effort, call `t3_thread_configure` with `modelSelection` and `applyAt: "next_turn"`. - The next turn starts with it, and so do messages already queued. Reading the - configuration shows the pending change; scheduling the current model cancels - it. Switching to another provider instance still needs an idle thread. + Messages already queued start with it, and so do later agent messages. A + later message sent from the T3 app carries the composer's model instead. + Reading the configuration shows the pending change; scheduling the current + model cancels it. Switching to another provider instance still needs an idle + thread. - When `t3_thread_send` queues behind a busy run, its `queue` result gives the message's position, the messages ahead of it, and how long the active run has been going. From 0af621e3f11121b17ac95cc4791d178c2aa80c61 Mon Sep 17 00:00:00 2001 From: Chris OHearn Date: Thu, 12 Nov 2026 20:17:45 -0700 Subject: [PATCH 08/14] feat(mcp): agent sends and posts keep a thread's snooze On 2026-11-13 a worker's handoff woke two threads that were snoozed until 11-18 and 11-24, because any send or post ended a snooze. Agent sends and posts now leave a snoozed thread asleep by default. A send is held behind the thread's last run until the snooze ends or someone unsnoozes it, and a post is only recorded. Both results report snoozedUntil with a warning, and respectSnooze: false keeps the old waking behavior. Messages sent from the app still wake the thread. Co-Authored-By: Claude Opus 5.5 --- .../src/mcp/OrchestratorMcpService.test.ts | 59 +++++++++ apps/server/src/mcp/OrchestratorMcpService.ts | 18 +++ apps/server/src/mcp/snoozeNotice.ts | 21 +++ .../src/orchestration-v2/Orchestrator.ts | 22 +++- .../SnoozeDeferredDelivery.test.ts | 25 ++++ .../SnoozeDeferredDelivery.ts | 120 ++++++++++++++++++ .../ThreadManagementService.ts | 3 + .../src/orchestration-v2/runtimeLayer.test.ts | 96 +++++++++++++- .../src/orchestration-v2/runtimeLayer.ts | 4 + .../src/provider/agentContextBudget.json | 2 +- docs/user/outside-agents.md | 4 + packages/contracts/src/orchestrationV2.ts | 4 + packages/contracts/src/orchestratorMcp.ts | 16 +++ 13 files changed, 389 insertions(+), 5 deletions(-) create mode 100644 apps/server/src/mcp/snoozeNotice.ts create mode 100644 apps/server/src/orchestration-v2/SnoozeDeferredDelivery.test.ts create mode 100644 apps/server/src/orchestration-v2/SnoozeDeferredDelivery.ts diff --git a/apps/server/src/mcp/OrchestratorMcpService.test.ts b/apps/server/src/mcp/OrchestratorMcpService.test.ts index 3a2391a031d7d..afd6eed1063b7 100644 --- a/apps/server/src/mcp/OrchestratorMcpService.test.ts +++ b/apps/server/src/mcp/OrchestratorMcpService.test.ts @@ -4141,6 +4141,65 @@ describe("OrchestratorMcpService thread lookup", () => { }), ); + it.effect("keeps a target's snooze unless told to wake it, and says so", () => + Effect.gen(function* () { + const sent = yield* Ref.make(0); + const snoozedUntil = DateTime.makeUnsafe("2099-01-01T00:00:00Z"); + const snoozed = { ...launched, snoozedUntil }; + const dispatched: Array = []; + const results = yield* Effect.gen(function* () { + const mcp = yield* OrchestratorMcpService.OrchestratorMcpService; + return [ + yield* mcp.sendToThread(client, { threadId: launched.id, message: "held" }), + yield* mcp.postToThread(client, { threadId: launched.id, message: "posted" }), + yield* mcp.sendToThread(client, { + threadId: launched.id, + message: "wake", + respectSnooze: false, + }), + ]; + }).pipe( + Effect.provide( + service([snoozed], sent, { + getProjectThreadRecords: () => Effect.succeed(idleThreadProjection(snoozed)), + dispatch: (command) => + Effect.sync(() => { + dispatched.push(command); + return { sequence: 1, storedEvents: [] }; + }), + sendToThread: (input) => + Effect.sync(() => { + dispatched.push(input); + return { + delivery: "queued", + run: { + id: RunId.make("run:held"), + status: "queued", + ...(input.respectSnooze ? { snoozeDeferred: true } : {}), + }, + } as never; + }), + getThreadRecords: () => + Effect.succeed(idleThreadProjection(snoozed) as OrchestrationV2ThreadProjection), + }), + ), + ); + expect(dispatched).toMatchObject([ + { respectSnooze: true }, + { postOnly: true, respectSnooze: true }, + { text: "wake" }, + ]); + expect((dispatched[2] as { respectSnooze?: boolean }).respectSnooze).toBeUndefined(); + const [held, posted, woke] = results; + for (const result of results) { + expect(result.snoozedUntil).toBe("2099-01-01T00:00:00.000Z"); + } + expect(held!.warning).toContain("waits, held, until it wakes"); + expect(posted!.warning).toContain("stays snoozed"); + expect(woke!.warning).toContain("ended the snooze"); + }), + ); + it.effect("reports where a queued send waits behind the active run", () => Effect.gen(function* () { const sent = yield* Ref.make(0); diff --git a/apps/server/src/mcp/OrchestratorMcpService.ts b/apps/server/src/mcp/OrchestratorMcpService.ts index 0b069dde60fce..76d66463fd329 100644 --- a/apps/server/src/mcp/OrchestratorMcpService.ts +++ b/apps/server/src/mcp/OrchestratorMcpService.ts @@ -142,6 +142,7 @@ import { import { isLiveCallerShell, threadNotFound } from "./threadAccess.ts"; import { resolveReadableThread } from "./threadReference.ts"; import { queuedRunMessageIds, queueStanding } from "./queueStanding.ts"; +import { snoozeNotice } from "./snoozeNotice.ts"; import * as SecretRequests from "../secrets/SecretRequests.ts"; import * as PeerForwarding from "../peer/PeerForwarding.ts"; import * as RemoteDelegation from "../peer/RemoteDelegation.ts"; @@ -3353,10 +3354,12 @@ const make = Effect.gen(function* () { const key = yield* requestKey(input.clientRequestId); const operation = "thread-post"; const messageId = stableOperationMessageId({ scope, requestKey: key, operation }); + const respectSnooze = input.respectSnooze ?? true; yield* threadManagement .dispatch({ type: "message.dispatch", postOnly: true, + ...(respectSnooze ? { respectSnooze: true } : {}), commandId: stableCommandId({ scope, requestKey: key, operation }), threadId: input.threadId, ...(parent === undefined ? {} : { senderThreadId: parent.thread.id }), @@ -3376,6 +3379,11 @@ const make = Effect.gen(function* () { threadId: input.threadId, link: threadLinkFor(scope, input.threadId, target.thread.title), messageId, + ...snoozeNotice( + target.thread.snoozedUntil, + yield* Clock.currentTimeMillis, + respectSnooze ? "posted" : "woke", + ), }; }), sendToThread: Effect.fn("OrchestratorMcpService.sendToThread")(function* (scope, input) { @@ -3473,6 +3481,7 @@ const make = Effect.gen(function* () { attachments: [], mode, ...(input.freshContext || input.coordinatorRollover ? { freshContext: true } : {}), + ...((input.respectSnooze ?? true) ? { respectSnooze: true } : {}), createdBy: "agent", creationSource: "mcp", }) @@ -3499,6 +3508,15 @@ const make = Effect.gen(function* () { return { ...(notify === undefined ? {} : { notify }), ...(queue === undefined ? {} : { queue }), + ...snoozeNotice( + target.thread.snoozedUntil, + yield* Clock.currentTimeMillis, + result.run.snoozeDeferred === true + ? "held" + : result.delivery === "steered" && (input.respectSnooze ?? true) + ? "steered" + : "woke", + ), threadId: input.threadId, link: threadLinkFor(scope, input.threadId, target.thread.title), messageId, diff --git a/apps/server/src/mcp/snoozeNotice.ts b/apps/server/src/mcp/snoozeNotice.ts new file mode 100644 index 0000000000000..3c43b5072c844 --- /dev/null +++ b/apps/server/src/mcp/snoozeNotice.ts @@ -0,0 +1,21 @@ +import * as DateTime from "effect/DateTime"; + +export type SnoozeOutcome = "held" | "posted" | "steered" | "woke"; + +/** What a sender learns about a target's snooze; nothing when the thread was awake. */ +export function snoozeNotice( + snoozedUntil: DateTime.Utc | null | undefined, + nowMs: number, + outcome: SnoozeOutcome, +): { readonly snoozedUntil: string; readonly warning: string } | Record { + if (snoozedUntil == null || DateTime.toEpochMillis(snoozedUntil) <= nowMs) return {}; + const until = DateTime.formatIso(snoozedUntil); + const prefix = `Thread is snoozed until ${until}.`; + const warning = { + held: `${prefix} The message waits, held, until it wakes. Pass respectSnooze: false to wake it now.`, + posted: `${prefix} The message was recorded and the thread stays snoozed.`, + steered: `${prefix} The message joined its running turn, and the thread stays snoozed.`, + woke: `${prefix} This message ended the snooze.`, + }[outcome]; + return { snoozedUntil: until, warning }; +} diff --git a/apps/server/src/orchestration-v2/Orchestrator.ts b/apps/server/src/orchestration-v2/Orchestrator.ts index e2ba4d522bfa9..badc9dbd7eff9 100644 --- a/apps/server/src/orchestration-v2/Orchestrator.ts +++ b/apps/server/src/orchestration-v2/Orchestrator.ts @@ -4581,7 +4581,11 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio ) .map((message) => message.id), ); - if (queuedRuns.some((run) => !automaticMessageIds.has(run.userMessageId))) { + if ( + queuedRuns.some( + (run) => run.snoozeDeferred !== true && !automaticMessageIds.has(run.userMessageId), + ) + ) { return yield* new OrchestratorDispatchError({ commandId: command.commandId, commandType: command.type, @@ -6986,7 +6990,16 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio command.notification !== undefined || command.delegatedCompletion !== undefined || serverNotice; - if (projection.thread.snoozedUntil != null && !automaticWake) { + // A sender that respects the snooze leaves it: a post is only recorded, and a turn waits, + // held behind the thread's last run, until the thread wakes. A thread with no run wakes. + const snoozeHeldUntil = projection.thread.snoozedUntil; + const respectsSnooze = + command.respectSnooze === true && + !automaticWake && + snoozeHeldUntil != null && + DateTime.toEpochMillis(snoozeHeldUntil) > DateTime.toEpochMillis(yield* DateTime.now) && + (command.postOnly === true || latestExecutedRun(projection.runs) != null); + if (projection.thread.snoozedUntil != null && !automaticWake && !respectsSnooze) { const now = yield* DateTime.now; const thread: OrchestrationV2AppThread = { ...projection.thread, @@ -7480,7 +7493,8 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio projection.thread.worktreePath === null ? latestRun : undefined; - const queueBehindRun = activeRun ?? worktreeMissingRun; + const queueBehindRun = + activeRun ?? worktreeMissingRun ?? (respectsSnooze ? (latestRun ?? undefined) : undefined); const pendingMergeBackTransfers = pendingMergeBackTransfersForThread(projection); const startsOrQueuesRun = dispatchMode.type === "defer_start" || @@ -7682,7 +7696,9 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio activeAttemptId: attemptId, status: "queued", ...(steerWhenReadyRunId === undefined ? {} : { steerWhenReadyRunId }), + ...(respectsSnooze ? { snoozeDeferred: true } : {}), ...(worktreeMissingRun !== undefined || + respectsSnooze || (heldRunsToRelease.length === 0 && queueIsHeld && !wakeSkipsHold && diff --git a/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.test.ts b/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.test.ts new file mode 100644 index 0000000000000..2bf5358fb0c53 --- /dev/null +++ b/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.test.ts @@ -0,0 +1,25 @@ +import { describe, expect, it } from "vite-plus/test"; + +import { snoozeDeferredReleases } from "./SnoozeDeferredDelivery.ts"; + +describe("snoozeDeferredReleases", () => { + it("releases awake threads and wakes at the earliest snooze still holding a turn", () => { + const now = Date.parse("2026-11-13T03:00:00Z"); + const thread = (threadId: string, snoozedUntil: string | null) => ({ + threadId, + snoozedUntil, + firstRunId: `run:${threadId}`, + }); + const { due, wakeAtMs } = snoozeDeferredReleases( + [ + thread("unsnoozed", null), + thread("expired", "2026-11-13T02:59:59.000Z"), + thread("later", "2026-11-24T00:00:00.000Z"), + thread("sooner", "2026-11-18T00:00:00.000Z"), + ], + now, + ); + expect(due.map((entry) => entry.threadId)).toEqual(["unsnoozed", "expired"]); + expect(wakeAtMs).toBe(Date.parse("2026-11-18T00:00:00.000Z")); + }); +}); diff --git a/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.ts b/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.ts new file mode 100644 index 0000000000000..52ac10bb86aba --- /dev/null +++ b/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.ts @@ -0,0 +1,120 @@ +import { CommandId, ThreadId } from "@t3tools/contracts"; +import * as DateTime from "effect/DateTime"; +import * as Effect from "effect/Effect"; +import * as Layer from "effect/Layer"; +import * as Stream from "effect/Stream"; +import * as SqlClient from "effect/sql/SqlClient"; +import type { OrchestrationV2DomainEvent } from "@t3tools/contracts"; + +import * as DueHint from "../scheduling/DueHint.ts"; +import * as Scheduler from "../scheduling/Scheduler.ts"; +import { forkParked } from "../serverActivation.ts"; +import * as Orchestrator from "./Orchestrator.ts"; +import * as ThreadManagement from "./ThreadManagementService.ts"; + +const RELEASE_RETRY_MS = 60_000; + +export interface SnoozeDeferredThread { + readonly threadId: string; + readonly snoozedUntil: string | null; + /** The first held turn, so a release names this deferral and a later one gets its own. */ + readonly firstRunId: string; +} + +/** Threads to release now, and when the next snooze holding a turn ends. */ +export function snoozeDeferredReleases( + threads: ReadonlyArray, + nowMs: number, +): { readonly due: ReadonlyArray; readonly wakeAtMs: number } { + const due: Array = []; + let wakeAtMs = Infinity; + for (const thread of threads) { + const untilMs = thread.snoozedUntil === null ? Number.NaN : Date.parse(thread.snoozedUntil); + if (Number.isFinite(untilMs) && untilMs > nowMs) wakeAtMs = Math.min(wakeAtMs, untilMs); + else due.push(thread); + } + return { due, wakeAtMs }; +} + +/** Threads with turns held for a snooze. The partial recovery index covers queued runs. */ +export const readSnoozeDeferredThreads = Effect.fn("SnoozeDeferredDelivery.read")(function* () { + const sql = yield* SqlClient.SqlClient; + const rows = yield* sql<{ + readonly thread_id: string; + readonly snoozed_until: string | null; + readonly first_run_id: string; + }>` + SELECT r.thread_id, json_extract(t.payload_json, '$.snoozedUntil') AS snoozed_until, + MIN(r.run_id) AS first_run_id + FROM orchestration_v2_projection_runs AS r + JOIN orchestration_v2_projection_threads AS t ON t.thread_id = r.thread_id + WHERE r.status = 'queued' + AND json_extract(r.payload_json, '$.snoozeDeferred') = 1 + AND json_extract(r.payload_json, '$.queueHeld') = 1 + AND t.deleted_at IS NULL + GROUP BY r.thread_id + `; + return rows.map((row): SnoozeDeferredThread => ({ + threadId: row.thread_id, + snoozedUntil: row.snoozed_until, + firstRunId: row.first_run_id, + })); +}); + +const affectsDeferral = (event: OrchestrationV2DomainEvent) => + event.type.startsWith("thread.") || event.type === "run.created" || event.type === "run.updated"; + +const makeSweep = Effect.gen(function* () { + const sql = yield* SqlClient.SqlClient; + const threads = yield* ThreadManagement.ThreadManagementService; + const orchestrator = yield* Orchestrator.OrchestratorV2; + const due = DueHint.make(); + yield* forkParked( + Stream.runForEach(orchestrator.streamDomainEvents, (event) => + affectsDeferral(event) ? due.invalidate : Effect.void, + ), + ); + return Effect.fn("SnoozeDeferredDelivery.sweep")(function* () { + const nowMs = DateTime.toEpochMillis(yield* DateTime.now); + if (yield* due.isIdle(nowMs)) return; + const readVersion = yield* due.version; + const { due: releases, wakeAtMs } = snoozeDeferredReleases( + yield* readSnoozeDeferredThreads().pipe( + Effect.provideService(SqlClient.SqlClient, sql), + Effect.orElseSucceed(() => []), + ), + nowMs, + ); + for (const thread of releases) { + yield* threads + .dispatch({ + type: "queue.resume", + commandId: CommandId.make(`snooze-deferred-release:${thread.firstRunId}`), + threadId: ThreadId.make(thread.threadId), + }) + .pipe( + Effect.catchCause((cause) => + Effect.logWarning("orchestration-v2.snooze-deferred.release-failed", { + threadId: thread.threadId, + cause, + }), + ), + ); + } + // A release's events invalidate the hint; one that failed, such as a limited provider, + // retries in a minute instead of every tick. + yield* due.record( + readVersion, + releases.length === 0 ? wakeAtMs : nowMs + RELEASE_RETRY_MS, + nowMs, + ); + }); +}); + +export const layer = Layer.effectDiscard( + Effect.gen(function* () { + const sweep = yield* makeSweep; + const scheduler = yield* Scheduler.Scheduler; + yield* scheduler.register("snooze-deferred-delivery", sweep()); + }), +); diff --git a/apps/server/src/orchestration-v2/ThreadManagementService.ts b/apps/server/src/orchestration-v2/ThreadManagementService.ts index d8118f13454f3..42fe08b5527cf 100644 --- a/apps/server/src/orchestration-v2/ThreadManagementService.ts +++ b/apps/server/src/orchestration-v2/ThreadManagementService.ts @@ -163,6 +163,8 @@ export interface ThreadManagementSendInput { readonly mode: ThreadManagementSendMode; /** Start a new provider session; the orchestrator queues it instead of steering. */ readonly freshContext?: boolean; + /** On a snoozed thread, hold the turn until it wakes instead of waking it. */ + readonly respectSnooze?: boolean; readonly createdBy: OrchestrationV2Actor; readonly creationSource: OrchestrationV2CreationSource; } @@ -903,6 +905,7 @@ const make = Effect.gen(function* () { attachments: input.attachments, ...(input.modelSelection === undefined ? {} : { modelSelection: input.modelSelection }), ...(input.freshContext ? { freshContext: true } : {}), + ...(input.respectSnooze ? { respectSnooze: true } : {}), dispatchMode, ...(mode === "auto" ? { deliveryIntent: "auto" } : {}), createdBy: input.createdBy, diff --git a/apps/server/src/orchestration-v2/runtimeLayer.test.ts b/apps/server/src/orchestration-v2/runtimeLayer.test.ts index ba06a7b381c2f..93e5d13785408 100644 --- a/apps/server/src/orchestration-v2/runtimeLayer.test.ts +++ b/apps/server/src/orchestration-v2/runtimeLayer.test.ts @@ -98,6 +98,7 @@ import * as ScratchThreadPromotion from "../project/ScratchThreadPromotion.ts"; import * as ScheduledTaskService from "../scheduledTasks/ScheduledTaskService.ts"; import * as ManagedPolicy from "../policy/ManagedPolicy.ts"; import * as Scheduler from "../scheduling/Scheduler.ts"; +import * as SnoozeDeferredDelivery from "./SnoozeDeferredDelivery.ts"; import * as SecretRequests from "../secrets/SecretRequests.ts"; import * as DeviceHost from "../device/DeviceHost.ts"; import * as DeviceService from "../device/DeviceService.ts"; @@ -335,7 +336,7 @@ const makeLayerTest = (settings?: Parameters[0] ).pipe( Layer.provide(McpSessionRegistryTestkit.layer), Layer.provide(McpProviderSessions.layer), - Layer.provide(SqlitePersistence.layerMemory), + Layer.provideMerge(SqlitePersistence.layerMemory), Layer.provide(layerCheckpointStoreTest), Layer.provide(layerServerConfig), Layer.provide(ServerSettings.layerTest(settings)), @@ -8602,6 +8603,99 @@ it.layer(layerTest)("OrchestrationV2LayerLive lifecycle", (it) => { }), ); + it.effect("holds a send that respects a snooze until the thread wakes", () => + Effect.gen(function* () { + const orchestrator = yield* Orchestrator.OrchestratorV2; + const eventSink = yield* EventSink.EventSinkV2; + const threadId = ThreadId.make("runtime-layer-respect-snooze"); + yield* orchestrator.dispatch({ + type: "thread.create", + commandId: CommandId.make(`${threadId}:create`), + threadId, + projectId: ProjectId.make(`${threadId}:project`), + createdBy: "user", + creationSource: "web", + title: "Snoozed hold", + modelSelection, + runtimeMode: "full-access", + interactionMode: "default", + branch: null, + worktreePath: process.cwd(), + }); + const message = (key: string, extra: { postOnly?: true; respectSnooze?: true } = {}) => + orchestrator.dispatch({ + type: "message.dispatch", + commandId: CommandId.make(`${threadId}:${key}`), + threadId, + messageId: MessageId.make(`${threadId}:${key}`), + text: key, + attachments: [], + dispatchMode: { type: "start_immediately" }, + createdBy: "agent", + creationSource: "mcp", + ...extra, + }); + yield* message("first"); + const [first] = (yield* orchestrator.getThreadProjection(threadId)).runs; + yield* eventSink.write({ + events: [ + { + id: EventId.make(`${threadId}:first-completed`), + type: "run.updated", + threadId, + runId: first!.id, + occurredAt: yield* DateTime.now, + payload: { ...first!, status: "completed", completedAt: yield* DateTime.now }, + }, + ], + }); + const snooze = (until: string) => + orchestrator.dispatch({ + type: "thread.snooze", + commandId: CommandId.make(`${threadId}:snooze:${until}`), + threadId, + snoozedUntil: until, + }); + yield* snooze("2099-01-01T00:00:00.000Z"); + + yield* message("post", { postOnly: true, respectSnooze: true }); + yield* message("held", { respectSnooze: true }); + const held = yield* orchestrator.getThreadProjection(threadId); + assert.isNotNull(held.thread.snoozedUntil); + const heldRun = held.runs.find((run) => run.userMessageId === `${threadId}:held`)!; + assert.equal(heldRun.status, "queued"); + assert.isTrue(heldRun.queueHeld); + assert.isTrue(heldRun.snoozeDeferred); + // Its own held turn does not stop the thread from being snoozed again. + yield* snooze("2099-02-01T00:00:00.000Z"); + assert.deepEqual(yield* SnoozeDeferredDelivery.readSnoozeDeferredThreads(), [ + { threadId, snoozedUntil: "2099-02-01T00:00:00.000Z", firstRunId: heldRun.id }, + ]); + + yield* orchestrator.dispatch({ + type: "thread.unsnooze", + commandId: CommandId.make(`${threadId}:unsnooze`), + threadId, + reason: "user", + }); + const [awake] = yield* SnoozeDeferredDelivery.readSnoozeDeferredThreads(); + assert.equal( + SnoozeDeferredDelivery.snoozeDeferredReleases( + [awake!], + DateTime.toEpochMillis(yield* DateTime.now), + ).due.length, + 1, + ); + yield* orchestrator.dispatch({ + type: "queue.resume", + commandId: CommandId.make(`snooze-deferred-release:${heldRun.id}`), + threadId, + }); + const released = yield* orchestrator.getThreadProjection(threadId); + assert.equal(released.runs.find((run) => run.id === heldRun.id)?.status, "starting"); + }), + ); + it.effect("starts every message queued behind a scheduled model change with it", () => Effect.gen(function* () { const orchestrator = yield* Orchestrator.OrchestratorV2; diff --git a/apps/server/src/orchestration-v2/runtimeLayer.ts b/apps/server/src/orchestration-v2/runtimeLayer.ts index d83f0603d7f7c..fff2513cd2057 100644 --- a/apps/server/src/orchestration-v2/runtimeLayer.ts +++ b/apps/server/src/orchestration-v2/runtimeLayer.ts @@ -1,5 +1,6 @@ import * as WorktreeBranchSync from "./WorktreeBranchSync.ts"; import * as GuestShareService from "../guest/GuestShareService.ts"; +import * as SnoozeDeferredDelivery from "./SnoozeDeferredDelivery.ts"; import * as UsageLimitRecoveryWorker from "./UsageLimitRecoveryWorker.ts"; import * as Scheduler from "../scheduling/Scheduler.ts"; import * as Layer from "effect/Layer"; @@ -406,6 +407,9 @@ export const layerProduction = Layer.mergeAll( ), ), ), + SnoozeDeferredDelivery.layer.pipe( + Layer.provide(Layer.mergeAll(layerThreadManagementProvided, layerOrchestratorProvided)), + ), layerProviderContinuationWorkerProvided, layerAgentSessionScannerProvided, layerAgentSessionImporterProvided, diff --git a/apps/server/src/provider/agentContextBudget.json b/apps/server/src/provider/agentContextBudget.json index 011b10cc25633..8000af794ca54 100644 --- a/apps/server/src/provider/agentContextBudget.json +++ b/apps/server/src/provider/agentContextBudget.json @@ -1,5 +1,5 @@ { "claudeSystemAppendBytes": 5597, "codexAdditionalContextBytes": 7327, - "mcpToolListJsonBytes": 56571 + "mcpToolListJsonBytes": 56835 } diff --git a/docs/user/outside-agents.md b/docs/user/outside-agents.md index 2f391d671bf0f..eca381b725f76 100644 --- a/docs/user/outside-agents.md +++ b/docs/user/outside-agents.md @@ -109,6 +109,10 @@ T3 Code. - When `t3_thread_send` queues behind a busy run, its `queue` result gives the message's position, the messages ahead of it, and how long the active run has been going. +- A snoozed thread stays snoozed. `t3_thread_send` holds the message until the + snooze ends or someone wakes the thread, and `t3_thread_post` only records it. + Both return `snoozedUntil` and a warning. Pass `respectSnooze: false` to wake + the thread now. Messages sent from the T3 app still wake it. ## Claude Code diff --git a/packages/contracts/src/orchestrationV2.ts b/packages/contracts/src/orchestrationV2.ts index caa83bd11992c..604f40bec5577 100644 --- a/packages/contracts/src/orchestrationV2.ts +++ b/packages/contracts/src/orchestrationV2.ts @@ -782,6 +782,8 @@ export const OrchestrationV2Run = Schema.Struct({ status: OrchestrationV2RunStatus, queuePosition: Schema.optional(Schema.NullOr(PositiveInt)), queueHeld: Schema.optional(Schema.Boolean), + /** Held by a send that respected a snooze; released when the thread wakes. */ + snoozeDeferred: Schema.optional(Schema.Boolean), steerWhenReadyRunId: Schema.optional(RunId), requestedAt: Schema.DateTimeUtc, startedAt: Schema.NullOr(Schema.DateTimeUtc), @@ -3371,6 +3373,8 @@ export const OrchestrationV2Command = Schema.Union([ idleCompaction: Schema.optional(OrchestrationV2IdleCompaction), /** Start a new provider session without the thread's earlier context. Never steers. */ freshContext: Schema.optional(Schema.Boolean), + /** On a snoozed thread: keep the snooze and hold the turn until it ends. */ + respectSnooze: Schema.optional(Schema.Boolean), commandId: CommandId, threadId: ThreadId, messageId: MessageId, diff --git a/packages/contracts/src/orchestratorMcp.ts b/packages/contracts/src/orchestratorMcp.ts index 9573f82c09552..ab2687ae13031 100644 --- a/packages/contracts/src/orchestratorMcp.ts +++ b/packages/contracts/src/orchestratorMcp.ts @@ -564,17 +564,31 @@ export const OrchestratorMcpThreadResult = Schema.Struct({ }); export type OrchestratorMcpThreadResult = typeof OrchestratorMcpThreadResult.Type; +const RespectSnooze = Schema.optional( + Schema.Boolean.annotate({ + description: "Default true: keep a snooze; a send waits until it ends. false wakes the thread.", + }), +); + +/** Set when the target is snoozed, so a sender sees the hold instead of silently ending it. */ +const SnoozeNotice = { + snoozedUntil: Schema.optional(IsoDateTime), + warning: Schema.optional(Schema.String), +}; + export const OrchestratorMcpThreadPostInput = Schema.Struct({ environmentId: OrchestratorMcpEnvironmentTarget, threadId: ThreadId, message: OrchestratorMcpPrompt, clientRequestId: Schema.optional(OrchestratorMcpClientRequestId), + respectSnooze: RespectSnooze, }); export type OrchestratorMcpThreadPostInput = typeof OrchestratorMcpThreadPostInput.Type; export const OrchestratorMcpThreadPostResult = Schema.Struct({ threadId: ThreadId, link: Schema.String, messageId: MessageId, + ...SnoozeNotice, }); export type OrchestratorMcpThreadPostResult = typeof OrchestratorMcpThreadPostResult.Type; @@ -584,6 +598,7 @@ export const OrchestratorMcpThreadSendInput = Schema.Struct({ threadId: ThreadId, message: OrchestratorMcpPrompt, mode: Schema.optional(Schema.Literals(["auto", "queue", "steer", "restart"])), + respectSnooze: RespectSnooze, freshContext: Schema.optional( Schema.Boolean.annotate({ description: @@ -620,6 +635,7 @@ export const OrchestratorMcpThreadSendResult = Schema.Struct({ status: OrchestrationV2RunStatus, delivery: Schema.Literals(["started", "queued", "steered", "restarted"]), queue: Schema.optional(OrchestratorMcpQueueStanding), + ...SnoozeNotice, }); export type OrchestratorMcpThreadSendResult = typeof OrchestratorMcpThreadSendResult.Type; From 1794b1d2dda4a03d0f850927fed5b3b5eb61270a Mon Sep 17 00:00:00 2001 From: Chris OHearn Date: Thu, 12 Nov 2026 20:24:16 -0700 Subject: [PATCH 09/14] fix(mcp): release snooze-held turns once, and only when the thread wakes A turn held for a snooze lost its hold whenever a later background run completed, and nothing stopped a released turn that failed from being released again by the sweep. Automatic releases now skip deferred turns, and any release clears the deferral. Usage-limit snoozes, which the server sets itself, still wake on a send. t3_thread_send_attachments keeps the snooze too, and the snooze notice reflects the thread's state after the send. The release sweep is now tested on the test clock. Co-Authored-By: Claude Opus 5.5 --- .../src/mcp/OrchestratorMcpService.test.ts | 8 ++ apps/server/src/mcp/OrchestratorMcpService.ts | 33 ++++--- .../src/mcp/toolkits/attachment/handlers.ts | 2 + .../src/orchestration-v2/Orchestrator.ts | 31 +++++- .../SnoozeDeferredDelivery.test.ts | 94 +++++++++++++++---- .../SnoozeDeferredDelivery.ts | 33 +++++-- .../src/orchestration-v2/runtimeLayer.test.ts | 6 +- .../orchestrator-mcp-server.md | 8 ++ 8 files changed, 171 insertions(+), 44 deletions(-) diff --git a/apps/server/src/mcp/OrchestratorMcpService.test.ts b/apps/server/src/mcp/OrchestratorMcpService.test.ts index afd6eed1063b7..f6ef83c966832 100644 --- a/apps/server/src/mcp/OrchestratorMcpService.test.ts +++ b/apps/server/src/mcp/OrchestratorMcpService.test.ts @@ -4161,6 +4161,14 @@ describe("OrchestratorMcpService thread lookup", () => { }).pipe( Effect.provide( service([snoozed], sent, { + // The orchestrator keeps the snooze only for a sender that respects it. + getThreadShell: () => + Effect.succeed( + dispatched.length === 0 || + (dispatched.at(-1) as { respectSnooze?: boolean }).respectSnooze === true + ? snoozed + : launched, + ), getProjectThreadRecords: () => Effect.succeed(idleThreadProjection(snoozed)), dispatch: (command) => Effect.sync(() => { diff --git a/apps/server/src/mcp/OrchestratorMcpService.ts b/apps/server/src/mcp/OrchestratorMcpService.ts index 76d66463fd329..3236c27df84d6 100644 --- a/apps/server/src/mcp/OrchestratorMcpService.ts +++ b/apps/server/src/mcp/OrchestratorMcpService.ts @@ -1312,6 +1312,21 @@ const make = Effect.gen(function* () { const loadProviders = providerRegistry.getProviders; + // Read after the dispatch: the orchestrator decides whether a snooze stays, and a usage-limit + // snooze always ends. + const snoozeOutcome = Effect.fn("OrchestratorMcpService.snoozeOutcome")(function* ( + threadId: ThreadId, + snoozedUntil: DateTime.Utc | null | undefined, + kept: "held" | "posted" | "steered", + ) { + const nowMs = yield* Clock.currentTimeMillis; + if (snoozedUntil == null || DateTime.toEpochMillis(snoozedUntil) <= nowMs) return {}; + const after = yield* threadManagement + .getThreadShell(threadId) + .pipe(Effect.orElseSucceed(() => null)); + return snoozeNotice(snoozedUntil, nowMs, after?.snoozedUntil == null ? "woke" : kept); + }); + // Best effort: the message is already queued, so a failed read only omits the standing. const readQueueStanding = Effect.fn("OrchestratorMcpService.readQueueStanding")( function* (threadId: ThreadId, runId: RunId) { @@ -3379,11 +3394,7 @@ const make = Effect.gen(function* () { threadId: input.threadId, link: threadLinkFor(scope, input.threadId, target.thread.title), messageId, - ...snoozeNotice( - target.thread.snoozedUntil, - yield* Clock.currentTimeMillis, - respectSnooze ? "posted" : "woke", - ), + ...(yield* snoozeOutcome(input.threadId, target.thread.snoozedUntil, "posted")), }; }), sendToThread: Effect.fn("OrchestratorMcpService.sendToThread")(function* (scope, input) { @@ -3508,15 +3519,11 @@ const make = Effect.gen(function* () { return { ...(notify === undefined ? {} : { notify }), ...(queue === undefined ? {} : { queue }), - ...snoozeNotice( + ...(yield* snoozeOutcome( + input.threadId, target.thread.snoozedUntil, - yield* Clock.currentTimeMillis, - result.run.snoozeDeferred === true - ? "held" - : result.delivery === "steered" && (input.respectSnooze ?? true) - ? "steered" - : "woke", - ), + result.run.snoozeDeferred === true ? "held" : "steered", + )), threadId: input.threadId, link: threadLinkFor(scope, input.threadId, target.thread.title), messageId, diff --git a/apps/server/src/mcp/toolkits/attachment/handlers.ts b/apps/server/src/mcp/toolkits/attachment/handlers.ts index 5aa5185a7ba01..044682291a270 100644 --- a/apps/server/src/mcp/toolkits/attachment/handlers.ts +++ b/apps/server/src/mcp/toolkits/attachment/handlers.ts @@ -107,6 +107,8 @@ export const layer = McpToolAccess.toLayer( text: input.message ?? "", attachments, mode: "auto", + // As with t3_thread_send, an agent's message leaves a snoozed thread asleep. + respectSnooze: true, createdBy: "agent", creationSource: "mcp", }).pipe( diff --git a/apps/server/src/orchestration-v2/Orchestrator.ts b/apps/server/src/orchestration-v2/Orchestrator.ts index badc9dbd7eff9..be5d05025da49 100644 --- a/apps/server/src/orchestration-v2/Orchestrator.ts +++ b/apps/server/src/orchestration-v2/Orchestrator.ts @@ -910,6 +910,12 @@ function worktreeSetupPending( ); } +/** A released turn is no longer a snooze's: a later failure hold must not re-release it. */ +function withoutSnoozeDeferral(run: OrchestrationV2Run): OrchestrationV2Run { + const { snoozeDeferred: _snoozeDeferred, ...released } = run; + return released; +} + function nextQueuedRun( projection: Pick, ): OrchestrationV2Run | undefined { @@ -3226,7 +3232,10 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio .map((message) => message.id), ); const now = yield* DateTime.now; - const released = held.filter((run) => unattended.has(run.userMessageId)); + // A snooze's held turn waits for the thread to wake, not for later runs. + const released = held.filter( + (run) => unattended.has(run.userMessageId) && run.snoozeDeferred !== true, + ); if (released.length === 0) return; yield* writeSystemEvents( released.map((run) => ({ @@ -6991,13 +7000,19 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio command.delegatedCompletion !== undefined || serverNotice; // A sender that respects the snooze leaves it: a post is only recorded, and a turn waits, - // held behind the thread's last run, until the thread wakes. A thread with no run wakes. + // held behind the thread's last run, until the thread wakes. A thread with no run wakes, + // and so does one the server snoozed until its usage limit resets: that is no one's hold. const snoozeHeldUntil = projection.thread.snoozedUntil; + const limitRecovery = projection.thread.limitRecovery; const respectsSnooze = command.respectSnooze === true && !automaticWake && snoozeHeldUntil != null && DateTime.toEpochMillis(snoozeHeldUntil) > DateTime.toEpochMillis(yield* DateTime.now) && + !( + limitRecovery?.snooze === true && + DateTime.toEpochMillis(snoozeHeldUntil) === Date.parse(limitRecovery.resetAt) + ) && (command.postOnly === true || latestExecutedRun(projection.runs) != null); if (projection.thread.snoozedUntil != null && !automaticWake && !respectsSnooze) { const now = yield* DateTime.now; @@ -7539,7 +7554,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio runId: held.id, providerInstanceId: held.providerInstanceId, occurredAt: releasedAt, - payload: { ...held, queueHeld: false }, + payload: { ...withoutSnoozeDeferral(held), queueHeld: false }, }); } if (shouldQueue) { @@ -12380,7 +12395,13 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio // from a later run (a stop, say) is not this failure's to release. const failureOwnsQueue = latestExecutedRun(projection.runs)?.id === state.run.id; for (const run of projection.runs) { - if (!failureOwnsQueue || run.status !== "queued" || run.queueHeld !== true) continue; + if ( + !failureOwnsQueue || + run.status !== "queued" || + run.queueHeld !== true || + run.snoozeDeferred === true + ) + continue; yield* emitEvent({ type: "run.updated", threadId: command.threadId, @@ -15440,7 +15461,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio runId: run.id, providerInstanceId: run.providerInstanceId, occurredAt: now, - payload: { ...run, queueHeld: false }, + payload: { ...withoutSnoozeDeferral(run), queueHeld: false }, }); } if (queued.length === 0) { diff --git a/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.test.ts b/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.test.ts index 2bf5358fb0c53..2894734b379e2 100644 --- a/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.test.ts +++ b/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.test.ts @@ -1,25 +1,87 @@ -import { describe, expect, it } from "vite-plus/test"; +import { assert, describe, it } from "@effect/vitest"; +import type { OrchestrationV2Command, OrchestrationV2DomainEvent } from "@t3tools/contracts"; +import * as Effect from "effect/Effect"; +import * as Layer from "effect/Layer"; +import * as Queue from "effect/Queue"; +import * as Ref from "effect/Ref"; +import * as Stream from "effect/Stream"; +import * as TestClock from "effect/testing/TestClock"; -import { snoozeDeferredReleases } from "./SnoozeDeferredDelivery.ts"; +import * as Scheduler from "../scheduling/Scheduler.ts"; +import * as Orchestrator from "./Orchestrator.ts"; +import * as SnoozeDeferredDelivery from "./SnoozeDeferredDelivery.ts"; +import * as ThreadManagement from "./ThreadManagementService.ts"; + +const startMs = Date.parse("2026-11-13T03:00:00.000Z"); +const deferred = (threadId: string, snoozedUntil: string | null) => ({ + threadId, + snoozedUntil, + firstRunId: `run:${threadId}`, +}); describe("snoozeDeferredReleases", () => { it("releases awake threads and wakes at the earliest snooze still holding a turn", () => { - const now = Date.parse("2026-11-13T03:00:00Z"); - const thread = (threadId: string, snoozedUntil: string | null) => ({ - threadId, - snoozedUntil, - firstRunId: `run:${threadId}`, - }); - const { due, wakeAtMs } = snoozeDeferredReleases( + const { due, wakeAtMs } = SnoozeDeferredDelivery.snoozeDeferredReleases( [ - thread("unsnoozed", null), - thread("expired", "2026-11-13T02:59:59.000Z"), - thread("later", "2026-11-24T00:00:00.000Z"), - thread("sooner", "2026-11-18T00:00:00.000Z"), + deferred("unsnoozed", null), + deferred("expired", "2026-11-13T02:59:59.000Z"), + deferred("later", "2026-11-24T00:00:00.000Z"), + deferred("sooner", "2026-11-18T00:00:00.000Z"), ], - now, + startMs, ); - expect(due.map((entry) => entry.threadId)).toEqual(["unsnoozed", "expired"]); - expect(wakeAtMs).toBe(Date.parse("2026-11-18T00:00:00.000Z")); + assert.deepEqual( + due.map((entry) => entry.threadId), + ["unsnoozed", "expired"], + ); + assert.equal(wakeAtMs, Date.parse("2026-11-18T00:00:00.000Z")); }); }); + +it.effect("resumes a held turn when its snooze ends or the thread is woken, once", () => + Effect.gen(function* () { + yield* TestClock.setTime(startMs); + const rows = yield* Ref.make([deferred("snoozed", "2026-11-13T03:01:00.000Z")]); + const released = yield* Queue.unbounded(); + const events = yield* Queue.unbounded(); + const layer = SnoozeDeferredDelivery.layerWorker.pipe( + Layer.provide( + Layer.mergeAll( + Scheduler.layer, + Layer.succeed(SnoozeDeferredDelivery.SnoozeDeferredStore, { + read: Ref.get(rows), + }), + Layer.mock(ThreadManagement.ThreadManagementService)({ + // A release clears the turn's deferral, so the store stops listing it. + dispatch: (command) => + Ref.update(rows, (current) => + current.filter((row) => row.threadId !== command.threadId), + ).pipe( + Effect.andThen(Queue.offer(released, command)), + Effect.as({ sequence: 1, storedEvents: [] }), + ), + }), + Layer.mock(Orchestrator.OrchestratorV2)({ + streamDomainEvents: Stream.fromQueue(events), + }), + ), + ), + ); + yield* Effect.gen(function* () { + yield* TestClock.adjust("60 seconds"); + assert.deepEqual(yield* Queue.take(released), { + type: "queue.resume", + commandId: "snooze-deferred-release:run:snoozed", + threadId: "snoozed", + } as never); + + yield* Ref.set(rows, [deferred("woken", null)]); + yield* Queue.offer(events, { type: "thread.unsnoozed" } as never); + yield* TestClock.adjust("5 seconds"); + assert.equal((yield* Queue.take(released)).threadId, "woken"); + + yield* TestClock.adjust("10 minutes"); + assert.equal(yield* Queue.size(released), 0); + }).pipe(Effect.provide(layer)); + }), +); diff --git a/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.ts b/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.ts index 52ac10bb86aba..6ee213014dba5 100644 --- a/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.ts +++ b/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.ts @@ -1,4 +1,5 @@ import { CommandId, ThreadId } from "@t3tools/contracts"; +import * as Context from "effect/Context"; import * as DateTime from "effect/DateTime"; import * as Effect from "effect/Effect"; import * as Layer from "effect/Layer"; @@ -61,11 +62,29 @@ export const readSnoozeDeferredThreads = Effect.fn("SnoozeDeferredDelivery.read" })); }); +export class SnoozeDeferredStore extends Context.Service< + SnoozeDeferredStore, + { readonly read: Effect.Effect> } +>()("t3/orchestration-v2/SnoozeDeferredStore") {} + +const layerStore = Layer.effect( + SnoozeDeferredStore, + Effect.gen(function* () { + const sql = yield* SqlClient.SqlClient; + return SnoozeDeferredStore.of({ + read: readSnoozeDeferredThreads().pipe( + Effect.provideService(SqlClient.SqlClient, sql), + Effect.orElseSucceed(() => []), + ), + }); + }), +); + const affectsDeferral = (event: OrchestrationV2DomainEvent) => event.type.startsWith("thread.") || event.type === "run.created" || event.type === "run.updated"; const makeSweep = Effect.gen(function* () { - const sql = yield* SqlClient.SqlClient; + const store = yield* SnoozeDeferredStore; const threads = yield* ThreadManagement.ThreadManagementService; const orchestrator = yield* Orchestrator.OrchestratorV2; const due = DueHint.make(); @@ -78,13 +97,7 @@ const makeSweep = Effect.gen(function* () { const nowMs = DateTime.toEpochMillis(yield* DateTime.now); if (yield* due.isIdle(nowMs)) return; const readVersion = yield* due.version; - const { due: releases, wakeAtMs } = snoozeDeferredReleases( - yield* readSnoozeDeferredThreads().pipe( - Effect.provideService(SqlClient.SqlClient, sql), - Effect.orElseSucceed(() => []), - ), - nowMs, - ); + const { due: releases, wakeAtMs } = snoozeDeferredReleases(yield* store.read, nowMs); for (const thread of releases) { yield* threads .dispatch({ @@ -111,10 +124,12 @@ const makeSweep = Effect.gen(function* () { }); }); -export const layer = Layer.effectDiscard( +export const layerWorker = Layer.effectDiscard( Effect.gen(function* () { const sweep = yield* makeSweep; const scheduler = yield* Scheduler.Scheduler; yield* scheduler.register("snooze-deferred-delivery", sweep()); }), ); + +export const layer = layerWorker.pipe(Layer.provide(layerStore)); diff --git a/apps/server/src/orchestration-v2/runtimeLayer.test.ts b/apps/server/src/orchestration-v2/runtimeLayer.test.ts index 93e5d13785408..2867db0894213 100644 --- a/apps/server/src/orchestration-v2/runtimeLayer.test.ts +++ b/apps/server/src/orchestration-v2/runtimeLayer.test.ts @@ -8692,7 +8692,11 @@ it.layer(layerTest)("OrchestrationV2LayerLive lifecycle", (it) => { threadId, }); const released = yield* orchestrator.getThreadProjection(threadId); - assert.equal(released.runs.find((run) => run.id === heldRun.id)?.status, "starting"); + const releasedRun = released.runs.find((run) => run.id === heldRun.id)!; + assert.equal(releasedRun.status, "starting"); + // Released, it is no longer the snooze's: a failure hold later must not release it again. + assert.isUndefined(releasedRun.snoozeDeferred); + assert.deepEqual(yield* SnoozeDeferredDelivery.readSnoozeDeferredThreads(), []); }), ); diff --git a/docs/orchestration-v2/orchestrator-mcp-server.md b/docs/orchestration-v2/orchestrator-mcp-server.md index f3ef6ff6ddaf9..2740aed5c53f0 100644 --- a/docs/orchestration-v2/orchestrator-mcp-server.md +++ b/docs/orchestration-v2/orchestrator-mcp-server.md @@ -459,6 +459,14 @@ Sends a message to any ordinary or delegated thread in the environment: applies: the provider cannot stop a turn, Stop has already reached the turn, or the turn or the new message is `/compact` or `/logout`. +A snoozed target stays snoozed unless `respectSnooze: false`. The message's run +is queued and held behind the thread's last run, marked `snoozeDeferred`, and +`SnoozeDeferredDelivery` resumes the queue once the snooze ends or the thread is +woken. A held run that something else releases stops being deferred, so a later +failure hold is never released by that sweep. A thread that has never run, and a +snooze the server set until a usage limit resets, wake as before. Messages from +the app always wake the thread. + The target runtime and interaction modes may not be broader than the caller's. Stable command and message IDs are derived from `clientRequestId` for idempotent retries. From 963ad2fcaad37f58c7df4c956fd460ed1f2a096d Mon Sep 17 00:00:00 2001 From: Chris OHearn Date: Thu, 12 Nov 2026 20:33:32 -0700 Subject: [PATCH 10/14] test(server): type the snooze release worker test and its service key Co-Authored-By: Claude Opus 5.5 --- .../SnoozeDeferredDelivery.test.ts | 20 ++++++++++--------- .../SnoozeDeferredDelivery.ts | 2 +- 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.test.ts b/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.test.ts index 2894734b379e2..bdcee212f6f62 100644 --- a/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.test.ts +++ b/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.test.ts @@ -1,5 +1,5 @@ import { assert, describe, it } from "@effect/vitest"; -import type { OrchestrationV2Command, OrchestrationV2DomainEvent } from "@t3tools/contracts"; +import type { OrchestrationV2DomainEvent } from "@t3tools/contracts"; import * as Effect from "effect/Effect"; import * as Layer from "effect/Layer"; import * as Queue from "effect/Queue"; @@ -42,7 +42,7 @@ it.effect("resumes a held turn when its snooze ends or the thread is woken, once Effect.gen(function* () { yield* TestClock.setTime(startMs); const rows = yield* Ref.make([deferred("snoozed", "2026-11-13T03:01:00.000Z")]); - const released = yield* Queue.unbounded(); + const released = yield* Queue.unbounded>>(); const events = yield* Queue.unbounded(); const layer = SnoozeDeferredDelivery.layerWorker.pipe( Layer.provide( @@ -53,13 +53,15 @@ it.effect("resumes a held turn when its snooze ends or the thread is woken, once }), Layer.mock(ThreadManagement.ThreadManagementService)({ // A release clears the turn's deferral, so the store stops listing it. - dispatch: (command) => - Ref.update(rows, (current) => - current.filter((row) => row.threadId !== command.threadId), + dispatch: (command) => { + const resumed = command as unknown as Readonly>; + return Ref.update(rows, (current) => + current.filter((row) => row.threadId !== resumed["threadId"]), ).pipe( - Effect.andThen(Queue.offer(released, command)), + Effect.andThen(Queue.offer(released, resumed)), Effect.as({ sequence: 1, storedEvents: [] }), - ), + ); + }, }), Layer.mock(Orchestrator.OrchestratorV2)({ streamDomainEvents: Stream.fromQueue(events), @@ -73,12 +75,12 @@ it.effect("resumes a held turn when its snooze ends or the thread is woken, once type: "queue.resume", commandId: "snooze-deferred-release:run:snoozed", threadId: "snoozed", - } as never); + }); yield* Ref.set(rows, [deferred("woken", null)]); yield* Queue.offer(events, { type: "thread.unsnoozed" } as never); yield* TestClock.adjust("5 seconds"); - assert.equal((yield* Queue.take(released)).threadId, "woken"); + assert.equal((yield* Queue.take(released))["threadId"], "woken"); yield* TestClock.adjust("10 minutes"); assert.equal(yield* Queue.size(released), 0); diff --git a/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.ts b/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.ts index 6ee213014dba5..229da82e30a45 100644 --- a/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.ts +++ b/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.ts @@ -65,7 +65,7 @@ export const readSnoozeDeferredThreads = Effect.fn("SnoozeDeferredDelivery.read" export class SnoozeDeferredStore extends Context.Service< SnoozeDeferredStore, { readonly read: Effect.Effect> } ->()("t3/orchestration-v2/SnoozeDeferredStore") {} +>()("t3/orchestration-v2/SnoozeDeferredDelivery/SnoozeDeferredStore") {} const layerStore = Layer.effect( SnoozeDeferredStore, From 43d12e57743e02f75d9b5d080e95cfbcd52cd119 Mon Sep 17 00:00:00 2001 From: Chris OHearn Date: Thu, 12 Nov 2026 21:19:35 -0700 Subject: [PATCH 11/14] docs(jarvis): record the snooze default for agent sends and scheduled model changes (0017) Co-Authored-By: Claude Opus 5.5 --- ...ect-snoozes-and-scheduled-model-changes.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 docs/jarvis/decisions/0017-agent-sends-respect-snoozes-and-scheduled-model-changes.md diff --git a/docs/jarvis/decisions/0017-agent-sends-respect-snoozes-and-scheduled-model-changes.md b/docs/jarvis/decisions/0017-agent-sends-respect-snoozes-and-scheduled-model-changes.md new file mode 100644 index 0000000000000..8c663c0b24439 --- /dev/null +++ b/docs/jarvis/decisions/0017-agent-sends-respect-snoozes-and-scheduled-model-changes.md @@ -0,0 +1,32 @@ +# Agent sends respect snoozes; busy threads take scheduled model changes + +Accepted 2026-11-13. Number provisional until merge. + +## Decision + +**Snoozes.** A snooze is a person's dated hold. + +- `t3_thread_send`, `t3_thread_post` and `t3_thread_send_attachments` leave a snoozed thread snoozed by default (`respectSnooze` defaults to true). +- A send's turn is queued and held until the snooze ends or someone wakes the thread, and the server then resumes the queue. A post is only recorded. +- Both results return `snoozedUntil` and a warning. +- `respectSnooze: false` wakes the thread, as every send did before. +- Messages a person sends from the app still wake it. So do sends to a thread that has never run, and to a thread the server snoozed until a usage limit resets. + +**Scheduled model changes.** `t3_thread_configure` with `modelSelection` and `applyAt: "next_turn"` works on a busy thread instead of being refused. + +- The thread starts its next turn with the new model or options. +- Messages already queued start with it too. +- Reading the configuration shows the pending change, and scheduling the current model cancels it. +- Switching provider instance and changing `runtimeMode` still need an idle thread. + +## Why + +On 2026-11-13 a worker's handoff woke two threads that were snoozed until 11-18 and 11-24, and nobody had released those holds. Agents send for many reasons (relays, handoffs, nudges), and none of them should end a person's hold without saying so. The explicit override and the warning keep the old behaviour one argument away. + +The Jarvis inbox always has a run going. Every effort change to it was refused as busy: five times on 2026-11-12. A change that did apply on a busy thread was also undone, because queued messages carry the model they were queued with. + +## Costs + +- An agent waiting on a snoozed thread now waits until it wakes. +- Repeated sends to a snoozed thread each queue a held turn, and all of them run at wake. The supervisor skips snoozed threads. +- At a scheduled change's boundary, a replaced session that still runs background work holds the queue, which only the app can resume. This was already true for a model picked ahead of a queued message. From 146946ff75b00b931fbc76652c7c92b39b241bfd Mon Sep 17 00:00:00 2001 From: Chris OHearn Date: Thu, 12 Nov 2026 21:38:25 -0700 Subject: [PATCH 12/14] fix(mcp): retry refused snooze releases, wake on isSnoozed, keep queued model picks From the PR #94 review: - A refused queue.resume left a fixed command id whose rejected receipt every retry replayed. Each release attempt now gets its own id, and a usage-limit resume releases snooze-held turns once the thread is awake. - Snooze checks use isSnoozed, so a thread that woke on an error or a request stops holding agent messages. isSnoozed moves to SnoozeState.ts to avoid an import cycle. - A scheduled model change leaves queued messages that named a model alone, and later sends take the change, not an older queued pick. - A deleted thread asked for by its exact id is reported as deleted, not swapped for its bare uuid. - Shorter respectSnooze and applyAt text: the tool list grows 270 bytes, not 409. Co-Authored-By: Claude Opus 5.5 --- apps/server/src/mcp/threadReference.test.ts | 15 ++++- apps/server/src/mcp/threadReference.ts | 32 ++++++--- apps/server/src/mcp/toolkits/thread/tools.ts | 3 +- .../src/orchestration-v2/Orchestrator.ts | 61 +++++++++++++---- .../SnoozeDeferredDelivery.test.ts | 67 ++++++++++++++----- .../SnoozeDeferredDelivery.ts | 22 +++++- .../src/orchestration-v2/SnoozeState.ts | 39 +++++++++++ .../ThreadSettlementService.ts | 36 +--------- .../src/orchestration-v2/runtimeLayer.test.ts | 12 +++- .../src/provider/agentContextBudget.json | 2 +- ...ect-snoozes-and-scheduled-model-changes.md | 2 +- .../orchestrator-mcp-server.md | 5 +- docs/user/outside-agents.md | 5 +- packages/contracts/src/orchestrationV2.ts | 2 + packages/contracts/src/orchestratorMcp.ts | 4 +- 15 files changed, 218 insertions(+), 89 deletions(-) create mode 100644 apps/server/src/orchestration-v2/SnoozeState.ts diff --git a/apps/server/src/mcp/threadReference.test.ts b/apps/server/src/mcp/threadReference.test.ts index a5d27dadcc0f8..992ff13cca70e 100644 --- a/apps/server/src/mcp/threadReference.test.ts +++ b/apps/server/src/mcp/threadReference.test.ts @@ -13,13 +13,17 @@ const mcpThread = ThreadId.make(`mcp:${uuid}`); const launchThread = ThreadId.make(`mcp:launch:${"be52150e".repeat(8)}`); const nativeThread = ThreadId.make("7e56b504-8739-4f3f-80e7-298410d87ec0"); const deletedThread = ThreadId.make("mcp:0dd09096-12e3-4179-87d5-42fa45c77d5e"); +// A deleted mcp: thread whose bare uuid is another, live thread. +const replacedUuid = "29b25a73-a7a7-4321-bef4-2b4eb4386aa8"; +const deletedReplaced = ThreadId.make(`mcp:${replacedUuid}`); +const liveReplaced = ThreadId.make(replacedUuid); const threads = { getThreadShell: (threadId: ThreadId) => Effect.succeed( - threadId === deletedThread + threadId === deletedThread || threadId === deletedReplaced ? { ...liveThreadShell(threadId), deletedAt: DateTime.makeUnsafe(0) } - : [mcpThread, launchThread, nativeThread].includes(threadId) + : [mcpThread, launchThread, nativeThread, liveReplaced].includes(threadId) ? liveThreadShell(threadId) : null, ), @@ -67,6 +71,13 @@ describe("resolveReadableThread", () => { it.effect("says a thread was deleted, and names the closest ids for one never here", () => Effect.gen(function* () { expect((yield* refuse(deletedThread)).message).toBe(`Thread ${deletedThread} was deleted.`); + expect((yield* refuse(deletedReplaced)).message).toBe( + `Thread ${deletedReplaced} was deleted.`, + ); + // A bare uuid of a deleted mcp: thread says so too. + expect((yield* refuse(deletedThread.slice(4))).message).toBe( + `Thread ${deletedThread} was deleted.`, + ); const typo = yield* refuse("mcp:5d0b4a3e-0000-4000-8000-000000000000"); expect(typo.code).toBe("thread_not_found"); diff --git a/apps/server/src/mcp/threadReference.ts b/apps/server/src/mcp/threadReference.ts index 224856e49f272..7fb0ee4f747c0 100644 --- a/apps/server/src/mcp/threadReference.ts +++ b/apps/server/src/mcp/threadReference.ts @@ -35,10 +35,10 @@ const idCore = (threadId: string) => * pass the bare uuid. Reads have no per-thread grant, so the id is resolved here instead of * hinted; write tools keep their exact-id checks. */ -const variants = (threadId: ThreadId): ReadonlyArray => { - if (threadId.startsWith("mcp:launch:")) return [threadId]; - if (threadId.startsWith("mcp:")) return [threadId, ThreadId.make(threadId.slice(4))]; - return [threadId, ThreadId.make(`mcp:${threadId}`)]; +const alternate = (threadId: ThreadId): ThreadId | undefined => { + if (threadId.startsWith("mcp:launch:")) return undefined; + if (threadId.startsWith("mcp:")) return ThreadId.make(threadId.slice(4)); + return ThreadId.make(`mcp:${threadId}`); }; const closestMatches = Effect.fn("mcp.threadReference.closestMatches")(function* ( @@ -81,14 +81,26 @@ export const resolveReadableThread = Effect.fn("mcp.resolveReadableThread")(func } candidates = threadLinkCandidates(link, environmentId).map((ref) => ref.threadId); } - let deleted: ThreadId | undefined; - for (const candidate of candidates.flatMap(variants)) { - const shell: OrchestrationV2ThreadShell | null = yield* threads - .getThreadShell(candidate) - .pipe(Effect.mapError(unavailable)); + const shellOf = (threadId: ThreadId) => + threads.getThreadShell(threadId).pipe(Effect.mapError(unavailable)); + // The id as given wins, deleted or not; another spelling stands in only for an id never here. + for (const candidate of candidates) { + const shell: OrchestrationV2ThreadShell | null = yield* shellOf(candidate); if (shell === null) continue; if (shell.deletedAt === null) return { threadId: candidate, shell }; - deleted ??= candidate; + return yield* new OrchestratorMcpFailure({ + code: "thread_not_found", + message: `Thread ${candidate} was deleted.`, + }); + } + let deleted: ThreadId | undefined; + for (const candidate of candidates) { + const other = alternate(candidate); + if (other === undefined) continue; + const shell = yield* shellOf(other); + if (shell === null) continue; + if (shell.deletedAt === null) return { threadId: other, shell }; + deleted ??= other; } if (deleted !== undefined) { return yield* new OrchestratorMcpFailure({ diff --git a/apps/server/src/mcp/toolkits/thread/tools.ts b/apps/server/src/mcp/toolkits/thread/tools.ts index 8ebccd91d00a6..adea3d9983337 100644 --- a/apps/server/src/mcp/toolkits/thread/tools.ts +++ b/apps/server/src/mcp/toolkits/thread/tools.ts @@ -203,8 +203,7 @@ const ThreadConfigureTool = Tool.make("t3_thread_configure", { modelSelection: Schema.optional(ModelSelection), applyAt: Schema.optional( Schema.Literal("next_turn").annotate({ - description: - "Busy thread: apply modelSelection from the next turn, queued messages included.", + description: "Busy thread: apply from the next turn, queued messages included.", }), ), runtimeMode: Schema.optional(RuntimeMode), diff --git a/apps/server/src/orchestration-v2/Orchestrator.ts b/apps/server/src/orchestration-v2/Orchestrator.ts index be5d05025da49..b8a7221b0df0e 100644 --- a/apps/server/src/orchestration-v2/Orchestrator.ts +++ b/apps/server/src/orchestration-v2/Orchestrator.ts @@ -192,6 +192,7 @@ import * as RunExecutionService from "./RunExecutionService.ts"; import { ProviderSessionManagerV2 } from "./ProviderSessionManager.ts"; import { ProviderSwitchServiceV2 } from "./ProviderSwitchService.ts"; import { isAutomaticCompletionRun, queuedRunsInDeliveryOrder } from "./QueuedRunOrder.ts"; +import { isSnoozed } from "./SnoozeState.ts"; import { isRuntimePolicyAboveCeilingError, RuntimePolicyV2 } from "./RuntimePolicy.ts"; import { endOrphanedNativeSubagent, @@ -969,13 +970,20 @@ function nextTurnModelSelection( return thread.scheduledModelSelection?.modelSelection ?? thread.modelSelection; } -/** A run queued before a scheduled change starts with it, as one queued before a failover does. */ +/** + * A run queued before a scheduled change starts with it, as one queued before a failover does, + * unless its sender named a model. + */ function queuedBeforeScheduledSelection( projection: Pick, run: OrchestrationV2Run, ): boolean { const scheduled = projection.thread.scheduledModelSelection; - return scheduled != null && run.ordinal <= scheduled.queuedThroughOrdinal; + return ( + scheduled != null && + run.ordinal <= scheduled.queuedThroughOrdinal && + run.explicitModelSelection !== true + ); } /** Drops a scheduled change once the run starting now leaves no run queued before it. */ @@ -989,7 +997,7 @@ function threadAtRunStart( (run) => run.id !== startingRunId && run.status === "queued" && - run.ordinal <= scheduled.queuedThroughOrdinal, + queuedBeforeScheduledSelection(projection, run), ); return waiting ? projection.thread : { ...projection.thread, scheduledModelSelection: null }; } @@ -1019,11 +1027,14 @@ function queuedRunModelSelection( function queueTailModelSelection( projection: Pick, ): ModelSelection { - return ( - queuedRunsInDeliveryOrder(projection).findLast( - (run) => !queuedRunFollowsThread(projection, run), - )?.modelSelection ?? nextTurnModelSelection(projection.thread) + const tail = queuedRunsInDeliveryOrder(projection).findLast( + (run) => !queuedRunFollowsThread(projection, run), ); + const scheduled = projection.thread.scheduledModelSelection; + // A pick queued before a scheduled change is older than it; later sends take the change. + return tail !== undefined && (scheduled == null || tail.ordinal > scheduled.queuedThroughOrdinal) + ? tail.modelSelection + : nextTurnModelSelection(projection.thread); } /** @@ -3232,9 +3243,23 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio .map((message) => message.id), ); const now = yield* DateTime.now; - // A snooze's held turn waits for the thread to wake, not for later runs. + // A snooze's held turn waits for the thread to wake; once it has, a completed run (a usage + // limit's resume, say) releases it like the others. + const snoozeHolds = + held.some((run) => run.snoozeDeferred === true) && + isSnoozed( + (yield* projectionStore + .getThreadShell(threadId) + .pipe(Effect.orElseSucceed(() => null))) ?? { + ...projection.thread, + status: "idle", + latestRunCompletedAt: null, + pendingRuntimeRequest: null, + }, + DateTime.toEpochMillis(now), + ); const released = held.filter( - (run) => unattended.has(run.userMessageId) && run.snoozeDeferred !== true, + (run) => unattended.has(run.userMessageId) && !(run.snoozeDeferred === true && snoozeHolds), ); if (released.length === 0) return; yield* writeSystemEvents( @@ -3244,7 +3269,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio runId: run.id, providerInstanceId: run.providerInstanceId, occurredAt: now, - payload: { ...run, queueHeld: false }, + payload: { ...withoutSnoozeDeferral(run), queueHeld: false }, })), ); }); @@ -7002,18 +7027,29 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio // A sender that respects the snooze leaves it: a post is only recorded, and a turn waits, // held behind the thread's last run, until the thread wakes. A thread with no run wakes, // and so does one the server snoozed until its usage limit resets: that is no one's hold. + // The snooze counts as the sidebar shows it: an error or a request has already woken it. const snoozeHeldUntil = projection.thread.snoozedUntil; const limitRecovery = projection.thread.limitRecovery; const respectsSnooze = command.respectSnooze === true && !automaticWake && snoozeHeldUntil != null && - DateTime.toEpochMillis(snoozeHeldUntil) > DateTime.toEpochMillis(yield* DateTime.now) && !( limitRecovery?.snooze === true && DateTime.toEpochMillis(snoozeHeldUntil) === Date.parse(limitRecovery.resetAt) ) && - (command.postOnly === true || latestExecutedRun(projection.runs) != null); + (command.postOnly === true || latestExecutedRun(projection.runs) != null) && + isSnoozed( + (yield* projectionStore + .getThreadShell(command.threadId) + .pipe(Effect.orElseSucceed(() => null))) ?? { + ...projection.thread, + status: "idle", + latestRunCompletedAt: null, + pendingRuntimeRequest: null, + }, + DateTime.toEpochMillis(yield* DateTime.now), + ); if (projection.thread.snoozedUntil != null && !automaticWake && !respectsSnooze) { const now = yield* DateTime.now; const thread: OrchestrationV2AppThread = { @@ -7712,6 +7748,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio status: "queued", ...(steerWhenReadyRunId === undefined ? {} : { steerWhenReadyRunId }), ...(respectsSnooze ? { snoozeDeferred: true } : {}), + ...(command.modelSelection === undefined ? {} : { explicitModelSelection: true }), ...(worktreeMissingRun !== undefined || respectsSnooze || (heldRunsToRelease.length === 0 && diff --git a/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.test.ts b/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.test.ts index bdcee212f6f62..f833daa9fa3a9 100644 --- a/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.test.ts +++ b/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.test.ts @@ -1,5 +1,6 @@ import { assert, describe, it } from "@effect/vitest"; import type { OrchestrationV2DomainEvent } from "@t3tools/contracts"; +import * as DateTime from "effect/DateTime"; import * as Effect from "effect/Effect"; import * as Layer from "effect/Layer"; import * as Queue from "effect/Queue"; @@ -38,12 +39,24 @@ describe("snoozeDeferredReleases", () => { }); }); -it.effect("resumes a held turn when its snooze ends or the thread is woken, once", () => +it.effect("resumes a held turn when the thread wakes, retrying a refused resume", () => Effect.gen(function* () { yield* TestClock.setTime(startMs); - const rows = yield* Ref.make([deferred("snoozed", "2026-11-13T03:01:00.000Z")]); - const released = yield* Queue.unbounded>>(); + const rows = yield* Ref.make([ + deferred("snoozed", "2026-11-13T03:01:00.000Z"), + deferred("failed", "2026-11-24T00:00:00.000Z"), + ]); + const attempts = yield* Queue.unbounded>>(); + const refuseNext = yield* Ref.make(new Set(["snoozed"])); const events = yield* Queue.unbounded(); + const snoozedShell = (status: string, completedAt: string | null) => ({ + snoozedUntil: DateTime.makeUnsafe("2026-11-24T00:00:00.000Z"), + snoozedAt: DateTime.makeUnsafe("2026-11-13T02:00:00.000Z"), + latestRunCompletedAt: completedAt === null ? null : DateTime.makeUnsafe(completedAt), + status, + pendingRuntimeRequest: null, + pendingGuestMessageCount: 0, + }); const layer = SnoozeDeferredDelivery.layerWorker.pipe( Layer.provide( Layer.mergeAll( @@ -52,14 +65,30 @@ it.effect("resumes a held turn when its snooze ends or the thread is woken, once read: Ref.get(rows), }), Layer.mock(ThreadManagement.ThreadManagementService)({ - // A release clears the turn's deferral, so the store stops listing it. + // "failed" failed after it was snoozed, which wakes it as the sidebar shows it. + getThreadShell: (threadId) => + Effect.succeed( + (threadId === "failed" + ? snoozedShell("failed", "2026-11-13T02:30:00.000Z") + : snoozedShell("idle", null)) as never, + ), + // A refusal, such as a limited provider, releases nothing; a release clears the deferral. dispatch: (command) => { - const resumed = command as unknown as Readonly>; - return Ref.update(rows, (current) => - current.filter((row) => row.threadId !== resumed["threadId"]), - ).pipe( - Effect.andThen(Queue.offer(released, resumed)), - Effect.as({ sequence: 1, storedEvents: [] }), + const attempt = command as unknown as Readonly>; + const threadId = attempt["threadId"]!; + return Queue.offer(attempts, attempt).pipe( + Effect.andThen(Ref.get(refuseNext)), + Effect.flatMap((refused) => + refused.has(threadId) + ? Ref.update(refuseNext, (current) => { + const next = new Set(current); + next.delete(threadId); + return next; + }).pipe(Effect.andThen(Effect.fail("refused" as never))) + : Ref.update(rows, (current) => + current.filter((row) => row.threadId !== threadId), + ).pipe(Effect.as({ sequence: 1, storedEvents: [] })), + ), ); }, }), @@ -70,20 +99,24 @@ it.effect("resumes a held turn when its snooze ends or the thread is woken, once ), ); yield* Effect.gen(function* () { + // The first sweep releases the thread that woke on its failure, long before its date. + assert.equal((yield* Queue.take(attempts))["threadId"], "failed"); + + yield* TestClock.adjust("60 seconds"); + const refused = yield* Queue.take(attempts); + assert.equal(refused["threadId"], "snoozed"); yield* TestClock.adjust("60 seconds"); - assert.deepEqual(yield* Queue.take(released), { - type: "queue.resume", - commandId: "snooze-deferred-release:run:snoozed", - threadId: "snoozed", - }); + const retried = yield* Queue.take(attempts); + assert.equal(retried["threadId"], "snoozed"); + assert.notEqual(retried["commandId"], refused["commandId"]); yield* Ref.set(rows, [deferred("woken", null)]); yield* Queue.offer(events, { type: "thread.unsnoozed" } as never); yield* TestClock.adjust("5 seconds"); - assert.equal((yield* Queue.take(released))["threadId"], "woken"); + assert.equal((yield* Queue.take(attempts))["threadId"], "woken"); yield* TestClock.adjust("10 minutes"); - assert.equal(yield* Queue.size(released), 0); + assert.equal(yield* Queue.size(attempts), 0); }).pipe(Effect.provide(layer)); }), ); diff --git a/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.ts b/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.ts index 229da82e30a45..cbb1908be7076 100644 --- a/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.ts +++ b/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.ts @@ -11,6 +11,7 @@ import * as DueHint from "../scheduling/DueHint.ts"; import * as Scheduler from "../scheduling/Scheduler.ts"; import { forkParked } from "../serverActivation.ts"; import * as Orchestrator from "./Orchestrator.ts"; +import { isSnoozed } from "./SnoozeState.ts"; import * as ThreadManagement from "./ThreadManagementService.ts"; const RELEASE_RETRY_MS = 60_000; @@ -80,8 +81,12 @@ const layerStore = Layer.effect( }), ); +// A failed run or a new request can wake a thread before its date, as the sidebar shows it. const affectsDeferral = (event: OrchestrationV2DomainEvent) => - event.type.startsWith("thread.") || event.type === "run.created" || event.type === "run.updated"; + event.type.startsWith("thread.") || + event.type === "run.created" || + event.type === "run.updated" || + event.type === "runtime-request.updated"; const makeSweep = Effect.gen(function* () { const store = yield* SnoozeDeferredStore; @@ -97,12 +102,23 @@ const makeSweep = Effect.gen(function* () { const nowMs = DateTime.toEpochMillis(yield* DateTime.now); if (yield* due.isIdle(nowMs)) return; const readVersion = yield* due.version; - const { due: releases, wakeAtMs } = snoozeDeferredReleases(yield* store.read, nowMs); + const rows = yield* Effect.forEach(yield* store.read, (row) => + row.snoozedUntil === null || Date.parse(row.snoozedUntil) <= nowMs + ? Effect.succeed(row) + : threads.getThreadShell(ThreadId.make(row.threadId)).pipe( + Effect.map((shell) => + shell !== null && !isSnoozed(shell, nowMs) ? { ...row, snoozedUntil: null } : row, + ), + Effect.orElseSucceed(() => row), + ), + ); + const { due: releases, wakeAtMs } = snoozeDeferredReleases(rows, nowMs); for (const thread of releases) { yield* threads .dispatch({ type: "queue.resume", - commandId: CommandId.make(`snooze-deferred-release:${thread.firstRunId}`), + // One id per attempt: a refused resume (a limited provider) stays retryable. + commandId: CommandId.make(`snooze-deferred-release:${thread.firstRunId}:${nowMs}`), threadId: ThreadId.make(thread.threadId), }) .pipe( diff --git a/apps/server/src/orchestration-v2/SnoozeState.ts b/apps/server/src/orchestration-v2/SnoozeState.ts new file mode 100644 index 0000000000000..9764f8194181c --- /dev/null +++ b/apps/server/src/orchestration-v2/SnoozeState.ts @@ -0,0 +1,39 @@ +import * as DateTime from "effect/DateTime"; + +import type * as ProjectionStore from "./ProjectionStore.ts"; + +const toMillis = (value: DateTime.Utc | null | undefined): number | null => + value == null ? null : DateTime.toEpochMillis(value); + +/** Match client effectiveSnoozed so agents and sidebar agree. */ +export function isSnoozed( + thread: Pick< + ProjectionStore.ProjectionSettlementCandidate, + | "snoozedUntil" + | "snoozedAt" + | "latestRunCompletedAt" + | "status" + | "pendingRuntimeRequest" + | "pendingGuestMessageCount" + >, + nowMs: number, +): boolean { + const snoozedUntilMs = toMillis(thread.snoozedUntil); + if (snoozedUntilMs === null || snoozedUntilMs <= nowMs) return false; + // Same as the client: a waiting guest message wakes the thread, and the snooze stays stored. + if ((thread.pendingGuestMessageCount ?? 0) > 0) return false; + const snoozedAtMs = toMillis(thread.snoozedAt); + if ( + thread.pendingRuntimeRequest !== null && + (thread.pendingRuntimeRequest.kind !== "user_input" || + snoozedAtMs === null || + DateTime.toEpochMillis(thread.pendingRuntimeRequest.createdAt) > snoozedAtMs) + ) { + return false; + } + const completedAtMs = toMillis(thread.latestRunCompletedAt); + const wokeOnError = + thread.status === "failed" && + (snoozedAtMs === null || (completedAtMs !== null && completedAtMs > snoozedAtMs)); + return !wokeOnError; +} diff --git a/apps/server/src/orchestration-v2/ThreadSettlementService.ts b/apps/server/src/orchestration-v2/ThreadSettlementService.ts index 3481a61a21a96..b8ea140b1c86a 100644 --- a/apps/server/src/orchestration-v2/ThreadSettlementService.ts +++ b/apps/server/src/orchestration-v2/ThreadSettlementService.ts @@ -36,6 +36,9 @@ import * as ProjectStore from "./ProjectStore.ts"; import { sourceControlDefinitions } from "../sourceControl/sourceControlDefinitions.ts"; import * as Orchestrator from "./Orchestrator.ts"; import * as ProjectionStore from "./ProjectionStore.ts"; +import { isSnoozed } from "./SnoozeState.ts"; + +export { isSnoozed }; export interface SettlementPullRequest { readonly state: "open" | "closed" | "merged"; @@ -160,39 +163,6 @@ export function isAutoSettlementCandidate( return !isSnoozed(thread, nowMs); } -/** Match client effectiveSnoozed so agents and sidebar agree. */ -export function isSnoozed( - thread: Pick< - ProjectionStore.ProjectionSettlementCandidate, - | "snoozedUntil" - | "snoozedAt" - | "latestRunCompletedAt" - | "status" - | "pendingRuntimeRequest" - | "pendingGuestMessageCount" - >, - nowMs: number, -): boolean { - const snoozedUntilMs = toMillis(thread.snoozedUntil); - if (snoozedUntilMs === null || snoozedUntilMs <= nowMs) return false; - // Same as the client: a waiting guest message wakes the thread, and the snooze stays stored. - if ((thread.pendingGuestMessageCount ?? 0) > 0) return false; - const snoozedAtMs = toMillis(thread.snoozedAt); - if ( - thread.pendingRuntimeRequest !== null && - (thread.pendingRuntimeRequest.kind !== "user_input" || - snoozedAtMs === null || - DateTime.toEpochMillis(thread.pendingRuntimeRequest.createdAt) > snoozedAtMs) - ) { - return false; - } - const completedAtMs = toMillis(thread.latestRunCompletedAt); - const wokeOnError = - thread.status === "failed" && - (snoozedAtMs === null || (completedAtMs !== null && completedAtMs > snoozedAtMs)); - return !wokeOnError; -} - export function resolveAutoSettlementAt(input: { readonly thread: ProjectionStore.ProjectionSettlementCandidate; readonly pullRequest: SettlementPullRequest | null; diff --git a/apps/server/src/orchestration-v2/runtimeLayer.test.ts b/apps/server/src/orchestration-v2/runtimeLayer.test.ts index 2867db0894213..7014ee3e2a648 100644 --- a/apps/server/src/orchestration-v2/runtimeLayer.test.ts +++ b/apps/server/src/orchestration-v2/runtimeLayer.test.ts @@ -8720,6 +8720,7 @@ it.layer(layerTest)("OrchestrationV2LayerLive lifecycle", (it) => { branch: null, worktreePath: process.cwd(), }); + const pickedSelection = { ...modelSelection, model: "gpt-5.3" }; const send = (key: string) => orchestrator.dispatch({ type: "message.dispatch", @@ -8728,11 +8729,13 @@ it.layer(layerTest)("OrchestrationV2LayerLive lifecycle", (it) => { messageId: MessageId.make(`${threadId}:${key}`), text: key, attachments: [], + ...(key === "picked" ? { modelSelection: pickedSelection } : {}), dispatchMode: { type: key === "active" ? "start_immediately" : "queue_after_active" }, createdBy: "agent", creationSource: "mcp", }); - for (const key of ["active", "before-1", "before-2"]) yield* send(key); + // "picked" named its own model before the change was scheduled, so it keeps it. + for (const key of ["active", "before-1", "before-2", "picked"]) yield* send(key); yield* orchestrator.dispatch({ type: "thread.model-selection.set", commandId: CommandId.make(`${threadId}:schedule`), @@ -8747,7 +8750,7 @@ it.layer(layerTest)("OrchestrationV2LayerLive lifecycle", (it) => { scheduled.thread.scheduledModelSelection?.modelSelection, scheduledSelection, ); - const [active, before1, before2, after] = scheduled.runs; + const [active, before1, before2, picked, after] = scheduled.runs; assert.deepEqual(after?.modelSelection, scheduledSelection); const complete = (runId: RunId) => @@ -8784,6 +8787,11 @@ it.layer(layerTest)("OrchestrationV2LayerLive lifecycle", (it) => { assert.equal(started2.status, "starting"); assert.deepEqual(started2.modelSelection, scheduledSelection); assert.isNull(secondBoundary.thread.scheduledModelSelection ?? null); + + const thirdBoundary = yield* complete(before2!.id); + const startedPick = thirdBoundary.runs.find((run) => run.id === picked!.id)!; + assert.equal(startedPick.status, "starting"); + assert.deepEqual(startedPick.modelSelection, pickedSelection); }), ); diff --git a/apps/server/src/provider/agentContextBudget.json b/apps/server/src/provider/agentContextBudget.json index 8000af794ca54..b955017c80e7a 100644 --- a/apps/server/src/provider/agentContextBudget.json +++ b/apps/server/src/provider/agentContextBudget.json @@ -1,5 +1,5 @@ { "claudeSystemAppendBytes": 5597, "codexAdditionalContextBytes": 7327, - "mcpToolListJsonBytes": 56835 + "mcpToolListJsonBytes": 56696 } diff --git a/docs/jarvis/decisions/0017-agent-sends-respect-snoozes-and-scheduled-model-changes.md b/docs/jarvis/decisions/0017-agent-sends-respect-snoozes-and-scheduled-model-changes.md index 8c663c0b24439..7579f51a9ec49 100644 --- a/docs/jarvis/decisions/0017-agent-sends-respect-snoozes-and-scheduled-model-changes.md +++ b/docs/jarvis/decisions/0017-agent-sends-respect-snoozes-and-scheduled-model-changes.md @@ -15,7 +15,7 @@ Accepted 2026-11-13. Number provisional until merge. **Scheduled model changes.** `t3_thread_configure` with `modelSelection` and `applyAt: "next_turn"` works on a busy thread instead of being refused. - The thread starts its next turn with the new model or options. -- Messages already queued start with it too. +- Messages already queued start with it too, unless their sender named a model. - Reading the configuration shows the pending change, and scheduling the current model cancels it. - Switching provider instance and changing `runtimeMode` still need an idle thread. diff --git a/docs/orchestration-v2/orchestrator-mcp-server.md b/docs/orchestration-v2/orchestrator-mcp-server.md index 2740aed5c53f0..05b8af676d278 100644 --- a/docs/orchestration-v2/orchestrator-mcp-server.md +++ b/docs/orchestration-v2/orchestrator-mcp-server.md @@ -461,8 +461,9 @@ Sends a message to any ordinary or delegated thread in the environment: A snoozed target stays snoozed unless `respectSnooze: false`. The message's run is queued and held behind the thread's last run, marked `snoozeDeferred`, and -`SnoozeDeferredDelivery` resumes the queue once the snooze ends or the thread is -woken. A held run that something else releases stops being deferred, so a later +`SnoozeDeferredDelivery` resumes the queue once the thread wakes (as `isSnoozed` +decides, so an error or a request counts), with a fresh command id per attempt +so a refused resume is retried; a usage limit's resume releases the turn too. A held run that something else releases stops being deferred, so a later failure hold is never released by that sweep. A thread that has never run, and a snooze the server set until a usage limit resets, wake as before. Messages from the app always wake the thread. diff --git a/docs/user/outside-agents.md b/docs/user/outside-agents.md index eca381b725f76..9194558e9db18 100644 --- a/docs/user/outside-agents.md +++ b/docs/user/outside-agents.md @@ -101,8 +101,9 @@ T3 Code. change and caller appear in thread activity. - To change a busy thread's model or options, such as an inbox thread's effort, call `t3_thread_configure` with `modelSelection` and `applyAt: "next_turn"`. - Messages already queued start with it, and so do later agent messages. A - later message sent from the T3 app carries the composer's model instead. + Messages already queued start with it, and so do later agent messages, + except a message that named its own model, such as one sent from the T3 app + with the composer's model. Reading the configuration shows the pending change; scheduling the current model cancels it. Switching to another provider instance still needs an idle thread. diff --git a/packages/contracts/src/orchestrationV2.ts b/packages/contracts/src/orchestrationV2.ts index 604f40bec5577..921527932a5cf 100644 --- a/packages/contracts/src/orchestrationV2.ts +++ b/packages/contracts/src/orchestrationV2.ts @@ -784,6 +784,8 @@ export const OrchestrationV2Run = Schema.Struct({ queueHeld: Schema.optional(Schema.Boolean), /** Held by a send that respected a snooze; released when the thread wakes. */ snoozeDeferred: Schema.optional(Schema.Boolean), + /** Queued with a model its sender named; a scheduled model change leaves it alone. */ + explicitModelSelection: Schema.optional(Schema.Boolean), steerWhenReadyRunId: Schema.optional(RunId), requestedAt: Schema.DateTimeUtc, startedAt: Schema.NullOr(Schema.DateTimeUtc), diff --git a/packages/contracts/src/orchestratorMcp.ts b/packages/contracts/src/orchestratorMcp.ts index ab2687ae13031..f05c7ccb0065a 100644 --- a/packages/contracts/src/orchestratorMcp.ts +++ b/packages/contracts/src/orchestratorMcp.ts @@ -566,7 +566,7 @@ export type OrchestratorMcpThreadResult = typeof OrchestratorMcpThreadResult.Typ const RespectSnooze = Schema.optional( Schema.Boolean.annotate({ - description: "Default true: keep a snooze; a send waits until it ends. false wakes the thread.", + description: "Default true: a snoozed thread waits. false wakes it.", }), ); @@ -581,7 +581,7 @@ export const OrchestratorMcpThreadPostInput = Schema.Struct({ threadId: ThreadId, message: OrchestratorMcpPrompt, clientRequestId: Schema.optional(OrchestratorMcpClientRequestId), - respectSnooze: RespectSnooze, + respectSnooze: Schema.optional(Schema.Boolean), }); export type OrchestratorMcpThreadPostInput = typeof OrchestratorMcpThreadPostInput.Type; export const OrchestratorMcpThreadPostResult = Schema.Struct({ From cfe85b0224fc82157169161f77271592f05f3f67 Mon Sep 17 00:00:00 2001 From: Chris OHearn Date: Thu, 12 Nov 2026 21:40:18 -0700 Subject: [PATCH 13/14] chore(server): re-measure the agent context budget on the integration tip Co-Authored-By: Claude Opus 5.5 --- apps/server/src/provider/agentContextBudget.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/server/src/provider/agentContextBudget.json b/apps/server/src/provider/agentContextBudget.json index b955017c80e7a..687496b338583 100644 --- a/apps/server/src/provider/agentContextBudget.json +++ b/apps/server/src/provider/agentContextBudget.json @@ -1,5 +1,5 @@ { "claudeSystemAppendBytes": 5597, "codexAdditionalContextBytes": 7327, - "mcpToolListJsonBytes": 56696 + "mcpToolListJsonBytes": 57528 } From b564470f383fe2e3841183d76531222832ad1ced Mon Sep 17 00:00:00 2001 From: Chris OHearn Date: Thu, 12 Nov 2026 22:05:11 -0700 Subject: [PATCH 14/14] fix(server): an unfreeze leaves a sleeping thread's snooze-held turns held Resuming a queue, an unfreeze included, released every queued run. That included turns an agent's send held for a snooze that still holds the thread. queue.resume now leaves those while the thread is snoozed. The snooze sweep only resumes awake threads, so it still releases them. The sweep also skips frozen threads, whose queue only an unfreeze resumes. Co-Authored-By: Claude Opus 5.5 --- .../src/orchestration-v2/Orchestrator.ts | 18 ++++- .../src/orchestration-v2/ThreadFreeze.test.ts | 77 +++++++++++++++++++ 2 files changed, 94 insertions(+), 1 deletion(-) diff --git a/apps/server/src/orchestration-v2/Orchestrator.ts b/apps/server/src/orchestration-v2/Orchestrator.ts index 80bde7cae31d2..8908049aaf3e0 100644 --- a/apps/server/src/orchestration-v2/Orchestrator.ts +++ b/apps/server/src/orchestration-v2/Orchestrator.ts @@ -15613,7 +15613,23 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio }); } const now = yield* DateTime.now; - const queued = projection.runs.filter((run) => run.status === "queued"); + // Resuming (an unfreeze included) leaves a snooze's held turns while the thread sleeps. + const snoozeHolds = + projection.runs.some((run) => run.status === "queued" && run.snoozeDeferred === true) && + isSnoozed( + (yield* projectionStore + .getThreadShell(command.threadId) + .pipe(Effect.orElseSucceed(() => null))) ?? { + ...projection.thread, + status: "idle", + latestRunCompletedAt: null, + pendingRuntimeRequest: null, + }, + DateTime.toEpochMillis(now), + ); + const queued = projection.runs.filter( + (run) => run.status === "queued" && !(snoozeHolds && run.snoozeDeferred === true), + ); for (const run of queued) { yield* emit( events, diff --git a/apps/server/src/orchestration-v2/ThreadFreeze.test.ts b/apps/server/src/orchestration-v2/ThreadFreeze.test.ts index 76bd773a930fa..00e3b9c21bd55 100644 --- a/apps/server/src/orchestration-v2/ThreadFreeze.test.ts +++ b/apps/server/src/orchestration-v2/ThreadFreeze.test.ts @@ -18,6 +18,7 @@ import { CodexProviderCapabilitiesV2 } from "./Adapters/CodexAdapterV2.ts"; import * as CommandReceiptStore from "./CommandReceiptStore.ts"; import { CommandActor } from "./CommandActor.ts"; import { ThreadFreezeGate } from "./ThreadFreeze.ts"; +import * as SnoozeDeferredDelivery from "./SnoozeDeferredDelivery.ts"; import * as Orchestrator from "./Orchestrator.ts"; import * as EffectOutbox from "./EffectOutbox.ts"; import * as ProjectionStore from "./ProjectionStore.ts"; @@ -341,3 +342,79 @@ it.effect( assert.notInclude(started.runs[0], "queued"); }).pipe(Effect.provide(layerTest)), ); + +it.effect("a freeze and a snooze each keep their own holds", () => + Effect.gen(function* () { + const orchestrator = yield* Orchestrator.OrchestratorV2; + const id = threadId("snoozed"); + yield* create(id); + yield* send(id, "first"); + yield* freeze(id); + yield* orchestrator.dispatch({ + type: "thread.snooze", + commandId: CommandId.make(`snooze:${id}`), + threadId: id, + snoozedUntil: "2099-01-01T00:00:00.000Z", + }); + yield* orchestrator.dispatch({ + type: "message.dispatch", + commandId: CommandId.make(`send:${id}:agent`), + threadId: id, + messageId: MessageId.make(`message:${id}:agent`), + text: "agent", + attachments: [], + dispatchMode: { type: "start_immediately" }, + respectSnooze: true, + createdBy: "agent", + creationSource: "mcp", + }); + const heldRun = () => + state(id).pipe( + Effect.map(({ projection }) => + projection.runs.find((run) => run.userMessageId === `message:${id}:agent`), + ), + ); + assert.include(yield* heldRun(), { status: "queued", queueHeld: true, snoozeDeferred: true }); + // The snooze sweep leaves a frozen thread to its unfreeze. + assert.deepEqual( + (yield* SnoozeDeferredDelivery.readSnoozeDeferredThreads()).filter( + (row) => row.threadId === id, + ), + [], + ); + + // Unfreezing resumes the queue, but the thread still sleeps: the snooze's hold stays. + yield* orchestrator + .dispatch({ + type: "queue.resume", + commandId: CommandId.make(`unfreeze:${id}`), + threadId: id, + }) + .pipe( + Effect.provideService(ThreadFreezeGate, { + op: "unfreeze", + by: { kind: "agent", label: "Coordinator" }, + at: "2026-11-13T01:00:00.000Z", + freshContext: false, + }), + ); + assert.equal((yield* state(id)).frozen, null); + assert.include(yield* heldRun(), { status: "queued", queueHeld: true, snoozeDeferred: true }); + + // Awake, the sweep's resume releases it. + yield* orchestrator.dispatch({ + type: "thread.unsnooze", + commandId: CommandId.make(`unsnooze:${id}`), + threadId: id, + reason: "user", + }); + yield* orchestrator.dispatch({ + type: "queue.resume", + commandId: CommandId.make(`snooze-release:${id}`), + threadId: id, + }); + const released = yield* heldRun(); + assert.notEqual(released?.queueHeld, true); + assert.isUndefined(released?.snoozeDeferred); + }).pipe(Effect.provide(layerTest)), +);