From e2619c802fae7f07914aefafbb7d8e72f2065817 Mon Sep 17 00:00:00 2001 From: nullStack65 <112618179+nullStack65@users.noreply.github.com> Date: Fri, 20 Nov 2026 20:02:43 +0000 Subject: [PATCH 1/2] feat(server): nudge a thread to delegate once it does the work itself An opt-in per-thread setting counts a root run's own tool calls and, at each threshold, reminds the agent to hand the work off. It steers a running turn only when the provider can take a steer without interrupting the tool in progress; otherwise the note waits for the next run. Off by default, and a thread cannot change its own setting. Model: grok/grok-4.7 Task: feat Agent: Claude Code Co-Authored-By: Claude Code --- apps/server/src/mcp/OrchestratorMcpService.ts | 1 + .../src/mcp/ThreadMetadataMcpService.ts | 38 +- .../src/mcp/toolkits/orchestrator/tools.ts | 2 +- .../DelegationNudge.integration.test.ts | 406 ++++++++++++++++++ .../src/orchestration-v2/DelegationNudge.ts | 84 ++++ .../DelegationNudgeReactor.ts | 282 ++++++++++++ .../src/orchestration-v2/Orchestrator.ts | 30 +- .../src/orchestration-v2/ProjectionStore.ts | 38 +- .../ProviderTurnStartService.ts | 11 +- .../ThreadSettlementService.ts | 1 + .../testkit/OrchestratorScenario.ts | 1 + .../testkit/ProviderReplayHarness.ts | 18 + apps/server/src/relay/AgentAwarenessRelay.ts | 2 + apps/server/src/server.ts | 10 + .../client-runtime/src/operations/commands.ts | 16 + .../src/state/orchestrationV2Projection.ts | 8 + packages/contracts/src/delegationNudge.ts | 73 ++++ packages/contracts/src/index.ts | 1 + packages/contracts/src/orchestrationV2.ts | 39 ++ packages/contracts/src/orchestratorMcp.ts | 3 + packages/contracts/src/threadMetadataMcp.ts | 14 +- 21 files changed, 1062 insertions(+), 16 deletions(-) create mode 100644 apps/server/src/orchestration-v2/DelegationNudge.integration.test.ts create mode 100644 apps/server/src/orchestration-v2/DelegationNudge.ts create mode 100644 apps/server/src/orchestration-v2/DelegationNudgeReactor.ts create mode 100644 packages/contracts/src/delegationNudge.ts 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..df2de8d709814 --- /dev/null +++ b/apps/server/src/orchestration-v2/DelegationNudgeReactor.ts @@ -0,0 +1,282 @@ +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 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: [], + dispatchMode: { type: "steer_active", targetRunId: run.id }, + 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; + } + 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 = (input: { + readonly threadId: ThreadId; + readonly runId: RunId; + readonly note: string; + readonly nudgesFired: number; + }) => + Effect.gen(function* () { + 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/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; From ba384a095bba0635e8ef52eb72b2cc4cfd3b6ae2 Mon Sep 17 00:00:00 2001 From: nullStack65 <112618179+nullStack65@users.noreply.github.com> Date: Fri, 20 Nov 2026 20:28:11 +0000 Subject: [PATCH 2/2] fix(server): deliver the delegation nudge as a queued notice A notification that arrives already asking to steer is refused, so the reminder never reached the turn. Send it queued, the way the other server notices do, and let the planner steer it when the provider can take it. Model: grok/grok-4.7 Task: fix Agent: Claude Code Co-Authored-By: Claude Code --- .../src/orchestration-v2/DelegationNudgeReactor.ts | 13 ++++++++----- docs/orchestration-v2/orchestrator-mcp-server.md | 12 ++++++++++++ 2 files changed, 20 insertions(+), 5 deletions(-) diff --git a/apps/server/src/orchestration-v2/DelegationNudgeReactor.ts b/apps/server/src/orchestration-v2/DelegationNudgeReactor.ts index df2de8d709814..252d1ccec6f40 100644 --- a/apps/server/src/orchestration-v2/DelegationNudgeReactor.ts +++ b/apps/server/src/orchestration-v2/DelegationNudgeReactor.ts @@ -10,6 +10,7 @@ import { } 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"; @@ -137,13 +138,16 @@ export const make = Effect.gen(function* () { summary: "Delegation reminder", }, attachments: [], - dispatchMode: { type: "steer_active", targetRunId: run.id }, + // 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; + return { ...delivered, deferredNote: undefined }; } return { ...stats, deferredNote: note }; }); @@ -192,13 +196,12 @@ export const make = Effect.gen(function* () { ); }); - const deliverReminder = (input: { + const deliverReminder = Effect.fn("DelegationNudgeReactor.deliverReminder")(function* (input: { readonly threadId: ThreadId; readonly runId: RunId; readonly note: string; readonly nudgesFired: number; - }) => - Effect.gen(function* () { + }) { 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); 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