@plurnk/plurnk-mcp 3.2.1 → 3.3.0

package/README.md

@@ -132,7 +132,8 @@ PLURNK_MCP_forge_ENABLED=0
 
 HTTP authorization belongs in the complete definition. Bearer tokens and
 OAuth client secrets are symbolic `${NAME}` environment references, resolved
-only when preparing a connection; interactive grants remain in memory.
+only when preparing a connection; an interactive sign-in stays in memory until
+the daemon stops.
 See [`.env.defaults`](./.env.defaults) for all controls and
 [`SPEC.md`](./SPEC.md#mcp-configuration-configuration) for the contract.
 
@@ -186,26 +187,40 @@ client.
 HTTP servers support bearer references, client credentials, and interactive
 OAuth; stdio servers read their credentials from the environment. A server that
 challenges an anonymous connection comes up `authorization-required`, without
-publishing partial tools. A URL-only definition is sufficient; no callback
-port needs to be configured. The terminal client's `/mcp oauth <alias>` binds
-an available loopback port and calls `workspace.mcp.oauth.begin` before opening
-the returned authorization URL. A fixed OAuth redirect, if configured, is
-respected. Supplying the
-callback URL explicitly also works for remote/headless use. The client submits
-the complete URL through `workspace.mcp.oauth.complete`. Its `202` acknowledges
-sign-in; tools activate at the next safe workspace boundary, without another
-callback submission. `list` shows their current readiness. PKCE,
+publishing partial tools. One that answers its catalog anonymously and refuses a
+request instead goes `authorization-required` at that refusal, and the request
+fails with that code ({§mcp-request-unauthorized}); either way its alias stays
+registered, out of service ({§mcp-unavailable-runtime}). A URL-only definition
+is sufficient; no callback port needs to be configured. The terminal client's
+`/mcp oauth <alias>` binds an available loopback port and calls
+`workspace.mcp.oauth.begin` before opening the returned authorization URL. A
+fixed OAuth redirect, if configured, is respected. A server that publishes no
+OAuth metadata needs its authorization server named as `authorization.issuer`,
+and `authorization.authorizationParams` adds provider request parameters such as
+`access_type=offline` where a refresh token is issued only on request
+({§oauth-issuer}). Supplying the callback URL explicitly also works for
+remote/headless use. The client submits the complete URL through
+`workspace.mcp.oauth.complete`. Its `202` acknowledges sign-in; tools activate
+at the next safe workspace boundary, between turns, without another callback
+submission. Until then `list` and a call to the alias report the published
+state, so a turn in flight still sees the alias awaiting sign-in. A sign-in
+outlives its connection: the alias's later connections with the same definition
+present it, refreshing it as it lapses — when an idle workspace returns, on
+`enable`, or on `disable` then `enable` — until its authorization server rejects
+it, another sign-in replaces it, or the daemon stops ({§oauth-grant}). `list`
+shows an active alias's grant as its `detail.grant`: its issuer, the scope its
+authorization server stated, and whether it refreshes, never a token. PKCE,
 issuer and resource validation, refresh, scope escalation, and credentials
-remain inside the host connection. Callback addresses and credentials never
-replace the saved definition. `enable` retries a connection; it does not replace
-user sign-in. Rejected configured credentials are reported as authentication
-failures rather than retryable server downtime.
+remain inside the host. Callback addresses and credentials never replace the
+saved definition. `enable` retries a connection; it does not replace user
+sign-in. Rejected configured credentials are reported as authentication failures
+rather than retryable server downtime.
 
 ## Verification
 
 ```sh
 npm test -w @plurnk/plurnk-mcp
-PLURNK_MODEL=<selector> npm run test:live:specimen -w @plurnk/plurnk-service -- "live mcp: current third-party stdio and HTTP servers compose through the assembled product"
+PLURNK_MODEL=<selector> npm run test:live -- --specimen "live mcp: current third-party stdio and HTTP servers compose through the assembled product"
 ```
 
 The package gate runs the exact current SDK and official conformance

package/SPEC.md

@@ -33,6 +33,15 @@ per-connection and absent from a legacy peer.
 
 ## §mcp-core-matrix Core capability matrix
 
+<!-- map -->
+| Tag | Promise |
+| --- | --- |
+| {§mcp-catalog-convergence} | A catalog is complete or it is an error. |
+| {§mcp-catalog-deadline} | `PLURNK_MCP_CONNECT_TIMEOUT` bounds connection setup and, separately, each complete catalog/list walk,… |
+| {§mcp-retry-pacing} | Every retry the adapter schedules on its own — reopening a dropped subscription, refreshing a catalog a… |
+| {§mcp-catalog-list-absence} | An unsupported list method does not disable the server. |
+<!-- /map -->
+
 The accountable capability matrix lives in `capabilityMatrix.ts`
 ({§mcp-capability-matrix}). This table describes the pinned revision;
 {§mcp-authority} owns the SDK-negotiated older-peer surface.
@@ -167,6 +176,15 @@ conformance stays a separate named gate, never folded into a matrix row.
 
 ## §mcp-transports Transport bindings
 
+<!-- map -->
+| Tag | Promise |
+| --- | --- |
+| {§mcp-endpoint-security} | Configured MCP and registry endpoints accept HTTP or HTTPS, including private-network hosts. |
+| {§mcp-stdio-process-ownership} | A stdio connection owns the complete process group created for its server. |
+| {§mcp-redirect-refused} | An HTTP endpoint is never redirected. |
+| {§mcp-header-declarations} | A tool with an invalid `x-mcp-header` declaration is never called. |
+<!-- /map -->
+
 | Binding | Contract |
 |---|---|
 | 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 |
@@ -194,17 +212,15 @@ case-insensitively, and body/header disagreement fails instead of guessing.
 For `tasks/get`, `tasks/update`, and `tasks/cancel`, `Mcp-Name` is the encoded
 `taskId` required by the Tasks extension.
 
-§mcp-header-declarations **A tool with an invalid `x-mcp-header` declaration is never called.** Before
-either request leg of a tool call, Tasks or direct, the tool's `inputSchema` is scanned for
-`x-mcp-header` declarations: each sits on a property reached through `properties` alone, never under
-`items`, `additionalProperties`, a combinator, a conditional, `$defs` or a `$ref` target; names a
-non-empty RFC 9110 token that is unique case-insensitively; and types `string`, `integer` or `boolean`,
-never `number` (SEP-2243). The definition the caller supplies is the one scanned; otherwise the server's
-listing supplies it, and a Tasks call whose listing lacks the tool fails as unlisted. A definition that
-breaks any of these refuses the call with `tool-header-invalid` ({§problems-mcp}) naming the tool and
-the declaration, and no request is sent. A direct call never waits on a failed listing
-({§mcp-catalog-deadline}): with no definition at hand there is nothing to scan and no routing header to
-derive, so it proceeds as a plain `tools/call`.
+§mcp-header-declarations **A tool with an invalid `x-mcp-header` declaration is never called.** Before either request leg of a tool call, Tasks or direct, the tool's `inputSchema` is scanned for `x-mcp-header` declarations. A definition that breaks any rule below refuses the call with `tool-header-invalid` ({§problems-mcp}) naming the tool and the declaration, and no request is sent.
+
+| Rule | What |
+| --- | --- |
+| Placement | each sits on a property reached through `properties` alone, never under `items`, `additionalProperties`, a combinator, a conditional, `$defs` or a `$ref` target |
+| Name | a non-empty RFC 9110 token that is unique case-insensitively |
+| Type | `string`, `integer` or `boolean`, never `number` (SEP-2243) |
+| The definition scanned | the one the caller supplies; otherwise the server's listing supplies it, and a Tasks call whose listing lacks the tool fails as unlisted |
+| A direct call | never waits on a failed listing ({§mcp-catalog-deadline}): with no definition at hand there is nothing to scan and no routing header to derive, so it proceeds as a plain `tools/call` |
 
 ## §mcp-errors Error allocation
 
@@ -226,6 +242,27 @@ originating distinction in its canonical Problem/result path.
 
 ## §mcp-configuration Configuration
 
+<!-- map -->
+| Tag | Promise |
+| --- | --- |
+| {§mcp-file-configuration} | Standalone `mcp.json` files are read-only configuration inputs, not plugins. |
+| {§mcp-plugin-configuration} | Plugin MCP components use their format's interpretation, not the native file dialect. |
+| {§mcp-activation-isolation} | Cold endpoint failure is capability-local. |
+| {§mcp-unavailable-runtime} | An enabled server that cannot run keeps its alias. |
+| {§mcp-definitions} | A server is not a plugin installation. |
+| {§mcp-launch-directory} | An implicit working directory is workspace-owned state, not the project. |
+| {§mcp-summary-derivation} | Orientation prefers the server's own purpose over display labels; no capabilities are inferred. |
+| {§mcp-server-settings} | Independent behavior settings do not change connection definitions. |
+| {§mcp-module} | The MCP family beneath the coordinator |
+| {§mcp-launch-environment} | Ambient inheritance and explicit bindings are distinct. |
+| {§mcp-management-actions} | MCP is one family of workspace Functionality |
+| {§mcp-registry-discovery} | `discover` searches the MCP Registry. |
+| {§mcp-preparation-diagnostics} | Unavailable preparation reports observations. |
+| {§oauth-continuation} | A URL-only HTTP definition is sufficient to reach the client sign-in handoff. |
+| {§oauth-issuer} | A configured issuer is where a sign-in starts and the one server it trusts. |
+| {§oauth-begin-unchallenged} | A sign-in starts where no connection is challenged. |
+<!-- /map -->
+
 MCP servers are complete connection definitions ({§mcp-server-definition}). Standalone files, plugin components, and environment declarations
 supply the service baseline; live additions belong to the workspace. All use the common resolution
 and lifecycle ({§configuration-definition-resolution}, {§functionality-coordinator}). Disabled definitions remain
@@ -288,13 +325,23 @@ source repair replaces them, rather than retaining a historical warning.
 
 §mcp-activation-isolation **Cold endpoint failure is capability-local.** An enabled server
 that cannot connect or complete discovery during workspace 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
+enabled and client-visible as `unavailable`. It publishes no tools, resources, or
+documentation, only its alias out of service ({§mcp-unavailable-runtime}), 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. An interactive enable continues to reject an unavailable candidate
 without changing durable state.
 
+§mcp-unavailable-runtime **An enabled server that cannot run keeps its alias.** Preparation registers
+every enabled server: an active one with its tools and resources, any other as a runtime out of
+service whose availability states what keeps it from running, so a call to the alias is refused with
+that state ({§exec-registry-resolves}) and never as a name nothing registered.
+
+| State | The refusal names |
+| --- | --- |
+| `authorization-required` | the operator's sign-in it awaits |
+| `unavailable` | what preparation observed: its Problem's bounded diagnostic, else its detail |
+
 | Variable | Contract |
 |---|---|
 | `PLURNK_MCP_<alias>` | Complete `McpServerDefinition` JSON; transport and authentication replace together |
@@ -395,30 +442,19 @@ environment change; there is no automatic restart or stale-configuration state.
 have no local process environment; their native header and authorization references use the
 same workspace-composed operator environment.
 
-§mcp-management-actions MCP is one family of workspace Functionality ({§functionality-coordinator}). The
-coordinator publishes `workspace.mcp.list | add | replace | enable | disable | remove`, with `discover`
-while a registry is configured, and the model's
-`mcp` runtime with the common semantics, durable state, and publication; this module
-registers the family adapter and owns protocol truth beneath it. `available` is the configured service baseline; `add`, `replace` ({§functionality-replacement}), and `remove` change workspace state ({§mcp-definitions}), and
-`discover` searches the MCP Registry ({§mcp-registry-discovery}). `prepare` connects the enabled set, reusing
-unchanged live attachments, and returns one runtime 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 snapshot in three phases: `publish` adopts the connected
-set and consumes or records pending authorizations, synchronously; `commit` closes connections the new
-set no longer uses; `abort` closes only what the attempt opened.
-
-§mcp-registry-discovery **`discover` searches the MCP Registry.** The family serves discovery
-while `PLURNK_MCP_REGISTRY_URL`, read when the module is constructed, names a registry; empty,
-the family has no `discover` ({§functionality-discover-advertisement}). Its one input, `query`,
-asks that registry (API v0.1) for one page of at most `PLURNK_MCP_REGISTRY_LIMIT` servers, each at
-its latest version, whose names match. Each npm, PyPI, NuGet or OCI package with a stdio transport
-becomes a stdio entry run as the registry's own examples run it (`npx -y`, `uvx`, `dnx`, or
-`docker run -i --rm` passing each declared variable through), and each Streamable HTTP remote becomes a
-URL entry with its non-secret literal headers. An entry that needs a person's input first, such as a
-template variable or a required argument with no value, has none. A candidate is a complete definition;
-its summary names the environment variables and headers the
-server needs, and its provenance names the registry and the server's `name@version`.
+§mcp-management-actions **MCP is one family of workspace Functionality** ({§functionality-coordinator}). The coordinator publishes `workspace.mcp.list | add | replace | enable | disable | remove`, with `discover` while a registry is configured, and the model's `mcp` runtime with the common semantics, durable state, and publication; this module registers the family adapter and owns protocol truth beneath it.
+
+| Verb | What |
+| --- | --- |
+| `available` | the configured service baseline |
+| `add`, `replace` ({§functionality-replacement}), `remove` | change workspace state ({§mcp-definitions}) |
+| `discover` | searches the MCP Registry ({§mcp-registry-discovery}) |
+| `prepare` | connects the enabled set, reusing unchanged live attachments, and returns one runtime per enabled server, with its resource facet when active ({§mcp-unavailable-runtime}), one outcome per alias (`active` with catalog detail — negotiated protocol version, server identity, capabilities, tool names, resource and prompt counts — and any grant it presents ({§oauth-grant}), `unavailable` with its exact Problem, or `authorization-required` with its URL), and a snapshot in three phases |
+| `publish` | adopts the connected set and consumes or records pending authorizations, synchronously |
+| `commit` | closes connections the new set no longer uses |
+| `abort` | closes only what the attempt opened |
+
+§mcp-registry-discovery **`discover` searches the MCP Registry.** The family serves discovery while `PLURNK_MCP_REGISTRY_URL`, read when the module is constructed, names a registry; empty, the family has no `discover` ({§functionality-discover-advertisement}). Its one input, `query`, asks that registry (API v0.1) for one page of at most `PLURNK_MCP_REGISTRY_LIMIT` servers, each at its latest version, whose names match.
 
 | Discovery, admission, or installation condition | Problem | Status |
 |---|---|---|
