@plurnk/plurnk-mcp 1.16.5 → 1.17.0

package/.env.defaults

@@ -1,46 +1,42 @@
-# --- @plurnk/plurnk-mcp : current MCP host module ---
+# @plurnk/plurnk-mcp — Worker MCP attachments.
+# Alias blocks make servers available; ENABLED selects initial attachments.
+# A Worker can add/enable/disable/remove attachments through its Functionality controls.
 
-# Bound only connection and protocol discovery. Individual MCP operations use
-# the request timeout below and remain cancellable through their Plurnk run.
+# Connection and protocol-discovery deadline, positive ms.
 PLURNK_MCP_CONNECT_TIMEOUT=30000
+# Individual operation deadline, positive ms; caller cancellation still applies.
 PLURNK_MCP_REQUEST_TIMEOUT=86400000
-
-# Configured servers are available to clients. Only this exact JSON-array
-# subset connects and becomes model-visible by default; workspaces may override it.
+# Initially enabled aliases, JSON array; [] = none.
 PLURNK_MCP_ENABLED=[]
-
-# Turn 0 surveys enabled tool FAMILIES (one row per server, summary = its
-# one-liner). Servers named here also expand their complete tool tree into
-# the turn-0 survey:
+# Expand these servers' tool lists in turn 0; otherwise show one row per server.
 # PLURNK_MCP_EXPANDED=[]
 
-# Each configured server contributes its enabled `[server] (tool)` rows and server:// resources.
-#
-# Streamable HTTP:
-# PLURNK_MCP_github=https://example.test/mcp
-# PLURNK_MCP_github_BEARER=${GITHUB_TOKEN}
-# PLURNK_MCP_github_TOOLS=["issue_read","issue_search"]
-# PLURNK_MCP_github_READ=["issue_read","issue_search"]
-#
-# stdio: the target is one exact executable path/name, including whitespace.
-# Arguments are a JSON array so Plurnk does not invent or interpret a shell.
-# PLURNK_MCP_atlas=node
-# PLURNK_MCP_atlas_ARGS=["/absolute/path/to/atlas-server.mjs"]
-# PLURNK_MCP_atlas_CWD=/absolute/working/directory
-# PLURNK_MCP_atlas_ENV={"TOKEN":"${ATLAS_TOKEN}"}
-#
-# npx (installed-on-demand executables) — the documented Brave Search fixture,
-# demo-tier only; credentials stay one ${NAME} reference in the operator env:
-# PLURNK_MCP_BRAVE=npx
-# PLURNK_MCP_BRAVE_ARGS=["-y","@brave/brave-search-mcp-server@2.1.0"]
-# PLURNK_MCP_BRAVE_ENV={"BRAVE_API_KEY":"${BRAVE_API_KEY}"}
-# PLURNK_MCP_BRAVE_TOOLS=["brave_web_search","brave_news_search"]
-# PLURNK_MCP_BRAVE_READ=["brave_web_search","brave_news_search"]
-#
-# _SUMMARY companions are fallbacks only — declare one when the server's own
-# summary metadata is missing, confusing, or garbage. The family row can carry
-# its flagship invocation form directly:
-# PLURNK_MCP_BRAVE_SUMMARY=EXEC [brave] (brave_web_search) <!-- Retrieve web results -->
-# PLURNK_MCP_BRAVE_BRAVE_WEB_SEARCH_SUMMARY=General web search.
-#
-# Then list it above to make it model-visible, e.g. PLURNK_MCP_ENABLED=["brave"].
+# --- HTTP target ---
+# URL, optional bearer reference, optional headers (string-valued JSON object).
+# PLURNK_MCP_forge=https://example.test/mcp
+# PLURNK_MCP_forge_BEARER=${FORGE_TOKEN}
+# PLURNK_MCP_forge_HEADERS={"X-Tenant":"${FORGE_TENANT}"}
+
+# --- stdio target ---
+# One exact executable (not a shell command); ARGS is a literal JSON array.
+# CWD is optional; ENV overlays the subprocess environment, resolving ${NAME} references.
+# PLURNK_MCP_browser=node
+# PLURNK_MCP_browser_ARGS=["/absolute/path/to/browser-server.mjs"]
+# PLURNK_MCP_browser_CWD=/absolute/working/directory
+# PLURNK_MCP_browser_ENV={"TOKEN":"${BROWSER_TOKEN}"}
+
+# --- Tool admission and orientation ---
+# Optional tool allowlist; omitted = all server tools. READ marks tools as read-only for admission.
+# PLURNK_MCP_forge_TOOLS=["issue_read","issue_search"]
+# PLURNK_MCP_forge_READ=["issue_read","issue_search"]
+# Summary fallbacks when server metadata is inadequate; per-server or per-tool.
+# PLURNK_MCP_forge_SUMMARY=```forge (issue_read) <!-- Read forge issues -->```
+# PLURNK_MCP_forge_issue_read_SUMMARY=Read one issue.
+
+# --- Optional Brave Search ---
+# PLURNK_MCP_brave=npx
+# PLURNK_MCP_brave_ARGS=["-y","@brave/brave-search-mcp-server@2.1.0"]
+# PLURNK_MCP_brave_ENV={"BRAVE_API_KEY":"${BRAVE_API_KEY}"}
+# PLURNK_MCP_brave_TOOLS=["brave_web_search","brave_news_search"]
+# PLURNK_MCP_brave_READ=["brave_web_search","brave_news_search"]
+# PLURNK_MCP_ENABLED=["brave"]

