@plurnk/plurnk-mcp 1.7.0 → 1.9.0

package/SPEC.md

@@ -9,23 +9,34 @@ executor, resource, proposal, entry, Problem, and lifecycle contracts.
 
 ## §mcp-authority Protocol authority
 
-The only accepted revision is `2026-07-28`, specification commit
+The host's own wire authority is revision `2026-07-28`, specification commit
 `5f5440bb26a62e2cf3440b92da5a667efa03b267`. The implementation exact-pins
 `@modelcontextprotocol/client@2.0.0`. SDK exports are not protocol authority:
 that package deliberately retains legacy and deprecated API shapes. It owns
 core negotiation and transport; this package owns only exact-pinned extension
 wire that the SDK does not yet implement.
 
-The optional Tasks authority is the official `experimental-ext-tasks` contract
-at commit `2c1425d9a288b9b1f489430fe1e00bb392b47e48`. Its absence from the current
-SDK runtime does not revive that SDK's retained 2025 Tasks vocabulary.
+Connection setup negotiates-and-degrades. A server that negotiates the pinned
+revision and offers `server/discover` is a **modern** peer: it gets the complete
+extension wire (the `_meta` envelope, `resultType`, the Tasks extension) and its
+discover result is the identity and capability source. A server the SDK
+negotiated below the pin is an ordinary MCP peer: it serves the standard
+tool/resource/prompt surface from its `initialize` result at its negotiated
+revision, and the host applies no envelope, discover, or Tasks requirements to
+it. There is no rejection for offering an older supported revision and no
+protocol downgrade of the host's own extension wire: modern peers and legacy
+peers simply carry different surfaces.
 
-Every request carries the modern `_meta` envelope. Connection setup verifies
-`server/discover` at the pinned revision before publishing any runtime or
-scheme. There is no protocol downgrade or legacy fallback.
+The optional Tasks authority is the official `experimental-ext-tasks` contract
+at commit `2c1425d9a288b9b1f489430fe1e00bb392b47e48`. It is negotiated
+per-connection and absent from a legacy peer.
 
 ## §mcp-core-matrix Core capability matrix
 
+The accountable capability matrix lives in `capabilityMatrix.ts`
+({§mcp-capability-matrix}); this section states the core surface contract the
+matrix rows cite.
+
 | Surface | Upstream contract | Plurnk host disposition |
 |---|---|---|
 | Base | JSON-RPC 2.0; per-request protocol, identity, and capability metadata; every result has `resultType` | Require the modern envelope and preserve protocol results and errors without reconstructing them |
@@ -58,6 +69,26 @@ Polling honors each current `pollIntervalMs` under the one owning operation
 deadline. Task input keys are fulfilled at most once, in one atomic client
 interaction per observed input set. A completed Task is validated as the
 originating tool result; a failed Task preserves its JSON-RPC error.
+Handle ownership and the restart journey are bounded in {§tasks-lifetime}.
+
+## §tasks-lifetime Tasks lifetime and re-run
+
+Task handles are owned in-process by the connection and operation that created
+them; Plurnk deliberately declines durable task-handle recovery. A durable
+handle would need a persisted scheduler and a home for a result whose owning
+operation does not outlive the daemon; the ordinary Plurnk journey is that a
+restart re-runs the operation, which drives a fresh task. The server's own
+persistence of task state is respected only within one connection lifetime;
+nothing task-shaped is written to SQLite and no MCP sidecar lifecycle exists.
+
+| Boundary | Behaviour |
+|---|---|
+| Client disconnect | The daemon-owned operation and its task keep running; the client reattaches to the operation, not the task. |
+| Daemon restart | The connection and every in-flight task handle die with it; the tool call fails like any interrupted operation, the loop re-runs, and the tool call creates a fresh task. |
+| Worker reactivation | The attachment reconstructs from its durable definition; in-flight tasks on the replaced connection are abandoned, not resumed. |
+| Expiry | The owning operation deadline bounds polling; a non-converging task fails at the standard round bound and is cancelled. |
+| Cancellation | Owner abort cancels the task before settling; the handle is then terminal. |
+| Already terminal | Terminal results and errors are consumed by the drive loop; a completed or failed task is never re-polled or re-resumed. |
 
 ## §mcp-exclusions Removed, deprecated, and excluded surfaces
 
@@ -71,9 +102,29 @@ originating tool result; a failed Task preserves its JSON-RPC error.
 | Removed | `resources/subscribe`, `resources/unsubscribe`, SSE resumption and `Last-Event-ID` | Use `subscriptions/listen`; reissue a lost request with a new ID |
 | Removed | Legacy Tasks `tasks/list`, `tasks/result`, and task-augmentation request fields | Use only the negotiated final Tasks extension |
 | Excluded | Other official, experimental, or private extensions | Require a separately owned contract before negotiation |