@@ -426,6 +462,13 @@ server needs, and its provenance names the registry and the server's `name@versi
 | The complete connection definition is invalid | `definition-invalid` | 400 |
 | The alias differs from the definition's name | `alias-mismatch` | 400 |
 
+| Registry server | Candidate |
+| --- | --- |
+| Each npm, PyPI, NuGet or OCI package with a stdio transport | a stdio entry run as the registry's own examples run it (`npx -y`, `uvx`, `dnx`, or `docker run -i --rm` passing each declared variable through) |
+| Each Streamable HTTP remote | a URL entry with its non-secret literal headers |
+| One that needs a person's input first, such as a template variable or a required argument with no value | none |
+| Every candidate | a complete definition; its summary names the environment variables and headers the server needs, and its provenance names the registry and the server's `name@version` |
+
 Protocol continuations remain MCP-registered workspace actions beneath the
 common grammar:
 
@@ -443,7 +486,7 @@ Worker's own accepted mutation publishes them as unavailable
 | Endpoint condition | Problem |
 |---|---|
 | Cannot connect or complete discovery/catalog preparation at the negotiated revision | `502 server-unavailable`, retryable; names the server and its `type` without exposing credentials |
-| HTTP 401 without configured credentials | Enabled `authorization-required`, no runtime and no URL until the client begins sign-in |
+| HTTP 401 without configured credentials | Enabled `authorization-required`, its alias out of service ({§mcp-unavailable-runtime}), and no URL until the client begins sign-in |
 | HTTP 401 with configured credentials | `502 server-authentication-failed`, non-retryable, with `upstreamStatus: 401`; credentials are not replaced by interactive OAuth |
 | Sign-in discovery lacks validated authorization metadata or a usable client-registration method | `502 oauth-metadata-unavailable` or `oauth-registration-unavailable`, non-retryable; retain the definition and surface the setup boundary, not retryable downtime |
 | The endpoint answers with a redirect | `502 server-redirected`, non-retryable ({§mcp-redirect-refused}) |
