From dd01b61c5b39fcbc971b9477811e15735b72889a Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Fri, 20 Nov 2026 02:58:54 +0000 Subject: [PATCH 1/3] fork seams: server.ts is a declared seam; announce the handoff owner line (#361) List-only change: server.ts's text is unchanged. Its ten pending fork lines (ceiling 10) move to a "files" entry with exactly those lines in "added", so the seam check now pins each one instead of only their count. One new line is announced for the follow-up pull request that lets the handoff service alone own a thread with handoff on (upstream idle compaction skips it). Part of #361 Co-Authored-By: Claude Opus 5.5 --- .github/fork-seams.json | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/.github/fork-seams.json b/.github/fork-seams.json index d87b5963d0cdb..59d2f221b32d2 100644 --- a/.github/fork-seams.json +++ b/.github/fork-seams.json @@ -30,6 +30,27 @@ "...applyForkSettingsPatch(current, forkPatch)," ] }, + "apps/server/src/server.ts": { + "why": "The fork's service layers are wired here in one place each, from fork/forkLayers.ts (#384), so this file keeps as few fork lines as it can. The ten lines in \"added\" were its pending lines (ceiling 10) when it moved here (#361). The announced line gives the runtime's workers upstream's orchestrator with one change: an idle compaction send to a thread whose handoff mode is \"handoff\" is skipped, so the handoff service alone owns that thread (fork/handoff, #361).", + "added": [ + "import * as ForkLayers from \"./fork/forkLayers.ts\";", + "// Fork (waits): the `pr` judge reads through the same pull request service and its caches.", + "Layer.provide(layerPullRequestService.pipe(Layer.provide(RuntimeLayer.layerProjectService))),", + "ForkLayers.holdWorkAgentActivity(AgentAwarenessRelay.layer),", + "ForkLayers.layerRuntimeServices,", + "Layer.effectDiscard(ForkLayers.startRemoteDelegation),", + "ForkLayers.layerRoutes,", + "const layerWorkAdmission = yield* ForkLayers.makeWorkAdmissionLayer(config);", + "Layer.provide(ForkLayers.holdWorkCloudLink(CloudLink.layer, ConnectReachability.layer)),", + "Layer.provide(Layer.merge(layerActivation, layerWorkAdmission))," + ], + "announced": { + "since": "2026-11-20", + "added": [ + "Layer.provide(ForkLayers.handoffThreadsSkipIdleCompaction), // Fork: one owner (fork/handoff)" + ] + } + }, "apps/server/src/serverSettings.ts": { "why": "Every settings write goes through upstream's patch and write paths here. The fork swaps in its patch (fork/serverSettingsPatch.ts, under upstream's name, so a project's MCP profile a client left out is kept) and calls its save check (fork/serverSettingsWriteCheck.ts) once in each write path. The load decodes the file after fork/settingsFileRead.ts (old auto-update names renamed, an unusable interval left out so it reads as its default). The lines from \"import { renameRetiredAutoUpdateKeys }\" on predate this list and record main as it was when every upstream file began to count (#277); they are to move into apps/server/src/fork/ (follow-up), and the file cannot grow meanwhile.", "added": [ @@ -216,7 +237,6 @@ "apps/server/src/scheduling/DueHint.ts": 5, "apps/server/src/scheduling/Scheduler.test.ts": 24, "apps/server/src/scheduling/Scheduler.ts": 13, - "apps/server/src/server.ts": 10, "apps/server/src/serverRuntimeStartup.ts": 54, "apps/server/src/serverRuntimeState.test.ts": 21, "apps/server/src/serverRuntimeState.ts": 4, From fb8f86fa9baa592b093ed981da5d8ec844ca36be Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Fri, 20 Nov 2026 03:08:55 +0000 Subject: [PATCH 2/3] fork(handoff): one owner per thread; project-off tests (#361) With handoff on for a thread (mode handoff from the server, its project or the thread's own entry), upstream's idle compaction now skips that thread, so a compaction and a handoff never both act on it. A thin wrapper of upstream's orchestrator (fork/handoff/handoffOwner.ts) skips only an idle compaction send to such a thread, decided at the send. IdleCompactionService.ts stays upstream's; server.ts gets the one line announced in the seam list, first in the runtime workers' pipe. threadHandoffSettings is now the one place that picks a thread's handoff settings, for both the wrapper and the handoff service. Tests: upstream's own idle compaction worker behind the wrapper (each mode, project and thread entry; switched on or off while it waits; the same run twice; the owner unreadable), the server.ts wiring, and the handoff service with a project switched off (past the size limit, while it waits on a busy thread, while the idle timer sleeps). Fixes #361 Co-Authored-By: Claude Opus 5.5 --- .github/fork-seams.json | 13 +- apps/server/src/fork/forkLayers.ts | 8 + .../src/fork/handoff/HandoffService.test.ts | 76 +++++ .../server/src/fork/handoff/HandoffService.ts | 8 +- .../src/fork/handoff/handoffOwner.test.ts | 287 ++++++++++++++++++ apps/server/src/fork/handoff/handoffOwner.ts | 94 ++++++ apps/server/src/server.ts | 1 + docs/fork/README.md | 3 +- docs/fork/handoff.md | 21 +- 9 files changed, 492 insertions(+), 19 deletions(-) create mode 100644 apps/server/src/fork/handoff/handoffOwner.test.ts create mode 100644 apps/server/src/fork/handoff/handoffOwner.ts diff --git a/.github/fork-seams.json b/.github/fork-seams.json index 59d2f221b32d2..ce7fc5d84b1df 100644 --- a/.github/fork-seams.json +++ b/.github/fork-seams.json @@ -31,7 +31,7 @@ ] }, "apps/server/src/server.ts": { - "why": "The fork's service layers are wired here in one place each, from fork/forkLayers.ts (#384), so this file keeps as few fork lines as it can. The ten lines in \"added\" were its pending lines (ceiling 10) when it moved here (#361). The announced line gives the runtime's workers upstream's orchestrator with one change: an idle compaction send to a thread whose handoff mode is \"handoff\" is skipped, so the handoff service alone owns that thread (fork/handoff, #361).", + "why": "The fork's service layers are wired here in one place each, from fork/forkLayers.ts (#384), so this file keeps as few fork lines as it can. The first ten lines in \"added\" were its pending lines (ceiling 10) when it moved here (#361). The last one gives the runtime's workers upstream's orchestrator with one change: an idle compaction send to a thread whose handoff mode is \"handoff\" is skipped, so the handoff service alone owns that thread (fork/handoff, #361).", "added": [ "import * as ForkLayers from \"./fork/forkLayers.ts\";", "// Fork (waits): the `pr` judge reads through the same pull request service and its caches.", @@ -42,14 +42,9 @@ "ForkLayers.layerRoutes,", "const layerWorkAdmission = yield* ForkLayers.makeWorkAdmissionLayer(config);", "Layer.provide(ForkLayers.holdWorkCloudLink(CloudLink.layer, ConnectReachability.layer)),", - "Layer.provide(Layer.merge(layerActivation, layerWorkAdmission))," - ], - "announced": { - "since": "2026-11-20", - "added": [ - "Layer.provide(ForkLayers.handoffThreadsSkipIdleCompaction), // Fork: one owner (fork/handoff)" - ] - } + "Layer.provide(Layer.merge(layerActivation, layerWorkAdmission)),", + "Layer.provide(ForkLayers.handoffThreadsSkipIdleCompaction), // Fork: one owner (fork/handoff)" + ] }, "apps/server/src/serverSettings.ts": { "why": "Every settings write goes through upstream's patch and write paths here. The fork swaps in its patch (fork/serverSettingsPatch.ts, under upstream's name, so a project's MCP profile a client left out is kept) and calls its save check (fork/serverSettingsWriteCheck.ts) once in each write path. The load decodes the file after fork/settingsFileRead.ts (old auto-update names renamed, an unusable interval left out so it reads as its default). The lines from \"import { renameRetiredAutoUpdateKeys }\" on predate this list and record main as it was when every upstream file began to count (#277); they are to move into apps/server/src/fork/ (follow-up), and the file cannot grow meanwhile.", diff --git a/apps/server/src/fork/forkLayers.ts b/apps/server/src/fork/forkLayers.ts index b33d835f70cb3..3b9a77b6186f0 100644 --- a/apps/server/src/fork/forkLayers.ts +++ b/apps/server/src/fork/forkLayers.ts @@ -16,6 +16,7 @@ import * as UsagePacer from "../usage/UsagePacer.ts"; import * as UsageReadingsHistory from "../usage/UsageReadingsHistory.ts"; import * as WorkAdmission from "../workAdmission.ts"; import * as ActivityProbe from "./activityProbe.ts"; +import * as HandoffOwner from "./handoff/handoffOwner.ts"; import * as HandoffService from "./handoff/HandoffService.ts"; /** Wraps upstream's agent activity relay: a held server (`serve --hold-work`) publishes none. */ @@ -43,6 +44,13 @@ export const layerRuntimeServices = Layer.mergeAll( HandoffService.layer, ); +/** + * Provided to the runtime's core dependencies (server.ts's `layerRuntimeCoreDependenciesBase`, first + * in its pipe, so only its own workers see it): upstream's orchestrator, except that idle compaction + * skips a thread whose handoff mode is `handoff`, which the handoff service alone owns. + */ +export const handoffThreadsSkipIdleCompaction = HandoffOwner.layer; + /** In the routes, after upstream's follower of tasks in linked environments. */ export const layerRoutes = Layer.mergeAll( // /mcp reads the usage pacer and the slot gate only if they are there (the usage pacing gate, diff --git a/apps/server/src/fork/handoff/HandoffService.test.ts b/apps/server/src/fork/handoff/HandoffService.test.ts index dd5991530b06c..9670cbd1966a6 100644 --- a/apps/server/src/fork/handoff/HandoffService.test.ts +++ b/apps/server/src/fork/handoff/HandoffService.test.ts @@ -16,6 +16,7 @@ import { type OrchestrationV2ThreadProjection, RunId, RuntimeRequestId, + type ServerSettings as ServerSettingsValue, } from "@t3tools/contracts"; import * as DateTime from "effect/DateTime"; import * as Deferred from "effect/Deferred"; @@ -70,6 +71,8 @@ const threadChanged = (data: OrchestrationV2ThreadProjection) => const harness = (state: { data: OrchestrationV2ThreadProjection; settings: Partial; + /** The thread's project override (over the defaults), or none. */ + project?: Partial | undefined; /** Runs inside the mocked dispatch, after the command is recorded. */ onDispatch?: (command: OrchestrationV2ServerCommand) => Effect.Effect; }) => @@ -120,6 +123,14 @@ const harness = (state: { getSettings: Effect.sync(() => ({ ...DEFAULT_SERVER_SETTINGS, handoff: { ...DEFAULT_HANDOFF_SETTINGS, ...state.settings }, + projectSettingsOverrides: + state.project === undefined + ? {} + : ({ + [state.data.thread.projectId]: { + handoff: { ...DEFAULT_HANDOFF_SETTINGS, ...state.project }, + }, + } as unknown as ServerSettingsValue["projectSettingsOverrides"]), })), }), ); @@ -286,6 +297,71 @@ describe("HandoffService", () => { }), ); + it.effect.each([ + { server: on, project: { mode: "off" }, sends: 0 }, + { server: on, project: { mode: "compact" }, sends: 0 }, + { server: {}, project: on, sends: 1 }, + // The project's own thread entry wins over its mode, as for the server's. + { server: on, project: { mode: "off", threads: { [threadId]: "handoff" } }, sends: 1 }, + { server: on, project: { mode: "handoff", threads: { [threadId]: "off" } }, sends: 0 }, + ] as ReadonlyArray<{ + server: Partial; + project: Partial; + sends: number; + }>)( + "a project's own setting decides for its threads, past the size limit (sends $sends)", + ({ server, project, sends }) => + Effect.gen(function* () { + const state = { data: projection({ usedTokens: 400_000 }), settings: server, project }; + const { sent, emit, reads } = yield* harness(state); + yield* emit(runUpdated(run()), "handOffWhenDue", 1); + expect(messages(sent)).toHaveLength(sends); + // Off for the thread reads nothing more than its settings. + if (sends === 0) expect(reads.count).toBe(0); + }), + ); + + it.effect( + "its project switched off while the handoff waits on a busy thread: sends nothing", + () => + Effect.gen(function* () { + const quiet = projection({ usedTokens: 160_000 }); + const state = { + data: { + ...quiet, + runtimeRequests: [ + { id: RuntimeRequestId.make("request-1"), status: "pending" }, + ] as unknown as OrchestrationV2ThreadProjection["runtimeRequests"], + }, + settings: on, + project: undefined as Partial | undefined, + }; + const { sent, emit } = yield* harness(state); + yield* emit(runUpdated(run()), "readThread", 1); + state.project = { mode: "off" }; + state.data = quiet; + yield* emit(threadChanged(state.data), "handOffWhenDue", 1); + expect(sent).toEqual([]); + }), + ); + + it.effect("its project switched off while the idle timer sleeps: sends nothing", () => + Effect.gen(function* () { + const state = { + data: projection({ usedTokens: 100_000, cacheExpiresInMs: 10 * MINUTE_MS }), + settings: on, + project: undefined as Partial | undefined, + }; + const { sent, emit } = yield* harness(state); + yield* emit(runUpdated(run()), "readThread", 1); + yield* TestClock.adjust(MINUTE_MS); + state.project = { mode: "off" }; + yield* TestClock.adjust(10 * MINUTE_MS); + yield* emit(null, "handOffWhenDue", 1); + expect(sent).toEqual([]); + }), + ); + it.effect.each([ { read: true, visits: 1 }, { read: false, visits: 0 }, diff --git a/apps/server/src/fork/handoff/HandoffService.ts b/apps/server/src/fork/handoff/HandoffService.ts index 83ddfcec4c166..d53dfec506c30 100644 --- a/apps/server/src/fork/handoff/HandoffService.ts +++ b/apps/server/src/fork/handoff/HandoffService.ts @@ -7,7 +7,6 @@ import { CommandId, MessageId, type OrchestrationV2Run, - resolveHandoffSettings, type RunId, type ThreadId, } from "@t3tools/contracts"; @@ -28,6 +27,7 @@ import { type HandoffTrigger, handoffDecision } from "./handoffDecision.ts"; import { dispatchHandoff, readHandoffRecords } from "./handoffDispatch.ts"; import { HANDOFF_RETRY_SUFFIX, handoffThreadFacts, parseHandoffMessageId } from "./handoffFacts.ts"; import { handoffMessageText } from "./handoffMessage.ts"; +import { threadHandoffSettings } from "./handoffOwner.ts"; /** Part 3 reads the turn items of this many latest runs; the budget keeps the newest of them. */ const TRANSCRIPT_RUNS = 20; @@ -47,11 +47,7 @@ export const make = Effect.gen(function* () { const readThread = Effect.fn("HandoffService.readThread")(function* (threadId: ThreadId) { const current = yield* serverSettings.getSettings; const thread = yield* projections.getThread(threadId); - const resolved = resolveHandoffSettings( - current.handoff, - current.projectSettingsOverrides[thread.projectId]?.handoff, - threadId, - ); + const resolved = threadHandoffSettings(current, thread.projectId, threadId); // Off (the default) and `compact` read nothing more. if (resolved.mode !== "handoff") return null; return { ...resolved, records: yield* withStores(readHandoffRecords(threadId)) }; diff --git a/apps/server/src/fork/handoff/handoffOwner.test.ts b/apps/server/src/fork/handoff/handoffOwner.test.ts new file mode 100644 index 0000000000000..f8e7da828f415 --- /dev/null +++ b/apps/server/src/fork/handoff/handoffOwner.test.ts @@ -0,0 +1,287 @@ +/** + * Fork: one owner per thread. Upstream's own idle compaction worker runs against mocked stores + * behind the fork's orchestrator wrapper: a thread with handoff on is never compacted, any other + * thread is compacted exactly as upstream does, and server.ts gives the wrapper to that worker. + */ +import * as NodeServices from "@effect/platform-node/NodeServices"; +import { describe, expect, it } from "@effect/vitest"; +import { + DEFAULT_HANDOFF_SETTINGS, + DEFAULT_SERVER_SETTINGS, + EventId, + type HandoffSettings, + type OrchestrationV2ServerCommand, + type OrchestrationV2ThreadProjection, + type ServerSettings as ServerSettingsValue, +} from "@t3tools/contracts"; +import * as Deferred from "effect/Deferred"; +import * as Effect from "effect/Effect"; +import * as FileSystem from "effect/FileSystem"; +import * as Layer from "effect/Layer"; +import * as Path from "effect/Path"; +import * as Stream from "effect/Stream"; +import * as Tracer from "effect/Tracer"; +import * as TestClock from "effect/testing/TestClock"; + +import * as IdleCompactionService from "../../orchestration-v2/IdleCompactionService.ts"; +import * as Orchestrator from "../../orchestration-v2/Orchestrator.ts"; +import * as ProjectionStore from "../../orchestration-v2/ProjectionStore.ts"; +import * as ServerSettings from "../../serverSettings.ts"; +import { at, MINUTE_MS, NOW_MS, projection, run, runId, threadId } from "./handoff.testkit.ts"; +import * as HandoffOwner from "./handoffOwner.ts"; + +const projectId = projection({ usedTokens: 0 }).thread.projectId; + +interface State { + data: OrchestrationV2ThreadProjection; + /** The server's handoff settings, over the defaults (off). */ + server: Partial; + /** The thread's project override: absent, or its handoff settings over the defaults. */ + project?: Partial; + /** The wrapper's thread lookup fails (a store error at that moment). */ + findFails?: boolean; +} + +const settingsOf = (state: State): ServerSettingsValue => ({ + ...DEFAULT_SERVER_SETTINGS, + // Upstream's idle compaction on, for the thread's built-in Claude instance. + idleCompaction: "beforeCacheExpires", + providerInstances: {}, + handoff: { ...DEFAULT_HANDOFF_SETTINGS, ...state.server }, + projectSettingsOverrides: + state.project === undefined + ? {} + : ({ + [projectId]: { handoff: { ...DEFAULT_HANDOFF_SETTINGS, ...state.project } }, + } as unknown as ServerSettingsValue["projectSettingsOverrides"]), +}); + +/** + * Upstream's idle compaction worker behind `HandoffOwner.make`, with mocked stores read at every + * call (a test may change `state` while compaction waits). Returns the commands that reached + * upstream's orchestrator and a wait for the worker's `count`th finished decision. + */ +const compaction = (state: State, completions = 1) => + Effect.gen(function* () { + yield* TestClock.setTime(NOW_MS); + const sent: Array = []; + let ended = 0; + const done = yield* Deferred.make(); + const tracer = Tracer.make({ + span(options) { + const span = new Tracer.NativeSpan(options); + const end = span.end.bind(span); + span.end = (...args) => { + end(...args); + if (span.name === "IdleCompactionService.compactWhenDue" && ++ended >= completions) + Deferred.doneUnsafe(done, Effect.void); + }; + return span; + }, + }); + const completed = { + id: EventId.make("event:run-1:completed"), + type: "run.updated", + threadId, + runId, + occurredAt: at(), + payload: run(), + } as const; + const upstream = Layer.mock(Orchestrator.OrchestratorV2)({ + streamDomainEvents: Stream.make(...Array.from({ length: completions }, () => completed)), + dispatch: (command) => + Effect.sync(() => { + sent.push(command); + return { sequence: sent.length, storedEvents: [] }; + }), + }); + const stores = Layer.mergeAll( + Layer.mock(ProjectionStore.ProjectionStoreV2)({ + getThread: () => Effect.sync(() => state.data.thread), + findThread: () => + state.findFails === true + ? Effect.fail(new Error("store unavailable") as never) + : Effect.sync(() => state.data.thread), + getThreadRecords: () => Effect.sync(() => state.data), + }), + Layer.mock(ServerSettings.ServerSettingsService)({ + getSettings: Effect.sync(() => settingsOf(state)), + }), + ); + const wrapped = Layer.effect(Orchestrator.OrchestratorV2, HandoffOwner.make).pipe( + Layer.provide(upstream), + Layer.provideMerge(stores), + ); + yield* IdleCompactionService.make.pipe( + Effect.flatMap((service) => service.start()), + Effect.provide(wrapped), + Effect.withTracer(tracer), + ); + return { sent, done: Deferred.await(done) }; + }); + +/** A long Claude thread whose prompt cache expires in `expiresInMs` (compaction starts 2 min before). */ +const longThread = (expiresInMs = 2 * MINUTE_MS) => + projection({ usedTokens: 250_000, cacheExpiresInMs: expiresInMs }); + +const compactions = (sent: ReadonlyArray) => + sent.filter((command) => command.type === "message.dispatch" && command.idleCompaction); + +describe("one owner per thread: idle compaction and handoff", () => { + it.effect.each([ + { name: "handoff off (the default)", server: {}, compacts: 1 }, + { name: "handoff mode compact", server: { mode: "compact" }, compacts: 1 }, + { name: "handoff on for the server", server: { mode: "handoff" }, compacts: 0 }, + { + name: "handoff on for the server, its project off", + server: { mode: "handoff" }, + project: { mode: "off" }, + compacts: 1, + }, + { + name: "handoff off for the server, its project on", + server: {}, + project: { mode: "handoff" }, + compacts: 0, + }, + { + name: "handoff on for this thread only", + server: { threads: { [threadId]: "handoff" } }, + compacts: 0, + }, + { + name: "handoff on for another thread only", + server: { threads: { "other-thread": "handoff" } }, + compacts: 1, + }, + ] as ReadonlyArray<{ + name: string; + server: Partial; + project?: Partial; + compacts: number; + }>)("$name: compacts $compacts time(s)", ({ server, project, compacts }) => + Effect.gen(function* () { + const state: State = { + data: longThread(), + server, + ...(project === undefined ? {} : { project }), + }; + const { sent, done } = yield* compaction(state); + yield* done; + expect(compactions(sent)).toHaveLength(compacts); + // Nothing else is sent on the thread's behalf. + expect(sent).toHaveLength(compacts); + }), + ); + + it.effect("handoff switched on while compaction waits: decided at the send, so none", () => + Effect.gen(function* () { + const state: State = { data: longThread(10 * MINUTE_MS), server: {} }; + const { sent, done } = yield* compaction(state); + yield* TestClock.adjust(MINUTE_MS); + state.server = { mode: "handoff" }; + yield* TestClock.adjust(7 * MINUTE_MS); + yield* done; + expect(sent).toEqual([]); + }), + ); + + it.effect("handoff switched off while compaction waits: upstream compacts as before", () => + Effect.gen(function* () { + const state: State = { data: longThread(10 * MINUTE_MS), server: { mode: "handoff" } }; + const { sent, done } = yield* compaction(state); + yield* TestClock.adjust(MINUTE_MS); + state.project = { mode: "off" }; + yield* TestClock.adjust(7 * MINUTE_MS); + yield* done; + expect(compactions(sent)).toHaveLength(1); + }), + ); + + it.effect("the same run reported twice (runs again): still no compaction", () => + Effect.gen(function* () { + const state: State = { data: longThread(), server: { mode: "handoff" } }; + const { sent, done } = yield* compaction(state, 2); + yield* done; + expect(sent).toEqual([]); + }), + ); + + it.effect("the owner cannot be read: upstream decides, and compacts", () => + Effect.gen(function* () { + // Only the wrapper looks the thread up with `findThread`; upstream's own reads still work. + const state: State = { data: longThread(), server: { mode: "handoff" }, findFails: true }; + const { sent, done } = yield* compaction(state); + yield* done; + expect(compactions(sent)).toHaveLength(1); + }), + ); +}); + +describe("skipIdleCompactionOfOwnedThreads", () => { + const command = (idleCompaction: boolean): OrchestrationV2ServerCommand => + ({ + type: "message.dispatch", + threadId, + ...(idleCompaction ? { idleCompaction: "beforeCacheExpires" } : {}), + }) as unknown as OrchestrationV2ServerCommand; + + it.effect( + "passes every other command through, and asks about the owner only for compaction", + () => + Effect.gen(function* () { + const sent: Array = []; + const asked: Array = []; + const upstream = { + dispatch: (sentCommand: OrchestrationV2ServerCommand) => + Effect.sync(() => { + sent.push(sentCommand); + return { sequence: sent.length, storedEvents: [] }; + }), + } as unknown as Orchestrator.OrchestratorV2["Service"]; + const wrapped = HandoffOwner.skipIdleCompactionOfOwnedThreads(upstream, (id) => + Effect.sync(() => { + asked.push(id); + return true; + }), + ); + const other = command(false); + const stop = { type: "thread.stop", threadId } as unknown as OrchestrationV2ServerCommand; + yield* wrapped.dispatch(other); + yield* wrapped.dispatch(stop); + expect(sent).toEqual([other, stop]); + expect(asked).toEqual([]); + expect(yield* wrapped.dispatch(command(true))).toEqual({ sequence: 0, storedEvents: [] }); + expect(sent).toEqual([other, stop]); + expect(asked).toEqual([threadId]); + }), + ); +}); + +describe("server.ts wiring", () => { + it.effect( + "gives the wrapper to the runtime workers' pipe, which holds upstream's idle compaction worker", + () => + Effect.gen(function* () { + const path = yield* Path.Path; + const fileSystem = yield* FileSystem.FileSystem; + const server = yield* fileSystem.readFileString( + yield* path.fromFileUrl(new URL("../../server.ts", import.meta.url)), + ); + const start = server.indexOf("const layerRuntimeCoreDependenciesBase = Layer.mergeAll("); + expect(start).toBeGreaterThan(-1); + // The mergeAll's own pipe, at the start of a line (its members have pipes of their own). + const pipe = server.indexOf("\n).pipe(\n", start) + 1; + expect(pipe).toBeGreaterThan(start); + const block = server.slice(start, pipe); + expect(block).toMatch(/^\s*layerIdleCompactionWorker,$/m); + // First in the pipe: below it, upstream's orchestrator reaches only the workers above. + const firstInPipe = server.slice( + pipe, + server.indexOf("\n", server.indexOf("\n", pipe) + 1), + ); + expect(firstInPipe).toContain("Layer.provide(ForkLayers.handoffThreadsSkipIdleCompaction)"); + expect(server.split("ForkLayers.handoffThreadsSkipIdleCompaction")).toHaveLength(2); + }).pipe(Effect.provide(NodeServices.layer)), + ); +}); diff --git a/apps/server/src/fork/handoff/handoffOwner.ts b/apps/server/src/fork/handoff/handoffOwner.ts new file mode 100644 index 0000000000000..faf16585ddfcc --- /dev/null +++ b/apps/server/src/fork/handoff/handoffOwner.ts @@ -0,0 +1,94 @@ +/** + * Fork: one owner per thread. Upstream's idle compaction skips a thread whose handoff mode is + * `handoff`, decided at the send, so a compaction and a handoff never both act on it. Every other + * command passes through; `IdleCompactionService.ts` stays upstream's. + */ +import { + type OrchestrationV2ServerCommand, + type ProjectId, + resolveHandoffSettings, + type ServerSettings as ServerSettingsValue, + type ThreadId, +} from "@t3tools/contracts"; +import * as Effect from "effect/Effect"; +import * as Layer from "effect/Layer"; + +import * as Orchestrator from "../../orchestration-v2/Orchestrator.ts"; +import * as ProjectionStore from "../../orchestration-v2/ProjectionStore.ts"; +import * as ServerSettings from "../../serverSettings.ts"; + +/** A thread's handoff settings and mode: its project's override, else the server's (one source). */ +export const threadHandoffSettings = ( + current: Pick, + projectId: ProjectId, + threadId: ThreadId, +): ReturnType => + resolveHandoffSettings( + current.handoff, + Object.hasOwn(current.projectSettingsOverrides, projectId) + ? current.projectSettingsOverrides[projectId]?.handoff + : undefined, + threadId, + ); + +const isIdleCompaction = ( + command: OrchestrationV2ServerCommand, +): command is Extract => + command.type === "message.dispatch" && command.idleCompaction !== undefined; + +/** + * Upstream's orchestrator, except that an idle compaction send to a thread `ownsThread` claims is + * skipped (it reports nothing stored). Any other command is upstream's own call, unchanged. + */ +export const skipIdleCompactionOfOwnedThreads = ( + orchestrator: Orchestrator.OrchestratorV2["Service"], + ownsThread: (threadId: ThreadId) => Effect.Effect, +): Orchestrator.OrchestratorV2["Service"] => ({ + ...orchestrator, + dispatch: (command) => + isIdleCompaction(command) + ? ownsThread(command.threadId).pipe( + Effect.flatMap((owned) => + owned + ? Effect.logInfo("idle compaction skipped: handoff owns this thread", { + threadId: command.threadId, + }).pipe(Effect.as({ sequence: 0, storedEvents: [] })) + : orchestrator.dispatch(command), + ), + ) + : orchestrator.dispatch(command), +}); + +/** + * Upstream's orchestrator, with idle compaction skipped on a thread whose handoff mode is `handoff`. + * Read at each send, so a setting changed while compaction waited counts. When the settings or the + * thread cannot be read, upstream decides (compaction goes ahead). + */ +export const make = Effect.gen(function* () { + const orchestrator = yield* Orchestrator.OrchestratorV2; + const serverSettings = yield* ServerSettings.ServerSettingsService; + const projections = yield* ProjectionStore.ProjectionStoreV2; + const handoffOwns = Effect.fn("HandoffOwner.handoffOwns")( + function* (threadId: ThreadId) { + const thread = yield* projections.findThread(threadId); + if (thread === null) return false; + const current = yield* serverSettings.getSettings; + return threadHandoffSettings(current, thread.projectId, threadId).mode === "handoff"; + }, + (effect, threadId) => + effect.pipe( + Effect.catch((cause) => + Effect.logWarning("handoff owner unknown; idle compaction decides", { + threadId, + cause, + }).pipe(Effect.as(false)), + ), + ), + ); + return skipIdleCompactionOfOwnedThreads(orchestrator, handoffOwns); +}); + +/** `make` for the runtime's workers (`ForkLayers.handoffThreadsSkipIdleCompaction`). */ +export const layer = Layer.effect(Orchestrator.OrchestratorV2, make).pipe( + Layer.provide(ProjectionStore.layer), +); diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts index 984bc3ed693bd..1b16ca1a35fa1 100644 --- a/apps/server/src/server.ts +++ b/apps/server/src/server.ts @@ -737,6 +737,7 @@ const layerRuntimeCoreDependenciesBase = Layer.mergeAll( ReplayMarkers.layer, Layer.effectDiscard(ProjectSettingsOverrideSweep.sweep), ).pipe( + Layer.provide(ForkLayers.handoffThreadsSkipIdleCompaction), // Fork: one owner (fork/handoff) Layer.provideMerge(layerOrchestrationApplication), Layer.provideMerge(RuntimeLayer.layerEventInfrastructure), Layer.provideMerge(Layer.merge(ProjectStore.layer, ThreadSearch.layer)), diff --git a/docs/fork/README.md b/docs/fork/README.md index 44be38463caaa..d3bc7cf9ba7f5 100644 --- a/docs/fork/README.md +++ b/docs/fork/README.md @@ -412,7 +412,8 @@ thread's children, watched pull requests and waits keep working. How and when: [handoff.md](handoff.md). Only the person can change it; agents cannot. `mode` is `off` (the default: upstream's compaction -settings apply as they are), `handoff`, or `compact` (the same as `off`, so one thread can opt out +settings apply as they are), `handoff` (upstream's idle compaction then skips the thread, so +only the handoff acts on it), or `compact` (the same as `off`, so one thread can opt out of its project's `handoff`). `threads` maps a thread id to a mode and wins over `mode` (at most 500). `source` says who writes the handoff: `agent` (the old session, in one turn; `instructions` replaces the built-in text) or `command` (a program given as `command`, run without a shell; it diff --git a/docs/fork/handoff.md b/docs/fork/handoff.md index e94d7af965ea6..548837bbed302 100644 --- a/docs/fork/handoff.md +++ b/docs/fork/handoff.md @@ -28,6 +28,15 @@ settings first: with a mode other than `handoff` it reads nothing more and sends Token counts are the provider's own last reading for the active session. A provider that reports none never hands off. +## One owner per thread + +With handoff on for a thread (mode `handoff`, from the server, its project or the thread's own +entry), upstream's idle compaction skips that thread, so a compaction and a handoff never both act +on it. The handoff settings alone decide what happens when it sits idle: `idleTokens` `0` means no +idle action at all. The check happens at the moment compaction would send, so a setting changed +while compaction waited counts. With any other mode, upstream's idle compaction works as before. +If the thread or the settings cannot be read at that moment, compaction goes ahead. + ## Only at a quiet thread A thread is quiet when none of these is true: a run is queued or running, a request (an approval or @@ -95,8 +104,14 @@ written out in full. The message says when no effort is set. `handoffFacts.ts`, `handoffMessage.ts`, `handoffDecision.ts`). Settings: `packages/contracts/src/handoff.ts`. - `Orchestrator.ts` stays upstream's (the fork check refuses edits to it). Every handoff send goes - through `dispatchHandoff` (`handoffDispatch.ts`), and a test checks that. No upstream file is - edited: the service starts from `ForkLayers.layerRuntimeServices` (`apps/server/src/fork/forkLayers.ts`), - the fork file `server.ts` already wires. + through `dispatchHandoff` (`handoffDispatch.ts`), and a test checks that. The service starts from + `ForkLayers.layerRuntimeServices` (`apps/server/src/fork/forkLayers.ts`), which `server.ts` + already wires. +- One owner per thread: `handoffOwner.ts` wraps upstream's orchestrator for the runtime's workers + and skips only an idle compaction send to a thread with handoff on. `IdleCompactionService.ts` + stays upstream's; `server.ts` gets one fork line, + `Layer.provide(ForkLayers.handoffThreadsSkipIdleCompaction)`, first in the pipe of + `layerRuntimeCoreDependenciesBase`, and a test checks it is there. `threadHandoffSettings` (same + file) is the one place that picks a thread's settings for both the wrapper and the service. - The message reuses upstream's handoff budget (`handoffBudget`) and transcript reading (`ContextHandoffService.ts`); nothing is copied. From 5d53687fdc5d4228b99ff31934061363dc4ce087 Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Fri, 20 Nov 2026 04:49:45 +0000 Subject: [PATCH 3/3] Seam list: the handoff idle-compaction line is now added, not announced This change adds the line to apps/server/src/server.ts, so the stale-list test refuses it under "announced". Move it to "added". Co-Authored-By: Claude Opus 5.5 --- .github/fork-seams.json | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/.github/fork-seams.json b/.github/fork-seams.json index 59d2f221b32d2..0b41e43eeb0fe 100644 --- a/.github/fork-seams.json +++ b/.github/fork-seams.json @@ -31,7 +31,7 @@ ] }, "apps/server/src/server.ts": { - "why": "The fork's service layers are wired here in one place each, from fork/forkLayers.ts (#384), so this file keeps as few fork lines as it can. The ten lines in \"added\" were its pending lines (ceiling 10) when it moved here (#361). The announced line gives the runtime's workers upstream's orchestrator with one change: an idle compaction send to a thread whose handoff mode is \"handoff\" is skipped, so the handoff service alone owns that thread (fork/handoff, #361).", + "why": "The fork's service layers are wired here in one place each, from fork/forkLayers.ts (#384), so this file keeps as few fork lines as it can. The ten lines in \"added\" were its pending lines (ceiling 10) when it moved here (#361). The last line in \"added\" gives the runtime's workers upstream's orchestrator with one change: an idle compaction send to a thread whose handoff mode is \"handoff\" is skipped, so the handoff service alone owns that thread (fork/handoff, #361).", "added": [ "import * as ForkLayers from \"./fork/forkLayers.ts\";", "// Fork (waits): the `pr` judge reads through the same pull request service and its caches.", @@ -42,14 +42,9 @@ "ForkLayers.layerRoutes,", "const layerWorkAdmission = yield* ForkLayers.makeWorkAdmissionLayer(config);", "Layer.provide(ForkLayers.holdWorkCloudLink(CloudLink.layer, ConnectReachability.layer)),", - "Layer.provide(Layer.merge(layerActivation, layerWorkAdmission))," - ], - "announced": { - "since": "2026-11-20", - "added": [ - "Layer.provide(ForkLayers.handoffThreadsSkipIdleCompaction), // Fork: one owner (fork/handoff)" - ] - } + "Layer.provide(Layer.merge(layerActivation, layerWorkAdmission)),", + "Layer.provide(ForkLayers.handoffThreadsSkipIdleCompaction), // Fork: one owner (fork/handoff)" + ] }, "apps/server/src/serverSettings.ts": { "why": "Every settings write goes through upstream's patch and write paths here. The fork swaps in its patch (fork/serverSettingsPatch.ts, under upstream's name, so a project's MCP profile a client left out is kept) and calls its save check (fork/serverSettingsWriteCheck.ts) once in each write path. The load decodes the file after fork/settingsFileRead.ts (old auto-update names renamed, an unusable interval left out so it reads as its default). The lines from \"import { renameRetiredAutoUpdateKeys }\" on predate this list and record main as it was when every upstream file began to count (#277); they are to move into apps/server/src/fork/ (follow-up), and the file cannot grow meanwhile.",