-| Excluded | Legacy revisions and dual-era operation | Pin `2026-07-28`; never probe-and-fallback |
+| Excluded | Dual-era operation | Modern peers and legacy peers carry different surfaces; the host never mixes the two on one connection |
 | Excluded | MCP server and authorization-server roles | This package is the host/client only |
 
+## §mcp-capability-matrix Accountable capability matrix
+
+`capabilityMatrix.ts` is the one accountable support matrix: one row per core
+surface, official extension, or explicitly selected experimental candidate,
+carrying authority, disposition (supported, partial, excluded, deferred),
+advertisement, interactivity, and evidence citations. Rows are "supported"
+only when every layer their owning contract includes has real coverage; a row
+cannot claim support merely because the direct SDK or conformance path passes.
+Every evidence citation must resolve through a named specification tag or a
+named composed test.
+
+The static wire advertisement is derived from the matrix by construction
+(`staticClientCapabilities`): an extension reaches the wire only because its
+row says `always`, and a `conditional` extension is added only by its owning
+connection logic ({§oauth-client-credentials}). The matrix unit tests enforce
+unique identities, no excluded row advertising, supported rows citing evidence,
+composed coverage for interactive advertised rows, and exact reconciliation
+between the matrix and the derived advertisement. Official required
+conformance stays a separate named gate, never folded into a matrix row.
+
 ## §mcp-transports Transport bindings
 
 | Binding | Contract |
@@ -81,6 +132,11 @@ originating tool result; a failed Task preserves its JSON-RPC error.
 | stdio | Spawn one exact executable with an explicit argument array and no shell; newline-delimited JSON-RPC is the only stdout/stdin traffic; stderr is diagnostic; shutdown closes stdin, waits, then terminates if necessary |
 | Streamable HTTP | Send one POST per request or notification; accept JSON or SSE responses; close the response stream to cancel; never open the removed general GET stream |
 
+§mcp-stdio-process-ownership A stdio connection owns the complete process group
+created for its server. Ordinary closure forwards stdin EOF and permits a
+bounded graceful exit; an expired shutdown bound or disappearance of the host
+process forcibly terminates the group, including descendants.
+
 Every HTTP request carries matching `MCP-Protocol-Version` and `Mcp-Method`
 headers. Named requests also carry `Mcp-Name`; declared primitive tool
 parameters carry validated `Mcp-Param-*` headers. Header names compare
@@ -108,11 +164,23 @@ originating distinction in its canonical Problem/result path.
 
 ## §mcp-configuration Configuration
 
-Two inputs produce one effective definition per workspace. Service environment
-variables are convenience defaults instantiated independently for every
-workspace. The workspace's durable attachment map may add a server, replace a
-default, or retain a tombstone that suppresses a default after detach. Neither
-source expands the model-facing namespace with a second discovery surface.
+Service configuration and worker state produce one available set and one
+enabled subset per worker. Every `PLURNK_MCP_<server>` declares an available
+service-owned definition. `PLURNK_MCP_ENABLED` names the exact subset enabled
+when a worker has no override. Worker state may positively override a
+service definition's enabledness or own an added definition and its enabledness.
+Disabled definitions remain client-visible but contribute no connection,
+Registry, documentation, or resource authority.
+
+§mcp-activation-isolation **Cold endpoint failure is capability-local.** Invalid
+service configuration or durable state fails admission, but an enabled server
+that cannot connect or complete discovery during worker activation remains
+enabled and client-visible as `unavailable`. It publishes no runtime, tools,
+resources, or documentation and cannot prevent other capabilities or the daemon
+from starting or serving dormant workers. Enabling that already-enabled alias is an explicit reconnect
+attempt; failure preserves the unavailable snapshot, while success atomically
+replaces it. Interactive add and enable mutations continue to reject an
+unavailable candidate without changing durable state.
 
 | Variable | Contract |
 |---|---|
@@ -124,6 +192,10 @@ source expands the model-facing namespace with a second discovery surface.
 | `PLURNK_MCP_<server>_HEADERS` | JSON string map for supplementary HTTP headers |
 | `PLURNK_MCP_<server>_TOOLS` | Optional JSON array of exact enabled tool names; absent enables all listed server tools, while `[]` enables none |
 | `PLURNK_MCP_<server>_READ` | JSON string array forming an exact subset of enabled tools that the operator classifies as read-only; every other enabled tool retains the conservative `host` effect |
+| `PLURNK_MCP_<server>_SUMMARY` | Authored one-line server orientation ({§mcp-summary-derivation}) |
+| `PLURNK_MCP_<server>_<tool>_SUMMARY` | Authored one-line tool orientation; tool names fold the same way and may contain underscores |
+| `PLURNK_MCP_ENABLED` | JSON array of exact configured server aliases enabled by default; absent or `[]` enables none |
+| `PLURNK_MCP_EXPANDED` | JSON array subset of enabled servers whose complete tool tree also expands into the turn-0 tools survey ({§tools-resource-materialization}); absent or `[]` expands none |
 | `PLURNK_MCP_CONNECT_TIMEOUT` | Positive integer milliseconds |
 | `PLURNK_MCP_REQUEST_TIMEOUT` | Positive integer milliseconds |
 