@@ -483,7 +526,8 @@ client is registered, or workspace lease retained merely for that challenge.
 The client binds its callback before `oauth.begin`; absent an explicitly
 configured redirect, it obtains an ephemeral loopback port (RFC 8252 §7.3).
 The MCP SDK owns metadata discovery, registration, PKCE and token exchange.
-An explicit OAuth definition may supply scope and client-registration metadata;
+An explicit OAuth definition may supply scope, client-registration metadata, an issuer and
+authorization parameters ({§oauth-issuer});
 its optional fixed redirect is respected, never silently rewritten. Bearer,
 client-credentials and Authorization-header configurations cannot be replaced
 by `oauth.begin`. Callback addresses and acquired credentials are session state,
@@ -504,29 +548,15 @@ sequenceDiagram
     MCP-->>Model: active tools through normal publication
 ```
 
-`oauth.begin` prepares an authorization attempt without enabling the alias or
-waiting for workspace quiescence. It returns `202` with an `authorization.url`
-when consent is required, `202` without that field when an accepted connection
-awaits publication, or `200` when tools are already active. These results name
-the alias, not a capability snapshot. The adapter retains one pending candidate
-per `(workspace, alias)` holding the connection and one workspace residency
-lease. An unchanged publication preserves that independent attempt; a new
-challenge supersedes it ({§oauth-lifetime}).
-Concurrent begin requests for one alias are refused; a later begun attempt
-supersedes the prior one unless its grant is already accepted and awaiting
-publication. An in-flight begin cannot attach after disable,
-remove or definition replacement. `oauth.complete` accepts the complete callback URL so state, `code`, and
-`iss` remain one parsing unit. Grant acceptance returns without waiting for
-workspace quiescence; it is not a configuration mutation and cannot re-enable
-an alias. The existing catalog-refresh path prepares and publishes the current
-enabled definitions, then consumes the candidate and releases its lease.
-The accepted result does not claim tool readiness: `list` reports the current
-published snapshot, including any subsequent preparation failure. 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.begin` prepares an authorization attempt without enabling the alias or waiting for workspace quiescence; `oauth.complete` accepts the complete callback URL so state, `code`, and `iss` remain one parsing unit.
+
+| Fact | Rule |
+| --- | --- |
+| `oauth.begin` returns | `202` with an `authorization.url` when consent is required, `202` without that field when an accepted connection awaits publication, or `200` when tools are already active; these results name the alias, not a capability snapshot |
+| The pending candidate | the adapter retains one per `(workspace, alias)` holding the connection and one workspace residency lease; an unchanged publication preserves that independent attempt, and a new challenge supersedes it ({§oauth-lifetime}) |
+| Concurrent begins | concurrent begin requests for one alias are refused; a later begun attempt supersedes the prior one unless its grant is already accepted and awaiting publication; an in-flight begin cannot attach after disable, remove or definition replacement |
+| Grant acceptance | returns without waiting for workspace quiescence; it is not a configuration mutation and cannot re-enable an alias; the existing catalog-refresh path prepares and publishes the current enabled definitions, then consumes the candidate and releases its lease; the accepted result does not claim tool readiness: `list` and a call to the alias report the current published snapshot, including any subsequent preparation failure, so a turn holding the workspace when the sign-in is accepted still sees the alias awaiting it, and the next turn sees its publication ({§module-workspace-quiescence}) |
+| A bad callback | one 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 |
 
 | Callback boundary | Result |
 |---|---|
