get_nexus_info and a server-side attention roll-up #155
Labels
No labels
bug
duplicate
enhancement
help wanted
invalid
question
wontfix
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
lz/agent-nexus#155
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
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/statephase, quota, and the fleet-wide attention roll-up.The roll-up is the work
nexus/src/lib/attention.tsderives 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.
stopWorkerwritesworkers.statusand never touches a session row, so every session of a deliberately stopped workspace still readsstatus: '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, neverhealth.claudeRunning. The field is three-valued, and its'unknown'arm (container gone, session row gone) shipsclaudeRunning: falseas a placeholder rather than an observation — so the boolean turns "we could not look" into "claude is dead". It also decides the opposite way fromunhealthyReasoninSessions.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
erroredexcept when the row reportedended, which onlySessionEndcan say and which never fires for a crash. The converse matters as much: a live claude makes anendedreport stale, so it is ignored rather than believed.attention_statebeing 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
convergeSessionsnulls 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_limitsis an absent key until the first inference call;context_window.used_percentageisnullwhile its siblingtotal_input_tokensis0; per-session cost is simply missing after a Nexus restart. A quota window whoseresets_athas passed is unknown, not zero —getAccountQuotaprunes 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.
#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):
nexus/src/lib/server/mcp/tools/. Nothing there may importregistry.ts— the cycle is aReferenceErrorunder Rollup and silentlyundefinedunder esbuild, and neither build warns.nameis typed`nexus_${string}`, so this isnexus_get_status, notget_nexus_info.annotationsrequires all four hints explicitly. This one isreadOnly: true, destructive: false, idempotent: true, openWorld: false.outputSchemais mandatory, andrunreturns the payload typed against it. Note the SDK validatesstructuredContentagainst it on every call, and a mismatch comes back asisError: truecontent on a 200 — not a JSON-RPC error — so assertisErrorexplicitly or a broken tool passes.Worked example:
mcp/tools/workspaces.ts.Two decisions taken since this was filed:
Trim the contents to
needs_you[]andquota. Nophase, nounlocked, no workspace counts. The first two are setup-flow concepts a token holder cannot act on, and the counts duplicatenexus_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_sessionstakesworkspaceas optional since #174, so one call sees the fleet.The roll-up itself is unchanged and is still the work.
mcpSessiondeliberately ships the rawattention_statewithnulldocumented 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:
convergeSessionsnulls attention for a workspace that is not running, so seeded rows lose it within a poll. A run that seedsneeds-youand reads backnullis the backend working correctly.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:
sessionMarkfrom$lib/attention. That is legal and already precedented —mcp/projection.tsimportsisRunningfrom$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 nophase, nounlockedand no workspace counts — the counts duplicatenexus_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.