@@ -135,9 +207,22 @@ executable string even when its path contains whitespace; arguments never hide
 inside it. Bearer authentication and a case-insensitive `Authorization` entry
 in `_HEADERS` are mutually exclusive.
 
+§mcp-summary-derivation **Every orientation line derives from authored
+metadata — never a container template.** The runtime declaration's summary
+resolves in order: the `_SUMMARY` companion, the server's own
+`serverInfo.description`, its display `title` (both spec metadata — a title
+like "Chrome DevTools MCP server" is already a one-liner), the first sentence
+of its `instructions` essay, then a factual tool-name list. Each tool's one-liner
+resolves: its `_<server>_<tool>_SUMMARY` companion, `annotations.title`, the
+first sentence of its `description` (capped), then the tool name. The family
+doc's Summary section and the survey row carry the server one-liner; the tool
+doc's Summary section IS the invocation form
+`EXEC [server] (tool) <!-- one-liner -->`, so the discovery row teaches the
+call ({§tools-resource-materialization}). Summary companions expand `${NAME}`
+references like every other companion.
+
 §mcp-definition-wire The contracts-owned `McpServerDefinition` JSON Schema is
-the one workspace action and durable-state shape. It is a closed discriminated
-union:
+the normalized durable definition shape. It is a closed discriminated union:
 
 | Transport / authorization | Required definition | Optional definition |
 |---|---|---|
@@ -147,7 +232,7 @@ union:
 | `http` + interactive OAuth / CIMD preferred | above plus `authorization: { type: "oauth", redirectUrl, clientMetadataUrl }` | `scope`; DCR remains the server-advertised fallback when CIMD is unavailable |
 | `http` + interactive OAuth / pre-registered | above plus `authorization: { type: "oauth", redirectUrl, clientId, clientSecret: "${NAME}" }` | `scope` |
 | `http` + interactive OAuth / DCR fallback only | above plus `authorization: { type: "oauth", redirectUrl }` | `scope` |
-| `http` + client credentials | above plus `authorization: { type: "client-credentials", clientId, clientSecret: "${NAME}" }` | `scope` |
+| `http` + client credentials | above plus `authorization: { type: "client-credentials", clientId, clientSecret: "${NAME}" }` | `scope`; `issuer` binds the credential to its authorization server ({§oauth-client-credentials}) |
 
 `tools` absent enables the complete listed set; `[]` enables none. `read` is an
 exact subset of the enabled set. A credential field is one complete symbolic
@@ -159,56 +244,182 @@ discovery state, and authorization callback state remain process-memory
 credentials; a restart reconstructs the attachment as authorization-required
 instead of writing secrets into SQLite.
 
-### §mcp-management-actions Workspace management
-
-Every action below declares `scope: "workspace"` under
-{§module-action-registration}. AG-UI binds its workspace; none accepts a
-workspace identifier in params.
+The contracts-owned `McpServerDefinition` is the exact definition one `add`
+accepts and the coordinator persists; a client composes it from its target
+(an absolute HTTP(S) URL selects Streamable HTTP, anything else is one exact
+stdio executable) and its options (`args`, `cwd`, `env`, `headers`,
+`authorization`, `tools`, `read`). The normalized definition rejects
+transport-inapplicable options before any connection work.
+
+§mcp-configuration-cascade MCP server configuration has one field-wise
+precedence order: service environment, then the Worker's durable definition.
+Arrays and maps replace their lower value instead of appending or merging.
+Client configuration is not a live layer: the contracts-owned
+`{§mcp-configuration-overlay}` enters only as the `configuration` of a
+`discover` query, is parsed by the same owner and path as service environment
+declarations, and yields inert candidates with client-configuration provenance
+({§mcp-discovery}); adding one persists a complete, normalized, unexpanded
+Worker definition. Thus later enablement needs neither the originating client
+nor its configuration file, and symbolic credentials remain resolvable only by
+the service at connection preparation.
+
+### §mcp-module The MCP family beneath the coordinator
+
+§mcp-management-actions MCP is one family of Worker Functionality
+({§functionality-coordinator}): the coordinator publishes `worker.mcp.list |
+discover | add | enable | disable | remove` and the model's `EXEC [mcp]`
+family with the common semantics, durable state, and publication; this module
+registers the family adapter and owns protocol truth beneath it. `available`
+is the service environment with its `PLURNK_MCP_ENABLED` defaults; `admit`
+validates one exact definition and binds the alias to its `name`; `prepare`
+connects the enabled set, reusing unchanged live attachments, and returns one
+executor family and resource facet per connected server, one outcome per alias
+(`active` with catalog detail — negotiated protocol version, server identity,
+capabilities, tool names, resource and prompt counts — `unavailable` with its
+exact Problem, or `authorization-required` with its URL), and a two-phase
+snapshot: `commit` closes connections the new set no longer uses and records
+pending authorizations; `abort` closes only what the attempt opened.
+
+Two protocol continuations remain MCP-registered worker actions beneath the
+common grammar:
 
 | Action | Parameters | Result / effect |
 |---|---|---|