@@ -538,19 +568,40 @@ error text.
 | Preparation failure published as unavailable | Preserve the preparation diagnostic; release the pending lease and close its unused connection. |
 | Callback after publication | The attempt has been consumed; `404 oauth-not-pending`. |
 
+§oauth-issuer **A configured issuer is where a sign-in starts and the one server it trusts.** An
+interactive definition's `authorization.issuer` names the authorization server: discovery reads its
+metadata (RFC 8414, then OpenID Connect Discovery) whether or not the MCP server publishes
+protected-resource metadata, and the client registration, tokens and refresh are bound to it. With
+none named, the SDK discovers the server from the resource's protected-resource metadata, falling
+back to the resource's origin; where neither publishes metadata, a sign-in fails
+`502 oauth-metadata-unavailable` and its recovery names the issuer field. `authorization.authorizationParams`
+join every authorization request the definition makes, such as `access_type=offline` for a server
+that issues a refresh token only when asked; the parameters the flow sets itself cannot be named
+({§mcp-oauth}).
+
+§oauth-begin-unchallenged **A sign-in starts where no connection is challenged.** A server may answer
+its catalog to anyone and refuse only requests ({§mcp-request-unauthorized}), so the connection
+`oauth.begin` prepares meets no challenge.
+
+| The alias awaits a sign-in because | and begin's connection meets no challenge |
+| --- | --- |
+| a request was refused | begin starts the SDK's authorization on that connection and returns its URL as for a challenged one; a refusal of that start is a preparation failure ({§mcp-preparation-diagnostics}) and leaves no pending attempt |
+| its connection was challenged | the connection is accepted as it is: `202` without a URL, publishing at the next boundary |
+
 ## §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 workspace state holds only the
