diff --git a/apps/server/src/mcp/OrchestratorMcpService.test.ts b/apps/server/src/mcp/OrchestratorMcpService.test.ts index db2e6ad290e7b..893992f17b604 100644 --- a/apps/server/src/mcp/OrchestratorMcpService.test.ts +++ b/apps/server/src/mcp/OrchestratorMcpService.test.ts @@ -1986,8 +1986,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)))); }), @@ -3982,6 +3996,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, }), @@ -4002,7 +4017,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); @@ -4161,6 +4180,125 @@ 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, { + // 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(() => { + 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); + 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", () => @@ -4277,8 +4415,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}`); } @@ -4289,8 +4427,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"); @@ -4301,7 +4439,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 8c1efaba86c06..4bd094eed8b2e 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"; @@ -140,6 +140,9 @@ import { taskPrompt, } from "./delegatedTaskModes.ts"; 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"; @@ -411,7 +414,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 { @@ -1280,19 +1283,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)); @@ -1310,11 +1308,40 @@ 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; + // 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) { + 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))); @@ -1361,6 +1388,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) { @@ -1372,7 +1403,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( @@ -1412,13 +1443,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( @@ -2514,7 +2545,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 @@ -2563,7 +2594,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 @@ -3135,17 +3169,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)); @@ -3226,8 +3257,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; @@ -3351,10 +3386,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 }), @@ -3374,6 +3411,7 @@ const make = Effect.gen(function* () { threadId: input.threadId, link: threadLinkFor(scope, input.threadId, target.thread.title), messageId, + ...(yield* snoozeOutcome(input.threadId, target.thread.snoozedUntil, "posted")), }; }), sendToThread: Effect.fn("OrchestratorMcpService.sendToThread")(function* (scope, input) { @@ -3471,6 +3509,7 @@ const make = Effect.gen(function* () { attachments: [], mode, ...(input.freshContext || input.coordinatorRollover ? { freshContext: true } : {}), + ...((input.respectSnooze ?? true) ? { respectSnooze: true } : {}), createdBy: "agent", creationSource: "mcp", }) @@ -3490,8 +3529,18 @@ 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 }), + ...(yield* snoozeOutcome( + input.threadId, + target.thread.snoozedUntil, + 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/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/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/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/mcp/threadReference.test.ts b/apps/server/src/mcp/threadReference.test.ts new file mode 100644 index 0000000000000..992ff13cca70e --- /dev/null +++ b/apps/server/src/mcp/threadReference.test.ts @@ -0,0 +1,90 @@ +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"); +// 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 === deletedReplaced + ? { ...liveThreadShell(threadId), deletedAt: DateTime.makeUnsafe(0) } + : [mcpThread, launchThread, nativeThread, liveReplaced].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.`); + 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"); + 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..7fb0ee4f747c0 --- /dev/null +++ b/apps/server/src/mcp/threadReference.ts @@ -0,0 +1,119 @@ +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 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* ( + 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); + } + 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 }; + 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({ + 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.`, + }); +}); 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/mcp/toolkits/core.test.ts b/apps/server/src/mcp/toolkits/core.test.ts index 7b16c22858402..9438795a5d0d0 100644 --- a/apps/server/src/mcp/toolkits/core.test.ts +++ b/apps/server/src/mcp/toolkits/core.test.ts @@ -1310,6 +1310,100 @@ it.effect("a read-only client reads threads and is refused every write before it const dispatched: Array = []; let acknowledgeOnly = false; +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, 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( + Effect.provide( + layerThreadToolkit.pipe( + Layer.provideMerge(McpHttpServer.layerInProcessMcpServer), + Layer.provide(NodeCrypto.layer), + Layer.provide( + Layer.mock(ThreadManagement.ThreadManagementService)({ + getThreadShell: () => Effect.succeed(busyThread as never), + acknowledgeOnly: () => Effect.succeed(false), + getProjectThreadRecords: () => + Effect.succeed({ + thread: { + ...busyThread, + ...(commands.length === 0 ? {} : { scheduledModelSelection: scheduled }), + }, + } as never), + dispatch: (command) => + Effect.sync(() => { + commands.push(command); + return { sequence: 7 } as never; + }), + }), + ), + Layer.provide( + Layer.mock(ProviderRegistry.ProviderRegistry)({ + getProviders: Effect.succeed([ + { instanceId: "codex", models: [{ slug: "gpt-5" }, { slug: "gpt-6" }] } 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/project/handlers.test.ts b/apps/server/src/mcp/toolkits/project/handlers.test.ts index 69de65f6387d8..6a5c002e8e112 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/mcp/toolkits/thread/handlers.ts b/apps/server/src/mcp/toolkits/thread/handlers.ts index 2f2bb7f55a3ca..16870d2523619 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"; @@ -258,6 +263,7 @@ export const layer = McpToolAccess.toLayer(ThreadToolkit, { (input) => input.modelSelection === undefined && input.runtimeMode === undefined && + input.applyAt === undefined && input.acknowledgeOnly === undefined, McpToolAccess.reads((input) => Effect.gen(function* () { @@ -268,6 +274,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, acknowledgeOnly: yield* threads @@ -292,6 +306,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 @@ -314,10 +335,53 @@ 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; + // 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, 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 ba79df8fe1e0d..9ee510469e4aa 100644 --- a/apps/server/src/mcp/toolkits/thread/tools.ts +++ b/apps/server/src/mcp/toolkits/thread/tools.ts @@ -204,6 +204,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, // Optional: a linked environment on another build does not report it. @@ -217,10 +220,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 from the next turn, queued messages included.", + }), + ), runtimeMode: Schema.optional(RuntimeMode), acknowledgeOnly: Schema.optional(Schema.Boolean), }), - 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 fc42b54e27ed9..8908049aaf3e0 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, @@ -200,6 +201,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, @@ -918,6 +920,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 { @@ -961,12 +969,58 @@ 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, + * 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 && + run.explicitModelSelection !== true + ); +} + +/** 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" && + queuedBeforeScheduledSelection(projection, run), + ); + 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( @@ -974,7 +1028,7 @@ function queuedRunModelSelection( run: OrchestrationV2Run, ): ModelSelection { return queuedRunFollowsThread(projection, run) - ? projection.thread.modelSelection + ? nextTurnModelSelection(projection.thread) : run.modelSelection; } @@ -982,11 +1036,14 @@ function queuedRunModelSelection( function queueTailModelSelection( projection: Pick, ): ModelSelection { - return ( - queuedRunsInDeliveryOrder(projection).findLast( - (run) => !queuedRunFollowsThread(projection, run), - )?.modelSelection ?? projection.thread.modelSelection + 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); } /** @@ -2495,6 +2552,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 && @@ -2963,18 +3021,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, @@ -3194,7 +3253,24 @@ 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; 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 && snoozeHolds), + ); if (released.length === 0) return; yield* writeSystemEvents( released.map((run) => ({ @@ -3203,7 +3279,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 }, })), ); }); @@ -4404,6 +4480,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: [], @@ -4415,7 +4510,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio }); } } - return plan; + return { ...plan, scheduled: undefined }; }) : null; @@ -4540,7 +4635,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, @@ -5019,10 +5118,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, }; } @@ -5089,9 +5196,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; } @@ -5142,6 +5251,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 ) { @@ -6935,7 +7045,33 @@ 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, + // 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 && + !( + limitRecovery?.snooze === true && + DateTime.toEpochMillis(snoozeHeldUntil) === Date.parse(limitRecovery.resetAt) + ) && + (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 = { ...projection.thread, @@ -7471,6 +7607,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, ); @@ -7487,10 +7627,12 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio projection.thread.worktreePath === null ? latestRun : undefined; - // A send to a frozen idle thread queues, held, behind the last run it executed, or with no - // provider thread yet when it never ran. + // A send to a frozen idle thread, or one held for a snooze, queues held behind the last run + // it executed (a frozen thread with no run yet gets no provider thread). const queueBehindRun = - activeRun ?? worktreeMissingRun ?? (frozenHold ? (latestRun ?? undefined) : undefined); + activeRun ?? + worktreeMissingRun ?? + (frozenHold || respectsSnooze ? (latestRun ?? undefined) : undefined); const pendingMergeBackTransfers = pendingMergeBackTransfersForThread(projection); const startsOrQueuesRun = dispatchMode.type === "defer_start" || @@ -7535,7 +7677,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) { @@ -7695,7 +7837,10 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio activeAttemptId: attemptId, status: "queued", ...(steerWhenReadyRunId === undefined ? {} : { steerWhenReadyRunId }), + ...(respectsSnooze ? { snoozeDeferred: true } : {}), + ...(command.modelSelection === undefined ? {} : { explicitModelSelection: true }), ...(worktreeMissingRun !== undefined || + respectsSnooze || frozenHold || (heldRunsToRelease.length === 0 && queueIsHeld && @@ -7915,23 +8060,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, @@ -12376,7 +12523,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, @@ -15460,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, @@ -15471,7 +15640,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 && frozen == null) { 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..f833daa9fa3a9 --- /dev/null +++ b/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.test.ts @@ -0,0 +1,122 @@ +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"; +import * as Ref from "effect/Ref"; +import * as Stream from "effect/Stream"; +import * as TestClock from "effect/testing/TestClock"; + +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 { due, wakeAtMs } = SnoozeDeferredDelivery.snoozeDeferredReleases( + [ + 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"), + ], + startMs, + ); + 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 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"), + 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( + Scheduler.layer, + Layer.succeed(SnoozeDeferredDelivery.SnoozeDeferredStore, { + read: Ref.get(rows), + }), + Layer.mock(ThreadManagement.ThreadManagementService)({ + // "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 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: [] })), + ), + ); + }, + }), + Layer.mock(Orchestrator.OrchestratorV2)({ + streamDomainEvents: Stream.fromQueue(events), + }), + ), + ), + ); + 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"); + 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(attempts))["threadId"], "woken"); + + yield* TestClock.adjust("10 minutes"); + 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 new file mode 100644 index 0000000000000..1e2324b7096c7 --- /dev/null +++ b/apps/server/src/orchestration-v2/SnoozeDeferredDelivery.ts @@ -0,0 +1,153 @@ +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"; +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 { isSnoozed } from "./SnoozeState.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 + -- A frozen thread refuses resumes; unfreezing it resumes the queue. + AND json_extract(t.payload_json, '$.frozen') 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, + })); +}); + +export class SnoozeDeferredStore extends Context.Service< + SnoozeDeferredStore, + { readonly read: Effect.Effect> } +>()("t3/orchestration-v2/SnoozeDeferredDelivery/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(() => []), + ), + }); + }), +); + +// 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 === "runtime-request.updated"; + +const makeSweep = Effect.gen(function* () { + const store = yield* SnoozeDeferredStore; + 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 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", + // 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( + 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 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/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/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)), +); diff --git a/apps/server/src/orchestration-v2/ThreadManagementService.ts b/apps/server/src/orchestration-v2/ThreadManagementService.ts index 3c27cba119aa7..259210887eab9 100644 --- a/apps/server/src/orchestration-v2/ThreadManagementService.ts +++ b/apps/server/src/orchestration-v2/ThreadManagementService.ts @@ -165,6 +165,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; } @@ -911,6 +913,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/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 cafdf068dc8e6..7014ee3e2a648 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,198 @@ 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); + 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(), []); + }), + ); + + 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 pickedSelection = { ...modelSelection, model: "gpt-5.3" }; + const send = (key: string) => + orchestrator.dispatch({ + type: "message.dispatch", + commandId: CommandId.make(`${threadId}:${key}`), + threadId, + 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", + }); + // "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`), + 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, picked, 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); + + 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); + }), + ); + 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/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/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 }> = []; diff --git a/apps/server/src/provider/agentContextBudget.json b/apps/server/src/provider/agentContextBudget.json index b373520153d4b..a6c8616b1e88e 100644 --- a/apps/server/src/provider/agentContextBudget.json +++ b/apps/server/src/provider/agentContextBudget.json @@ -1,5 +1,5 @@ { "claudeSystemAppendBytes": 5597, "codexAdditionalContextBytes": 7327, - "mcpToolListJsonBytes": 58061 + "mcpToolListJsonBytes": 58331 } 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..7579f51a9ec49 --- /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, 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. + +## 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. diff --git a/docs/orchestration-v2/orchestrator-mcp-server.md b/docs/orchestration-v2/orchestrator-mcp-server.md index f3ef6ff6ddaf9..05b8af676d278 100644 --- a/docs/orchestration-v2/orchestrator-mcp-server.md +++ b/docs/orchestration-v2/orchestrator-mcp-server.md @@ -459,6 +459,15 @@ 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 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. + 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. diff --git a/docs/user/outside-agents.md b/docs/user/outside-agents.md index 9571aefc37569..efc0058967358 100644 --- a/docs/user/outside-agents.md +++ b/docs/user/outside-agents.md @@ -99,6 +99,21 @@ 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"`. + 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. +- 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 @@ -136,7 +151,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 diff --git a/packages/contracts/src/orchestrationV2.ts b/packages/contracts/src/orchestrationV2.ts index 7e386baf1d6d0..aa3506f848d81 100644 --- a/packages/contracts/src/orchestrationV2.ts +++ b/packages/contracts/src/orchestrationV2.ts @@ -457,6 +457,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, @@ -464,6 +476,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), @@ -776,6 +789,10 @@ 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), + /** 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), @@ -3342,6 +3359,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"), @@ -3365,6 +3384,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 1c7bcdbc09328..9ff8144776c82 100644 --- a/packages/contracts/src/orchestratorMcp.ts +++ b/packages/contracts/src/orchestratorMcp.ts @@ -567,17 +567,31 @@ export const OrchestratorMcpThreadResult = Schema.Struct({ }); export type OrchestratorMcpThreadResult = typeof OrchestratorMcpThreadResult.Type; +const RespectSnooze = Schema.optional( + Schema.Boolean.annotate({ + description: "Default true: a snoozed thread waits. false wakes it.", + }), +); + +/** 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: Schema.optional(Schema.Boolean), }); 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; @@ -587,6 +601,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: @@ -603,6 +618,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, @@ -616,6 +641,8 @@ export const OrchestratorMcpThreadSendResult = Schema.Struct({ held: Schema.optional(Schema.Literal(true)), /** Set when a freeze holds the send. */ frozen: Schema.optional(Schema.Literal(true)), + queue: Schema.optional(OrchestratorMcpQueueStanding), + ...SnoozeNotice, }); export type OrchestratorMcpThreadSendResult = typeof OrchestratorMcpThreadSendResult.Type;