-| `workspace.mcp.list` | none | Sorted effective server summaries: name, source, transport, connection/authorization state, negotiated identity/capabilities, enabled tools, and read subset. No credential values. |
-| `workspace.mcp.attach` | `server: McpServerDefinition` | Adds a name absent from the effective workspace. Preparation completes before publication. |
-| `workspace.mcp.replace` | `server: McpServerDefinition` | Replaces one effective definition under the same name; absence is 404. |
-| `workspace.mcp.detach` | `name` | Removes a workspace attachment or writes a tombstone for a service default, then removes its exact Registry, docs, and resource authority. |
-| `workspace.mcp.reconnect` | `name` | Builds a fresh connection from the existing unexpanded definition and atomically replaces the old connection after successful preparation. |
-| `workspace.mcp.oauth.complete` | `name`, `callbackUrl` | State- and issuer-validates one pending interactive callback through the SDK, completes connection preparation, then performs the originally requested attach, replace, or reconnect. |
-| `workspace.mcp.complete` | `server`, `ref`, `argument`; optional `context` | Requests negotiated prompt/resource-template argument completion for a client-owned interaction. |
-
-Expected preparation failures cross the action boundary as MCP-management
-Problems rather than generic AG-UI failures:
+| `worker.mcp.oauth.complete` | `alias`, `callbackUrl` | State- and issuer-validates one pending interactive callback through the SDK, completes connection preparation, and re-enables the alias through the coordinator ({§oauth-continuation}); the result is the common mutation result. |
+| `worker.mcp.complete` | `server`, `ref`, `argument`; optional `context` | Requests negotiated prompt/resource-template argument completion for a client-owned interaction. |
+
+§mcp-discovery Discovery is inert. `configuration` (a client's own
+`PLURNK_MCP_*` overlay) becomes candidates without connecting; `source` — an
+absolute HTTP(S) URL or one whitespace-separated command line — is probed at the
+negotiated revision for its catalog and released, yielding one candidate with
+direct-target provenance (an authorization challenge yields the candidate with
+that fact in its summary); a bare `query` requires a configured downstream
+registry and is `501 registry-not-configured` until one exists. No candidate
+is installed, persisted, enabled, or executed by discovery.
+
+Expected preparation failures cross the boundary as MCP-management Problems
+rather than generic failures; an explicit client action rejects them and a
+Worker's own accepted mutation publishes them as unavailable
+({§functionality-model-mutation}):
 
 | Endpoint condition | Problem |
 |---|---|