-unexpanded definition ({§mcp-configuration}). There is no daemon callback HTTP
-listener, authority-root resource, or daemon-side browser side channel: an
-interactive client may receive its configured loopback redirect, or accept a
-pasted callback for remote/headless use. It returns the complete URL through `workspace.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.
+Interactive OAuth state is process memory: an accepted sign-in's client
+registration and access and refresh tokens are its alias's grant
+({§oauth-grant}), and the PKCE verifier and pending state live only in the
+pending candidate. Nothing OAuth-secret is written to SQLite; the durable
+workspace state holds only the unexpanded definition ({§mcp-configuration}).
+There is no daemon callback HTTP listener, authority-root resource, or
+daemon-side browser side channel: an interactive client may receive its
+configured loopback redirect, or accept a pasted callback for remote/headless
+use. It returns the complete URL through `workspace.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 |
 |---|---|
@@ -558,11 +609,25 @@ as an accidental failure.
 | 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; a challenged attachment publishes `authorization-required` and enable returns `202`. A URL is present only when a callback is already configured. 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. |
-| Workspace disable/remove | Closes the attachment and clears its pending candidate; no durable secret deletion is needed because nothing secret is durable. |
+| Token expiry | An expired access token surfaces as one unauthorized response; the SDK re-acquires via `refresh_token` when one was issued; otherwise the request fails and the alias awaits a sign-in ({§mcp-request-unauthorized}). |
+| Refresh | Happens only against the issuer bound during the original authorization; the refreshed token replaces the grant's, for every later connection ({§oauth-grant}). |
+| Workspace cooling | Closes the alias's connection; the grant outlives it, and the alias's next connection presents it ({§oauth-grant}). |
+| Workspace disable/remove | Closes the attachment and clears its pending candidate; the grant stays for the alias's return with the definition it was accepted for ({§oauth-grant}). No durable secret deletion is needed because nothing secret is durable. |
 | Server replacement | Publication discards any superseded pending connection and releases its residency, including replacement by a definition without OAuth. Completion of an unpublished configuration drift fails `409 oauth-target-conflict` instead of replaying a stale snapshot. |
-| Cross-authorization protection | Candidates are keyed by `(workspace, alias)`; callback state, PKCE, and issuer are validated by the SDK against the attempt that created them, so no other workspace, alias, or attempt can complete this authorization. |
+| Cross-authorization protection | Candidates and grants are keyed by `(workspace, alias)`; callback state, PKCE, and issuer are validated by the SDK against the attempt that created them, so no other workspace, alias, or attempt can complete this authorization. |
+
+§oauth-grant **A grant outlives its connection.** An accepted sign-in is its alias's grant, held per
+`(workspace, alias)` with the definition it was accepted for. Only a redirect the definition
+configures still has a client waiting at it once the sign-in is accepted.
+
+| When | The grant |
+| --- | --- |
+| A connection the module opens for the alias with that definition, after cooling, an explicit enable, or disable and enable | is presented, and refreshed as it lapses |
+| An active alias's connection presents it | is listed in the alias's `detail.grant`: the `issuer` its tokens came from, the `scope` that authorization server stated, and whether it is `refreshable`; never a token or a time. An active alias presenting no grant lists none |
+| A connection serves another definition, or another workspace | is never presented |
+| Its server refuses it, at connection or on a request ({§mcp-request-unauthorized}) | starts a sign-in only at a redirect the definition configures; otherwise the alias awaits the sign-in a client begins ({§oauth-continuation}) |
+| A sign-in for the alias is accepted | is replaced by the new one |
+| Its authorization server rejects it, or the daemon stops | ends |
 
 ## §oauth-client-credentials Client-credentials grant adoption
 
@@ -638,19 +703,20 @@ boundaries; neither closes or replaces the committed connection.
 | Aborted publication | Does not acknowledge the unpublished catalog. |
 | Disable/remove, workspace cooling, or shutdown | Retires obsolete refresh timers and invalidations. |
 