package/README.md

@@ -13,11 +13,11 @@ serves its standard surface at its own negotiated revision. Plurnk does not
 downgrade its own extension wire, but it does not reject an older supported
 revision.
 
-## Manage Worker servers
+## Manage workspace servers
 
-Service environment variables provide available servers for every Worker;
+Service environment variables provide available servers for every workspace;
 `PLURNK_MCP_ENABLED` selects the exact cold-enabled subset. Users can add,
-enable, disable, or remove one Worker's servers without restarting the daemon. An
+enable, disable, or remove a workspace's servers without restarting the daemon. An
 existing AG-UI connection sends the ordinary management-action form under
 `forwardedProps.plurnk.action`:
 
@@ -27,7 +27,7 @@ existing AG-UI connection sends the ordinary management-action form under
     "plurnk": {
       "workspace": "example",
       "action": {
-        "kind": "worker.mcp.add",
+        "kind": "workspace.mcp.add",
         "alias": "project",
         "definition": {
           "name": "project",
@@ -45,22 +45,29 @@ existing AG-UI connection sends the ordinary management-action form under
 ```
 
 The standard `plurnk.action.result` event reports success or exact RFC 9457
-Problem Details. The definition is durable and Worker-private; symbolic
+Problem Details. The definition is durable and workspace-shared; symbolic
 environment references remain unexpanded at rest.
 
-MCP is one family of Worker Functionality; the common lifecycle actions are
+MCP is one family of workspace Functionality; the common lifecycle actions are
 published by the coordinator and the two continuations by this module:
 
 | Action | Parameters |
 |---|---|
-| `worker.mcp.list` | — |
-| `worker.mcp.discover` | optional `query`, `source` (URL or command line), `configuration` (a client's `PLURNK_MCP_*` overlay) |
-| `worker.mcp.add` | optional `alias` (must equal the definition's `name`), `definition: McpServerDefinition` |
-| `worker.mcp.enable` / `disable` / `remove` | `alias` |
-| `worker.mcp.oauth.complete` | `alias`, complete `callbackUrl` |
-| `worker.mcp.complete` | `server`, completion `ref` and `argument`; optional `context` |
-
-The model manages the same family through `EXEC [mcp] (list|discover|add|enable|disable|remove)`.
+| `workspace.mcp.list` | — |
+| `workspace.mcp.discover` | optional `query`, `source` (URL or command line), `configuration` (a client's `PLURNK_MCP_*` overlay) |
+| `workspace.mcp.add` | optional `alias` (must equal the definition's `name`), `definition: McpServerDefinition` |
+| `workspace.mcp.enable` / `disable` / `remove` | `alias` |
+| `workspace.mcp.oauth.complete` | `alias`, complete `callbackUrl` |
+| `workspace.mcp.complete` | `server`, completion `ref` and `argument`; optional `context` |
+
+The model manages the same family through ```` ```mcp (list|discover|add|enable|disable|remove) ````.
+
+Tool discovery uses ordinary `FIND (worker:///_plurnk/tools/*.md)` and READ.
+Each server's document lists enabled EXEC calls with required-field previews
+and links to full input schemas under `tools/<server>/<encoded-tool>.md`.
+The manager uses the same layout under `plurnk/mcp.md` and `plurnk/mcp/`;
+schema documents preserve descriptions and constraints without adding them to
+the initial survey ({§tools-resource-discovery}).
 
 The owning [specification](./SPEC.md) defines the complete action and server
 definition contracts.
@@ -80,9 +87,11 @@ PLURNK_MCP_GITEA_ARGS=["plurnk_pk"]
 
 The client carries its raw declarations while listing and enabling. Listing is
 inert. `/mcp enable gitea` (or `plurnk mcp enable gitea` in a bound conversation)
-composes service, durable worker, client, and optional command-file fields
+composes service, durable workspace, client, and optional command-file fields
 in that order, prepares the connection, then persists the complete unexpanded
-worker specialization. Arrays and maps replace rather than append or merge.
+workspace definition. Arrays and maps replace rather than append or merge.
+Reapplying an identical definition is idempotent. A different definition for
+the same workspace alias requires explicit removal before replacement.
 
 ## Demo fixtures
 
@@ -156,18 +165,24 @@ Portable timeouts and complete examples live in [`.env.defaults`](./.env.default
 
 | MCP surface | Plurnk surface |
 |---|---|
-| Server tools | `worker://~/_plurnk/tools/<server>.md` family summary |
-| Enabled tool | Exact `worker://~/_plurnk/tools/<server>/<encoded-tool>.md` document and `### EXEC0 [server] (tool)` |
+| Server tools | `worker:///_plurnk/tools/<server>.md` family summary |
+| Enabled tool | Exact `worker:///_plurnk/tools/<server>/<encoded-tool>.md` document and ```` ```server (tool) ```` |
 | Resource catalog | `server:///` or `server:///resources` |
 | Resource | `server:///resources/<encoded-uri>` through ordinary `FIND` and `READ` |
 | Prompt catalog | `server:///prompts` |
 | Prompt retrieval | `server:///prompts/<encoded-name>?argument=value` through ordinary `READ` |
-| Completion | Client-owned `worker.mcp.complete` action |
+| Completion | Client-owned `workspace.mcp.complete` action |
+| Tool image/audio or embedded resource | A named resource beneath the invocation's `resources/`; eight hexadecimal characters when unnamed |
+| Exact tool-result evidence | The invocation's `#json` channel, retrieved on demand |
 
 Tool results, resource bodies, prompt messages, and failures become ordinary
 Plurnk entries and channels. Disabled tools appear in neither teaching nor
 admission. There is no MCP-specific model discovery grammar.
 
+Results link to media rather than dumping base64. An ordinary `READ` delivers
+supported images natively; other content and unsupported models retain the
+text/byte view. Listing the resource alone does not attach it.
+
 Current pagination, cache hints, unified subscriptions, progress,
 cancellation, multi-round-trip input, elicitation, and negotiated Tasks remain
 inside the owning operation. Client input uses the standard AG-UI interrupt and
@@ -180,7 +195,7 @@ HTTP definitions support bearer references, client credentials, and
 interactive OAuth. Stdio never receives OAuth. Interactive add or enable returns
 `{ "status": 202, "authorization": { "url": "..." } }` without publishing a
 partial server. After the user completes that URL, the client submits its
-complete callback URL through `worker.mcp.oauth.complete`. PKCE, issuer and
+complete callback URL through `workspace.mcp.oauth.complete`. PKCE, issuer and
 resource validation, refresh, scope escalation, and credentials remain inside
 the host connection.
 

package/SPEC.md

@@ -45,7 +45,7 @@ matrix rows cite.
 | Resources | Negotiated server capability: `resources/list`, `resources/templates/list`, `resources/read` | Publish catalogs, templates, and materialized contents through the server's resource authority |
 | Prompts | Negotiated server capability: `prompts/list`, `prompts/get` | Publish prompt definitions and retrieve prompt messages through the same server authority |
 | Completion | Negotiated server capability: `completion/complete` | Make prompt and resource-template completion available to the host interaction that owns the argument |
-| Pagination | Opaque cursors on list methods | Drain every page with a finite non-convergence guard; never publish a partial catalog as complete |
+| Pagination | Opaque cursors on list methods | Drain every page with a finite non-convergence guard; never publish a partial catalog as complete ({§mcp-catalog-convergence}) |
 | Caching | `server/discover`, list methods, and `resources/read` carry `ttlMs` and `cacheScope` | Honor freshness and notification invalidation; partition private entries by authorization context |
 | Subscriptions | `subscriptions/listen` plus acknowledged filters and correlated notifications | Keep one current filter for list changes, resource URIs read into cache, and active Task IDs; overlap filter replacement, re-listen after loss, and never use the removed resource subscription methods |
 | Progress | Request-scoped `notifications/progress` | Project progress onto the owning Plurnk operation without creating an independent protocol lifecycle |
@@ -54,6 +54,16 @@ matrix rows cite.
 | Elicitation | Active client capability carried through MRTR | Advertise supported form/URL modes and route the request through Plurnk's client-owned interaction lifecycle |
 | Authorization | OAuth profile for HTTP transports | Require validated protected-resource and authorization-server metadata; never infer endpoints; use PKCE, issuer validation, resource indicators, refresh, and bounded scope escalation; never apply OAuth to stdio |
 
+§mcp-catalog-convergence **A catalog is complete or it is an error.** The pinned SDK's aggregating
+list walk (`listTools`, `listResources`, `listResourceTemplates`, `listPrompts`) stops silently when
+a server returns a cursor it already returned, drops `nextCursor`, and caches the partial aggregate
+as if it were whole; only its page cap (`listMaxPages`) throws. The host's client watches the pages
+the SDK requests and refuses the page that repeats a cursor with `CatalogNonConvergenceError`
+(method and cursor named), so the listing fails and nothing partial is published or cached.
+Pagination, caching, and the cap remain the SDK's; a converging server's pages aggregate exactly as
+before. This is a host guard over an upstream behavior, not a second paginator; the upstream
+report is #601's to file.
+
 ## §mcp-tasks Tasks extension
 
 Tasks is the optional `io.modelcontextprotocol/tasks` extension, never core
@@ -85,7 +95,7 @@ nothing task-shaped is written to SQLite and no MCP sidecar lifecycle exists.
 |---|---|
 | 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. |
+| Workspace 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. |
@@ -164,17 +174,17 @@ originating distinction in its canonical Problem/result path.
 
 ## §mcp-configuration Configuration
 
-Service configuration and worker state produce one available set and one
-enabled subset per worker. Every `PLURNK_MCP_<server>` declares an available
+Service configuration and workspace state produce one available set and one
+enabled subset per workspace. 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
+when a workspace has no override. Workspace 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
+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
@@ -195,7 +205,7 @@ unavailable candidate without changing durable state.
 | `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 every tool is surveyed at turn 0 — one FIND row per `### EXEC0` heading of the family document, with annotation and signature ({§tools-resource-materialization}); never a document delivered unasked; absent or `[]` expands none |
+| `PLURNK_MCP_EXPANDED` | JSON array subset of enabled servers whose every tool is surveyed at turn 0 — one FIND row per executable block of the family document, with aside and signature ({§tools-resource-materialization}); never a document delivered unasked; absent or `[]` expands none |
 | `PLURNK_MCP_CONNECT_TIMEOUT` | Positive integer milliseconds |
 | `PLURNK_MCP_REQUEST_TIMEOUT` | Positive integer milliseconds |
 
@@ -218,7 +228,7 @@ 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
+```` ```server (tool) <!-- one-liner --> ````, so the discovery row teaches the
 call ({§tools-resource-materialization}). Summary companions expand `${NAME}`
 references like every other companion.
 
@@ -253,22 +263,22 @@ stdio executable) and its options (`args`, `cwd`, `env`, `headers`,
 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.
+precedence order: service environment, then the workspace'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
+workspace 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]`
+§mcp-management-actions MCP is one family of workspace Functionality
+({§functionality-coordinator}): the coordinator publishes `workspace.mcp.list |
+discover | add | enable | disable | remove` and the model's `mcp` executable fence
 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`
@@ -281,13 +291,13 @@ 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
+Two protocol continuations remain MCP-registered workspace actions beneath the
 common grammar:
 
 | Action | Parameters | Result / effect |
 |---|---|---|
-| `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. |
+| `workspace.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. |
+| `workspace.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
@@ -314,8 +324,8 @@ in daemon diagnostics. No MCP resource Problem admits an unbounded SDK message.
 
 §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
+retains one pending candidate per `(workspace, alias)` holding the challenged
+connection and one workspace 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
@@ -332,25 +342,25 @@ error text.
 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
+OAuth-secret is written to SQLite; the durable workspace 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`
+client returns the complete callback 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 |
 |---|---|
-| 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. |
+| Pending authorization | One pending candidate per `(workspace, 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. |
+| Workspace 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. |
+| 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. |
 
 ## §oauth-client-credentials Client-credentials grant adoption
 
@@ -402,32 +412,32 @@ decision on durable identity material is ratified.
 
 ## §mcp-setup Atomic lifecycle
 
-When a cold worker is demanded, activation resolves service defaults and durable positive
-worker state, opens and discovers only enabled connections,
+When a cold workspace is demanded, activation resolves service defaults and durable positive
+workspace 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-worker-capabilities}. A configured tool absent from the server, a
+{§module-workspace-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 worker activation. No
+or a `read` name outside the enabled set fails that workspace activation. No
 partial namespace is published and every acquired candidate closes.
 
 - §mcp-catalog-refresh-in-place **A catalog change refreshes in place.** When a server announces a changed catalog, the alias is dirty and its executor is rebuilt on the next preparation — on the connection the alias already holds, never by spawning a second server: with an unchanged definition and a live connection, preparation re-lists the catalog over that connection, so neither an aborted attempt nor a commit has anything of the alias to close, and a failed re-listing leaves the current catalog in service. (#429's root: the SDK's negotiated connect probes a stdio server on a disposable sibling process before the real connect, so every stdio connect starts the server twice and the sibling exits on its own schedule — a test that reads "any exit" as "the committed server was closed" flakes under load. The committed server is the last one started; the refresh-in-place rule keeps it so.) Covered: `Module.test.ts` — one process ever, no close marker across the refresh.
 
-MCP participates in core Functionality residency ({§module-worker-residency}).
-Every tool call and Task retains the worker from executor entry through its
+MCP participates in core Functionality residency ({§module-workspace-residency}).
+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 worker snapshot and closes all of its
+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.
 
 Add and enable prepare the candidate while the old snapshot remains
-authoritative, then commit only at {§module-worker-quiescence}. Disable and
+authoritative, then commit only at {§module-workspace-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,
+old connection rejects replacement with `409 server-busy` 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
 commit leaves the durable definition, connection, Registry, docs, and resource
@@ -446,7 +456,7 @@ cancellation.
 
 One `ServerConnection` owns negotiation, SDK caches, authorization partition,
 subscriptions, active request controllers, MRTR rounds, and Tasks for one
-worker attachment. The host does not reproduce SDK protocol machinery.
+workspace attachment. The host does not reproduce SDK protocol machinery.
 
 | Protocol event | Plurnk composition |
 |---|---|
@@ -479,18 +489,34 @@ effect occurred.
 
 ## §mcp-result-content Passive result content
 
-The EXEC channel carries the tool's RESULT, never the transport envelope
-(`_meta`, `content`): text parts are written as text with their own newlines
-— `application/json` when the text is a JSON document, else `text/plain`;
+The default output channel carries the tool's result, not its transport envelope:
+text parts are written as text with their own newlines
+— whitespace-formatted `application/json` when the text is a complete JSON document,
+else unchanged `text/plain` ({§json-document-presentation});
 several text parts join with newlines; an empty content with
 `structuredContent` writes it pretty-printed — so the page rule and a scoped
-READ mean what they say and nothing reaches the model double-escaped. A result
-holding any non-text variant — image, audio, resource links, embedded
-text/blob resources — is preserved losslessly as one JSON value of the whole
-result ({§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
+READ mean what they say and nothing reaches the model double-escaped. The
+complete result, including metadata and annotations, remains available in
+`#json` as protocol evidence. The default body preserves content order:
+
+| Content | Model-facing projection |
+| --- | --- |
+| Text | Its text. |
+| Inline image/audio | Link to an invocation-owned typed byte resource, published through {§executor-entry-sink}. |
+| Embedded text/blob resource | Link to a typed resource snapshot; use the supplied URI's filename when present. |
+| Resource link | Link to the existing MCP resource address; acquisition occurs on READ, not on listing. |
+
+Unnamed resources receive eight-character hexadecimal identifiers, not ordinal
+labels. No binary base64 is copied into the default result body. Listing a
+resource creates no native model attachment; READ uses {§packet-attachment-parts},
+including scoped byte reads, supported modalities, and single-request delivery.
+Resource publication is passive; completion of the originating execution retains
+its ordinary wake semantics. A single `resources/read` content item becomes the
+resource's typed body; multiple items become named children under its `resources/`
+folder and a directory of links. Each response retains its complete `#json` evidence;
+reconstructing the same collection preserves child paths ({§resource-publication-names}).
+Generated catalogs and prompt documents use two-space
+JSON indentation; individual text resources preserve their source layout. 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
@@ -516,25 +542,32 @@ even then the capability would be per-client-advertised, never daemon-wide.
 
 | MCP surface | Plurnk 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 |
+| 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 |
 
+Qualified `<server>://<worker>/…` resources, prompts, and catalogs follow
+{§runtime-resource-binding}: the qualifier selects the stored projection, not
+a private attachment. Acquisition uses the workspace attachment; the requesting
+operation retains its policy and client interactions.
+Returned Plurnk resource links retain that qualifier; MCP protocol URIs remain
+unchanged on the wire.
+
 §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 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
+{§executor-tool-document} carries a compact summary, requiredness derived from
+the input schema, and the original schema itself. The common renderer owns
+{§executor-input-schema-preview}, not an MCP-specific schema interpreter.
+The compact family document contains annotated, copyable tool invocations with
+shallow required-field previews and alias-scoped schema links. Each linked child
+preserves the complete remote description and raw input schema, without
+reconstructing property tables or expanding nested constraints into the preview.
+A missing remote description falls back to the tool name 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.

package/dist/McpExecutor.d.ts

@@ -1,22 +1,19 @@
 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 { ContentBlock } from "@modelcontextprotocol/client";
 import type { ToolPolicy } from "./config.ts";
 export declare const serverSummary: (name: string, catalog: ServerCatalog | undefined, override: string | undefined) => string;
 export declare const runtimeServerSummary: (name: string, catalog: ServerCatalog | undefined, override: string | undefined) => RuntimeSummaryDecl;
 export type ToolResultShape = {
-    readonly content?: ReadonlyArray<{
-        readonly type: string;
-        readonly text?: string;
-        readonly [field: string]: unknown;
-    }>;
+    readonly content?: readonly ContentBlock[];
     readonly structuredContent?: unknown;
     readonly isError?: boolean;
 };
-export declare const toolResultBody: (result: ToolResultShape) => {
+export declare const toolResultBody: (result: ToolResultShape, runtime: string, entry?: ExecArgs["entry"]) => Promise<{
     content: string;
     mimetype: string;
-};
+}>;
 export declare const runtimeDecl: (name: string, summary: RuntimeSummaryDecl, expandTools: boolean) => RuntimeDecl;
 export default class McpExecutor extends BaseExecutor {
     #private;
@@ -24,55 +21,13 @@ export default class McpExecutor extends BaseExecutor {
         runtime: string;
         glyph: string;
     }, 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;
-        writableBy: ReadonlyArray<import("@plurnk/plurnk-schemes").WriterTier>;
-        volatile: boolean;
-        modelVisible: boolean;
-        folderScopes?: boolean;
-        textEditScopes?: boolean;
-        metadataModifier?: boolean;
-        lineAnchors?: boolean;
-        foldedByDefault?: boolean;
-        traits?: ReadonlyArray<string>;
-        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;
-        metadataModifier?: boolean;
-        lineAnchors?: boolean;
-        foldedByDefault?: boolean;
-        traits?: ReadonlyArray<string>;
-        documentation?: string;
-        glyph?: string;
-        storedScheme?: string;
-        category: "logging" | "control";
-        entryOwner?: never;
-        inherit?: never;
-        example: string;
-    };
     get channels(): Readonly<Record<string, ChannelDecl>>;
     effect(target: string | null): Effect;
+    get publishedChannel(): string;
     toolRegistry(): RuntimeToolRegistry;
     get catalog(): ServerCatalog;
     probe(signal?: AbortSignal): Promise<RuntimeAvailability>;
     requireAvailable(signal?: AbortSignal): Promise<RuntimeAvailability>;
-    run({ runtime, body, target, signal, write, setState, emit, interact, }: ExecArgs): Promise<ExecResult>;
+    run({ runtime, body, target, signal, write, setState, emit, interact, entry, }: ExecArgs): Promise<ExecResult>;
 }
 //# sourceMappingURL=McpExecutor.d.ts.map

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,kBAAkB,EAClB,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;AAiC9C,eAAO,MAAM,aAAa,SAChB,MAAM,WACH,aAAa,GAAG,SAAS,YACxB,MAAM,GAAG,SAAS,KAC7B,MAOF,CAAC;AAIF,eAAO,MAAM,oBAAoB,SACvB,MAAM,WACH,aAAa,GAAG,SAAS,YACxB,MAAM,GAAG,SAAS,KAC7B,kBAIF,CAAC;AAMF,MAAM,MAAM,eAAe,GAAG;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC,CAAC;IACvH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEF,eAAO,MAAM,cAAc,WAAY,eAAe,KAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAU3F,CAAC;AAaF,eAAO,MAAM,WAAW,SAAU,MAAM,WAAW,kBAAkB,eAAe,OAAO,KAAG,WAc5F,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,CAyHhC;CACJ"}
+{"version":3,"file":"McpExecutor.d.ts","sourceRoot":"","sources":["../src/McpExecutor.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,YAAY,EAKf,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;AAGjF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAiC9C,eAAO,MAAM,aAAa,SAChB,MAAM,WACH,aAAa,GAAG,SAAS,YACxB,MAAM,GAAG,SAAS,KAC7B,MAOF,CAAC;AAIF,eAAO,MAAM,oBAAoB,SACvB,MAAM,WACH,aAAa,GAAG,SAAS,YACxB,MAAM,GAAG,SAAS,KAC7B,kBAIF,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,CAyBvJ,CAAC;AAEF,eAAO,MAAM,WAAW,SAAU,MAAM,WAAW,kBAAkB,eAAe,OAAO,KAAG,WAc5F,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,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;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,EACR,KAAK,GACR,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CA2HhC;CACJ"}