refactor(sdk): make plugin hook order explicit, and five composition fixes

[matej21]

Six independent fixes around plugin composition, each its own commit.

Plugin hook order was incidental. SessionManager.buildPlugins iterates plugins in plain array order, and most agent hooks stop at the first non-null result — so a literal array in bootstrap.ts silently decides who wins. .dependencies() looks like it might govern order, but it only exposes another plugin's methods.

Host-selected plugin profiles make that sharper. There are now three hand-maintained arrays — fullPlugins, isolatePlugins (a subset for hosts with no OS process table) and the test harness's own list — and a subset is exactly where two hosts start running the same plugins in a different relative sequence, silently.

A plugin now declares .order(n) and the session's plugins are sorted by it, so the array decides nothing. The sort is stable and everything undeclared defaults to 1000, which keeps preset-level and third-party plugins running after the built-ins in registration order. The built-ins declare 10…150 matching their current positions: today's effective order is unchanged for both profiles, and a test pins the ladder to the list so the two cannot drift apart. Ordering is declared per plugin rather than derived from .dependencies() — a data dependency is not the same claim as hook precedence, and a topological sort over the former would reorder plugins that never asked for it. A subset of a sorted ladder is sorted whatever a host drops, so the property survives profile selection by construction; a test asserts every profile's array is in ascending declared order, making the sort provably a no-op for both. The harness's duplicate list is gone — it imports fullPlugins instead. The profiles stay in bootstrap.ts, where they are tied to the RPC contract (BuiltinMethodSchemas derives from fullPlugins); splitting that pairing to consolidate elsewhere would be the worse trade.

The audit behind this change is in the commit message. Two findings worth surfacing here:

• The sharpest precedence conflict — limits-guard's pause against context-compact's compaction — is not decided by the built-in array. Neither plugin is in it; both are preset-only, so their order has always come from the preset author's own plugins: [...] literal.
• First-non-null-wins has a live consequence nobody had noticed: on a turn where the model emits <user> tags (in userCommunication: xml | both), user-chat's afterInference returns modify and the loop stops, so limits-guard's no-progress and repetition counters silently skip that turn.

Neither was reordered here — both need a deliberate behaviour decision and are left for a follow-up. The mechanism to express that decision now exists.

Also in this PR:

• sessions.getEvents read up to limit ?? 1000 events, returned limit ?? 100, and reported the end of the read window as lastIndex — so a caller who omitted limit skipped 900 events on the next poll. The cursor now describes the page actually returned. The read window stays wider than the page (max(limit ?? 1000, offset + limit)) so a type/agentId filter still scans deeply enough to fill one; narrowing it to the page would silently halve what a filtered read finds. Under a filter, offset counts matches while the window counts raw events, so no fixed window can guarantee a deep filtered page — that case is unchanged, not fixed.
• The agent turn number lived only in memory, seeded by counting assistant messages, so a compaction made it go backwards on the next reload. It is now persisted on AgentState and maintained by the reducer; old logs replay through the same reducer, so no migration. This changes the count for an attempt that commits nothing — a pause, or an inference failure — from 1,2,3 to 1,1,2: such an attempt re-runs on the same pending messages, so it is the same turn. A skipped inference still commits and still consumes a number, as before. Per-commit is also the only definition that can be persisted, since nothing is emitted when an attempt begins.
• defineAgent kept the sub-agent graph in a module-level WeakMap keyed by object identity, so spreading or cloning a definition silently dropped its children. The refs now ride on the value under a symbol key.
• The built-in event factories behind the public BuiltinEvent union are exported, so reacting to a built-in event no longer needs a deep src/ import.
• A WebSocket reconnect re-synced services and session state but not the chat, leaving messages — and unanswered questions — missing until a full reload. The refetch overwrites the message list, so a send still in flight (tracked in pendingMessages, not yet on the server) is carried over rather than dropped.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CbVWntVv8xSdtn6DC6ZApM