-| Definitively does not offer pinned `2026-07-28` through `server/discover` | `502 protocol-revision-unsupported`, non-retryable; names the server, required revision and method, and directs the operator to upgrade or replace the legacy endpoint |
-| Cannot connect or complete current discovery/catalog preparation | `502 server-unavailable`, retryable; names the server and transport without exposing credentials |
-
-Interactive preparation returns a successful pending result shaped as
-`{ status: 202, authorization: { url } }`; it publishes no candidate runtime.
-The action owner retains one pending candidate per `(workspace, name)` and a
-new request cancels and replaces it. Unrelated workspace changes remain
-authoritative while authorization is pending; drift of the same server fails
-completion with a conflict instead of replaying a stale workspace snapshot.
-`oauth.complete` accepts the complete
-callback URL so state, `code`, and `iss` remain one parsing unit. A missing,
-expired, mismatched, or replayed callback fails without exposing attacker-owned
-OAuth error text. It completes either pending hydration or the originally
-requested attach, replace, or reconnect. There is no callback HTTP endpoint,
-authority-root resource, or MCP-specific AG-UI route.
+| Cannot connect or complete discovery/catalog preparation at the negotiated revision | `502 server-unavailable`, retryable; names the server and transport without exposing credentials |
+| Client-credentials grant rejected by the authorization server | `502 oauth-client-credentials-failed`, non-retryable; names the server and client id, never the secret ({§oauth-client-credentials}) |
+
+§oauth-continuation Interactive preparation publishes the alias as enabled and
+`authorization-required` with its URL; it publishes no runtime. The adapter
+retains one pending candidate per `(worker, alias)` holding the challenged
+connection and one Worker residency lease; a new challenge for the alias
+supersedes and releases the previous one ({§oauth-lifetime}).
+`oauth.complete` accepts the complete callback URL so state, `code`, and
+`iss` remain one parsing unit; it finishes the pending connection's
+authorization, prepares its active attachment, and re-enables the alias through
+the coordinator, whose publication consumes the prepared attachment and
+releases the lease. A callback for a superseded attempt fails as invalid; a
+committed attachment that no longer matches the pending definition fails
+with a conflict instead of replaying a stale snapshot. A missing, expired,
+mismatched, or replayed callback fails without exposing attacker-owned OAuth
+error text.
+
+## §oauth-lifetime Interactive OAuth lifetime and reauthorization
+
+Interactive OAuth state is deliberately ephemeral and process-memory: client
+registration data, access and refresh tokens, the PKCE verifier, and pending
+state live only in the owning connection or pending candidate. Nothing
+OAuth-secret is written to SQLite; the durable worker state holds only the
+unexpanded definition ({§mcp-configuration}). There is no callback HTTP
+listener, authority-root resource, or daemon-side browser side channel: the
+client returns the complete callback URL through `worker.mcp.oauth.complete`
+so `state`, `code`, and `iss` remain one parsing unit. Reauthorization after a
+daemon restart is the intended journey, documented here rather than presented
+as an accidental failure.
+
+| Journey point | Behaviour |
+|---|---|
+| Pending authorization | One pending candidate per `(worker, alias)`; a new add or customized enable cancels and replaces it. A callback from a superseded attempt fails state validation instead of cross-completing. |
+| Client disconnect | Does not touch the pending candidate; it can still be completed, or replaced by a fresh request. |
+| Daemon restart during pending | The candidate is lost: nothing was durable, no attachment publishes, and `oauth.complete` answers `404 oauth-not-pending`. Start authorization again. |
+| Daemon restart after authorization | The durable definition rehydrates but tokens are gone; the attachment publishes `authorization-required` and enable returns a fresh `{ status: 202, authorization: { url } }`. The operator reauthorizes. |
+| Token expiry | An expired access token surfaces as one unauthorized response; the SDK re-acquires via `refresh_token` when one was issued, otherwise re-enters interactive authorization. |
+| Refresh | Happens only against the issuer bound during the original authorization; the refreshed token replaces the in-memory token. |
+| Worker disable/remove | Closes the attachment and clears its pending candidate; no durable secret deletion is needed because nothing secret is durable. |
+| Server replacement | Completion compares the pending candidate's expected definition with the current one; drift of the same server fails `409 oauth-target-conflict` instead of replaying a stale snapshot. |
+| Cross-authorization protection | Candidates are keyed by `(worker, alias)`; callback state, PKCE, and issuer are validated by the SDK against the attempt that created them, so no other worker, alias, or attempt can complete this authorization. |
+
+## §oauth-client-credentials Client-credentials grant adoption
+
+The `client-credentials` arm of `McpServerDefinition.authorization` adopts the
+official `io.modelcontextprotocol/oauth-client-credentials` extension's
+client-secret form faithfully: an MCP connection whose definition holds a
+client-credentials grant advertises the extension capability in
+`clientCapabilities.extensions`; connections without one never claim it. The
+grant uses `client_secret_basic` authentication with `grant_type
+client_credentials`. Scope from the definition's optional `scope` is passed to
+the token request. The credential itself is one complete symbolic environment
+reference (`clientSecret: "${NAME}"`), expanded only while preparing the
+connection; it is never stored in SQLite, logged, or echoed in Problems.
+
+| Aspect | Behaviour |
+|---|---|
+| Issuer binding | The definition's optional `issuer` is passed as the SDK provider's `expectedIssuer`, stamping the credential with its authorization server so SEP-2352 issuer checks refuse to send it elsewhere. Absent, the SDK's legacy no-binding behaviour applies. |
+| Token lifetime | Token refresh is 401-triggered by the SDK client: an expired access token surfaces as one unauthorized response, the provider re-fetches with the stored credential, and the request is retried. Proactive expiry scheduling is a client-internal optimization, not a wire requirement; Plurnk does not wrap the SDK with its own scheduler. |
+| Rotation | `clientSecret` resolution happens per connection preparation, so rotating the operator environment value takes effect on the next preparation of the server. |
+| Errors | A rejected grant crosses the action boundary as `502 oauth-client-credentials-failed`, non-retryable, naming the server and client id only; SDK OAuth error text is never echoed. Other connection failures keep the generic `server-unavailable` allocation. |
+
+Static credentials authorize application principals (service attachments, CI,
+daemons), not human users. Private-key JWT and static JWT assertions for
+client authentication are a declared non-goal; the specification permits a
+secret-only client and Plurnk declines the assertion arms. The interactive
+OAuth arm is the human-principal path ({§mcp-management-actions}); bearer
+remains the private-service/legacy transport credential.
+
+## §mcp-ema-deferral Enterprise-managed authorization deferral
+
+Plurnk does not advertise or implement
+`io.modelcontextprotocol/enterprise-managed-authorization`. The SDK supplies
+the wire steps (ID-JAG acquisition via RFC 8693 and the RFC 7523 JWT bearer
+grant); the extension's remaining responsibilities are enterprise deployment
+policy, not open-source host mechanics:
+
+| Responsibility | Ownership |
+|---|---|
+| Capability advertisement, ID-JAG and access-token exchange, scope-error handling | Public protocol responsibilities the SDK host could own |
+| SSO acquisition of the identity assertion (ID token or SAML) | Presumes a user session the headless daemon does not own |
+| Saving the identity assertion for later use | Durable identity material; conflicts with the credential policy — secrets have one owner, the operator environment, and never a durable store |
+| IdP endpoint and client registration configuration | Organization-owned; Plurnk has no org-level configuration seam |
+
+The conformance client declines the enterprise scenarios, the capability
+matrix keeps the extension non-advertised ({§mcp-capability-matrix}), and the
+extension stays separate from core OAuth and client-credentials reporting.
+Re-evaluate when an organization-owned configuration owner exists and a
+decision on durable identity material is ratified.
 
 ## §mcp-setup Atomic lifecycle
 