-MCP participates in core Functionality residency ({§module-workspace-residency}).
-Preparation reports the current server alias through the coordinator's activity
-contract ({§functionality-preparation-visibility}); inspection never starts a
-connection ({§functionality-inspection}).
-Every tool call and Task retains the workspace 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 workspace 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.
+MCP participates in core Functionality residency
+({§module-workspace-residency}). Preparation reports the current server alias
+through the coordinator's activity contract
+({§functionality-preparation-visibility}); inspection never starts a connection
+({§functionality-inspection}). Every tool call and Task retains the workspace
+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 workspace snapshot
+and closes all of its connections; an accepted sign-in outlives them
+({§oauth-grant}). 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 publish only at {§module-workspace-quiescence}. Disable and
@@ -682,6 +748,16 @@ failures are reported. Core's shutdown deadline remains the outer bound
 
 ## §mcp-host-composition Protocol-to-Plurnk composition
 
+<!-- map -->
+| Tag | Promise |
+| --- | --- |
+| {§mcp-input-deadline} | Client-input waits consume the remaining owning operation budget (`PLURNK_MCP_REQUEST_TIMEOUT`); each MRTR… |
+| {§mcp-tool-replay} | A tool call is effectful unless host policy proves otherwise. |
+| {§mcp-tool-problem-detail} | Tool-call Problems keep runtime, tool, and any bounded remote diagnostic as structured extensions. |
+| {§mcp-request-unauthorized} | A request refused for want of a sign-in says so, and its alias then awaits one. |
+| {§mcp-trailing-aside} | A tool call's body is one JSON object. |
+<!-- /map -->
+
 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.
@@ -729,6 +805,21 @@ Nontext parts and structured data are not interpreted as explanations. With no
 text explanation the extension is absent; successful results do not acquire one.
 The complete result and passive output remain unchanged ({§mcp-result-content}).
 
+§mcp-request-unauthorized **A request refused for want of a sign-in says so, and its alias then awaits one.**
+A server may answer its catalog to anyone and challenge only a request, so preparation can publish it
+`active`. A later request — a tool call, a resource or prompt read, or a completion — is refused for
+want of a sign-in when it is answered with HTTP 401, or challenged in a way the SDK cannot meet without
+the operator's consent (an interactive grant it cannot refresh). The refusal depends on the definition:
+
+| Definition | A request refused for want of a sign-in |
+| --- | --- |
+| URL-only, or interactive OAuth | fails `401 authorization-required`, non-retryable, and republishes the alias `authorization-required`, out of service ({§mcp-unavailable-runtime}), with no URL until the client begins sign-in ({§oauth-continuation}) |
+| A bearer token, a client-credentials grant, or an Authorization header | fails as any failed request of its kind; no state changes and no sign-in is offered |
+
+Only a fresh connection answers the awaited sign-in — an accepted sign-in, an explicit enable, a changed
+definition, or the alias's return after disable, removal, cooling or a restart — and it publishes what
+its preparation observes, presenting the alias's grant where its definition has one ({§oauth-grant}).
+
 §mcp-trailing-aside A tool call's body is one JSON object. HTML comments after
 that object are the writer's aside, not arguments: when the body does not parse
 as written, trailing `<!-- … -->` comments are removed and the object is read.
@@ -891,9 +982,14 @@ servers are composition evidence only.
 | `tool-not-enabled` | 404 | The MCP tool is not enabled. Recovery: Select a target documented under worker:///_plurnk/tools/*runtime*/. |
 | `tool-reported-error` | 502 | The MCP tool reported an error (the tool call failed). |
 | `invalid-tool-arguments` | 400 | MCP tool arguments must be one JSON object. Recovery: One JSON object per MCP tool call. |
+| `resource-address-invalid` | 400 | The MCP resource address is invalid (a malformed encoded address); not retryable. |
+| `resource-part-not-found` | 404 | The resource response does not contain this part. |
+| `resource-read-failed` | 502 | MCP resource preparation failed; retryable, with the bounded upstream diagnostic. |
+| `resource-find-failed` | 502 | MCP resource listing failed; retryable, with the bounded upstream diagnostic. |
 | `oauth-client-credentials-failed` | 502 | MCP server '*name*' rejected the client-credentials grant. |
 | `server-authentication-failed` | 502 | MCP server '*name*' rejected authentication (HTTP 401). |
-| `oauth-metadata-unavailable` | 502 | MCP OAuth requires validated authorization-server metadata, and the server provided none. |
+| `authorization-required` | 401 | MCP server '*name*' awaits the operator's sign-in; the request was not completed. |
+| `oauth-metadata-unavailable` | 502 | MCP OAuth requires validated authorization-server metadata, and the server provided none. Recovery, when the definition names no issuer: Name the authorization server as the definition's authorization.issuer. |
 | `oauth-registration-unavailable` | 502 | No client is registered with the authorization server: none is configured for it, it advertises no Dynamic Client Registration endpoint, and no client metadata document it accepts is configured. |
 | `oauth-redirect-invalid` | 400 | The OAuth callback must use HTTPS or HTTP loopback with a usable port. |
 | `oauth-configuration-conflict` | 409 | MCP server '*alias*' is not configured for this interactive OAuth callback. |

