From 57ccbfd112fa14e21b2d86b419f0c722151cdeff Mon Sep 17 00:00:00 2001 From: nullStack65 <112618179+nullStack65@users.noreply.github.com> Date: Wed, 18 Nov 2026 21:41:07 +0000 Subject: [PATCH 1/3] feat(inbox): founder inboxes hold only threads waiting on that founder A founder's lane is now derived from thread state. Agent-filed work without a stated reason stays in Agents; an open decision request or a pending approval/user-input request puts a thread in the founder's action lane, and the founder's reply, resolve_decision or settle takes it back out. Agent launches and routes into a founder or shared inbox must give inboxRouting.reason. Co-Authored-By: Claude Opus 5.5 --- apps/server/src/mcp/OrchestratorMcpService.ts | 7 +- .../src/mcp/ThreadMetadataMcpService.ts | 25 ++++ .../src/mcp/toolkits/orchestrator/tools.ts | 2 +- .../src/mcp/toolkits/project/handlers.test.ts | 28 +++- .../src/mcp/toolkits/project/handlers.ts | 7 + .../Orchestrator.control-reads.test.ts | 80 +++++++++++ .../src/orchestration-v2/Orchestrator.ts | 36 +++-- .../src/orchestration-v2/ProjectionStore.ts | 32 ++++- .../src/provider/agentContextBudget.json | 2 +- evals/mcp-tool-use/cases/orchestration.ndjson | 2 + packages/contracts/src/orchestrationV2.ts | 9 +- packages/contracts/src/threadInbox.test.ts | 133 ++++++++++++++++-- packages/contracts/src/threadInbox.ts | 125 +++++++++++++--- .../contracts/src/threadMetadataMcp.test.ts | 7 + packages/contracts/src/threadMetadataMcp.ts | 16 ++- 15 files changed, 459 insertions(+), 52 deletions(-) diff --git a/apps/server/src/mcp/OrchestratorMcpService.ts b/apps/server/src/mcp/OrchestratorMcpService.ts index 169913bdac44..3a774671e841 100644 --- a/apps/server/src/mcp/OrchestratorMcpService.ts +++ b/apps/server/src/mcp/OrchestratorMcpService.ts @@ -66,6 +66,7 @@ import { latestProviderTurnForAttempt, resolveProjectProviderInstanceEnabled, SECRET_REQUEST_UNSAVED_NOTE, + agentLaunchInboxError, agentLaunchInboxRouting, } from "@t3tools/contracts"; import { getProviderOptionCurrentValue, withLegacyUltracodeEffort } from "@t3tools/shared/model"; @@ -989,7 +990,7 @@ function threadDetail( const latest = ThreadManagementService.latestRun(projection); const active = ThreadManagementService.latestActiveRun(projection); return { - ...(projection.thread.inbox === undefined ? {} : { inbox: projection.thread.inbox }), + ...(shell.inbox === undefined ? {} : { inbox: shell.inbox }), threadId: projection.thread.id, projectId: projection.thread.projectId, title: projection.thread.title, @@ -3124,6 +3125,10 @@ const make = Effect.gen(function* () { createThreads: Effect.fn("OrchestratorMcpService.createThreads")( function* (callerScope, input) { const { scope, parent } = yield* loadThreadCaller(callerScope, "create_threads"); + for (const request of input.threads) { + const inboxError = agentLaunchInboxError(request); + if (inboxError !== null) return yield* failure("invalid_request", inboxError); + } // Each thread shares this thread's checkout, so another environment cannot take it. for (const request of input.threads) { yield* admitPlacement( diff --git a/apps/server/src/mcp/ThreadMetadataMcpService.ts b/apps/server/src/mcp/ThreadMetadataMcpService.ts index 929fbed08279..ef010ff79abf 100644 --- a/apps/server/src/mcp/ThreadMetadataMcpService.ts +++ b/apps/server/src/mcp/ThreadMetadataMcpService.ts @@ -1,5 +1,7 @@ import { + agentInboxRoutingError, CommandId, + makeThreadInbox, OrchestratorMcpFailure, type OrchestrationV2AppThread, type OrchestrationV2Command, @@ -7,6 +9,7 @@ import { type ThreadMetadataMcpUpdateInput, type ThreadMetadataMcpUpdateResult, ThreadId, + routeThreadInbox, } from "@t3tools/contracts"; import * as Context from "effect/Context"; import * as SecureRandom from "effect/crypto/SecureRandom"; @@ -86,6 +89,20 @@ function metadataCommand(input: { threadId: input.threadId, regenerateTitle: true, }; + case "request_decision": + return { + type: "thread.metadata.update", + commandId: input.commandId, + threadId: input.threadId, + decisionRequest: input.update.decision!, + }; + case "resolve_decision": + return { + type: "thread.metadata.update", + commandId: input.commandId, + threadId: input.threadId, + decisionRequest: null, + }; } } @@ -157,6 +174,14 @@ const make = Effect.gen(function* () { `Thread ${threadId} was not found.`, ); } + const inboxError = + input.inboxRouting === undefined + ? null + : agentInboxRoutingError( + routeThreadInbox(shell.inbox ?? makeThreadInbox({ actor: null }), input.inboxRouting), + input.inboxRouting, + ); + if (inboxError !== null) return yield* failure("invalid_request", inboxError); const requestKey = input.clientRequestId === undefined ? yield* random.uuidV4() : input.clientRequestId; const updateCommandId = commandId({ diff --git a/apps/server/src/mcp/toolkits/orchestrator/tools.ts b/apps/server/src/mcp/toolkits/orchestrator/tools.ts index 252693b32156..8089fe52afa9 100644 --- a/apps/server/src/mcp/toolkits/orchestrator/tools.ts +++ b/apps/server/src/mcp/toolkits/orchestrator/tools.ts @@ -266,7 +266,7 @@ const ThreadReadTool = Tool.make("t3_thread_read", { const ThreadUpdateTool = Tool.make("t3_thread_update", { description: - "Route a thread with action:'route' and inboxRouting (owner, assignee, audience, attentionKind), or rename a thread (`action:'rename'` with `title`) or regenerate its title. Omit `threadId` for this 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`. 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/mcp/toolkits/project/handlers.test.ts b/apps/server/src/mcp/toolkits/project/handlers.test.ts index 79df1ca9e2bd..9572ed8d3279 100644 --- a/apps/server/src/mcp/toolkits/project/handlers.test.ts +++ b/apps/server/src/mcp/toolkits/project/handlers.test.ts @@ -416,7 +416,7 @@ it.effect("a launch with a model its provider does not advertise creates no thre }), ); -it.effect("a launch is filed in Agents unless the agent picks an inbox", () => +it.effect("a launch is filed in Agents unless the agent picks an inbox with a reason", () => Effect.gen(function* () { const launched: Array = []; const { projectId, dependencies } = clientLaunchHarness({ @@ -428,24 +428,40 @@ it.effect("a launch is filed in Agents unless the agent picks an inbox", () => McpToolAccess.HandlersLayer.layer(ProjectHandlers.layer).pipe(Layer.provide(dependencies)), ), ); - const launch = (inbox?: "kameron" | "shared") => + const launch = (inbox?: "kameron" | "shared", reason?: "conversation") => toolkit .handle("t3_thread_launch", { title: "Fix", projectId, ...(inbox === undefined ? {} : { inbox }), + ...(reason === undefined ? {} : { inboxRouting: { reason } }), }) - .pipe(Stream.unwrap, Stream.runCollect, Effect.provide(dependencies)); + .pipe( + Stream.unwrap, + Stream.runCollect, + Effect.map((result) => result.at(-1)?.result), + Effect.provide(dependencies), + ); yield* launch(); - yield* launch("kameron"); - yield* launch("shared"); + for (const inbox of ["kameron", "shared"] as const) { + expect(yield* launch(inbox)).toMatchObject({ + _tag: "OrchestratorMcpFailure", + code: "invalid_request", + message: expect.stringContaining("inboxRouting.reason"), + }); + } + yield* launch("kameron", "conversation"); + yield* launch("shared", "conversation"); expect(launched.map((input) => input.inboxRouting?.audience)).toEqual([ "agent-only", "kameron", "shared", ]); - expect(launched[1]?.inboxRouting?.assignee).toEqual({ kind: "human", id: "kameron" }); + expect(launched[1]?.inboxRouting).toMatchObject({ + assignee: { kind: "human", id: "kameron" }, + reason: "conversation", + }); }), ); diff --git a/apps/server/src/mcp/toolkits/project/handlers.ts b/apps/server/src/mcp/toolkits/project/handlers.ts index f66e13636d0f..f2762c7b3f12 100644 --- a/apps/server/src/mcp/toolkits/project/handlers.ts +++ b/apps/server/src/mcp/toolkits/project/handlers.ts @@ -1,4 +1,5 @@ import { + agentLaunchInboxError, agentLaunchInboxRouting, CommandId, type EnvironmentId, @@ -235,6 +236,12 @@ export const layer = McpToolAccess.toLayer(ProjectToolkit, { const threadId = ThreadId.make(commandId); const messageId = MessageId.make(commandId); const attachments = input.attachments ?? []; + const inboxError = agentLaunchInboxError(input); + if (inboxError !== null) + return yield* new OrchestratorMcpFailure({ + code: "invalid_request", + message: inboxError, + }); if (attachments.some((attachment) => !Claims.attachmentIsPendingUpload(attachment))) return yield* new OrchestratorMcpFailure({ code: "invalid_request", diff --git a/apps/server/src/orchestration-v2/Orchestrator.control-reads.test.ts b/apps/server/src/orchestration-v2/Orchestrator.control-reads.test.ts index 214f6cf360e2..14c3d07d8b73 100644 --- a/apps/server/src/orchestration-v2/Orchestrator.control-reads.test.ts +++ b/apps/server/src/orchestration-v2/Orchestrator.control-reads.test.ts @@ -5,6 +5,8 @@ import { CommandId, MessageId, EventId, + founderInboxLane, + inboxRoutingFor, NodeId, type OrchestrationV2DomainEvent, PlanId, @@ -462,6 +464,84 @@ it.effect("marks a never-visited thread's first completion unread", () => }).pipe(Effect.provide(layerTest)), ); +it.effect("a founder decision request holds an agent thread in their inbox until they answer", () => + Effect.gen(function* () { + const orchestrator = yield* Orchestrator.OrchestratorV2; + const projections = yield* ProjectionStore.ProjectionStoreV2; + const threadId = ThreadId.make("thread:decision-request"); + yield* orchestrator.dispatch({ + type: "thread.create", + commandId: CommandId.make("create-decision-request"), + threadId, + projectId: ProjectId.make("project:decision-request"), + title: "Autonomous work", + modelSelection, + runtimeMode: "full-access", + interactionMode: "default", + branch: null, + worktreePath: null, + createdBy: "agent", + creationSource: "mcp", + inboxOrigin: { kind: "agent", id: "lead" }, + inboxRouting: inboxRoutingFor("agents"), + }); + const lanes = Effect.gen(function* () { + const inbox = (yield* projections.getThreadShell(threadId))?.inbox; + return [founderInboxLane(inbox, "kameron"), founderInboxLane(inbox, "jeff")]; + }); + let step = 0; + const update = (decisionRequest: "ask" | null) => + orchestrator.dispatch({ + type: "thread.metadata.update", + commandId: CommandId.make(`decision-request-${++step}`), + threadId, + decisionRequest: + decisionRequest === null + ? null + : { founder: "kameron", kind: "approval", question: "Send this draft?" }, + }); + const message = (createdBy: "agent" | "user") => + Effect.gen(function* () { + yield* TestClock.adjust("1 second"); + const id = `decision-message-${++step}`; + yield* orchestrator.dispatch({ + type: "message.dispatch", + commandId: CommandId.make(id), + threadId, + messageId: MessageId.make(id), + text: createdBy === "user" ? "Yes, send it." : "Still working.", + attachments: [], + dispatchMode: { type: "defer_start" }, + createdBy, + creationSource: createdBy === "user" ? "web" : "mcp", + }); + }); + assert.deepEqual(yield* lanes, ["hidden", "hidden"]); + + yield* update("ask"); + assert.deepEqual(yield* lanes, ["action", "hidden"]); + yield* orchestrator.dispatch({ + type: "thread.settle", + commandId: CommandId.make("settle-decision-request"), + threadId, + }); + assert.deepEqual(yield* lanes, ["hidden", "hidden"]); + + yield* TestClock.adjust("1 second"); + yield* update("ask"); + yield* message("agent"); + assert.deepEqual(yield* lanes, ["action", "hidden"]); + yield* message("user"); + assert.deepEqual(yield* lanes, ["hidden", "hidden"]); + + yield* TestClock.adjust("1 second"); + yield* update("ask"); + assert.deepEqual(yield* lanes, ["action", "hidden"]); + yield* update(null); + assert.deepEqual(yield* lanes, ["hidden", "hidden"]); + }).pipe(Effect.provide(layerTest)), +); + const completeAndSnoozeThread = Effect.fn("test.completeAndSnoozeThread")(function* ( name: string, snoozeMinutes: number, diff --git a/apps/server/src/orchestration-v2/Orchestrator.ts b/apps/server/src/orchestration-v2/Orchestrator.ts index 7defde600c68..92d608cb8305 100644 --- a/apps/server/src/orchestration-v2/Orchestrator.ts +++ b/apps/server/src/orchestration-v2/Orchestrator.ts @@ -6,7 +6,7 @@ import type { OrchestrationV2ThreadHistoryPage, ProjectId, } from "@t3tools/contracts"; -import { makeThreadInbox, routeThreadInbox } from "@t3tools/contracts"; +import { makeThreadInbox, routeThreadInbox, type ThreadInbox } from "@t3tools/contracts"; import { ServerEnvironmentIdentity } from "../environment/ServerEnvironment.ts"; import { latestExecutedRun, @@ -797,6 +797,28 @@ function askedForLinkedMachine( return hint !== "" && hint === normalize(linked.hint) && hint === normalize(linked.linkedLabel); } +function withoutDecisionRequest(inbox: ThreadInbox): ThreadInbox { + const { decisionRequest: _closed, ...rest } = inbox; + return rest; +} + +function askedInbox( + inbox: ThreadInbox | undefined, + command: Extract, + now: DateTime.Utc, +): ThreadInbox { + const base = inbox ?? makeThreadInbox({ actor: null }); + const routed = + command.inboxRouting === undefined ? base : routeThreadInbox(base, command.inboxRouting); + if (command.decisionRequest === undefined) return routed; + return command.decisionRequest === null + ? withoutDecisionRequest(routed) + : { + ...routed, + decisionRequest: { ...command.decisionRequest, requestedAt: DateTime.formatIso(now) }, + }; +} + // A workspace change detaches the session, which can settle the calling run at once. Queuing its // follow-up in a later command would let a delegated task report its result before that exists. function metadataUpdateContinuation( @@ -4732,6 +4754,9 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio thread.settledOverride === "settled" && thread.settledAt !== null && !wasPinned; return { ...thread, + ...(thread.inbox?.decisionRequest === undefined + ? {} + : { inbox: withoutDecisionRequest(thread.inbox) }), settledOverride: "settled", settledAt: alreadySettled ? thread.settledAt : (command.settledAt ?? now), // Settled threads refuse recovery, so an armed resume would stay hidden until un-settled. @@ -4880,14 +4905,9 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio }; return { ...thread, - ...(command.inboxRouting === undefined + ...(command.inboxRouting === undefined && command.decisionRequest === undefined ? {} - : { - inbox: routeThreadInbox( - thread.inbox ?? makeThreadInbox({ actor: null }), - command.inboxRouting, - ), - }), + : { inbox: askedInbox(thread.inbox, command, now) }), ...(command.title === undefined ? {} : { title: command.title }), ...(command.limitRecovery === undefined ? {} : { limitRecovery }), ...(command.limitRecovery !== undefined && diff --git a/apps/server/src/orchestration-v2/ProjectionStore.ts b/apps/server/src/orchestration-v2/ProjectionStore.ts index b98ccff45e78..c029bd0e4781 100644 --- a/apps/server/src/orchestration-v2/ProjectionStore.ts +++ b/apps/server/src/orchestration-v2/ProjectionStore.ts @@ -1,5 +1,10 @@ import type { ProjectThreadAwarenessV2Input } from "@t3tools/shared/agentAwareness"; -import { applyOrchestrationV2ThreadVisit, pendingGuestMessageCount } from "@t3tools/contracts"; +import { + applyOrchestrationV2ThreadVisit, + pendingGuestMessageCount, + projectThreadInbox, + type ThreadInbox, +} from "@t3tools/contracts"; import { applyThreadPullRequestLinkUpdate } from "../sourceControl/threadPullRequests.ts"; import { projectTurnItemForWire } from "./WireProjection.ts"; import * as Stream from "effect/Stream"; @@ -1708,6 +1713,23 @@ const linkCardStillAsks = ( latestUserAuthoredMessageAt === null || !DateTime.isGreaterThan(latestUserAuthoredMessageAt, item.startedAt ?? item.updatedAt); +const shellInbox = ( + inbox: ThreadInbox | undefined, + pendingRuntimeRequest: OrchestrationV2PendingRuntimeRequestSummary | null, + latestUserAuthoredMessageAt: DateTime.Utc | null, +) => + inbox === undefined + ? {} + : { + inbox: projectThreadInbox(inbox, { + pendingHumanRequest: pendingRuntimeRequest !== null, + latestHumanMessageAt: + latestUserAuthoredMessageAt === null + ? null + : DateTime.formatIso(latestUserAuthoredMessageAt), + }), + }; + export function threadShellFromProjection( projection: OrchestrationV2ThreadProjection, ): OrchestrationV2ThreadShell { @@ -1785,7 +1807,7 @@ export function threadShellFromProjection( }); return { createdBy: projection.thread.createdBy, - ...(projection.thread.inbox === undefined ? {} : { inbox: projection.thread.inbox }), + ...shellInbox(projection.thread.inbox, pendingRuntimeRequest, latestUserAuthoredMessageAt), creationSource: projection.thread.creationSource, id: projection.thread.id, projectId: projection.thread.projectId, @@ -2125,7 +2147,11 @@ function shellFromState(input: { ...(input.state.thread.historyOrigin === undefined ? {} : { historyOrigin: input.state.thread.historyOrigin }), - ...(input.state.thread.inbox === undefined ? {} : { inbox: input.state.thread.inbox }), + ...shellInbox( + input.state.thread.inbox, + input.state.pendingRuntimeRequest, + input.state.latestUserAuthoredMessageAt, + ), ...(input.state.thread.linkOrigin === undefined ? {} : { linkOrigin: input.state.thread.linkOrigin }), diff --git a/apps/server/src/provider/agentContextBudget.json b/apps/server/src/provider/agentContextBudget.json index ab49f2b6c830..2522389c9f9e 100644 --- a/apps/server/src/provider/agentContextBudget.json +++ b/apps/server/src/provider/agentContextBudget.json @@ -1,5 +1,5 @@ { "claudeSystemAppendBytes": 5930, "codexAdditionalContextBytes": 7324, - "mcpToolListJsonBytes": 52637 + "mcpToolListJsonBytes": 53783 } diff --git a/evals/mcp-tool-use/cases/orchestration.ndjson b/evals/mcp-tool-use/cases/orchestration.ndjson index df13d9cd6313..7c3f01afdab1 100644 --- a/evals/mcp-tool-use/cases/orchestration.ndjson +++ b/evals/mcp-tool-use/cases/orchestration.ndjson @@ -45,3 +45,5 @@ {"id": "settle-after-merge-on-wake", "area": "orchestration", "kind": "bad", "pattern": "settle read as plain English for finish", "experience": "Asked to merge a PR once its checks pass and then settle this thread, the agent merged on the checks-passed wake and ended the turn without calling t3_thread_organize (#26749).", "rule": "Asked to settle ... a thread, including this one: call t3_thread_organize.", "privacy": "commit-safe", "notes": "From #26749's delayed pattern. Wake text is copied from pullRequestWatch.ts. Good: merge #123, then settle this thread on the same turn.", "setup": {"role": "top", "priorTurns": [{"role": "user", "text": "Okay this looks good to me. Any risk merging it?"}, {"role": "assistant", "text": "Low risk. [#123](https://github.com/acme/app/pull/123) only adds an accessible title to the HTML preview frame, and the new test covers it. Two checks are still running: Check and Test Web.", "toolCalls": [{"tool": "Bash", "input": {"command": "gh pr view 123 --json title,files --jq '.title, .files[].path'"}, "result": "fix(web): HTML preview frame gets an accessible title\napps/web/src/HtmlPreview.tsx\napps/web/src/HtmlPreview.test.tsx"}, {"tool": "Bash", "input": {"command": "gh pr checks 123"}, "result": "Lint\tpass\t41s\nTypecheck\tpass\t1m2s\nCheck\tpending\t0\nTest Web\tpending\t0"}, {"tool": "link_pull_request", "input": {"url": "https://github.com/acme/app/pull/123"}, "result": {"host": "github.com", "repository": "acme/app", "number": 123, "url": "https://github.com/acme/app/pull/123", "alreadyLinked": false}}]}, {"role": "user", "text": "Merge it once its checks pass, then settle this thread."}, {"role": "assistant", "text": "T3 Code is watching [#123](https://github.com/acme/app/pull/123). I'll merge it once Check and Test Web pass, then settle this thread.", "toolCalls": [{"tool": "watch_pull_request", "input": {"url": "https://github.com/acme/app/pull/123"}, "result": {"host": "github.com", "repository": "acme/app", "number": 123, "url": "https://github.com/acme/app/pull/123", "watching": true, "wasWatching": false}}]}], "mocks": {"watch_pull_request": "default", "link_pull_request": "default", "t3_thread_organize": {"settlesWhenTurnEnds": true}, "unwatch_pull_request": "default"}, "world": {"branch": "fix/html-preview-title", "commits": [{"sha": "abc1234", "subject": "fix(web): HTML preview frame gets an accessible title"}], "diff": "diff --git a/apps/web/src/HtmlPreview.tsx b/apps/web/src/HtmlPreview.tsx\n--- a/apps/web/src/HtmlPreview.tsx\n+++ b/apps/web/src/HtmlPreview.tsx\n@@ -1,3 +1,3 @@\n export function HtmlPreview({ html }: { html: string }) {\n- return