diff --git a/apps/server/src/mcp/OrchestratorMcpService.ts b/apps/server/src/mcp/OrchestratorMcpService.ts index 8ff41b8650f6d..a3d91a84bb472 100644 --- a/apps/server/src/mcp/OrchestratorMcpService.ts +++ b/apps/server/src/mcp/OrchestratorMcpService.ts @@ -1047,6 +1047,7 @@ function threadRun( requestedAt: DateTime.formatIso(run.requestedAt), startedAt: run.startedAt === null ? null : DateTime.formatIso(run.startedAt), completedAt: run.completedAt === null ? null : DateTime.formatIso(run.completedAt), + ...(run.delegationNudge === undefined ? {} : { delegationNudge: run.delegationNudge }), }; } diff --git a/apps/server/src/mcp/ThreadMetadataMcpService.ts b/apps/server/src/mcp/ThreadMetadataMcpService.ts index 19667572dd20f..3429348ba3f31 100644 --- a/apps/server/src/mcp/ThreadMetadataMcpService.ts +++ b/apps/server/src/mcp/ThreadMetadataMcpService.ts @@ -67,9 +67,10 @@ function metadataCommand(input: { readonly commandId: CommandId; readonly threadId: ThreadId; readonly update: ThreadMetadataMcpUpdateInput; + readonly actorThreadId: ThreadId | undefined; }): Extract< OrchestrationV2Command, - { readonly type: "thread.metadata.update" | "thread.standing.set" } + { readonly type: "thread.metadata.update" | "thread.standing.set" | "thread.delegation-nudge.set" } > { switch (input.update.action) { case "set_standing": @@ -79,6 +80,20 @@ function metadataCommand(input: { threadId: input.threadId, standing: input.update.standing ?? null, }; + case "set_delegation_nudge": + return { + type: "thread.delegation-nudge.set", + commandId: input.commandId, + threadId: input.threadId, + enabled: input.update.delegationNudge?.enabled ?? false, + ...(input.update.delegationNudge?.thresholds === undefined + ? {} + : { thresholds: input.update.delegationNudge.thresholds }), + changedBy: + input.actorThreadId === undefined + ? { kind: "mcp_client" } + : { kind: "agent", threadId: input.actorThreadId }, + }; case "route": return { type: "thread.metadata.update", @@ -123,12 +138,15 @@ function resultFromThread(input: { readonly sequence: number; readonly thread: Pick< OrchestrationV2AppThread, - "id" | "title" | "titleRegeneration" | "linkedPullRequest" | "updatedAt" | "inbox" | "standing" + "id" | "title" | "titleRegeneration" | "linkedPullRequest" | "updatedAt" | "inbox" | "standing" | "delegationNudge" >; }): ThreadMetadataMcpUpdateResult { return { ...(input.thread.inbox === undefined ? {} : { inbox: input.thread.inbox }), ...(input.thread.standing === undefined ? {} : { standing: input.thread.standing }), + ...(input.thread.delegationNudge === undefined + ? {} + : { delegationNudge: input.thread.delegationNudge }), threadId: input.thread.id, action: input.action, commandId: input.commandId, @@ -196,6 +214,15 @@ const make = Effect.gen(function* () { input.inboxRouting, ); if (inboxError !== null) return yield* failure("invalid_request", inboxError); + if ( + input.action === "set_delegation_nudge" && + scope.thread?.threadId === threadId + ) { + return yield* failure( + "invalid_request", + "A thread cannot change its own delegation nudge. Ask from another thread or the client.", + ); + } const requestKey = input.clientRequestId === undefined ? yield* random.uuidV4() : input.clientRequestId; const updateCommandId = commandId({ @@ -210,6 +237,7 @@ const make = Effect.gen(function* () { commandId: updateCommandId, threadId, update: input, + actorThreadId: scope.thread?.threadId, }), ) .pipe( @@ -223,12 +251,14 @@ const make = Effect.gen(function* () { const metadataEvent = dispatched.storedEvents.find( (stored) => stored.event.type === "thread.metadata-updated" || - stored.event.type === "thread.standing-updated", + stored.event.type === "thread.standing-updated" || + stored.event.type === "thread.delegation-nudge-updated", ); // Retries may find stored events compacted away; answer from the projection. const thread = metadataEvent?.event.type === "thread.metadata-updated" || - metadataEvent?.event.type === "thread.standing-updated" + metadataEvent?.event.type === "thread.standing-updated" || + metadataEvent?.event.type === "thread.delegation-nudge-updated" ? metadataEvent.event.payload : yield* threadManagement .getThreadShell(threadId) diff --git a/apps/server/src/mcp/toolkits/orchestrator/tools.ts b/apps/server/src/mcp/toolkits/orchestrator/tools.ts index ffcb93de70244..3e19c92f62061 100644 --- a/apps/server/src/mcp/toolkits/orchestrator/tools.ts +++ b/apps/server/src/mcp/toolkits/orchestrator/tools.ts @@ -268,7 +268,7 @@ const ThreadReadTool = Tool.make("t3_thread_read", { const ThreadUpdateTool = Tool.make("t3_thread_update", { description: - "Update a thread; omit `threadId` for this one. When a founder must decide, review or approve, use `action:'request_decision'` with `decision`: the thread shows in their inbox until they reply there, `resolve_decision`, or settle. `action:'route'` refiles it with `inboxRouting`; a founder's or the shared inbox needs `inboxRouting.reason`. `rename` takes `title`; `regenerate_title`. `set_standing` takes `standing` (bot persona, or null for an ordinary thread). Workspace and branch cannot change here.", + "Update a thread; omit `threadId` for this one. When a founder must decide, review or approve, use `action:'request_decision'` with `decision`: the thread shows in their inbox until they reply there, `resolve_decision`, or settle. `action:'route'` refiles it with `inboxRouting`; a founder's or the shared inbox needs `inboxRouting.reason`. `rename` takes `title`; `regenerate_title`. `set_standing` takes `standing` (bot persona, or null for an ordinary thread). `set_delegation_nudge` takes `delegationNudge` ({enabled, thresholds?}, default [5, 10]); a thread cannot change its own. Workspace and branch cannot change here.", // Keeps the input's action/field check, which rebuilding the struct would drop. parameters: ThreadMetadataMcpUpdateInput.mapFields( Struct.assign({ environmentId: OrchestratorMcpEnvironmentTarget }), diff --git a/apps/server/src/orchestration-v2/DelegationNudge.integration.test.ts b/apps/server/src/orchestration-v2/DelegationNudge.integration.test.ts new file mode 100644 index 0000000000000..87507bcf5e43f --- /dev/null +++ b/apps/server/src/orchestration-v2/DelegationNudge.integration.test.ts @@ -0,0 +1,406 @@ +import { assert, it } from "@effect/vitest"; +import { + CommandId, + MessageId, + ProjectId, + ProviderDriverKind, + ProviderInstanceId, + ProviderThreadId, + ProviderTurnId, + ThreadId, + TurnItemId, + type NodeId, + type OrchestrationV2DomainEvent, + type OrchestrationV2ProviderTurn, + type OrchestrationV2TurnItem, +} from "@t3tools/contracts"; +import * as DateTime from "effect/DateTime"; +import * as Effect from "effect/Effect"; +import * as Fiber from "effect/Fiber"; +import * as Queue from "effect/Queue"; +import * as Stream from "effect/Stream"; + +import { CodexProviderCapabilitiesV2 } from "./Adapters/CodexAdapterV2.ts"; +import * as EffectWorker from "./EffectWorker.ts"; +import * as Orchestrator from "./Orchestrator.ts"; +import * as ProviderAdapterRegistry from "./ProviderAdapterRegistry.ts"; +import * as ProviderReplayHarness from "./testkit/ProviderReplayHarness.ts"; +import * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter"; +import { checkpointWorkspace } from "@t3tools/provider-testing/replayWorkspace"; + +const driver = ProviderDriverKind.make("codex"); +const instanceId = ProviderInstanceId.make("codex"); +const modelSelection = { instanceId, model: "test-model" }; + +const harness = Effect.fn("delegationNudgeHarness")(function* ( + name: string, + turns: { + readonly supportsSteeringByInterruptRestart?: boolean; + readonly activeSteeringInterruptsTools?: boolean; + }, +) { + const cwd = yield* checkpointWorkspace(name); + const events = yield* Queue.unbounded(); + const started: string[] = []; + const steered: string[] = []; + const capabilities = { + ...CodexProviderCapabilitiesV2, + turns: { ...CodexProviderCapabilitiesV2.turns, ...turns }, + }; + const adapter: ProviderAdapter.ProviderAdapterV2["Service"] = { + instanceId, + driver, + getCapabilities: () => Effect.succeed(capabilities), + planSelectionTransition: () => Effect.succeed({ type: "apply_on_next_turn" }), + openSession: (input) => + Effect.gen(function* () { + const now = yield* DateTime.now; + return { + instanceId, + driver, + providerSessionId: input.providerSessionId, + providerSession: { + id: input.providerSessionId, + driver, + providerInstanceId: instanceId, + status: "ready", + cwd, + model: modelSelection.model, + capabilities, + createdAt: now, + updatedAt: now, + lastError: null, + }, + events: Stream.fromQueue(events), + ensureThread: ({ threadId }) => + Effect.succeed({ + id: ProviderThreadId.make(`provider-thread:${threadId}`), + driver, + providerInstanceId: instanceId, + providerSessionId: input.providerSessionId, + appThreadId: threadId, + ownerNodeId: null, + nativeThreadRef: { driver, nativeId: "native-thread", strength: "strong" }, + nativeConversationHeadRef: null, + status: "idle", + firstRunOrdinal: null, + lastRunOrdinal: null, + handoffIds: [], + forkedFrom: null, + createdAt: now, + updatedAt: now, + }), + resumeThread: ({ providerThread }) => Effect.succeed(providerThread), + startTurn: (turn) => + Effect.gen(function* () { + started.push(turn.message.text); + yield* Queue.offer(events, { + type: "provider_turn.updated", + driver, + providerTurn: { + id: ProviderTurnId.make(`provider-turn:${turn.attemptId}`), + providerThreadId: turn.providerThread.id, + nodeId: turn.rootNodeId, + runAttemptId: turn.attemptId, + nativeTurnRef: { driver, nativeId: `native:${turn.attemptId}`, strength: "strong" }, + ordinal: turn.providerTurnOrdinal, + status: "running", + startedAt: now, + completedAt: null, + }, + }); + }), + steerTurn: (turn) => Effect.sync(() => void steered.push(turn.message.text)), + interruptTurn: () => Effect.void, + respondToRuntimeRequest: () => Effect.void, + readThreadSnapshot: () => Effect.die("unused"), + rollbackThread: () => Effect.die("unused"), + forkThread: () => Effect.die("unused"), + }; + }), + }; + const layer = ProviderReplayHarness.layerWithRegistry( + { name }, + ProviderAdapterRegistry.layerSingle(adapter), + ); + const startFirstTurn = Effect.gen(function* () { + const orchestrator = yield* Orchestrator.OrchestratorV2; + const worker = yield* EffectWorker.OrchestrationEffectWorkerV2; + const threadId = ThreadId.make(`thread:${name}`); + yield* orchestrator.dispatch({ + type: "thread.create", + commandId: CommandId.make("create"), + threadId, + projectId: ProjectId.make(`project:${name}`), + title: "Delegation nudge", + modelSelection, + runtimeMode: "full-access", + interactionMode: "default", + branch: null, + worktreePath: cwd, + createdBy: "user", + creationSource: "web", + }); + yield* orchestrator.dispatch({ + type: "message.dispatch", + commandId: CommandId.make("first"), + threadId, + messageId: MessageId.make("message:first"), + text: "do the work", + attachments: [], + dispatchMode: { type: "start_immediately" }, + createdBy: "user", + creationSource: "web", + }); + const running = yield* watch( + orchestrator, + (event) => event.type === "provider-turn.updated" && event.payload.status === "running", + ); + yield* worker.drain(); + yield* Fiber.join(running); + return threadId; + }); + return { events, started, steered, layer, startFirstTurn }; +}); + +const watch = ( + orchestrator: Orchestrator.OrchestratorV2["Service"], + predicate: (event: OrchestrationV2DomainEvent) => boolean, +) => + orchestrator.streamDomainEvents.pipe( + Stream.filter(predicate), + Stream.take(1), + Stream.runDrain, + Effect.forkScoped, + ); + +const rootNodeId = (run: { readonly rootNodeId: NodeId | null }): NodeId => { + assert.notEqual(run.rootNodeId, null); + return run.rootNodeId!; +}; + +const tool = ( + threadId: ThreadId, + runId: NonNullable, + nodeId: NodeId, + providerThreadId: NonNullable, + providerTurnId: NonNullable, + id: string, + name: string, + now: DateTime.Utc, +) => + ({ + type: "turn_item.updated", + driver, + turnItem: { + id: TurnItemId.make(id), + threadId, + runId, + nodeId, + providerThreadId, + providerTurnId, + nativeItemRef: null, + parentItemId: null, + ordinal: 0, + status: "completed", + title: null, + startedAt: now, + completedAt: now, + updatedAt: now, + type: "dynamic_tool", + toolName: name, + input: {}, + }, + }) satisfies ProviderAdapter.ProviderAdapterV2Event; + +const completeTurn = ( + events: Queue.Queue, + turn: OrchestrationV2ProviderTurn, + runOrdinal: number, + now: DateTime.Utc, +) => + Effect.all( + [ + Queue.offer(events, { + type: "provider_turn.updated", + driver, + providerTurn: { ...turn, status: "completed", completedAt: now }, + }), + Queue.offer(events, { + type: "turn.terminal", + driver, + providerThreadId: turn.providerThreadId, + providerTurnId: turn.id, + runOrdinal, + status: "completed", + failure: null, + threadDisposition: "reusable", + }), + ], + { discard: true }, + ); + +it.effect("steers a capable provider at the first threshold and stays quiet after a delegation", () => + Effect.gen(function* () { + const { events, steered, layer, startFirstTurn } = yield* harness("nudge-steer", { + supportsSteeringByInterruptRestart: false, + }); + yield* Effect.gen(function* () { + const orchestrator = yield* Orchestrator.OrchestratorV2; + const worker = yield* EffectWorker.OrchestrationEffectWorkerV2; + const threadId = yield* startFirstTurn; + const projection = yield* orchestrator.getThreadProjection(threadId); + const run = projection.runs[0]!; + const turn = projection.providerTurns[0]!; + yield* orchestrator.dispatch({ + type: "thread.delegation-nudge.set", + commandId: CommandId.make("enable"), + threadId, + enabled: true, + }); + const now = yield* DateTime.now; + const offer = (id: string, name: string) => + Queue.offer( + events, + tool(threadId, run.id, rootNodeId(run), turn.providerThreadId, turn.id, id, name, now), + ); + const steeredEvent = yield* watch( + orchestrator, + (event) => event.type === "message.updated" && event.payload.text.includes("tool calls"), + ); + for (const index of [1, 2, 3, 4, 5]) yield* offer(`tool-${index}`, "Read"); + yield* Fiber.join(steeredEvent); + yield* worker.drain(); + assert.equal(steered.length, 1); + assert.match(steered[0]!, /5 tool calls/); + const delegated = yield* watch( + orchestrator, + (event) => + event.type === "run.delegation-nudge-recorded" && event.payload.stats.delegations === 1, + ); + yield* offer("tool-6", "mcp__t3-code__delegate_task"); + for (const index of [7, 8, 9, 10]) yield* offer(`tool-${index}`, "Read"); + yield* Fiber.join(delegated); + const stats = (yield* orchestrator.getThreadProjection(threadId)).runs[0]?.delegationNudge; + assert.equal(stats?.nudgesFired, 1); + assert.equal(stats?.delegations, 1); + assert.equal(stats?.deferredNote, undefined); + assert.equal(steered.length, 1); + }).pipe(Effect.provide(layer)); + }), +); + +it.effect("defers the note when steering would interrupt the running tool", () => + Effect.gen(function* () { + const { events, started, steered, layer, startFirstTurn } = yield* harness("nudge-defer", { + activeSteeringInterruptsTools: true, + }); + yield* Effect.gen(function* () { + const orchestrator = yield* Orchestrator.OrchestratorV2; + const worker = yield* EffectWorker.OrchestrationEffectWorkerV2; + const threadId = yield* startFirstTurn; + const projection = yield* orchestrator.getThreadProjection(threadId); + const run = projection.runs[0]!; + const turn = projection.providerTurns[0]!; + yield* orchestrator.dispatch({ + type: "thread.delegation-nudge.set", + commandId: CommandId.make("enable"), + threadId, + enabled: true, + thresholds: [1], + }); + const now = yield* DateTime.now; + const recorded = yield* watch( + orchestrator, + (event) => event.type === "run.delegation-nudge-recorded", + ); + yield* Queue.offer( + events, + tool(threadId, run.id, rootNodeId(run), turn.providerThreadId, turn.id, "tool-1", "Bash", now), + ); + yield* Fiber.join(recorded); + const note = (yield* orchestrator.getThreadProjection(threadId)).runs[0]?.delegationNudge; + assert.equal(steered.length, 0); + assert.match(note?.deferredNote ?? "", /1 tool call/); + yield* orchestrator.dispatch({ + type: "message.dispatch", + commandId: CommandId.make("second"), + threadId, + messageId: MessageId.make("message:second"), + text: "continue", + attachments: [], + dispatchMode: { type: "queue_after_active" }, + createdBy: "user", + creationSource: "web", + }); + const next = yield* watch( + orchestrator, + (event) => event.type === "provider-turn.updated" && event.payload.status === "running", + ); + yield* completeTurn(events, turn, run.ordinal, now); + yield* worker.drain(); + yield* orchestrator.resumeQueuedRuns; + yield* worker.drain(); + yield* Fiber.join(next); + assert.equal(steered.length, 0); + assert.equal(started.filter((text) => text.includes("delegate_task")).length, 1); + }).pipe(Effect.provide(layer)); + }), +); + +it.effect("does not count orchestrator tools and stays off by default", () => + Effect.gen(function* () { + const { events, steered, layer, startFirstTurn } = yield* harness("nudge-exclude", { + supportsSteeringByInterruptRestart: false, + }); + yield* Effect.gen(function* () { + const orchestrator = yield* Orchestrator.OrchestratorV2; + const threadId = yield* startFirstTurn; + const projection = yield* orchestrator.getThreadProjection(threadId); + const run = projection.runs[0]!; + const turn = projection.providerTurns[0]!; + const now = yield* DateTime.now; + const offer = (id: string, name: string) => + Queue.offer( + events, + tool(threadId, run.id, rootNodeId(run), turn.providerThreadId, turn.id, id, name, now), + ); + for (const [index, name] of [ + "mcp__t3-code__task_status", + "t3-code.orchestrator_capabilities", + "t3_thread_read", + ].entries()) { + yield* offer(`orch-${index}`, name); + } + const ingested = yield* watch( + orchestrator, + (event) => event.type === "turn-item.updated" && event.payload.id === "orch-2", + ); + yield* Fiber.join(ingested); + assert.equal( + (yield* orchestrator.getThreadProjection(threadId)).runs[0]?.delegationNudge, + undefined, + ); + assert.equal(steered.length, 0); + yield* orchestrator.dispatch({ + type: "thread.delegation-nudge.set", + commandId: CommandId.make("enable"), + threadId, + enabled: true, + thresholds: [1], + changedBy: { kind: "agent", threadId: ThreadId.make("thread:other") }, + }); + const setting = (yield* orchestrator.getThreadProjection(threadId)).thread.delegationNudge; + assert.equal(setting?.changedBy.kind, "agent"); + const recorded = yield* watch( + orchestrator, + (event) => event.type === "run.delegation-nudge-recorded", + ); + yield* offer("real", "Read"); + yield* Fiber.join(recorded); + const stats = (yield* orchestrator.getThreadProjection(threadId)).runs[0]?.delegationNudge; + assert.equal(stats?.countedToolCalls, 1); + assert.deepEqual(stats?.topTools, [{ name: "Read", count: 1 }]); + }).pipe(Effect.provide(layer)); + }), +); diff --git a/apps/server/src/orchestration-v2/DelegationNudge.ts b/apps/server/src/orchestration-v2/DelegationNudge.ts new file mode 100644 index 0000000000000..fd06f3e8dd785 --- /dev/null +++ b/apps/server/src/orchestration-v2/DelegationNudge.ts @@ -0,0 +1,84 @@ +import { + type OrchestrationV2TurnItem, + type RunDelegationNudgeStats, +} from "@t3tools/contracts"; +import { resolveT3McpToolId } from "@t3tools/shared/t3McpToolPresentation"; + +/** + * Orchestrator tools coordinate work instead of doing it, so they never count + * toward a reminder and a delegation among them resets the count. + */ +const ORCHESTRATOR_TOOLS: ReadonlySet = new Set([ + "delegate_task", + "task_status", + "task_cancel", + "create_threads", + "orchestrator_capabilities", + "schedule_task", + "run_scheduled_task_now", + "list_scheduled_tasks", + "delete_scheduled_task", +]); + +/** Handing work to another thread is the behavior the reminder asks for. */ +const DELEGATION_TOOLS: ReadonlySet = new Set([ + "delegate_task", + "create_threads", + "t3_thread_launch", +]); + +const TOP_TOOL_LIMIT = 5; + +export function countedToolName(item: OrchestrationV2TurnItem): string | null { + switch (item.type) { + case "dynamic_tool": { + const id = resolveT3McpToolId(item.toolName); + if (id !== null && (ORCHESTRATOR_TOOLS.has(id) || id.startsWith("t3_thread_"))) return null; + return item.toolName ?? "tool"; + } + case "command_execution": + return "command"; + case "file_change": + return "file_change"; + case "web_search": + return "web_search"; + case "file_search": + return "file_search"; + default: + return null; + } +} + +export function isDelegation(item: OrchestrationV2TurnItem): boolean { + if (item.type === "subagent") return true; + if (item.type !== "dynamic_tool") return false; + const id = resolveT3McpToolId(item.toolName); + return id !== null && DELEGATION_TOOLS.has(id); +} + +export function emptyDelegationNudgeStats(): RunDelegationNudgeStats { + return { countedToolCalls: 0, delegations: 0, nudgesFired: 0, topTools: [] }; +} + +export function recordCountedTool( + stats: RunDelegationNudgeStats, + name: string, +): RunDelegationNudgeStats { + const counts = new Map(stats.topTools.map((tool) => [tool.name, tool.count])); + counts.set(name, (counts.get(name) ?? 0) + 1); + return { + ...stats, + countedToolCalls: stats.countedToolCalls + 1, + topTools: [...counts] + .toSorted((left, right) => right[1] - left[1] || left[0].localeCompare(right[0])) + .slice(0, TOP_TOOL_LIMIT) + .map(([toolName, count]) => ({ name: toolName, count })), + }; +} + +export function delegationNudgeNote(threshold: number, firm: boolean): string { + const opening = firm + ? `You've now made ${threshold} tool calls on this request without delegating.` + : `You've made ${threshold} tool calls on this request without delegating.`; + return `${opening} If this is real work rather than a quick lookup to write a brief, hand it off with delegate_task.`; +} diff --git a/apps/server/src/orchestration-v2/DelegationNudgeReactor.ts b/apps/server/src/orchestration-v2/DelegationNudgeReactor.ts new file mode 100644 index 0000000000000..252d1ccec6f40 --- /dev/null +++ b/apps/server/src/orchestration-v2/DelegationNudgeReactor.ts @@ -0,0 +1,285 @@ +import { + CommandId, + MessageId, + type OrchestrationV2DomainEvent, + type OrchestrationV2Run, + type OrchestrationV2TurnItem, + type RunDelegationNudgeStats, + type RunId, + type ThreadId, +} from "@t3tools/contracts"; +import * as IdAllocator from "@t3tools/provider-core/server/IdAllocator"; +import { makeDrainableWorker } from "@t3tools/shared/DrainableWorker"; +import * as Cause from "effect/Cause"; +import * as DateTime from "effect/DateTime"; +import * as Effect from "effect/Effect"; +import * as SqlClient from "effect/sql/SqlClient"; +import * as Option from "effect/Option"; +import * as Queue from "effect/Queue"; +import * as Stream from "effect/Stream"; + +import { forkParked } from "../serverActivation.ts"; +import { + countedToolName, + delegationNudgeNote, + emptyDelegationNudgeStats, + isDelegation, + recordCountedTool, +} from "./DelegationNudge.ts"; +import * as EventSink from "./EventSink.ts"; +import * as Orchestrator from "./Orchestrator.ts"; +import * as ProjectionStore from "./ProjectionStore.ts"; + +const COUNTED_TYPES = [ + "dynamic_tool", + "command_execution", + "file_change", + "web_search", + "file_search", + "subagent", +] as const satisfies ReadonlyArray; + +interface RunWatch { + readonly seen: Set; + stats: RunDelegationNudgeStats; +} + +interface Reminder { + readonly threadId: ThreadId; + readonly runId: RunId; + readonly note: string; + readonly nudgesFired: number; +} + +/** + * Reminds an opted-in thread to delegate once its own run does the work. The + * stream starts at the latest event, so a restart rebuilds a live run's counts + * from the projection before counting anything new. + */ +export const make = Effect.gen(function* () { + const orchestrator = yield* Orchestrator.OrchestratorV2; + const eventSink = yield* EventSink.EventSinkV2; + const projections = yield* ProjectionStore.ProjectionStoreV2; + const sql = yield* SqlClient.SqlClient; + const ids = yield* IdAllocator.IdAllocatorV2; + const watches = new Map(); + // A plain queue, not a transactional one: the fiber that counted the tool is + // still inside the provider batch's transaction, and a transactional offer + // would resume its taker there. The steer then waits for that transaction to + // commit while the commit waits for the subscriber to return. + const reminders = yield* Queue.unbounded(); + + const watchFor = (run: OrchestrationV2Run): RunWatch => { + const existing = watches.get(run.id); + if (existing !== undefined) return existing; + const created = { seen: new Set(), stats: run.delegationNudge ?? emptyDelegationNudgeStats() }; + watches.set(run.id, created); + return created; + }; + + const record = Effect.fn("DelegationNudgeReactor.record")(function* ( + threadId: ThreadId, + run: OrchestrationV2Run, + stats: RunDelegationNudgeStats, + ) { + const now = yield* DateTime.now; + yield* eventSink.write({ + events: [ + { + id: yield* ids.allocate.event({ threadId }), + type: "run.delegation-nudge-recorded", + threadId, + runId: run.id, + providerInstanceId: run.providerInstanceId, + occurredAt: now, + payload: { runId: run.id, stats }, + }, + ], + }); + }); + + const deliver = Effect.fn("DelegationNudgeReactor.deliver")(function* ( + threadId: ThreadId, + run: OrchestrationV2Run, + stats: RunDelegationNudgeStats, + note: string, + ) { + const records = yield* projections.getThreadRecords(threadId, [ + "providerThreads", + "providerTurns", + "providerSessions", + ]); + const providerThread = records.providerThreads.find((row) => row.id === run.providerThreadId); + const turnRunning = records.providerTurns.some( + (turn) => turn.runAttemptId === run.activeAttemptId && turn.status === "running", + ); + // Capabilities are projected with the session, so a reminder can decide + // without the process-local session the steer effect loads later. + const turns = records.providerSessions.find( + (session) => session.id === providerThread?.providerSessionId, + )?.capabilities.turns; + // A steer that cancels the running tool, or one the policy would turn into an + // interrupt-and-restart, waits for the next run instead of stopping this one. + const canSteer = + turnRunning && + turns?.supportsActiveSteering === true && + turns.activeSteeringInterruptsTools !== true && + turns.supportsSteeringByInterruptRestart !== true; + if (canSteer) { + yield* orchestrator.dispatch({ + type: "message.dispatch", + commandId: CommandId.make(`server:delegation-nudge:${run.id}:${stats.nudgesFired}`), + threadId, + messageId: MessageId.make(`message:delegation-nudge:${run.id}:${stats.nudgesFired}`), + text: note, + notification: { + source: { kind: "system" }, + outcome: "updated", + summary: "Delegation reminder", + }, + attachments: [], + // Queued, like every other server notice: the planner refuses a + // notification that arrives already steering, then steers this one + // into the running turn when the provider can take it. + dispatchMode: { type: "queue_after_active" }, + createdBy: "agent", + creationSource: "server", + }); + // The note reached this turn, so the next run must not carry it again. + const { deferredNote: _delivered, ...delivered } = stats; + return { ...delivered, deferredNote: undefined }; + } + return { ...stats, deferredNote: note }; + }); + + const consider = Effect.fn("DelegationNudgeReactor.consider")(function* ( + threadId: ThreadId, + runId: RunId, + item: OrchestrationV2TurnItem | null, + ) { + const records = yield* projections.getThreadRecords(threadId, ["runs"]); + const setting = records.thread.delegationNudge; + if (setting?.enabled !== true) return; + const run = records.runs.find((candidate) => candidate.id === runId); + if (run === undefined || (run.status !== "running" && run.status !== "starting")) return; + const watch = watchFor(run); + if (watch.seen.size === 0 && run.delegationNudge === undefined) { + const prior = yield* projections.getThreadRecords(threadId, ["turnItems"], { + turnItemRunId: run.id, + turnItemTypes: [...COUNTED_TYPES], + }); + for (const existing of prior.turnItems) apply(watch, existing); + } + if (item !== null) apply(watch, item); + const threshold = setting.thresholds[watch.stats.nudgesFired]; + if ( + threshold === undefined || + watch.stats.delegations > 0 || + watch.stats.countedToolCalls < threshold + ) { + if (item !== null) yield* record(threadId, run, watch.stats); + return; + } + const note = delegationNudgeNote(threshold, watch.stats.nudgesFired > 0); + watch.stats = { ...watch.stats, nudgesFired: watch.stats.nudgesFired + 1, deferredNote: note }; + yield* record(threadId, run, watch.stats); + // Recorded before delivery so a crash keeps the note for the next run. + // Offered after the commit: offering now runs on the fiber ingesting the + // provider batch, and the steer it starts would wait for that batch. + yield* sql.afterCommit( + Queue.offer(reminders, { + threadId, + runId: run.id, + note, + nudgesFired: watch.stats.nudgesFired, + }).pipe(Effect.asVoid), + ); + }); + + const deliverReminder = Effect.fn("DelegationNudgeReactor.deliverReminder")(function* (input: { + readonly threadId: ThreadId; + readonly runId: RunId; + readonly note: string; + readonly nudgesFired: number; + }) { + const records = yield* projections.getThreadRecords(input.threadId, ["runs"]); + const run = records.runs.find((candidate) => candidate.id === input.runId); + const watch = run === undefined ? undefined : watches.get(run.id); + if (run === undefined || watch === undefined || watch.stats.nudgesFired !== input.nudgesFired) { + return; + } + const stats = yield* deliver(input.threadId, run, watch.stats, input.note); + if (stats.deferredNote === watch.stats.deferredNote) return; + watch.stats = stats; + yield* record(input.threadId, run, stats); + }); + + const worker = yield* makeDrainableWorker( + (input: { readonly threadId: ThreadId; readonly runId: RunId; readonly item: OrchestrationV2TurnItem | null }) => + consider(input.threadId, input.runId, input.item).pipe( + Effect.catchCauseIf( + (cause) => !Cause.hasInterruptsOnly(cause), + (cause) => + Effect.logWarning("delegation nudge check failed", { + threadId: input.threadId, + cause: Cause.pretty(cause), + }), + ), + ), + ); + + const processEvent = (event: OrchestrationV2DomainEvent) => { + if (event.type === "turn-item.updated" && event.runId !== undefined) { + const item = event.payload; + if (!COUNTED_TYPES.includes(item.type as (typeof COUNTED_TYPES)[number])) return Effect.void; + return worker.enqueue({ threadId: event.threadId, runId: event.runId, item }); + } + if (event.type === "run.updated" && event.payload.status === "running") { + return worker.enqueue({ threadId: event.threadId, runId: event.payload.id, item: null }); + } + if ( + event.type === "run.updated" && + !["running", "starting", "preparing", "queued", "waiting"].includes(event.payload.status) + ) { + watches.delete(event.payload.id); + } + return Effect.void; + }; + + // Forked at startup, so it never joins the provider batch's transaction the + // way a fiber forked from the counting subscriber would. + const deliverQueued = Queue.take(reminders).pipe( + Effect.andThen((reminder) => + deliverReminder(reminder).pipe( + Effect.catchCauseIf( + (cause) => !Cause.hasInterruptsOnly(cause), + (cause) => + Effect.logWarning("delegation nudge delivery failed", { + threadId: reminder.threadId, + cause: Cause.pretty(cause), + }), + ), + ), + ), + Effect.forever, + ); + + const start = Effect.fn("DelegationNudgeReactor.start")(function* () { + yield* forkParked(orchestrator.streamDomainEvents.pipe(Stream.runForEach(processEvent))); + yield* forkParked(deliverQueued); + }); + + return { start, drain: worker.drain }; +}); + +function apply(watch: RunWatch, item: OrchestrationV2TurnItem): void { + if (watch.seen.has(item.id)) return; + watch.seen.add(item.id); + if (isDelegation(item)) { + watch.stats = { ...watch.stats, delegations: watch.stats.delegations + 1 }; + return; + } + const name = countedToolName(item); + if (name !== null) watch.stats = recordCountedTool(watch.stats, name); +} + diff --git a/apps/server/src/orchestration-v2/Orchestrator.ts b/apps/server/src/orchestration-v2/Orchestrator.ts index ad3cce997779b..e0d2f95879cc9 100644 --- a/apps/server/src/orchestration-v2/Orchestrator.ts +++ b/apps/server/src/orchestration-v2/Orchestrator.ts @@ -80,6 +80,7 @@ import { TurnItemId, TrimmedNonEmptyString, managedRuntimeModeCeilingMessage, + DEFAULT_DELEGATION_NUDGE_THRESHOLDS, } from "@t3tools/contracts"; import * as KeyedLock from "@t3tools/shared/KeyedLock"; import { modelSelectionsEqual } from "@t3tools/shared/model"; @@ -642,6 +643,7 @@ function commandThreadId(command: OrchestrationV2ServerCommand): ThreadId { case "thread.active.reorder": case "thread.tag.set": case "thread.standing.set": + case "thread.delegation-nudge.set": case "thread.visit": case "thread.mark-unread": case "thread.metadata.update": @@ -4177,6 +4179,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio | "thread.pin.reorder" | "thread.tag.set" | "thread.standing.set" + | "thread.delegation-nudge.set" | "thread.active.reorder" | "thread.mark-unread" | "thread.metadata.update" @@ -4868,6 +4871,21 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio // Standing is identity, not activity: it never bumps updatedAt. return { ...thread, standing: command.standing }; } + case "thread.delegation-nudge.set": { + const thresholds = + command.thresholds ?? + thread.delegationNudge?.thresholds ?? + [...DEFAULT_DELEGATION_NUDGE_THRESHOLDS]; + return { + ...thread, + delegationNudge: { + enabled: command.enabled, + thresholds, + changedBy: command.changedBy ?? { kind: "user" }, + changedAt: DateTime.formatIso(now), + }, + }; + } case "thread.tag.set": { const current = thread.tags ?? []; return { @@ -5304,6 +5322,8 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio return "thread.tags-updated" as const; case "thread.standing.set": return "thread.standing-updated" as const; + case "thread.delegation-nudge.set": + return "thread.delegation-nudge-updated" as const; case "thread.mark-unread": return "thread.marked-unread" as const; case "thread.metadata.update": @@ -7344,11 +7364,12 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio dispatchMode = { type: "queue_after_active" }; } } - // Steer mailbox deliveries, delegated task questions, and command notices - // into an active goal under the thread lock: queued behind a long turn or a - // goal run, they are never seen. Never interrupt/restart a turn for one. + // Steer mailbox deliveries, delegated task questions, command notices, and + // delegation reminders into an active turn: queued behind a long turn they + // are never seen. Never interrupt/restart a turn for one. const noticeKind = command.notification?.source.kind; const commandNotice = noticeKind === "command" && command.creationSource === "server"; + const delegationReminder = noticeKind === "system" && command.creationSource === "server"; if ( !freshContext && (delegatedCompletion !== undefined @@ -7356,7 +7377,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio (id) => projection.subagents.find((task) => task.id === id)?.completionWake === "always", ) - : noticeKind === "delegated_task" || commandNotice) + : noticeKind === "delegated_task" || commandNotice || delegationReminder) ) { const active = projection.runs.find((run) => run.status === "running"); const providerThread = projection.providerThreads.find( @@ -15170,6 +15191,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio case "thread.active.reorder": case "thread.tag.set": case "thread.standing.set": + case "thread.delegation-nudge.set": case "thread.mark-unread": case "thread.pull-request.link": case "thread.pull-request.unlink": diff --git a/apps/server/src/orchestration-v2/ProjectionStore.ts b/apps/server/src/orchestration-v2/ProjectionStore.ts index 8402be3e50058..dc6c87c49e47c 100644 --- a/apps/server/src/orchestration-v2/ProjectionStore.ts +++ b/apps/server/src/orchestration-v2/ProjectionStore.ts @@ -891,6 +891,9 @@ function preserveRunRecordedFields( current.restartCancelledBackgroundWork !== undefined ? { restartCancelledBackgroundWork: current.restartCancelledBackgroundWork } : {}), + ...(next.delegationNudge === undefined && current.delegationNudge !== undefined + ? { delegationNudge: current.delegationNudge } + : {}), }; } @@ -974,6 +977,7 @@ export function applyToProjection( case "thread.active-reordered": case "thread.tags-updated": case "thread.standing-updated": + case "thread.delegation-nudge-updated": case "thread.pull-request-synced": return { ...base, @@ -1015,6 +1019,13 @@ export function applyToProjection( : run, ), }; + case "run.delegation-nudge-recorded": + return { + ...base, + runs: base.runs.map((run) => + run.id === event.payload.runId ? { ...run, delegationNudge: event.payload.stats } : run, + ), + }; case "run-attempt.created": case "run-attempt.updated": return withLocalVisibleTurnItems({ @@ -1258,6 +1269,9 @@ const encodeRunPayload = Schema.encodeEffect(Schema.fromJsonString(Orchestration const encodeRestartCancelledBackgroundWork = Schema.encodeEffect( Schema.fromJsonString(OrchestrationV2RunJsonSchema.fields.restartCancelledBackgroundWork), ); +const encodeRunDelegationNudgeStats = Schema.encodeEffect( + Schema.fromJsonString(OrchestrationV2RunJsonSchema.fields.delegationNudge), +); const encodeRunAttemptPayload = Schema.encodeEffect( Schema.fromJsonString(OrchestrationV2RunAttemptJsonSchema), ); @@ -1927,6 +1941,9 @@ export function threadShellFromProjection( pinOrderKey: projection.thread.pinOrderKey ?? null, ...(projection.thread.tags?.length ? { tags: projection.thread.tags } : {}), ...(projection.thread.standing ? { standing: projection.thread.standing } : {}), + ...(projection.thread.delegationNudge + ? { delegationNudge: projection.thread.delegationNudge } + : {}), lastVisitedAt: projection.thread.lastVisitedAt, opens: projection.thread.opens ?? null, titleRegeneration: projection.thread.titleRegeneration ?? null, @@ -2233,6 +2250,9 @@ function shellFromState(input: { pinOrderKey: input.state.thread.pinOrderKey ?? null, ...(input.state.thread.tags?.length ? { tags: input.state.thread.tags } : {}), ...(input.state.thread.standing ? { standing: input.state.thread.standing } : {}), + ...(input.state.thread.delegationNudge + ? { delegationNudge: input.state.thread.delegationNudge } + : {}), lastVisitedAt: input.state.thread.lastVisitedAt, opens: input.state.thread.opens ?? null, titleRegeneration: input.state.thread.titleRegeneration ?? null, @@ -2408,6 +2428,7 @@ export const layer: Layer.Layer = case "thread.active-reordered": case "thread.tags-updated": case "thread.standing-updated": + case "thread.delegation-nudge-updated": case "thread.visited": case "thread.marked-unread": case "thread.metadata-updated": @@ -2507,8 +2528,11 @@ export const layer: Layer.Layer = requested_at = excluded.requested_at, completed_at = excluded.completed_at, payload_json = ${keepRecordedRunField( - keepRecordedRunField(sql`excluded.payload_json`, "$.delegatedCompletion"), - "$.restartCancelledBackgroundWork", + keepRecordedRunField( + keepRecordedRunField(sql`excluded.payload_json`, "$.delegatedCompletion"), + "$.restartCancelledBackgroundWork", + ), + "$.delegationNudge", )} `; break; @@ -2529,6 +2553,15 @@ export const layer: Layer.Layer = `; break; } + case "run.delegation-nudge-recorded": { + const statsJson = yield* encodeRunDelegationNudgeStats(event.payload.stats); + yield* sql` + UPDATE orchestration_v2_projection_runs + SET payload_json = json_set(payload_json, '$.delegationNudge', json(${statsJson})) + WHERE run_id = ${event.payload.runId} AND thread_id = ${event.threadId} + `; + break; + } case "run-attempt.created": case "run-attempt.updated": { const payloadJson = yield* encodeRunAttemptPayload(event.payload); @@ -3229,6 +3262,7 @@ export const layer: Layer.Layer = event.type !== "thread.active-reordered" && event.type !== "thread.tags-updated" && event.type !== "thread.standing-updated" && + event.type !== "thread.delegation-nudge-updated" && event.type !== "thread.visited" && event.type !== "thread.visit-recorded" && event.type !== "thread.marked-unread" && diff --git a/apps/server/src/orchestration-v2/ProviderTurnStartService.ts b/apps/server/src/orchestration-v2/ProviderTurnStartService.ts index afbe74a9a1784..d2d92a40ce807 100644 --- a/apps/server/src/orchestration-v2/ProviderTurnStartService.ts +++ b/apps/server/src/orchestration-v2/ProviderTurnStartService.ts @@ -950,6 +950,11 @@ export const layer: Layer.Layer< restartCancelledWork.length === 0 ? "" : restartCancelledBackgroundWorkNote(restartCancelledWork); + const previousRun = projection.runs + .filter((source) => source.ordinal < run.ordinal) + .toSorted((left, right) => right.ordinal - left.ordinal)[0]; + const deferredNudge = previousRun?.delegationNudge?.deferredNote ?? ""; + const runNote = [restartNote, deferredNudge].filter((part) => part !== "").join("\n\n"); const tokenCap = yield* handoffTokenCapConfig.pipe( Effect.orElseSucceed(() => DEFAULT_HANDOFF_TOKEN_CAP), ); @@ -1095,7 +1100,7 @@ export const layer: Layer.Layer< return handoffBudget({ tokenCap, modelContextWindow, - userText: restartNote === "" ? userText : `${restartNote}\n\n${userText}`, + userText: runNote === "" ? userText : `${runNote}\n\n${userText}`, attachments: providerMessage.attachments, providerThread: budgetProviderThread, nativeContextEstimate: @@ -1815,7 +1820,7 @@ export const layer: Layer.Layer< sideChatHandoff === undefined || compact || goalCommand ? "" : sideChatHandoff.summaryText; - const context = [delivery.context, sideChatContext, restartNote] + const context = [delivery.context, sideChatContext, runNote] .filter((part) => part !== "") .join("\n\n"); const { restartContinuationOfRunId: _resumedRunId, ...promptedInput } = turnInput; @@ -1893,7 +1898,7 @@ export const layer: Layer.Layer< effectiveHandoffs.length === 0 && retryHandoff.length === 0 && sideChatHandoff === undefined && - restartNote === "" && + runNote === "" && !noteContinuation ? session : makeDeliverySession(session, startWithHandoffs); diff --git a/apps/server/src/orchestration-v2/ThreadSettlementService.ts b/apps/server/src/orchestration-v2/ThreadSettlementService.ts index 39315fe2af03f..1a3e76ab49880 100644 --- a/apps/server/src/orchestration-v2/ThreadSettlementService.ts +++ b/apps/server/src/orchestration-v2/ThreadSettlementService.ts @@ -800,6 +800,7 @@ export const make = Effect.gen(function* () { case "thread.pull-request-synced": case "provider-session.detached": case "run.background-work-cancelled": + case "run.delegation-nudge-recorded": return enqueueThread(event.threadId); // Sweep only when the work can have ended: progress updates cannot settle anything. case "subagent.updated": { diff --git a/apps/server/src/orchestration-v2/testkit/OrchestratorScenario.ts b/apps/server/src/orchestration-v2/testkit/OrchestratorScenario.ts index 1c6f58d0f66af..c713d66d04db1 100644 --- a/apps/server/src/orchestration-v2/testkit/OrchestratorScenario.ts +++ b/apps/server/src/orchestration-v2/testkit/OrchestratorScenario.ts @@ -156,6 +156,7 @@ function commandThreadIds(command: OrchestrationV2Command): ReadonlyArray( const layerEffectWorkerProvided = EffectWorker.layer.pipe( Layer.provide(Layer.merge(layerStores, layerEffectExecutorProvided)), ); + const layerDelegationNudge = Layer.effectDiscard( + Effect.gen(function* () { + const reactor = yield* DelegationNudgeReactor.make; + yield* reactor.start(); + }), + ).pipe( + Layer.provide( + Layer.mergeAll( + layerOrchestratorProvided, + layerEventSinkProvided, + layerStores, + layerDatabase, + IdAllocator.layer, + ), + ), + ); const layerReplayRuntime = Layer.mergeAll( layerEffectOutboxProvided, layerOrchestratorProvided, @@ -568,6 +585,7 @@ export function layerWithRegistry( layerContinuationWorkerProvided, layerCommandOutputHubProvided, ThreadCommandExecutor.layer, + layerDelegationNudge, ).pipe( Layer.provide(ProviderTurnStartServiceTestkit.layer), Layer.provide(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer)), diff --git a/apps/server/src/relay/AgentAwarenessRelay.ts b/apps/server/src/relay/AgentAwarenessRelay.ts index fab3e39878244..91dafb8c89cbe 100644 --- a/apps/server/src/relay/AgentAwarenessRelay.ts +++ b/apps/server/src/relay/AgentAwarenessRelay.ts @@ -118,12 +118,14 @@ function shouldPublishAgentAwarenessEvent( case "thread.active-reordered": case "thread.tags-updated": case "thread.standing-updated": + case "thread.delegation-nudge-updated": case "thread.visited": case "thread.visit-recorded": case "thread.marked-unread": case "thread.runtime-mode-updated": case "thread.interaction-mode-updated": case "run.background-work-cancelled": + case "run.delegation-nudge-recorded": case "run-attempt.created": case "run-attempt.updated": case "node.updated": diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts index d8cf2f4a8c7dd..9f6fb9e71a603 100644 --- a/apps/server/src/server.ts +++ b/apps/server/src/server.ts @@ -220,6 +220,7 @@ import * as ThreadSettlementService from "./orchestration-v2/ThreadSettlementSer import * as CompactionLoopGuard from "./orchestration-v2/CompactionLoopGuard.ts"; import * as IdleCompactionService from "./orchestration-v2/IdleCompactionService.ts"; import * as SessionSpendGuardReactor from "./orchestration-v2/SessionSpendGuardReactor.ts"; +import * as DelegationNudgeReactor from "./orchestration-v2/DelegationNudgeReactor.ts"; import * as ThreadPullRequestService from "./orchestration-v2/ThreadPullRequestService.ts"; import * as RunFinalizationService from "./orchestration-v2/RunFinalizationService.ts"; import * as ProjectionMaintenance from "./orchestration-v2/ProjectionMaintenance.ts"; @@ -655,6 +656,14 @@ const layerSessionSpendGuardWorker = Layer.effectDiscard( ), ); +const layerDelegationNudgeWorker = Layer.effectDiscard( + DelegationNudgeReactor.make.pipe(Effect.flatMap((service) => service.start())), +).pipe( + Layer.provide( + Layer.mergeAll(ProjectionStoreV2.layer, RuntimeLayer.layerEventSink, IdAllocator.layer), + ), +); + const layerCompactionLoopGuard = Layer.effectDiscard( CompactionLoopGuard.make.pipe(Effect.flatMap((service) => service.start())), ).pipe(Layer.provide(ProjectionStoreV2.layer)); @@ -715,6 +724,7 @@ const layerRuntimeCoreDependenciesBase = Layer.mergeAll( layerThreadSettlementWorker, layerIdleCompactionWorker, layerSessionSpendGuardWorker, + layerDelegationNudgeWorker, layerCompactionLoopGuard, StorageCleanup.layer.pipe(Layer.provide(ProjectionStoreV2.layer)), DatabaseStorage.layer.pipe( diff --git a/docs/orchestration-v2/orchestrator-mcp-server.md b/docs/orchestration-v2/orchestrator-mcp-server.md index fa2770bb10cf7..d5a4d85b3f5ca 100644 --- a/docs/orchestration-v2/orchestrator-mcp-server.md +++ b/docs/orchestration-v2/orchestrator-mcp-server.md @@ -412,6 +412,10 @@ still waits on after its run completed. A subagent or `background_task` holds the thread. A command or monitor holds it only with `awaited: true`, since agents often leave a dev server running. +Each run reports `delegationNudge` when the thread had the delegation nudge on +during it: counted tool calls, delegations, nudges fired, the most-used counted +tools, and a note still waiting to be delivered. Absent means the nudge was off. + ### `t3_thread_update` Updates metadata for the calling thread or any other thread in the environment. @@ -420,6 +424,14 @@ which rejects one. Pull request links go through the separate `link_pull_request` and `unlink_pull_request` tools. Branch and workspace changes are outside this tool. +`set_delegation_nudge` turns the delegation nudge on or off for a thread and +optionally replaces its thresholds. It is off unless set. While on, a root run +that keeps calling tools without handing work off is reminded, once per +threshold, to delegate. The reminder steers the running turn when the provider +can take a steer without interrupting the tool in progress, and otherwise waits +for the next run. The stored setting records who changed it. A thread cannot +change its own: the caller has to be another thread or a client. + The result includes the command ID and durable event sequence together with the resultant title, title-regeneration marker, and linked pull request. Reusing a `clientRequestId` for the same action and thread replays the same command diff --git a/packages/client-runtime/src/operations/commands.ts b/packages/client-runtime/src/operations/commands.ts index 5b7f7dfe39030..055d0d26250d6 100644 --- a/packages/client-runtime/src/operations/commands.ts +++ b/packages/client-runtime/src/operations/commands.ts @@ -601,6 +601,22 @@ export const setThreadStanding = Effect.fn("EnvironmentCommands.setThreadStandin }); }); +export interface SetThreadDelegationNudgeInput extends ThreadCommandInput { + readonly enabled: boolean; + readonly thresholds?: ReadonlyArray; +} +export const setThreadDelegationNudge = Effect.fn("EnvironmentCommands.setThreadDelegationNudge")( + function* (input: SetThreadDelegationNudgeInput) { + return yield* dispatch({ + type: "thread.delegation-nudge.set", + commandId: yield* allocateCommandId(input), + threadId: input.threadId, + enabled: input.enabled, + ...(input.thresholds === undefined ? {} : { thresholds: [...input.thresholds] }), + }); + }, +); + export interface SetThreadAutoSettleInput extends ThreadCommandInput { readonly enabled: boolean; } diff --git a/packages/client-runtime/src/state/orchestrationV2Projection.ts b/packages/client-runtime/src/state/orchestrationV2Projection.ts index b513380341a10..b1af2755229c8 100644 --- a/packages/client-runtime/src/state/orchestrationV2Projection.ts +++ b/packages/client-runtime/src/state/orchestrationV2Projection.ts @@ -324,6 +324,7 @@ export function applyOrchestrationV2ProjectionEvent( case "thread.visited": case "thread.tags-updated": case "thread.standing-updated": + case "thread.delegation-nudge-updated": case "thread.marked-unread": return { ...projection, thread: event.payload }; case "thread.visit-recorded": @@ -354,6 +355,13 @@ export function applyOrchestrationV2ProjectionEvent( : run, ), }; + case "run.delegation-nudge-recorded": + return { + ...base, + runs: base.runs.map((run) => + run.id === event.payload.runId ? { ...run, delegationNudge: event.payload.stats } : run, + ), + }; case "run-attempt.created": case "run-attempt.updated": { const next = { ...base, attempts: upsertEntity(base.attempts, event.payload) }; diff --git a/packages/contracts/src/delegationNudge.ts b/packages/contracts/src/delegationNudge.ts new file mode 100644 index 0000000000000..868fcdd2b7669 --- /dev/null +++ b/packages/contracts/src/delegationNudge.ts @@ -0,0 +1,73 @@ +import * as Effect from "effect/Effect"; +import * as Schema from "effect/Schema"; + +import { IsoDateTime, NonNegativeInt, PositiveInt, ThreadId } from "./baseSchemas.ts"; + +/** + * A delegation nudge reminds a coordinating thread to hand work off once it + * starts doing that work itself. It is opt-in per thread and never blocks a + * tool call; see docs/orchestration-v2/orchestrator-mcp-server.md. + */ + +/** Tool calls in one run before the first and second reminders. */ +export const DEFAULT_DELEGATION_NUDGE_THRESHOLDS: ReadonlyArray = [5, 10]; + +/** Ascending, distinct and short, so each threshold fires at most once per run. */ +export const DelegationNudgeThresholds = Schema.Array(PositiveInt).check( + Schema.makeFilter((thresholds) => + thresholds.length === 0 || thresholds.length > 4 + ? "Give one to four thresholds." + : thresholds.every((value, index) => index === 0 || value > thresholds[index - 1]!) + ? true + : "Thresholds must be strictly ascending.", + ), +); + +/** Who last changed the setting, so a thread cannot quietly retune its own reminders. */ +export const DelegationNudgeChangedBy = Schema.Union([ + Schema.Struct({ kind: Schema.Literal("user") }), + /** An agent in another T3 thread, through `t3_thread_update`. */ + Schema.Struct({ kind: Schema.Literal("agent"), threadId: ThreadId }), + /** An MCP client that is not running inside a T3 thread. */ + Schema.Struct({ kind: Schema.Literal("mcp_client") }), +]); +export type DelegationNudgeChangedBy = typeof DelegationNudgeChangedBy.Type; + +export const ThreadDelegationNudge = Schema.Struct({ + enabled: Schema.Boolean, + thresholds: DelegationNudgeThresholds, + changedBy: DelegationNudgeChangedBy, + changedAt: IsoDateTime, +}); +export type ThreadDelegationNudge = typeof ThreadDelegationNudge.Type; + +/** A stored value that no longer decodes reads as off, rather than failing the thread. */ +export const StoredThreadDelegationNudge = Schema.NullOr(ThreadDelegationNudge).pipe( + Schema.catchDecoding(() => Effect.succeedSome(null)), +); +export type StoredThreadDelegationNudge = typeof StoredThreadDelegationNudge.Type; + +export const DelegationNudgeToolCount = Schema.Struct({ + name: Schema.String, + count: PositiveInt, +}); + +/** What one run did while its thread had the nudge on. */ +export const RunDelegationNudgeStats = Schema.Struct({ + countedToolCalls: NonNegativeInt, + delegations: NonNegativeInt, + nudgesFired: NonNegativeInt, + /** Most-used counted tools, highest first. */ + topTools: Schema.Array(DelegationNudgeToolCount), + /** A reminder the provider could not take mid-turn; the next run carries it as context. */ + deferredNote: Schema.optional(Schema.String), +}); +export type RunDelegationNudgeStats = typeof RunDelegationNudgeStats.Type; + +/** What `t3_thread_update` and clients may write. */ +export const DelegationNudgeUpdate = Schema.Struct({ + enabled: Schema.Boolean, + /** Omitted keeps the current thresholds, or the defaults when there are none. */ + thresholds: Schema.optional(DelegationNudgeThresholds), +}); +export type DelegationNudgeUpdate = typeof DelegationNudgeUpdate.Type; diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts index 9dacb77c54884..26d9b3fe52c0f 100644 --- a/packages/contracts/src/index.ts +++ b/packages/contracts/src/index.ts @@ -50,6 +50,7 @@ export * from "./threadPullRequest.ts"; export * from "./threadSearch.ts"; export * from "./threadTags.ts"; export * from "./threadStanding.ts"; +export * from "./delegationNudge.ts"; export * from "./threadTitle.ts"; export * from "./t3ProjectFile.ts"; export * from "./editor.ts"; diff --git a/packages/contracts/src/orchestrationV2.ts b/packages/contracts/src/orchestrationV2.ts index 1d0863345b133..05ba6f9e23453 100644 --- a/packages/contracts/src/orchestrationV2.ts +++ b/packages/contracts/src/orchestrationV2.ts @@ -56,6 +56,12 @@ import { ChatAttachment } from "./chatAttachment.ts"; import { ThreadGuestShare } from "./guestShare.ts"; import { StoredThreadTags, ThreadTag } from "./threadTags.ts"; import { StoredThreadStanding, ThreadStanding } from "./threadStanding.ts"; +import { + DelegationNudgeChangedBy, + DelegationNudgeUpdate, + RunDelegationNudgeStats, + StoredThreadDelegationNudge, +} from "./delegationNudge.ts"; import { ThreadTitleRegenerationOutcome } from "./threadTitle.ts"; import { OrchestrationSearchThreadsInput, @@ -542,6 +548,8 @@ export const OrchestrationV2AppThread = Schema.Struct({ tags: Schema.optional(StoredThreadTags), /** Bot persona for a standing thread; absent or null is an ordinary thread. Independent of pinning. */ standing: Schema.optional(StoredThreadStanding), + /** Opt-in reminder to delegate once the thread does work itself; absent or null is off. */ + delegationNudge: Schema.optional(StoredThreadDelegationNudge), lastVisitedAt: Schema.NullOr(Schema.DateTimeUtc).pipe( Schema.withDecodingDefault(Effect.succeed(null)), ), @@ -786,9 +794,18 @@ export const OrchestrationV2Run = Schema.Struct({ workspacePreparation: Schema.optional(OrchestrationV2ThreadLaunchWorkspaceStrategy), /** Starts a new provider conversation; earlier runs stay visible but never reach the provider. */ freshContext: Schema.optional(Schema.Boolean), + /** Tool and delegation counts while the thread's delegation nudge was on. */ + delegationNudge: Schema.optional(RunDelegationNudgeStats), }); export type OrchestrationV2Run = typeof OrchestrationV2Run.Type; +export const OrchestrationV2RunDelegationNudgeRecorded = Schema.Struct({ + runId: RunId, + stats: RunDelegationNudgeStats, +}); +export type OrchestrationV2RunDelegationNudgeRecorded = + typeof OrchestrationV2RunDelegationNudgeRecorded.Type; + export function orchestrationV2RunWorkStartedAt( run: Pick, ): OrchestrationV2Run["requestedAt"] { @@ -2069,6 +2086,7 @@ export const OrchestrationV2DomainEvent = Schema.Union([ "thread.active-reordered", "thread.tags-updated", "thread.standing-updated", + "thread.delegation-nudge-updated", "thread.visited", "thread.marked-unread", "thread.metadata-updated", @@ -2106,6 +2124,11 @@ export const OrchestrationV2DomainEvent = Schema.Union([ type: Schema.Literal("run.background-work-cancelled"), payload: OrchestrationV2RunBackgroundWorkCancelled, }), + Schema.Struct({ + ...OrchestrationV2EventBase.fields, + type: Schema.Literal("run.delegation-nudge-recorded"), + payload: OrchestrationV2RunDelegationNudgeRecorded, + }), Schema.Struct({ ...OrchestrationV2EventBase.fields, type: Schema.Literal("run-attempt.created"), @@ -2340,6 +2363,8 @@ export const OrchestrationV2ThreadShell = Schema.Struct({ tags: Schema.optional(StoredThreadTags), /** Bot persona for a standing thread; absent or null is an ordinary thread. Independent of pinning. */ standing: Schema.optional(StoredThreadStanding), + /** Opt-in reminder to delegate; absent or null is off. */ + delegationNudge: Schema.optional(StoredThreadDelegationNudge), lastVisitedAt: Schema.optional(Schema.NullOr(Schema.DateTimeUtc)), opens: Schema.optional(LenientThreadOpens), titleRegeneration: Schema.optional( @@ -3045,6 +3070,7 @@ export const OrchestrationV2DomainEventJson = Schema.Union([ "thread.active-reordered", "thread.tags-updated", "thread.standing-updated", + "thread.delegation-nudge-updated", "thread.visited", "thread.marked-unread", "thread.pull-request-synced", @@ -3082,6 +3108,11 @@ export const OrchestrationV2DomainEventJson = Schema.Union([ type: Schema.Literal("run.background-work-cancelled"), payload: OrchestrationV2RunBackgroundWorkCancelled, }), + Schema.Struct({ + ...OrchestrationV2JsonEventBaseFields, + type: Schema.Literal("run.delegation-nudge-recorded"), + payload: OrchestrationV2RunDelegationNudgeRecorded, + }), Schema.Struct({ ...OrchestrationV2JsonEventBaseFields, type: Schema.Literal("run-attempt.created"), @@ -3320,6 +3351,14 @@ export const OrchestrationV2Command = Schema.Union([ /** The persona to show, or null to make it an ordinary thread again. */ standing: Schema.NullOr(ThreadStanding), }), + Schema.Struct({ + type: Schema.Literal("thread.delegation-nudge.set"), + commandId: CommandId, + threadId: ThreadId, + ...DelegationNudgeUpdate.fields, + /** Who asked; absent means the user. */ + changedBy: Schema.optional(DelegationNudgeChangedBy), + }), Schema.Struct({ type: Schema.Literal("thread.tag.set"), commandId: CommandId, diff --git a/packages/contracts/src/orchestratorMcp.ts b/packages/contracts/src/orchestratorMcp.ts index 2b91f933341ca..6258586ff5551 100644 --- a/packages/contracts/src/orchestratorMcp.ts +++ b/packages/contracts/src/orchestratorMcp.ts @@ -4,6 +4,7 @@ import * as Schema from "effect/Schema"; import * as SchemaTransformation from "effect/SchemaTransformation"; import { AuthMcpClientAccess } from "./auth.ts"; +import { RunDelegationNudgeStats } from "./delegationNudge.ts"; import { PeerLinkAppAccess } from "./peerLink.ts"; import { ContextTransferId, @@ -536,6 +537,8 @@ export const OrchestratorMcpThreadRun = Schema.Struct({ requestedAt: IsoDateTime, startedAt: Schema.NullOr(IsoDateTime), completedAt: Schema.NullOr(IsoDateTime), + /** Present once the thread's delegation nudge counted this run. */ + delegationNudge: Schema.optional(RunDelegationNudgeStats), }); export type OrchestratorMcpThreadRun = typeof OrchestratorMcpThreadRun.Type; diff --git a/packages/contracts/src/threadMetadataMcp.ts b/packages/contracts/src/threadMetadataMcp.ts index 95aca7489db33..e0b5058e520f4 100644 --- a/packages/contracts/src/threadMetadataMcp.ts +++ b/packages/contracts/src/threadMetadataMcp.ts @@ -10,6 +10,7 @@ import { import { ThreadDecisionAsk, ThreadInbox, ThreadInboxRoutingPatch } from "./threadInbox.ts"; import { ThreadLinkedPullRequest } from "./threadPullRequest.ts"; import { StoredThreadStanding, ThreadStanding } from "./threadStanding.ts"; +import { DelegationNudgeUpdate, StoredThreadDelegationNudge } from "./delegationNudge.ts"; import { ThreadTitleRegeneration } from "./threadTitle.ts"; export function hasOnlyPairedSurrogates(value: string): boolean { @@ -49,6 +50,7 @@ export const ThreadMetadataMcpAction = Schema.Literals([ "request_decision", "resolve_decision", "set_standing", + "set_delegation_nudge", ]); export type ThreadMetadataMcpAction = typeof ThreadMetadataMcpAction.Type; @@ -64,15 +66,22 @@ export const ThreadMetadataMcpUpdateInput = Schema.Struct({ "Required only when action is set_standing: a bot persona ({name, role?, avatarId, accent}) makes this a standing bot thread; null makes it an ordinary thread. Independent of pinning.", }), ), + delegationNudge: Schema.optional( + DelegationNudgeUpdate.annotate({ + description: + "Required only when action is set_delegation_nudge: {enabled, thresholds?}. When on, the thread is reminded to delegate after that many of its own tool calls in one request (default [5, 10]). A thread cannot change its own setting.", + }), + ), clientRequestId: Schema.optional(ThreadMetadataClientRequestId), }).check( Schema.makeFilter((input) => (input.action === "rename") === (input.title !== undefined) && (input.action === "route") === (input.inboxRouting !== undefined) && (input.action === "request_decision") === (input.decision !== undefined) && - (input.action === "set_standing") === (input.standing !== undefined) + (input.action === "set_standing") === (input.standing !== undefined) && + (input.action === "set_delegation_nudge") === (input.delegationNudge !== undefined) ? true - : "rename requires title; route requires inboxRouting; request_decision requires decision; set_standing requires standing; other actions reject those fields.", + : "rename requires title; route requires inboxRouting; request_decision requires decision; set_standing requires standing; set_delegation_nudge requires delegationNudge; other actions reject those fields.", ), ); export type ThreadMetadataMcpUpdateInput = typeof ThreadMetadataMcpUpdateInput.Type; @@ -87,6 +96,7 @@ export const ThreadMetadataMcpUpdateResult = Schema.Struct({ linkedPullRequest: Schema.NullOr(ThreadLinkedPullRequest), inbox: Schema.optionalKey(ThreadInbox), standing: Schema.optionalKey(StoredThreadStanding), + delegationNudge: Schema.optionalKey(StoredThreadDelegationNudge), updatedAt: IsoDateTime, }); export type ThreadMetadataMcpUpdateResult = typeof ThreadMetadataMcpUpdateResult.Type;