package/dist/McpExecutor.d.ts

@@ -1,6 +1,7 @@
 import { BaseExecutor } from "@plurnk/plurnk-execs";
 import type { ChannelDecl, Effect, ExecArgs, ExecResult, RuntimeAvailability, RuntimeDecl, RuntimeSummaryDecl, RuntimeToolRegistry } from "@plurnk/plurnk-execs";
-import ServerConnection, { type ServerCatalog } from "./client.ts";
+import type ServerConnection from "./client.ts";
+import { type ServerCatalog } from "./client.ts";
 import type { ContentBlock } from "@modelcontextprotocol/client";
 import type { ToolPolicy } from "./config.ts";
 export declare const serverSummary: (name: string, catalog: ServerCatalog | undefined) => string;
@@ -14,6 +15,14 @@ export declare const toolResultBody: (result: ToolResultShape, runtime: string,
     content: string;
     mimetype: string;
 }>;
+export declare class UnavailableServerExecutor extends BaseExecutor {
+    #private;
+    constructor(runtime: string, detail: string);
+    get channels(): Readonly<Record<string, ChannelDecl>>;
+    get publishedChannel(): string;
+    probe(): Promise<RuntimeAvailability>;
+    run(): Promise<ExecResult>;
+}
 export declare const runtimeDecl: (name: string, summary: RuntimeSummaryDecl, expandTools: boolean, instructions?: string) => RuntimeDecl;
 export default class McpExecutor extends BaseExecutor {
     #private;

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,EAIf,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EACR,WAAW,EACX,MAAM,EACN,QAAQ,EACR,UAAU,EAEV,mBAAmB,EACnB,WAAW,EACX,kBAAkB,EAClB,mBAAmB,EACtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,gBAAgB,EAAE,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,8BAA8B,CAAC;AAIjF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAY9C,eAAO,MAAM,aAAa,SAChB,MAAM,WACH,aAAa,GAAG,SAAS,KACnC,MAOF,CAAC;AAGF,eAAO,MAAM,oBAAoB,SACvB,MAAM,WACH,aAAa,GAAG,SAAS,KACnC,kBAKF,CAAC;AAMF,MAAM,MAAM,eAAe,GAAG;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEF,eAAO,MAAM,cAAc,WAAkB,eAAe,WAAW,MAAM,UAAU,QAAQ,CAAC,OAAO,CAAC,KAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAqBvJ,CAAC;AAwBF,eAAO,MAAM,WAAW,SAAU,MAAM,WAAW,kBAAkB,eAAe,OAAO,iBAAiB,MAAM,KAAG,WAenH,CAAC;AAuBH,MAAM,CAAC,OAAO,OAAO,WAAY,SAAQ,YAAY;;IAoBjD,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,EAMnC;IAED,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAOpD;IAEQ,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAK7C;IAED,IAAa,gBAAgB,IAAI,MAAM,CAEtC;IAyBD,YAAY,IAAI,mBAAmB,CAKlC;IAED,IAAI,OAAO,IAAI,aAAa,CAK3B;IAEc,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC,CASvE;IAEK,gBAAgB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAsBzE;IAEK,GAAG,CAAC,EACN,OAAO,EACP,IAAI,EACJ,MAAM,EACN,MAAM,EACN,KAAK,EACL,QAAQ,EACR,IAAI,EACJ,QAAQ,EACR,KAAK,GACR,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CAmIhC;CACJ"}
+{"version":3,"file":"McpExecutor.d.ts","sourceRoot":"","sources":["../src/McpExecutor.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,YAAY,EAIf,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EACR,WAAW,EACX,MAAM,EACN,QAAQ,EACR,UAAU,EAEV,mBAAmB,EACnB,WAAW,EACX,kBAAkB,EAClB,mBAAmB,EACtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,gBAAgB,MAAM,aAAa,CAAC;AAChD,OAAO,EAA4C,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAC3F,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,8BAA8B,CAAC;AAIjF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAY9C,eAAO,MAAM,aAAa,SAChB,MAAM,WACH,aAAa,GAAG,SAAS,KACnC,MAOF,CAAC;AAGF,eAAO,MAAM,oBAAoB,SACvB,MAAM,WACH,aAAa,GAAG,SAAS,KACnC,kBAKF,CAAC;AAMF,MAAM,MAAM,eAAe,GAAG;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEF,eAAO,MAAM,cAAc,WAAkB,eAAe,WAAW,MAAM,UAAU,QAAQ,CAAC,OAAO,CAAC,KAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAqBvJ,CAAC;AA2BF,qBAAa,yBAA0B,SAAQ,YAAY;;IAGvD,YAAY,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAG1C;IAED,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAEpD;IAED,IAAa,gBAAgB,IAAI,MAAM,CAEtC;IAEc,KAAK,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAEnD;IAEK,GAAG,IAAI,OAAO,CAAC,UAAU,CAAC,CAE/B;CACJ;AAED,eAAO,MAAM,WAAW,SAAU,MAAM,WAAW,kBAAkB,eAAe,OAAO,iBAAiB,MAAM,KAAG,WAenH,CAAC;AAuBH,MAAM,CAAC,OAAO,OAAO,WAAY,SAAQ,YAAY;;IAoBjD,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,EAMnC;IAED,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAOpD;IAEQ,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAK7C;IAED,IAAa,gBAAgB,IAAI,MAAM,CAEtC;IAyBD,YAAY,IAAI,mBAAmB,CAKlC;IAED,IAAI,OAAO,IAAI,aAAa,CAK3B;IAEc,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC,CASvE;IAEK,gBAAgB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAsBzE;IAEK,GAAG,CAAC,EACN,OAAO,EACP,IAAI,EACJ,MAAM,EACN,MAAM,EACN,KAAK,EACL,QAAQ,EACR,IAAI,EACJ,QAAQ,EACR,KAAK,GACR,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CAuIhC;CACJ"}

package/dist/McpExecutor.js

@@ -1,6 +1,6 @@
 import { BaseExecutor, ErrorDetail, Results, RuntimeInvocation, } from "@plurnk/plurnk-execs";
-import { formatJsonDocument } from "@plurnk/plurnk-contracts";
-import ServerConnection, {} from "./client.js";
+import { isRecord, formatJsonDocument } from "@plurnk/plurnk-contracts";
+import { AuthorizationRequiredError, awaitsSignIn } from "./client.js";
 import { resourcePath } from "./McpResources.js";
 import { HeaderDeclarationError } from "./protocolHeaders.js";
 import ContentProjection from "./ContentProjection.js";
@@ -58,16 +58,38 @@ const pageReceipt = (args, tool, body) => {
     const parsed = JSON.parse(body.content);
     if (!Array.isArray(parsed))
         return null;
-    const properties = (tool.inputSchema.properties ?? {});
+    const properties = isRecord(tool.inputSchema.properties) ? tool.inputSchema.properties : {};
     for (const name of PAGE_ARGUMENTS) {
         const sent = args[name];
-        const size = typeof sent === "number" ? sent : properties[name]?.default;
+        const property = properties[name];
+        const size = typeof sent === "number" ? sent : isRecord(property) ? property.default : undefined;
         if (typeof size !== "number" || !Number.isInteger(size) || size <= 0)
             continue;
         return parsed.length === size ? { size, returned: parsed.length } : null;
     }
     return null;
 };
+// {§mcp-unavailable-runtime} An enabled server that cannot run keeps its alias: core refuses a call to it with the
+// reason its availability states, before anything runs ({§exec-registry-resolves}), so this executor never runs.
+export class UnavailableServerExecutor extends BaseExecutor {
+    #availability;
+    constructor(runtime, detail) {
+        super({ runtime, glyph: "🔌" });
+        this.#availability = { available: false, detail };
+    }
+    get channels() {
+        return { [CHANNEL]: { mimetype: "application/json" }, json: { mimetype: "application/json" } };
+    }
+    get publishedChannel() {
+        return CHANNEL;
+    }
+    async probe() {
+        return this.#availability;
+    }
+    async run() {
+        throw new Error(`MCP server '${this.runtime}' is unavailable and runs nothing: ${this.#availability.detail ?? ""}`);
+    }
+}
 export const runtimeDecl = (name, summary, expandTools, instructions) => ({
     name,
     glyph: "🔌",
@@ -230,7 +252,7 @@ export default class McpExecutor extends BaseExecutor {
         if (input.length > 0) {
             try {
                 const parsed = McpExecutor.#parseArguments(input);
-                if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                if (!isRecord(parsed)) {
                     throw new TypeError("tool arguments must be an object");
                 }
                 args = parsed;
@@ -254,8 +276,8 @@ export default class McpExecutor extends BaseExecutor {
             const result = await this.#connection.callTool(target, args, signal, (progress) => emit(progressNotice(runtime, target, progress)), interact, tool);
             write("json", JSON.stringify(result, null, 2), "application/json");
             setState("json", "closed");
-            const body = await toolResultBody(result, runtime, entry);
-            write(CHANNEL, body.content, body.mimetype);
+            const resultBody = await toolResultBody(result, runtime, entry);
+            write(CHANNEL, resultBody.content, resultBody.mimetype);
             if (result.isError === true) {
                 const diagnostic = (result.content ?? [])
                     .flatMap((part) => part.type === "text" && part.text.trim().length > 0 ? [part.text] : [])
@@ -267,10 +289,14 @@ export default class McpExecutor extends BaseExecutor {
                 });
             }
             setState(CHANNEL, "closed");
-            const page = pageReceipt(args, tool, body);
+            const page = pageReceipt(args, tool, resultBody);
             return { status: 200, ...(page === null ? {} : { page }) };
         }
         catch (error) {
+            if (error instanceof AuthorizationRequiredError) {
+                // {§mcp-request-unauthorized} — the alias now awaits a sign-in.
+                return fail("authorization-required", 401, awaitsSignIn(runtime), { tool: target, retryable: false });
+            }
             if (error instanceof HeaderDeclarationError) {
                 // {§mcp-header-declarations} — refused before any request leg; the declaration is a field.
                 return fail("tool-header-invalid", 502, `MCP tool '${target}' declares an invalid x-mcp-header; the tool was not called.`, { tool: target, declaration: error.declaration, retryable: false });