From a2660cea8540af4ad6ec11a9b78b31fff497af19 Mon Sep 17 00:00:00 2001 From: John Doe <123843277+scuttletoby@users.noreply.github.com> Date: Sat, 21 Nov 2026 17:44:40 +0100 Subject: [PATCH] Placement P3 (facts out): t3_environment_read returns hostResources and placement t3_environment_read now returns two optional fields beside upstream's, for this machine and for a linked one (the read is forwarded there as before): - hostResources: CPU, cores and memory from HostResources, the result field of upstream PR #34293 (closed upstream without merging), same name and schema. Its export in McpHttpServer.ts, its lines in upstream test files and its new tool description are not carried: the fork adds no lines there. The fork file finds the sampler with Effect.serviceOption instead of a new tool dependency, so no upstream test needs a new mock. Its tests moved to fork test files. - placement: labels (empty: no setting holds them yet, P2 adds it), available and reason, runningAgents, slotsFree, memoryFloorMb, freeMemoryMb from the slot gate's existing status read (SlotGate.usage), and factsAt. A slot gate that cannot be read (fails, dies, takes longer than its own count limit, is not running, or the settings cannot be read) gives available: false with a reason and no count. A linked machine on an older T3 leaves both fields out: no facts, not a failed read. Nothing is stored; each read measures again. Result fields are not in the measured tool list, so the budget files are unchanged. The two environment toolkit files take the four lines announced in #779, moved from announced to added. Co-Authored-By: Claude Opus 5.5 --- .github/fork-seams.json | 24 +- FORK_CHANGES.md | 1 + .../src/fork/environmentFacts.linked.test.ts | 203 +++++++++++++ apps/server/src/fork/environmentFacts.test.ts | 276 ++++++++++++++++++ apps/server/src/fork/environmentFacts.ts | 116 ++++++++ .../src/mcp/toolkits/environment/handlers.ts | 2 + .../src/mcp/toolkits/environment/tools.ts | 2 + docs/fork/README.md | 29 ++ 8 files changed, 637 insertions(+), 16 deletions(-) create mode 100644 apps/server/src/fork/environmentFacts.linked.test.ts create mode 100644 apps/server/src/fork/environmentFacts.test.ts create mode 100644 apps/server/src/fork/environmentFacts.ts diff --git a/.github/fork-seams.json b/.github/fork-seams.json index 521a72356648c..b7867e1312a56 100644 --- a/.github/fork-seams.json +++ b/.github/fork-seams.json @@ -301,25 +301,17 @@ }, "apps/server/src/mcp/toolkits/environment/handlers.ts": { "why": "t3_environment_read returns this machine's facts beside upstream's fields, for an agent choosing a machine (placement design row P3, facts out): hostResources (CPU, cores, memory; the result field of upstream PR #34293, closed there unmerged) and the fork's placement (declared labels, and running agents, slots free and the memory floor read from the agent slot gate's status, or available false with a reason when the gate cannot be read), all from fork/environmentFacts.ts. A linked machine's read is forwarded as before and returns that machine's facts.", - "added": [], - "announced": { - "since": "2026-11-21", - "added": [ - "import * as EnvironmentFacts from \"../../../fork/environmentFacts.ts\"; // Fork (P3): facts out", - "...(yield* EnvironmentFacts.read), // Fork (P3): facts out" - ] - } + "added": [ + "import * as EnvironmentFacts from \"../../../fork/environmentFacts.ts\"; // Fork (P3): facts out", + "...(yield* EnvironmentFacts.read), // Fork (P3): facts out" + ] }, "apps/server/src/mcp/toolkits/environment/tools.ts": { "why": "t3_environment_read's result schema takes the two optional fork fields hostResources and placement (fork/environmentFacts.ts, placement design row P3), so a linked machine's facts decode here and a machine on an older T3 that leaves them out still decodes (no facts). Result fields are not in the advertised tool list the context budget measures, so the budget is unchanged.", - "added": [], - "announced": { - "since": "2026-11-21", - "added": [ - "import * as EnvironmentFacts from \"../../../fork/environmentFacts.ts\"; // Fork (P3): facts out", - "...EnvironmentFacts.ResultFields, // Fork (P3): facts out" - ] - } + "added": [ + "import * as EnvironmentFacts from \"../../../fork/environmentFacts.ts\"; // Fork (P3): facts out", + "...EnvironmentFacts.ResultFields, // Fork (P3): facts out" + ] } }, "//pending": "Upstream files whose fork lines predate counting every upstream file, each with its ceiling: the most fork lines it may hold against upstream (counted from upstream, as fork-follow runs the check). To move into fork files or pin as seams; lower a ceiling when lines move out and take a file off when none are left. A pull request may change them but not grow them.", diff --git a/FORK_CHANGES.md b/FORK_CHANGES.md index d8024da2ddcf7..37c7f0635e058 100644 --- a/FORK_CHANGES.md +++ b/FORK_CHANGES.md @@ -22,6 +22,7 @@ setting is missing here or a setting named here does not exist. | Usage pacing: a reserve of each limit window kept free for the person, and an even pace for agents. | Agents should not use up a subscription before its owner needs it. | `server.usagePacing` | off | [#52](https://github.com/scuttletoby/t3code/pull/52) | | The pacing gate on `delegate_task`: advise only, or move, lower the effort of, or hold a task on an account that is ahead of pace. | Delegated work follows the pace without the agent having to check. | `server.usagePacingGate`, `server.usagePacingLowerEffort` | off | [#73](https://github.com/scuttletoby/t3code/pull/73) | | Agent slots: `delegate_task` is refused above a number of running agents per machine or account, or below a memory floor. | Too many agents at once can overload a small machine. | `server.agentSlots` | off; rule only observes | [#84](https://github.com/scuttletoby/t3code/pull/84), [#89](https://github.com/scuttletoby/t3code/pull/89) | +| Machine facts: `t3_environment_read` also returns `hostResources` (CPU, cores, memory; the field of upstream PR #34293, closed there unmerged) and `placement` (labels, available and reason, running agents, slots free, memory floor, facts time), for this machine and a linked one. | An agent choosing where to run work can see which machine has room without asking the person. | none | always | [#779](https://github.com/scuttletoby/t3code/pull/779) | | Waits: agents can wait for a pull request, a file, a system unit, a named check command or a free agent slot (`wait_for`, `wait_list`, `wait_cancel`), and are woken when it happens. | An agent no longer polls or sleeps while it waits. | `server.waitFor`, `server.waitChecks`, `projectOverride.waitChecks` | off | [#84](https://github.com/scuttletoby/t3code/pull/84), [#90](https://github.com/scuttletoby/t3code/pull/90), [#91](https://github.com/scuttletoby/t3code/pull/91), [#103](https://github.com/scuttletoby/t3code/pull/103), [#106](https://github.com/scuttletoby/t3code/pull/106), [#109](https://github.com/scuttletoby/t3code/pull/109), [#110](https://github.com/scuttletoby/t3code/pull/110), [#116](https://github.com/scuttletoby/t3code/pull/116), [#119](https://github.com/scuttletoby/t3code/pull/119) | | Delegated results: `task_list` lists a thread's delegated tasks whose result it has not read, and its running children per place from live status; a parent whose finished child's result never arrived gets one reminder. | A finished child's result can no longer sit unseen. | `server.waitFor` (the reminder) | off; `task_list` always (read only) | [#622](https://github.com/scuttletoby/t3code/pull/622), [#641](https://github.com/scuttletoby/t3code/pull/641) | | The Settings page **Fork** (`/settings/fork`): every fork setting in one place, with one line per feature at the top saying whether it is on: waits, wait checks, agent slots, usage pacing (per account by name), model policy, review rules, automatic updates, handoff and playtest. MCP profiles are not on it yet. | Change every fork setting without editing a file. | `server.waitFor`, `server.waitChecks`, `server.agentSlots`, `server.usagePacing`, `server.usagePacingGate`, `server.usagePacingLowerEffort`, `server.reviewRules`, `server.modelPolicy`, `server.automaticUpdates`, `server.automaticUpdatesQuietCommand`, `server.handoff`, `server.playtest` | off | [#104](https://github.com/scuttletoby/t3code/pull/104), [#543](https://github.com/scuttletoby/t3code/pull/543), [#544](https://github.com/scuttletoby/t3code/pull/544) | diff --git a/apps/server/src/fork/environmentFacts.linked.test.ts b/apps/server/src/fork/environmentFacts.linked.test.ts new file mode 100644 index 0000000000000..645cd2787a0c2 --- /dev/null +++ b/apps/server/src/fork/environmentFacts.linked.test.ts @@ -0,0 +1,203 @@ +/** + * Fork (placement row P3): `t3_environment_read` naming a linked machine returns that machine's + * facts over a real link; one on an older T3 leaves them out (no facts, never a failed read). + */ +import { NodeHttpServer } from "@effect/platform-node"; +import * as NodeCrypto from "@effect/platform-node/NodeCrypto"; +import * as NodeServices from "@effect/platform-node/NodeServices"; +import { expect, it } from "@effect/vitest"; +import { ProviderInstanceId, ServerSettings, ThreadId } from "@t3tools/contracts"; +import * as Context from "effect/Context"; +import * as Effect from "effect/Effect"; +import * as Layer from "effect/Layer"; +import * as Schema from "effect/Schema"; +import { McpSchema, McpServer } from "effect/ai"; + +import * as McpHttpServer from "../mcp/McpHttpServer.ts"; +import * as McpInvocationContext from "../mcp/McpInvocationContext.ts"; +import * as McpToolAccess from "../mcp/McpToolAccess.ts"; +import { liveThreadShell } from "../mcp/McpToolAccess.testkit.ts"; +import * as EnvironmentHandlers from "../mcp/toolkits/environment/handlers.ts"; +import { EnvironmentToolkit } from "../mcp/toolkits/environment/tools.ts"; +import * as ThreadCommandExecutor from "../orchestration-v2/ThreadCommandExecutor.ts"; +import * as ThreadManagement from "../orchestration-v2/ThreadManagementService.ts"; +import * as PeerForwarding from "../peer/PeerForwarding.ts"; +import * as PeerLinks from "../peer/PeerLinks.ts"; +import { + descriptorOf, + layerLinkingEnvironment, + linkTo, + servePeer, +} from "../peer/PeerLinks.testkit.ts"; +import * as HostResources from "../resourceTelemetry/HostResources.ts"; +import * as Settings from "../serverSettings.ts"; +import * as SlotGate from "../slots/SlotGate.ts"; + +const laptop = descriptorOf("environment-laptop", "Laptop"); +const box = descriptorOf("environment-box", "Box"); +const fromFile = Schema.decodeUnknownSync(ServerSettings); + +const hostResourcesOf = (cpuCount: number) => ({ + sampledAt: 1_700_000_000_000, + cpuUtilization: 0.25, + cpuCount, + availableMemoryBytes: 8 * 1024 ** 3, + totalMemoryBytes: 16 * 1024 ** 3, +}); + +/** + * One machine's sampler, slot gate and settings: `maxPerMachine` slots, `used` of them in use. A + * served peer's requests carry its own settings service, which wins over this one there. + */ +const layerMachine = (cpuCount: number, maxPerMachine: number, used: number) => + Layer.mergeAll( + Layer.mock(HostResources.HostResources)({ read: Effect.succeed(hostResourcesOf(cpuCount)) }), + Layer.mock(SlotGate.SlotGate)({ + usage: Effect.succeed({ + machine: { used, max: maxPerMachine }, + accounts: [], + freeMemoryMb: 8192, + }), + }), + Layer.mock(Settings.ServerSettingsService)({ + getSettings: Effect.succeed( + fromFile({ linkedEnvironmentsEnabled: true, agentSlots: { enabled: true, maxPerMachine } }), + ), + }), + ); + +const layerCallerThreads = Layer.mock(ThreadManagement.ThreadManagementService)({ + getThreadShell: (threadId) => Effect.succeed(liveThreadShell(threadId)), +}); + +/** The environment toolkit as a T3 from before P3 serves it: identity and preferences only. */ +const layerOlderEnvironmentHandlers = McpToolAccess.toLayer(EnvironmentToolkit, { + t3_environment_read: McpToolAccess.reads(() => + Effect.gen(function* () { + const settings = yield* Settings.ServerSettingsService; + return { + environmentId: box.environmentId, + label: box.label, + serverVersion: box.serverVersion, + platform: box.platform, + preferences: EnvironmentHandlers.preferences( + yield* settings.getSettings.pipe(Effect.orDie), + ), + }; + }), + ), + t3_environment_preferences_update: McpToolAccess.writesEnvironment(() => + Effect.die("not called"), + ), +}); + +/** The box's `/mcp` with the environment toolkit, behind its real OAuth. */ +const serveBox = (older: boolean) => + servePeer( + box, + McpHttpServer.toolkitRegistration( + EnvironmentToolkit, + older ? layerOlderEnvironmentHandlers : EnvironmentHandlers.layer, + ).pipe( + Layer.provide(ThreadCommandExecutor.layer), + Layer.provide(layerCallerThreads), + Layer.provide(layerMachine(8, 4, 3)), + ), + ); + +const mcpClient = McpSchema.McpServerClient.of({ + clientId: 1, + protocolVersion: "2025-06-18", + clientCapabilities: {}, + clientInfo: { name: "environment-facts-test", version: "1" }, + initializePayload: { + protocolVersion: "2025-06-18", + capabilities: {}, + clientInfo: { name: "environment-facts-test", version: "1" }, + }, + getClient: Effect.die("unused"), +}); + +/** The laptop: the environment toolkit with forwarding, called from one of its threads. */ +const makeLaptop = Effect.gen(function* () { + const linking = yield* layerLinkingEnvironment(laptop).pipe(Layer.build); + const here = yield* McpHttpServer.toolkitRegistration( + EnvironmentToolkit, + EnvironmentHandlers.layer, + ).pipe( + Layer.provideMerge(McpHttpServer.layerInProcessMcpServer), + Layer.provide(ThreadCommandExecutor.layer), + Layer.provide(PeerForwarding.layer), + Layer.provide(layerMachine(4, 2, 0)), + Layer.provide(Layer.succeedContext(linking)), + Layer.provide(layerCallerThreads), + Layer.provide(NodeCrypto.layer), + Layer.provide(NodeServices.layer), + Layer.fresh, + Layer.build, + ); + const server = Context.get(here, McpServer.McpServer); + const read = (environmentId: string) => + server.callTool({ name: "t3_environment_read", arguments: { environmentId } }).pipe( + Effect.provideService(McpInvocationContext.McpInvocationContext, { + environmentId: laptop.environmentId, + requestNamespace: "provider-session:thread:laptop", + thread: { + threadId: ThreadId.make("thread:laptop"), + providerSessionId: "provider-session:thread:laptop", + providerInstanceId: ProviderInstanceId.make("codex"), + }, + client: undefined, + capabilities: new Set(["orchestration" as const]), + issuedAt: 1, + }), + Effect.provideService(McpSchema.McpServerClient, mcpClient), + ); + return { links: Context.get(linking, PeerLinks.PeerLinks), read }; +}); + +it.effect("a linked machine's read carries that machine's hostResources and placement", () => + Effect.scoped( + Effect.gen(function* () { + const b = yield* serveBox(false); + // The box's own settings, as its server reads them for each request. + yield* b.settings.updateSettings({ agentSlots: { enabled: true, maxPerMachine: 4 } }); + const a = yield* makeLaptop; + yield* linkTo(a.links, b, "auto"); + + const there = yield* a.read(box.environmentId); + expect(there.isError).toBe(false); + expect(there.structuredContent).toMatchObject({ + environmentId: box.environmentId, + hostResources: hostResourcesOf(8), + placement: { labels: [], available: true, runningAgents: 3, slotsFree: 1 }, + }); + expect( + (there.structuredContent as { placement: { factsAt: unknown } }).placement.factsAt, + ).toBeTypeOf("number"); + + const here = yield* a.read(laptop.environmentId); + expect(here.structuredContent).toMatchObject({ + environmentId: laptop.environmentId, + hostResources: hostResourcesOf(4), + placement: { labels: [], available: true, runningAgents: 0, slotsFree: 2 }, + }); + }), + ).pipe(Effect.provide(NodeHttpServer.layerTest)), +); + +it.effect("a linked machine on an older T3 leaves the facts out: no facts, not a failure", () => + Effect.scoped( + Effect.gen(function* () { + const b = yield* serveBox(true); + const a = yield* makeLaptop; + yield* linkTo(a.links, b, "auto"); + + const there = yield* a.read(box.environmentId); + expect(there.isError).toBe(false); + expect(there.structuredContent).toMatchObject({ environmentId: box.environmentId }); + expect(there.structuredContent).not.toHaveProperty("hostResources"); + expect(there.structuredContent).not.toHaveProperty("placement"); + }), + ).pipe(Effect.provide(NodeHttpServer.layerTest)), +); diff --git a/apps/server/src/fork/environmentFacts.test.ts b/apps/server/src/fork/environmentFacts.test.ts new file mode 100644 index 0000000000000..a67db83b913ef --- /dev/null +++ b/apps/server/src/fork/environmentFacts.test.ts @@ -0,0 +1,276 @@ +/** + * Fork (placement design row P3, facts out): `t3_environment_read` on this machine returns + * `hostResources` (an upstream pull request's field) and the fork's `placement`, through upstream's real + * environment handlers. A linked machine's read is in `environmentFacts.linked.test.ts`. + */ +import { expect, it } from "@effect/vitest"; +import { EnvironmentId, ProviderInstanceId, ServerSettings, ThreadId } from "@t3tools/contracts"; +import * as Deferred from "effect/Deferred"; +import * as Duration from "effect/Duration"; +import * as Effect from "effect/Effect"; +import * as Fiber from "effect/Fiber"; +import * as Layer from "effect/Layer"; +import * as Schema from "effect/Schema"; +import * as Stream from "effect/Stream"; +import * as TestClock from "effect/testing/TestClock"; + +import * as Environment from "../environment/ServerEnvironment.ts"; +import * as McpInvocationContext from "../mcp/McpInvocationContext.ts"; +import * as McpToolAccess from "../mcp/McpToolAccess.ts"; +import { liveThreadShell } from "../mcp/McpToolAccess.testkit.ts"; +import * as EnvironmentHandlers from "../mcp/toolkits/environment/handlers.ts"; +import { EnvironmentToolkit } from "../mcp/toolkits/environment/tools.ts"; +import * as ThreadCommandExecutor from "../orchestration-v2/ThreadCommandExecutor.ts"; +import * as ThreadManagement from "../orchestration-v2/ThreadManagementService.ts"; +import * as HostResources from "../resourceTelemetry/HostResources.ts"; +import * as Settings from "../serverSettings.ts"; +import * as SlotGate from "../slots/SlotGate.ts"; +import * as EnvironmentFacts from "./environmentFacts.ts"; + +const environmentId = EnvironmentId.make("environment:facts"); +const threadId = ThreadId.make("thread:facts"); +const fromFile = Schema.decodeUnknownSync(ServerSettings); + +const SLOTS_ON = fromFile({ + agentSlots: { enabled: true, maxPerMachine: 3, minFreeMemoryMb: 512 }, +}); + +const host = { + sampledAt: 1_700_000_000_000, + cpuUtilization: 0.25, + cpuCount: 8, + availableMemoryBytes: 4096 * 1024 * 1024, + totalMemoryBytes: 16 * 1024 ** 3, +}; + +const usageOf = (used: number, freeMemoryMb = 4096): SlotGate.SlotUsage => ({ + machine: { used, max: 3 }, + accounts: [], + freeMemoryMb, +}); + +interface World { + /** The slot gate's status read; `"missing"`: no gate on this server. */ + readonly usage?: Effect.Effect | "missing"; + /** `"missing"`: no host sampler on this server. */ + readonly host?: "missing"; + /** + * `"unreadable"`: the settings file can no longer be read once upstream's part of the read has + * read it (upstream's read fails the whole call when its own settings read fails). + */ + readonly settings?: ServerSettings | "unreadable"; +} + +const settingsGoneAfterFirstRead = () => { + let reads = 0; + return Effect.suspend(() => + ++reads === 1 + ? Effect.succeed(SLOTS_ON) + : Effect.fail({ _tag: "ServerSettingsError" } as never), + ); +}; + +const layerWorld = (world: World) => + Layer.mergeAll( + ThreadCommandExecutor.layer, + Layer.succeed(McpInvocationContext.McpInvocationContext, { + environmentId, + requestNamespace: "provider:facts", + thread: { + threadId, + providerSessionId: "provider:facts", + providerInstanceId: ProviderInstanceId.make("codex"), + }, + client: undefined, + capabilities: new Set(["orchestration" as const]), + issuedAt: 0, + }), + Layer.mock(ThreadManagement.ThreadManagementService)({ + getThreadShell: () => Effect.succeed(liveThreadShell(threadId)), + }), + Layer.mock(Environment.ServerEnvironment)({ + getDescriptor: Effect.succeed({ + environmentId, + label: "Facts", + platform: { os: "linux", arch: "x64" }, + serverVersion: "0.0.0", + capabilities: { repositoryIdentity: false }, + }), + }), + Layer.mock(Settings.ServerSettingsService)({ + getSettings: + world.settings === "unreadable" + ? settingsGoneAfterFirstRead() + : Effect.succeed(world.settings ?? SLOTS_ON), + }), + world.host === "missing" + ? Layer.empty + : Layer.mock(HostResources.HostResources)({ read: Effect.succeed(host) }), + world.usage === "missing" + ? Layer.empty + : Layer.mock(SlotGate.SlotGate)({ usage: world.usage ?? Effect.succeed(usageOf(1)) }), + ); + +/** Calls the tool as the MCP server does: the handler's result, then its JSON encoding. */ +const readFacts = (world: World) => + Effect.gen(function* () { + const toolkit = yield* EnvironmentToolkit; + const results = yield* toolkit + .handle("t3_environment_read", {}) + .pipe(Stream.unwrap, Stream.runCollect); + const last = results.at(-1)!; + expect(last.isFailure).toBe(false); + return last.encodedResult as { + readonly hostResources?: unknown; + readonly placement?: Record; + }; + }).pipe( + Effect.provide( + McpToolAccess.HandlersLayer.layer(EnvironmentHandlers.layer).pipe( + Layer.provideMerge(layerWorld(world)), + ), + ), + ); + +it.effect("this machine's read carries hostResources and placement, with the facts time", () => + Effect.gen(function* () { + yield* TestClock.setTime(1_800_000_000_000); + const result = yield* readFacts({}); + expect(result.hostResources).toEqual(host); + expect(result.placement).toEqual({ + labels: [], + available: true, + runningAgents: 1, + slotsFree: 2, + memoryFloorMb: 512, + freeMemoryMb: 4096, + factsAt: 1_800_000_000_000, + }); + }), +); + +it.effect("a slot gate that cannot count says unavailable with a reason, never slots free", () => + Effect.gen(function* () { + for (const usage of [ + Effect.succeed(null), + Effect.die("the thread list read crashed"), + // Longer than the gate's own read may take: the read gives up and says so. + Effect.never, + ]) { + const fiber = yield* readFacts({ usage }).pipe(Effect.forkChild); + yield* TestClock.adjust(Duration.seconds(7)); + const { placement } = yield* Fiber.join(fiber); + expect(placement).toMatchObject({ + available: false, + reason: EnvironmentFacts.REASON_GATE_UNREAD, + }); + expect(placement).not.toHaveProperty("slotsFree"); + expect(placement).not.toHaveProperty("runningAgents"); + expect(placement?.factsAt).toBeTypeOf("number"); + } + }), +); + +it.effect("no slot gate, or settings that cannot be read, give no count either", () => + Effect.gen(function* () { + const missing = yield* readFacts({ usage: "missing" }); + expect(missing.placement).toEqual({ + labels: [], + available: false, + reason: EnvironmentFacts.REASON_GATE_MISSING, + factsAt: 0, + }); + const unreadable = yield* readFacts({ settings: "unreadable" }); + expect(unreadable.placement).toEqual({ + labels: [], + available: false, + reason: EnvironmentFacts.REASON_SETTINGS_UNREAD, + factsAt: 0, + }); + }), +); + +it.effect("slots off (an empty or missing settings file) count nothing and limit nothing", () => + Effect.gen(function* () { + for (const settings of [fromFile({}), fromFile({ agentSlots: { enabled: false } })]) { + const { placement } = yield* readFacts({ settings, usage: Effect.die("not asked") }); + expect(placement).toEqual({ + labels: [], + available: true, + reason: EnvironmentFacts.REASON_SLOTS_OFF, + factsAt: 0, + }); + } + }), +); + +it.effect("a full machine, or one below its memory floor, is not available", () => + Effect.gen(function* () { + const full = yield* readFacts({ usage: Effect.succeed(usageOf(4)) }); + expect(full.placement).toMatchObject({ + available: false, + reason: EnvironmentFacts.REASON_FULL, + runningAgents: 4, + slotsFree: 0, + }); + const low = yield* readFacts({ usage: Effect.succeed(usageOf(1, 100)) }); + expect(low.placement).toMatchObject({ + available: false, + reason: EnvironmentFacts.REASON_LOW_MEMORY, + slotsFree: 2, + freeMemoryMb: 100, + memoryFloorMb: 512, + }); + const noLimit = yield* readFacts({ + settings: fromFile({ agentSlots: { enabled: true, maxPerAccount: { codex: 2 } } }), + usage: Effect.succeed({ ...usageOf(1), machine: { used: 1, max: null } }), + }); + expect(noLimit.placement).toMatchObject({ + available: true, + slotsFree: null, + memoryFloorMb: null, + }); + }), +); + +it.effect("no host sampler leaves hostResources out; placement still comes", () => + Effect.gen(function* () { + const result = yield* readFacts({ host: "missing" }); + expect(result).not.toHaveProperty("hostResources"); + expect(result.placement).toMatchObject({ available: true, slotsFree: 2 }); + }), +); + +it.effect("runs again: the same shape, measured again each time", () => + Effect.gen(function* () { + let asked = 0; + const usage = Effect.sync(() => usageOf(++asked)); + const first = yield* readFacts({ usage }); + yield* TestClock.adjust(Duration.seconds(30)); + const second = yield* readFacts({ usage }); + expect(Object.keys(second).toSorted()).toEqual(Object.keys(first).toSorted()); + expect(Object.keys(second.placement!).toSorted()).toEqual( + Object.keys(first.placement!).toSorted(), + ); + expect(first.placement).toMatchObject({ runningAgents: 1, slotsFree: 2, factsAt: 0 }); + expect(second.placement).toMatchObject({ runningAgents: 2, slotsFree: 1, factsAt: 30_000 }); + }), +); + +it.effect("a read stopped half-way leaves nothing behind: the next one reads afresh", () => + Effect.gen(function* () { + const asked = yield* Deferred.make(); + let calls = 0; + const usage = Effect.suspend(() => + ++calls === 1 + ? Deferred.succeed(asked, undefined).pipe(Effect.andThen(Effect.never)) + : Effect.succeed(usageOf(2)), + ); + const stopped = yield* readFacts({ usage }).pipe(Effect.forkChild); + yield* Deferred.await(asked); + yield* Fiber.interrupt(stopped); + const next = yield* readFacts({ usage }); + expect(calls).toBe(2); + expect(next.placement).toMatchObject({ available: true, runningAgents: 2, slotsFree: 1 }); + }), +); diff --git a/apps/server/src/fork/environmentFacts.ts b/apps/server/src/fork/environmentFacts.ts new file mode 100644 index 0000000000000..59b6f198d70ea --- /dev/null +++ b/apps/server/src/fork/environmentFacts.ts @@ -0,0 +1,116 @@ +/** + * Fork (placement row P3): the facts `t3_environment_read` returns beside upstream's fields, both + * optional ("Machine facts on t3_environment_read" in docs/fork/README.md). Slot facts come only + * from the gate's status read; a gate that cannot be read gives a reason, never a count. + */ +import { HostResourcesSnapshot, NonNegativeInt } from "@t3tools/contracts"; +import * as Clock from "effect/Clock"; +import * as Duration from "effect/Duration"; +import * as Effect from "effect/Effect"; +import * as Option from "effect/Option"; +import * as Schema from "effect/Schema"; + +import * as HostResources from "../resourceTelemetry/HostResources.ts"; +import * as Settings from "../serverSettings.ts"; +import * as SlotGate from "../slots/SlotGate.ts"; + +/** + * Placement facts. Every field but `labels`, `available` and `factsAt` is optional, so a machine on + * a newer or older fork build that adds or drops one still decodes here. + */ +export const Placement = Schema.Struct({ + /** Declared facts, typed once in that machine's Settings. Empty until that setting exists (P2). */ + labels: Schema.Array(Schema.String), + /** + * Whether the slot gate would take one more agent on this machine now. `false` also when the + * gate cannot be read: then no count is given, only `reason`. + */ + available: Schema.Boolean, + /** Why `available` is what it is, when the counts alone do not say it. */ + reason: Schema.optionalKey(Schema.String), + /** Agents running, starting or holding a slot here, as the slot gate counts them. */ + runningAgents: Schema.optionalKey(NonNegativeInt), + /** Machine slots left before the gate refuses; `null`: no machine limit is set. */ + slotsFree: Schema.optionalKey(Schema.NullOr(NonNegativeInt)), + /** The free memory the gate keeps (`agentSlots.minFreeMemoryMb`); `null`: none set. */ + memoryFloorMb: Schema.optionalKey(Schema.NullOr(NonNegativeInt)), + /** Free memory the gate measured with the counts, in MB. */ + freeMemoryMb: Schema.optionalKey(Schema.NullOr(NonNegativeInt)), + /** When these facts were read (ms since the epoch). */ + factsAt: NonNegativeInt, +}); +export type Placement = typeof Placement.Type; + +/** Spread into `t3_environment_read`'s success struct. */ +export const ResultFields = { + hostResources: Schema.optionalKey(HostResourcesSnapshot), + placement: Schema.optionalKey(Placement), +}; + +/** The gate's own read waits up to `COUNT_READ_TIMEOUT`; one second more, then it is unread. */ +const USAGE_READ_TIMEOUT = Duration.sum(SlotGate.COUNT_READ_TIMEOUT, Duration.seconds(1)); + +export const REASON_GATE_MISSING = "The agent slot gate is not running on this machine."; +export const REASON_GATE_UNREAD = + "The agent slot gate could not count the agents here now, so no slot count is given."; +export const REASON_SETTINGS_UNREAD = + "This machine's settings could not be read, so no slot count is given."; +export const REASON_SLOTS_OFF = + "Agent slots are off on this machine: it sets no limit and does not count its agents."; +export const REASON_FULL = "Every machine slot is in use."; +export const REASON_LOW_MEMORY = "Free memory is below the floor the slot gate keeps."; + +const unavailable = (reason: string) => ({ available: false, reason }) as const; + +/** The slot facts, read once; never fails, never dies. */ +const slotFacts = Effect.gen(function* () { + const gate = yield* Effect.serviceOption(SlotGate.SlotGate); + if (Option.isNone(gate)) return unavailable(REASON_GATE_MISSING); + const settingsService = yield* Effect.serviceOption(Settings.ServerSettingsService); + const settings = Option.isNone(settingsService) + ? Option.none() + : yield* settingsService.value.getSettings.pipe(Effect.option); + if (Option.isNone(settings)) return unavailable(REASON_SETTINGS_UNREAD); + const agentSlots = settings.value.agentSlots; + if (!agentSlots.enabled) return { available: true, reason: REASON_SLOTS_OFF } as const; + const usage = yield* gate.value.usage.pipe(Effect.timeoutOption(USAGE_READ_TIMEOUT)); + // `usage` is null while slots are off (checked above) or when its counts cannot be read. + if (Option.isNone(usage) || usage.value === null) return unavailable(REASON_GATE_UNREAD); + const { machine, freeMemoryMb } = usage.value; + const slotsFree = machine.max === null ? null : Math.max(0, machine.max - machine.used); + const memoryFloorMb = agentSlots.minFreeMemoryMb > 0 ? agentSlots.minFreeMemoryMb : null; + const lowMemory = memoryFloorMb !== null && freeMemoryMb !== null && freeMemoryMb < memoryFloorMb; + const reason = slotsFree === 0 ? REASON_FULL : lowMemory ? REASON_LOW_MEMORY : undefined; + return { + available: reason === undefined, + ...(reason === undefined ? {} : { reason }), + runningAgents: machine.used, + slotsFree, + memoryFloorMb, + freeMemoryMb, + }; +}).pipe(Effect.catchCause(() => Effect.succeed(unavailable(REASON_GATE_UNREAD)))); + +/** + * The facts for this machine's `t3_environment_read`. `hostResources` is left out when the host + * sampler is not there or its read fails; `placement` is always given. + */ +export const read = Effect.gen(function* () { + const host = yield* Effect.serviceOption(HostResources.HostResources); + const hostResources = Option.isNone(host) + ? Option.none() + : yield* host.value.read.pipe( + Effect.asSome, + Effect.catchCause(() => Effect.succeedNone), + ); + const slots = yield* slotFacts; + const placement: Placement = { + labels: [], + ...slots, + factsAt: yield* Clock.currentTimeMillis, + }; + return { + ...(Option.isSome(hostResources) ? { hostResources: hostResources.value } : {}), + placement, + }; +}).pipe(Effect.withSpan("EnvironmentFacts.read")); diff --git a/apps/server/src/mcp/toolkits/environment/handlers.ts b/apps/server/src/mcp/toolkits/environment/handlers.ts index fb1716885d6e8..dd6eb8f66022f 100644 --- a/apps/server/src/mcp/toolkits/environment/handlers.ts +++ b/apps/server/src/mcp/toolkits/environment/handlers.ts @@ -1,6 +1,7 @@ import { OrchestratorMcpFailure, type ServerSettings } from "@t3tools/contracts"; import * as Effect from "effect/Effect"; import * as Environment from "../../../environment/ServerEnvironment.ts"; +import * as EnvironmentFacts from "../../../fork/environmentFacts.ts"; // Fork (P3): facts out import * as ThreadCommandExecutor from "../../../orchestration-v2/ThreadCommandExecutor.ts"; import * as Settings from "../../../serverSettings.ts"; import * as McpInvocationContext from "../../McpInvocationContext.ts"; @@ -51,6 +52,7 @@ export const layer = McpToolAccess.toLayer(EnvironmentToolkit, { serverVersion: descriptor.serverVersion, platform: descriptor.platform, preferences: preferences(current), + ...(yield* EnvironmentFacts.read), // Fork (P3): facts out }; }), ), diff --git a/apps/server/src/mcp/toolkits/environment/tools.ts b/apps/server/src/mcp/toolkits/environment/tools.ts index 9e10380295de2..597a7f648d867 100644 --- a/apps/server/src/mcp/toolkits/environment/tools.ts +++ b/apps/server/src/mcp/toolkits/environment/tools.ts @@ -10,6 +10,7 @@ import { import * as Schema from "effect/Schema"; import { Tool, Toolkit } from "effect/ai"; import * as ServerEnvironment from "../../../environment/ServerEnvironment.ts"; +import * as EnvironmentFacts from "../../../fork/environmentFacts.ts"; // Fork (P3): facts out import * as ThreadCommandExecutor from "../../../orchestration-v2/ThreadCommandExecutor.ts"; import * as ThreadManagementService from "../../../orchestration-v2/ThreadManagementService.ts"; import * as Settings from "../../../serverSettings.ts"; @@ -49,6 +50,7 @@ const EnvironmentReadTool = Tool.make("t3_environment_read", { serverVersion: Schema.String, platform: ExecutionEnvironmentDescriptor.fields.platform, preferences: Schema.Struct(PreferenceFields), + ...EnvironmentFacts.ResultFields, // Fork (P3): facts out }), }) .annotate(Tool.Readonly, true) diff --git a/docs/fork/README.md b/docs/fork/README.md index d4a0f9d89faf0..2f665a8af690d 100644 --- a/docs/fork/README.md +++ b/docs/fork/README.md @@ -1011,6 +1011,35 @@ An early draft had a client setting for one "anchor machine" for new work. It wa shipped: upstream's load balancing does the same. Settings saved with it still load. See [anchor-machine.md](anchor-machine.md). +## Machine facts on `t3_environment_read` + +Placement design row P3 ("facts out"). `t3_environment_read` returns two optional fields beside +upstream's, for this machine and for a linked one (the read is forwarded there as before): + +- `hostResources`: CPU load, cores and memory, the snapshot the app's load balancing already + samples. This is the result field of upstream PR #34293, which was closed upstream without + merging; the fork carries the field (same name and schema) from its own file, + `apps/server/src/fork/environmentFacts.ts`. Not carried as it was: its export in + `McpHttpServer.ts`, its test lines in upstream's test files and its new tool description, since + the fork adds no lines to those files (its tests are in fork test files instead), and the tool's + dependency on the sampler (the fork's file finds it, and the slot gate, without one, so no + upstream test needs a new mock). +- `placement`: `labels` (facts typed once in that machine's Settings, such as owner logins; no + setting holds them yet, so they are empty until placement row P2 adds it), `available` and + `reason`, and, from the agent slot gate's own status read (the one `wait_list` shows): + `runningAgents` (running, starting or holding a slot), `slotsFree` (`null`: no machine limit), + `memoryFloorMb` (`agentSlots.minFreeMemoryMb`, `null`: none) and `freeMemoryMb`. `factsAt` is + when they were read. `available` is `false` when every machine slot is in use or free memory is + below the floor. With `agentSlots` off it is `true`, with a reason and no counts: the machine sets + no limit and does not count its agents. + +When the slot gate cannot be read (its count read fails or takes longer than its own limit, the +gate is not running, or the settings cannot be read), `placement` says `available: false` with a +reason and gives no count, so an agent never sees a guessed "slots free". A linked machine on an +older T3 leaves both fields out, which means "no facts", never a failed read. Nothing is stored: +each read measures again. The fields are part of the tool's result, not of the tool list an agent +loads, so the tool context budget is unchanged. + ## Install the fork today There is no one-line installer for the fork yet: `t3.codes/install.sh` and upstream's docs install