-For each workspace, hydration resolves service defaults against the durable
-attachment/tombstone map, opens and discovers every effective connection,
+When a cold worker is demanded, activation resolves service defaults and durable positive
+worker state, opens and discovers only enabled connections,
 lists the negotiated catalogs, applies enabled/effect policy, builds each exact
 tool Registry and resource facet, and submits one complete owner snapshot to
-{§module-workspace-capabilities}. A configured tool absent from the server, a
+{§module-worker-capabilities}. A configured tool absent from the server, a
 duplicate remote name, an enabled name not representable as a Plurnk target,
-or a `read` name outside the enabled set fails that workspace hydration. No
+or a `read` name outside the enabled set fails that worker activation. No
 partial namespace is published and every acquired candidate closes.
 
-Attach, replace, and reconnect prepare the candidate while the old snapshot
-remains authoritative, then commit only at {§module-workspace-quiescence}. The
+MCP participates in core Functionality residency ({§module-worker-residency}).
+Every tool call and Task retains the worker from executor entry through its
+terminal result; an interactive OAuth candidate retains it until completion,
+replacement, cancellation, or module shutdown. Catalog refresh timers are
+infrastructure, not residency owners: cooling serializes behind a refresh
+already running and cancels any timer not yet begun. At a lease-free quiescent
+boundary, deactivation removes the worker snapshot and closes all of its
+connections. Core separately withdraws the executor/scheme publication while
+preserving durable MCP state and generated reference entries for transparent
+reactivation.
+
+Add and enable prepare the candidate while the old snapshot remains
+authoritative, then commit only at {§module-worker-quiescence}. Disable and
+remove commit the complete reduced snapshot at the same boundary. The
 old connection rejects replacement while it owns an active protocol request,
 MRTR exchange, or Task. Cache/list-change watches are infrastructure and close
 with the old connection after the new snapshot commits. A failed candidate or
@@ -216,17 +427,19 @@ commit leaves the durable definition, connection, Registry, docs, and resource
 authority unchanged. Materialization and registration inspect the complete
 owning operation result; a non-success preserves its original Problem.
 
-Shutdown first prevents new work, cancels pending OAuth candidates and
-infrastructure watches, settles every active request and Task, closes every
-acquired connection, then reports all close failures. Whole-connection
-shutdown retires subscription work before closing its transport; it does not
-first issue a redundant per-listen cancellation.
+Shutdown first prevents new serialized work, cancels infrastructure watches,
+and closes every acquired connection—including a candidate still negotiating.
+That cancellation reaches pending OAuth, active requests, and Tasks. It then
+waits active mutations to settle, discards process-local snapshots, and reports
+every close failure. Whole-connection shutdown retires subscription work before
+closing its transport; it does not first issue a redundant per-listen
+cancellation.
 
 ## §mcp-host-composition Protocol-to-Plurnk composition
 
 One `ServerConnection` owns negotiation, SDK caches, authorization partition,
 subscriptions, active request controllers, MRTR rounds, and Tasks for one
-workspace attachment. The host does not reproduce SDK protocol machinery.
+worker attachment. The host does not reproduce SDK protocol machinery.
 
 | Protocol event | Plurnk composition |
 |---|---|
@@ -246,27 +459,62 @@ pending client-owned interaction exactly as proposal review does. MRTR round
 limits, request timeout, cancellation, and Task terminal state are one
 operation lifecycle; none becomes a hidden retry loop.
 
