Skip to content

Placement P3 (facts out): t3_environment_read returns hostResources and placement - #820

Merged
scuttletoby merged 2 commits into
mainfrom
fork/placement-p3-facts-out
Nov 22, 2026
Merged

scuttletoby merged 2 commits into
mainfrom
fork/placement-p3-facts-out

Conversation

@scuttletoby

Copy link
Copy Markdown
Owner

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 feat(server): let agents read host CPU and memory load through t3_environment_read pingdotgg/t3code#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.

Tests

New fork test files apps/server/src/fork/environmentFacts.test.ts and environmentFacts.linked.test.ts (this machine, a linked machine, an older linked T3, a slot gate that fails / dies / times out / is not running, unreadable settings; each read measures again, nothing stored).

General vs project

General: the facts are generic host facts for any fleet; no project names, paths or machines. Project facts (labels) come later from settings (P2).

Upstream fit

Builds on upstream t3_environment_read and the HostResources shape from an upstream PR that closed without merging (same name and schema); the only upstream-file lines are the four seam lines announced and pinned in #779.

Placement design P3, step 2 (code after the seam PR #779).

🤖 Generated with Claude Code

…nd 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 pingdotgg#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 <noreply@anthropic.com>
@scuttletoby

Copy link
Copy Markdown
Owner Author

Lens

Verdict: SAFE (head a2660ce). Normal tier, one lens (correctness, public/secret, state, seam, tests).

Blocking: none.

Major: none.

Minor (follow-ups, none blocks the merge):

  1. FORK_CHANGES.md:25: the new "Machine facts" row links only fork seams: announce the t3_environment_read facts lines (placement P3, step 1) #779 (the seam PR). The code is in Placement P3 (facts out): t3_environment_read returns hostResources and placement #820, so it should link Placement P3 (facts out): t3_environment_read returns hostResources and placement #820 (and fork seams: announce the t3_environment_read facts lines (placement P3, step 1) #779 if wanted).
  2. apps/server/src/fork/environmentFacts.ts:76 and docs/fork/README.md:1039: every t3_environment_read now runs SlotGate.usage. That is a full thread-list count (up to 5 s), a wait-store read and clearUsedLater, plus a host sample (200 ms on a cache miss). The worst case is about 6 s, even for a caller who only wants preferences. Also, "Nothing is stored" is true for the facts, but usage can clear used-up holds in the wait store. This is the same existing upkeep wait_list does, and it is safe to stop half-way (the keys stay in usedLater until the next clear). Suggest wording such as "nothing new is stored".
  3. environmentFacts.ts:102-104: the hostResources read has no timeout of its own. In practice it is bounded (200 ms sleep, local /proc and cgroup reads, macOS vm_stat capped at 1 s), so this is a note only.
  4. available covers the machine only. It ignores per-account limits (maxPerAccount), so an agent can see available: true and still have delegate_task refused for a full account. The docs say "on this machine". Consider one sentence saying so in the README.
  5. Tests: SlotGate.usage is always a mock. No test drives the real gate into a count read that times out and returns null, which the facts then report as REASON_GATE_UNREAD. The real gate's null-on-unread is covered by SlotGate's own tests, so the risk is low. A link that drops mid-forward is not tested here, but that is upstream's forwarding path, unchanged.

Checked and OK:

  • Wiring in the real server. The handler finds SlotGate and HostResources with Effect.serviceOption. Both are in the runtime context that /mcp handlers run in: ForkLayers.layerRuntimeServices for the gate and layerResourceDiagnostics (provideMerge) for the host sampler. This is the same lookup delegateChecks.ts already uses for delegate_task, and ForkLayers.layerRoutes already requires the gate to be present beside /mcp. So production does not silently fall back to "gate not running".
  • Facts match the gate. slotsFree = max(0, max - used). The memory floor uses MiB on both sides (BYTES_PER_MB = 1024*1024) with the same strict < comparison. enabled + mode:"observe" still enforces limits, and the facts treat it that way. Slots off (enabled:false, the default) gives available:true with a reason and no counts, which matches a gate that never refuses.
  • A gate that cannot be read. Each of these gives available:false, the right reason, and no count: usage returns null, dies, or never returns (timeoutOption at 5 s + 1 s; the gate's own read is interruptible under uninterruptibleMask/restore); no gate; settings unreadable on the second read. catchCause turns everything else into the "unread" reason. No count is ever made up.
  • Linked machine. The forwarded result is decoded with the local success schema. Both fields are optionalKey, so an older peer decodes with no facts and the read does not fail (tested over a real link with OAuth). Extra fields from a newer peer are ignored on decode.
  • Encoding. minFreeMemoryMb and maxPerMachine are NonNegativeInt in settings, and freeMemoryMb is floored from a value clamped at 0 or more. A strange settings value cannot make the result fail to encode and break upstream's read.
  • Public/secret. Results are numbers, fixed reason strings and labels: []. Error causes are dropped, not echoed. Host facts are the same snapshot upstream's WS serverGetHostResources already serves. No paths, hostnames, env or tokens.
  • State. Each read measures again. Nothing is cached beyond HostResources' existing 5 s cache, and nothing new is stored (tested: two reads in a row, and a read stopped half-way followed by a fresh read). The only fiber forked is the gate's existing shared count read, which its own timeout interrupts. Nothing hangs without a limit.
  • Seam. The upstream files (handlers.ts, tools.ts) gain exactly the four lines pinned and announced in fork seams: announce the t3_environment_read facts lines (placement P3, step 1) #779, and the announced entries move to added unchanged. node .github/scripts/fork-seam-check.cjs --no-upstream origin/main HEAD says only pinned seams. The other files are fork files.
  • Tests. src/fork/environmentFacts.test.ts (8 passed) and src/fork/environmentFacts.linked.test.ts (2 passed), each run on its own via heavy in a clean worktree of a2660ce. Both import the new environmentFacts.ts, so both fail on the old code.

# Conflicts:
#	.github/fork-seams.json
#	FORK_CHANGES.md
@scuttletoby
scuttletoby merged commit 7d7dd59 into main Nov 22, 2026
40 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant