get_nexus_info and a server-side attention roll-up #155

Closed
opened 2026-09-15 18:24:45 +02:00 by lz · 2 comments
Owner

The tool that answers "is anything waiting on me?" from a phone without opening Nexus. Arguably the highest-value tool in the set, and the only one needing new derivation rather than a wrapper over an existing service call.

Depends on #154. Scope: nexus:read.

Contents

/api/state phase, quota, and the fleet-wide attention roll-up.

The roll-up is the work

nexus/src/lib/attention.ts derives a session's mark client-side today and only ever paints the web UI. Exposing it is what makes the tool useful.

It has three inputs, and the third is the one people drop (AGENTS.md fact #26): the roster row, its health probe, and whether the workspace is running at all. stopWorker writes workers.status and never touches a session row, so every session of a deliberately stopped workspace still reads status: 'running' while its probe reports the container down. Derived without the third input, a workspace stopped on purpose reports its whole fleet entry as failing.

Read health.health, never health.claudeRunning. The field is three-valued, and its 'unknown' arm (container gone, session row gone) ships claudeRunning: false as a placeholder rather than an observation — so the boolean turns "we could not look" into "claude is dead". It also decides the opposite way from unhealthyReason in Sessions.svelte, which gates on the same field.

Within a running workspace the split is: the probe owns whether claude is alive, attention owns what a live agent is doing. An absent claude stays errored except when the row reported ended, which only SessionEnd can say and which never fires for a crash. The converse matters as much: a live claude makes an ended report stale, so it is ignored rather than believed.

attention_state being null is not idle — it means the feature has not reported yet.

Structure

Lift the derivation so client and server share one implementation, rather than reimplementing it server-side. A second copy will diverge, and the failure is a phone that disagrees with the browser about whether you are needed — which is worse than no tool at all.

Note convergeSessions nulls attention for a workspace that is not running, so seeded or fake rows lose their state within a poll. Stub the roster when testing.

Unknown is not falsy

Three signals in this area disagree and none may be inferred from a falsy value (fact #19): rate_limits is an absent key until the first inference call; context_window.used_percentage is null while its sibling total_input_tokens is 0; per-session cost is simply missing after a Nexus restart. A quota window whose resets_at has passed is unknown, not zero — getAccountQuota prunes it as a read-time filter, and the tool must serialize that as unknown rather than fabricating a number.

Done when

Asking Claude "does anything need me?" from a phone gives the same answer the sidebar gives in a browser, including for a deliberately stopped workspace, and the shared derivation is proven by a test that fails if either side is changed alone.

The tool that answers **"is anything waiting on me?"** from a phone without opening Nexus. Arguably the highest-value tool in the set, and the only one needing new derivation rather than a wrapper over an existing service call. Depends on #154. Scope: `nexus:read`. ## Contents `/api/state` phase, quota, and the **fleet-wide attention roll-up**. ## The roll-up is the work `nexus/src/lib/attention.ts` derives a session's mark client-side today and only ever paints the web UI. Exposing it is what makes the tool useful. **It has three inputs, and the third is the one people drop** (AGENTS.md fact #26): the roster row, its health probe, and **whether the workspace is running at all**. `stopWorker` writes `workers.status` and never touches a session row, so every session of a deliberately stopped workspace still reads `status: 'running'` while its probe reports the container down. Derived without the third input, a workspace stopped on purpose reports its whole fleet entry as failing. **Read `health.health`, never `health.claudeRunning`.** The field is three-valued, and its `'unknown'` arm (container gone, session row gone) ships `claudeRunning: false` as a *placeholder* rather than an observation — so the boolean turns "we could not look" into "claude is dead". It also decides the opposite way from `unhealthyReason` in `Sessions.svelte`, which gates on the same field. Within a running workspace the split is: the **probe** owns whether claude is alive, **attention** owns what a live agent is doing. An absent claude stays `errored` *except* when the row reported `ended`, which only `SessionEnd` can say and which never fires for a crash. The converse matters as much: a live claude makes an `ended` report stale, so it is ignored rather than believed. `attention_state` being null is **not** idle — it means the feature has not reported yet. ## Structure Lift the derivation so client and server share one implementation, rather than reimplementing it server-side. A second copy will diverge, and the failure is a phone that disagrees with the browser about whether you are needed — which is worse than no tool at all. Note `convergeSessions` nulls attention for a workspace that is not running, so seeded or fake rows lose their state within a poll. Stub the roster when testing. ## Unknown is not falsy Three signals in this area disagree and none may be inferred from a falsy value (fact #19): `rate_limits` is an **absent key** until the first inference call; `context_window.used_percentage` is **`null`** while its sibling `total_input_tokens` is `0`; per-session cost is simply **missing** after a Nexus restart. A quota window whose `resets_at` has passed is **unknown**, not zero — `getAccountQuota` prunes it as a read-time filter, and the tool must serialize that as unknown rather than fabricating a number. ## Done when Asking Claude "does anything need me?" from a phone gives the same answer the sidebar gives in a browser, including for a deliberately stopped workspace, and the shared derivation is proven by a test that fails if either side is changed alone.
lz added this to the MCP support (#140) milestone 2026-09-15 18:24:45 +02:00
Author
Owner

#174 put the tool surface on a contract. Four things this issue now has to follow, and three of them are compile errors rather than review comments (AGENTS.md fact #40):

  • The tool is a file under nexus/src/lib/server/mcp/tools/. Nothing there may import registry.ts — the cycle is a ReferenceError under Rollup and silently undefined under esbuild, and neither build warns.
  • name is typed `nexus_${string}`, so this is nexus_get_status, not get_nexus_info.
  • annotations requires all four hints explicitly. This one is readOnly: true, destructive: false, idempotent: true, openWorld: false.
  • outputSchema is mandatory, and run returns the payload typed against it. Note the SDK validates structuredContent against it on every call, and a mismatch comes back as isError: true content on a 200 — not a JSON-RPC error — so assert isError explicitly or a broken tool passes.

Worked example: mcp/tools/workspaces.ts.

Two decisions taken since this was filed:

Trim the contents to needs_you[] and quota. No phase, no unlocked, no workspace counts. The first two are setup-flow concepts a token holder cannot act on, and the counts duplicate nexus_list_workspaces — which is worse than redundant, because two reads at two moments can disagree.

The N+1 that made a counts field look necessary is already gone. nexus_list_sessions takes workspace as optional since #174, so one call sees the fleet.

The roll-up itself is unchanged and is still the work. mcpSession deliberately ships the raw attention_state with null documented as never reported, not idle — add the derived mark as a separate, clearly named field rather than by redefining that one.

One trap for the live check, from #174's: convergeSessions nulls attention for a workspace that is not running, so seeded rows lose it within a poll. A run that seeds needs-you and reads back null is the backend working correctly.

#174 put the tool surface on a contract. Four things this issue now has to follow, and three of them are compile errors rather than review comments (AGENTS.md fact #40): - The tool is a file under `nexus/src/lib/server/mcp/tools/`. Nothing there may import `registry.ts` — the cycle is a `ReferenceError` under Rollup and silently `undefined` under esbuild, and neither build warns. - `name` is typed ``` `nexus_${string}` ```, so this is **`nexus_get_status`**, not `get_nexus_info`. - `annotations` requires all four hints explicitly. This one is `readOnly: true, destructive: false, idempotent: true, openWorld: false`. - `outputSchema` is mandatory, and `run` returns the payload typed against it. Note the SDK **validates `structuredContent` against it on every call**, and a mismatch comes back as `isError: true` content on a 200 — not a JSON-RPC error — so assert `isError` explicitly or a broken tool passes. Worked example: `mcp/tools/workspaces.ts`. Two decisions taken since this was filed: **Trim the contents to `needs_you[]` and `quota`.** No `phase`, no `unlocked`, no workspace counts. The first two are setup-flow concepts a token holder cannot act on, and the counts duplicate `nexus_list_workspaces` — which is worse than redundant, because two reads at two moments can disagree. **The N+1 that made a counts field look necessary is already gone.** `nexus_list_sessions` takes `workspace` as optional since #174, so one call sees the fleet. The roll-up itself is unchanged and is still the work. `mcpSession` deliberately ships the **raw** `attention_state` with `null` documented as *never reported, not idle* — add the derived mark as a separate, clearly named field rather than by redefining that one. One trap for the live check, from #174's: `convergeSessions` nulls attention for a workspace that is not running, so seeded rows lose it within a poll. A run that seeds `needs-you` and reads back `null` is the backend working correctly.
Author
Owner

The fleet status layer (#177) absorbs the hard half of this.

The attention roll-up needs three inputs — the roster row, the health probe, and whether the workspace is running at all (fact #26) — and the fleet store is the first place that holds all three server-side. Today the derivation is client-only, which is exactly why this issue reads as "needs the fleet-wide attention roll-up, which is its real work".

Two consequences for how this gets built:

  • Derive the mark server-side and put it on the wire, by importing sessionMark from $lib/attention. That is legal and already precedented — mcp/projection.ts imports isRunning from $lib/workspace-state. It also deletes the client's probe scheduler rather than duplicating the derivation for MCP.
  • attention.test.ts's generated parity suite must be re-established against the new signature, not assumed unaffected. It currently pins the derivation against the pre-feature function across every health shape; a signature change that leaves it passing without exercising the new path is this repo's named defect shape.

The trimmed scope in the tool-surface artifact still stands: needs_you[] plus quota, with no phase, no unlocked and no workspace counts — the counts duplicate nexus_list_workspaces, which is worse than redundant because two reads at two moments can disagree.

Quota also moves into the store, so get_nexus_info's two halves come from one place.

The fleet status layer (#177) absorbs the hard half of this. The attention roll-up needs three inputs — the roster row, the health probe, and whether the workspace is running at all (fact #26) — and the fleet store is the first place that holds all three **server-side**. Today the derivation is client-only, which is exactly why this issue reads as "needs the fleet-wide attention roll-up, which is its real work". Two consequences for how this gets built: - **Derive the mark server-side and put it on the wire**, by importing `sessionMark` from `$lib/attention`. That is legal and already precedented — `mcp/projection.ts` imports `isRunning` from `$lib/workspace-state`. It also deletes the client's probe scheduler rather than duplicating the derivation for MCP. - **`attention.test.ts`'s generated parity suite must be re-established against the new signature**, not assumed unaffected. It currently pins the derivation against the pre-feature function across every health shape; a signature change that leaves it passing without exercising the new path is this repo's named defect shape. The trimmed scope in the tool-surface artifact still stands: `needs_you[]` plus quota, with no `phase`, no `unlocked` and no workspace counts — the counts duplicate `nexus_list_workspaces`, which is worse than redundant because two reads at two moments can disagree. Quota also moves into the store, so `get_nexus_info`'s two halves come from one place.
lz closed this issue 2026-09-23 18:45:16 +02:00
Sign in to join this conversation.
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
lz/agent-nexus#155
No description provided.