+## §mcp-result-content Passive result content
+
+Every passive content variant the modern revision defines — text, image,
+audio, resource links, and embedded text/blob resources — is preserved
+losslessly into the EXEC channel as one JSON value
+({§json-result-rendering}), the durable evidence path. Plurnk does not claim
+first-class client rendering of non-text variants and adds no MCP-only media
+envelopes: presentation is a client concern over ordinary typed
+entries/resources, and a text-only client degrades by rendering the JSON. A
+standalone `blob` content block is not a modern `tools/call` content member
+(blobs ride inside embedded blob resources) and is rejected as
+protocol-invalid. Size limits and MIME trust remain ordinary channel and
+entry policy, not MCP-specific rules.
+
+## §mcp-apps-exclusion MCP Apps exclusion
+
+Plurnk does not advertise or implement MCP Apps. An Apps host must sandbox
+render third-party HTML/JavaScript, enforce CSP and `_meta.ui` permissions,
+mediate a `postMessage` JSON-RPC `ui/` dialect, proxy app-initiated tool
+calls with consent, and own teardown. No Plurnk client can enforce that
+sandbox today (terminal and Neovim cannot), the daemon is not a second
+application platform, and AG-UI has no standard Apps projection — inventing
+a private event stream to carry Apps is rejected. Tool descriptions carrying
+`_meta.ui` metadata project into Plurnk without it: model-facing summaries
+derive only from name, description, title, and input schema, and no UI
+resource is fetched or preloaded. The capability matrix keeps the extension
+non-advertised ({§mcp-capability-matrix}). Re-evaluate only when a
+sandbox-capable client exists and a standard AG-UI projection is agreed;
+even then the capability would be per-client-advertised, never daemon-wide.
+
 ## §mcp-model-projection Model-facing projection
 
 | MCP surface | Plurnk surface |
 |---|---|
-| Server | One registered executor family and matching resource scheme |
-| Enabled tool | One exact Registered Tools row and `## EXEC0 [<server>] (<tool>)` call |
-| Enabled tool details | `worker://plurnk/docs/<server>.md` through the standard kernel documentation surface |
+| Server | One registered executor family, `worker://~/_plurnk/tools/<server>.md`, and matching resource scheme |
+| Enabled tool | One annotated call in the compact family document plus one exact `worker://~/_plurnk/tools/<server>/<encoded-tool>.md` input-contract document |
+| Tool survey | Ordinary FIND summary metadata from the standard executable-tool resource tree |
 | Resource catalog | `<server>:///` and `<server>:///resources` |
 | Resources | `<server>:///resources` and encoded resource-URI descendants |
 | Prompts | `<server>:///prompts` and encoded prompt-name descendants |
 
 §mcp-tool-presentation One canonical enabled-tool snapshot owns every
 model-facing and executable consequence. Each enabled remote tool becomes one
-exact target in {§executor-tool-registry}. Its Registered Tools row carries the
-remote description, requiredness derived from the input schema, and a
-deterministic one-line JSON-shaped signature: quoted property names, `?` on
-optional properties, primitive type words, and literal unions—never fabricated
-argument data. The snapshot's standard kernel document contains each enabled
-tool's description and exact input/output JSON Schemas. Disabled names appear
-in neither surface, and there is no MCP-specific FIND, READ, authority-root, or
-other model discovery mechanism for tools.
+exact target in {§executor-tool-registry}. Its standard
+{§executor-tool-document} carries the normalized remote description as Summary,
+requiredness derived from the input schema, and a deterministic one-line
+JSON-shaped invocation signature: quoted property names, `?` on optional
+properties, primitive type words, and literal unions—never fabricated argument
+data. The compact family document projects those same facts into annotated,
+copyable EXEC headings; each exact child additionally projects property-level
+input descriptions and standard constraints such as defaults, formats, ranges,
+lengths, and patterns. A missing remote description receives a deterministic
+server-and-tool summary rather than an invented capability claim. Output schemas
+do not enter model teaching; the returned value remains ordinary evidence. Disabled names
+appear in neither discovery nor admission, and there is no MCP-specific FIND,
+READ, authority-root, or other model discovery mechanism for tools.
 
 Core validates the exact target and the selected tool's invocation before
 effect admission. `McpExecutor.run()` independently rejects a target outside

package/dist/McpExecutor.d.ts

@@ -2,28 +2,53 @@ import { BaseExecutor } from "@plurnk/plurnk-execs";
 import type { ChannelDecl, Effect, ExecArgs, ExecResult, RuntimeAvailability, RuntimeDecl, RuntimeToolRegistry } from "@plurnk/plurnk-execs";
 import ServerConnection, { type ServerCatalog } from "./client.ts";
 import type { ToolPolicy } from "./config.ts";
