Files
hyprland-headless-stream-pl…/docs/TODO/README.md
T
HermenixandClaude Opus 5 e636472106 docs(mcp)!: mcp-v2, and the two limits the SDK imposes on it
`docs/CONTRACT-mcp.md` goes to mcp-v2 with a change table at the top, because
v1 lasted a day and an agent that learned it deserves to be told what moved
rather than to discover it. The new §4 freezes the resource surface: the eight
URIs, their bodies, their query parameters, and the five rules the layer keeps
(a read never writes; only declared parameters; a literal route beats a
template; a frame's media type comes from its bytes; no subscriptions). §6
gains the other half of the error mapping -- for a resource read every exit
code arrives as `-32602` with the remedy in `message` and the structured object
in `data`, because `ReadResourceResult` has no `isError` to use instead.

§2 records what `--toolsets` is and is not: there is no grouping primitive in
MCP, the `Tool` object has nowhere to put a family, and tools are a flat list
in the specification too -- so the only lever is which tools the server lists,
decided by whoever spawns it.

README.md leads with the split rather than with a tool count, since that is the
thing a reader has to understand before any of the names make sense, and shows
the `--toolsets` form for a client with a tight budget. ARCHITECTURE.md's sixth
box grows its second half and says why `shot` is on both sides.

A second TODO, `mcp-resources-cannot-be-subscribed-to.md`, records the limit
that cost the most: `Server.get_capabilities` hardcodes
`ResourcesCapability(subscribe=False, …)`, so registering a
`subscribe_resource` handler changes nothing and a client is correctly told not
to try. Subscriptions would have been the principled answer to the missing
`logs --follow` -- it is the one place this design wanted a capability the SDK
will not advertise -- so the file names the one-line local override, says what
it risks, and recommends upstreaming the real fix.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 11:50:12 +00:00

2.4 KiB

TODO

Known, unfixed problems — each one real, none of them guessed at.

Each file answers three questions and stops:

  • The issue — what is actually wrong, with the evidence for it.
  • Ideas — more than one, and which one is the recommended route.
  • Why it matters — the impact, not the principle.
item severity state
cursor-visibility-in-captures high answered: the compositor draws no cursor for a virtual pointer. Needs a decision on an overlay marker
scroll-has-no-compositor-proof medium works live; unproven in a gate
reconcile-while-containers-are-off medium partly fixed: discovery now survives a restart; teardown still lives inside the feature
kill-can-leave-the-app-alive medium found by counting windows, not sessions
capture-binary-and-the-unit-path medium found the first time the app was run as a unit: a unit's PATH has no grim
mcp-in-process-has-no-call-deadline medium two costs of running the CLI in process: no killable deadline, and no sg recovery
mcp-resources-cannot-be-subscribed-to medium the SDK hardcodes subscribe=False, so a log resource can only be re-read

Closed since this folder was written:

  • "Containers do not bind" — fixed. Windows are assigned by the pid the compositor reports, moved onto their desk's workspace and read back. Two sessions now hold two outputs with a real browser on each.
  • "The pointer is unusable while containers are off" — fixed with it. The pointer aims at the session's desk, and desks hold applications.
  • "Discovery refuses when two compositor instances exist" — fixed. Each candidate is asked for its version and the one that answers is used.

Severity here means "how much of the feature is actually delivered", not "how loud the failure is". The highest is highest because a whole class of work is blocked on it: the pointer is exact and invisible, so nothing can show where anything happened.

When one of these is fixed, delete its file and the row — this folder is a list of what is still true, not a history of what was thought.