-export declare const runtimeDecl: (name: string) => RuntimeDecl;
+export declare const serverSummary: (name: string, catalog: ServerCatalog | undefined, override: string | undefined) => string;
+export declare const runtimeDecl: (name: string, summary: string, expandTools: boolean) => RuntimeDecl;
 export default class McpExecutor extends BaseExecutor {
     #private;
     constructor(metadata: {
         runtime: string;
         glyph: string;
-    }, connection: ServerConnection, policy?: Partial<ToolPolicy>);
+    }, connection: ServerConnection, retainWorkspace: () => () => void, policy?: Partial<ToolPolicy>, toolSummaries?: ReadonlyMap<string, string>);
     get manifest(): {
         name: string;
+        authority?: import("@plurnk/plurnk-schemes").SchemeAuthority;
         channels: Record<string, string>;
         defaultChannel: string;
-        category: "data" | "logging" | "control";
         writableBy: ReadonlyArray<import("@plurnk/plurnk-schemes").WriterTier>;
         volatile: boolean;
         modelVisible: boolean;
         folderScopes?: boolean;
         textEditScopes?: boolean;
+        lineAnchors?: boolean;
         foldedByDefault?: boolean;
         flags?: import("@plurnk/plurnk-schemes").SchemeFlagAffinity;
         documentation?: string;
         glyph?: string;
         storedScheme?: string;
+        category: "data";
+        entryOwner: import("@plurnk/plurnk-schemes").SchemeEntryOwner;
+        inherit: import("@plurnk/plurnk-schemes").SchemeEntryInheritance;
+        example: string;
+    } | {
+        name: string;
+        authority?: import("@plurnk/plurnk-schemes").SchemeAuthority;
+        channels: Record<string, string>;
+        defaultChannel: string;
+        writableBy: ReadonlyArray<import("@plurnk/plurnk-schemes").WriterTier>;
+        volatile: boolean;
+        modelVisible: boolean;
+        folderScopes?: boolean;
+        textEditScopes?: boolean;
+        lineAnchors?: boolean;
+        foldedByDefault?: boolean;
+        flags?: import("@plurnk/plurnk-schemes").SchemeFlagAffinity;
+        documentation?: string;
+        glyph?: string;
+        storedScheme?: string;
+        category: "logging" | "control";
+        entryOwner?: never;
+        inherit?: never;
         example: string;
     };
     get channels(): Readonly<Record<string, ChannelDecl>>;

package/dist/McpExecutor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"McpExecutor.d.ts","sourceRoot":"","sources":["../src/McpExecutor.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,YAAY,EAMf,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EACR,WAAW,EACX,MAAM,EACN,QAAQ,EACR,UAAU,EAEV,mBAAmB,EACnB,WAAW,EACX,mBAAmB,EACtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,gBAAgB,EAAE,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAK9C,eAAO,MAAM,WAAW,SAAU,MAAM,KAAG,WASzC,CAAC;AAuBH,MAAM,CAAC,OAAO,OAAO,WAAY,SAAQ,YAAY;;IAOjD,YACI,QAAQ,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAC5C,UAAU,EAAE,gBAAgB,EAC5B,MAAM,GAAE,OAAO,CAAC,UAAU,CAAM,EAMnC;IAED,IAAa,QAAQ;;;;;;;;;;;;;;;;MAKpB;IAED,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAMpD;IAEQ,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAK7C;IAgCD,YAAY,IAAI,mBAAmB,CAKlC;IAED,IAAI,OAAO,IAAI,aAAa,CAK3B;IAEc,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAgBvE;IAEK,gBAAgB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAqBzE;IAEK,GAAG,CAAC,EACN,OAAO,EACP,IAAI,EACJ,MAAM,EACN,MAAM,EACN,KAAK,EACL,QAAQ,EACR,IAAI,EACJ,QAAQ,GACX,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CAiHhC;CACJ"}
+{"version":3,"file":"McpExecutor.d.ts","sourceRoot":"","sources":["../src/McpExecutor.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,YAAY,EAMf,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EACR,WAAW,EACX,MAAM,EACN,QAAQ,EACR,UAAU,EAEV,mBAAmB,EACnB,WAAW,EACX,mBAAmB,EACtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,gBAAgB,EAAE,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAkB9C,eAAO,MAAM,aAAa,SAChB,MAAM,WACH,aAAa,GAAG,SAAS,YACxB,MAAM,GAAG,SAAS,KAC7B,MAYF,CAAC;AAEF,eAAO,MAAM,WAAW,SAAU,MAAM,WAAW,MAAM,eAAe,OAAO,KAAG,WAchF,CAAC;AAuBH,MAAM,CAAC,OAAO,OAAO,WAAY,SAAQ,YAAY;;IASjD,YACI,QAAQ,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAC5C,UAAU,EAAE,gBAAgB,EAC5B,eAAe,EAAE,MAAM,MAAM,IAAI,EACjC,MAAM,GAAE,OAAO,CAAC,UAAU,CAAM,EAChC,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EAQ9C;IAED,IAAa,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAKpB;IAED,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAMpD;IAEQ,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAK7C;IAgCD,YAAY,IAAI,mBAAmB,CAKlC;IAED,IAAI,OAAO,IAAI,aAAa,CAK3B;IAEc,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAgBvE;IAEK,gBAAgB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAqBzE;IAEK,GAAG,CAAC,EACN,OAAO,EACP,IAAI,EACJ,MAAM,EACN,MAAM,EACN,KAAK,EACL,QAAQ,EACR,IAAI,EACJ,QAAQ,GACX,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CAoHhC;CACJ"}