@cyanheads/mcp-ts-core 0.11.4 → 0.12.0

package/skills/add-tool/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a new MCP tool definition. Use when the user asks to add a tool, create a new tool, or implement a new capability for the server.
 metadata:
   author: cyanheads
-  version: "2.16"
+  version: "2.18"
   audience: external
   type: reference
 ---
@@ -16,8 +16,7 @@ Tools use the `tool()` builder from `@cyanheads/mcp-ts-core`. Each tool lives in
 ## Steps
 
 1. **Gather** the tool's name, purpose, and input/output shape from the user's request — ask only if genuinely absent
-2. **Determine if long-running** — if the tool involves streaming, polling, or
-   multi-step async work, it should use `task: true`
+2. **Determine if it needs input the caller may not supply** — a confirmation, a choice, the client's roots — which makes it a multi-round-trip handler (`ctx.requestInput` / `ctx.inputs`, see `api-context`)
 3. **Create the file** at `src/mcp-server/tools/definitions/{{tool-name}}.tool.ts`
 4. **Register** the tool in the project's existing `createApp()` tool list (directly in `src/index.ts` for fresh scaffolds, or via a barrel if the repo already has one)
 5. **Run `bun run devcheck`** to verify — if Biome reports formatting issues, run `bun run format` to auto-fix, then re-run devcheck
@@ -130,31 +129,48 @@ export const {{TOOL_EXPORT}} = tool('{{tool_name}}', {
 });
 ```
 
-### Task tool variant
+### Multi-round-trip variant
 
-Add `task: true` and use `ctx.progress` for long-running operations:
+A handler that needs something the caller didn't supply returns `ctx.requestInput(...)` and is re-entered with the answers on `ctx.inputs`. There is no mid-handler `await` for user input, and no capability check — the surface is always present, on every transport and both protocol eras.
 
 ```typescript
+import { inputRequired, tool, z } from '@cyanheads/mcp-ts-core';
+import { validationError } from '@cyanheads/mcp-ts-core/errors';
+
+const Confirm = z.object({ confirm: z.boolean().describe('Whether to proceed.') });
+
 export const {{TOOL_EXPORT}} = tool('{{tool_name}}', {
   description: '{{TOOL_DESCRIPTION}}',
-  task: true,
   input: z.object({ /* ... */ }),
   output: z.object({ /* ... */ }),
-
-  async handler(input, ctx) {
-    // ctx.progress is guaranteed non-null when task: true — the ! assertion is safe here.
-    await ctx.progress!.setTotal(totalSteps);
-    for (const step of steps) {
-      if (ctx.signal.aborted) break;
-      await ctx.progress!.update(`Processing: ${step}`);
-      // ... do work ...
-      await ctx.progress!.increment();
+  annotations: { destructiveHint: true },
+
+  handler(input, ctx) {
+    // Read what a prior round collected before asking for anything.
+    const answer = ctx.inputs.accepted('confirm', Confirm);
+    if (!answer) {
+      // A declined or cancelled prompt is a dead end — don't re-ask it.
+      const view = ctx.inputs.view('confirm');
+      if (view.kind === 'elicit' && view.action !== 'accept') {
+        throw validationError(`User ${view.action} the confirmation.`);
+      }
+      return ctx.requestInput({
+        inputRequests: {
+          confirm: inputRequired.elicit({
+            message: `Proceed with ${input.target}?`,
+            requestedSchema: Confirm,
+          }),
+        },
+      });
     }
+    // `answer` is narrowed here.
     return { /* output */ };
   },
 });
 ```
 
+Write it as `return ctx.requestInput(...)` — the `never` return type makes it valid in return position for any output, and it is what lets TypeScript narrow the line below. Full reference (`inputRequired.elicitUrl` / `.createMessage` / `.listRoots`, `requestState`, decline handling): `skills/api-context`.
+
 ### Registration
 
 ```typescript
@@ -208,7 +224,40 @@ export const submitObservations = getServerConfig().enableWrites
 | `/.well-known/mcp.json` `definitions.tools` (Server Card) | **Yes**, with `disabled` field — discovery agents see them as present-but-uncallable |
 | `/` (HTML landing page) | **Yes**, in a 4th muted bucket after `read \| write \| destructive` |
 
-The wrapper composes with both standard and task tools, and preserves all original definition fields (handler, schemas, auth scopes, error contracts) — when re-enabled, the tool already conforms to every lint rule.
+The wrapper preserves all original definition fields (handler, schemas, auth scopes, error contracts) — when re-enabled, the tool already conforms to every lint rule.
+
+## Schemas: what the framework stores vs. what clients see
+
+`tool()` and the handler factory do not hand your Zod schemas to the SDK verbatim. Two deliberate transforms sit in between.
+
+### Input is strict
+
+`tool()` stores `input` with `.strict()` applied, and the advertised `inputSchema` carries `additionalProperties: false` to match. An unrecognized argument key is **rejected by name** before the handler runs:
+
+```text
+Input validation error: Invalid arguments for tool <name>: Unrecognized key: "querry"
+```
+
+That arrives as an `isError: true` result, not a JSON-RPC error, and produces no framework span or log. The alternative — silently stripping the key — turns a caller's typo into a wrong answer they cannot detect: the value vanishes before the handler runs and the call fails downstream pointing at the wrong problem.
+
+Two limits worth knowing when you write a schema:
+
+- **Root level only**, matching `.strict()` itself. A nested `z.object()` inside the input still strips unknown keys unless it is strict in its own right — mark the nested option objects you want guarded.
+- **An explicit opening wins.** A definition that declared `.passthrough()` or `.catchall(...)` asked for an open object, and `tool()` leaves it alone. Use that (deliberately) for tools that proxy arbitrary upstream query parameters.
+
+### The advertised `outputSchema` is widened
+
+The framework parses a successful result against the strict effective schema — `output`, extended with the `enrichment` block when one is declared — so a required field the handler never populated still fails loudly. What it *advertises* in `tools/list` is a widened projection of that schema: every success field optional, plus a declared `error` property describing the failure envelope.
+
+The reason is client-side validation. A failing tool returns `structuredContent: { error: … }`, which can never satisfy a success-only schema; clients whose SDK validates `structuredContent` without first checking `isError` reject that envelope with `-32602` before the error ever reaches the agent. Widening the advertised schema is the only fix a server can ship, because the validator runs in the caller.
+
+The root stays `type: 'object'` (a discriminated union would emit `anyOf` with no `type`, which the 2025-era legacy projection rewrites — breaking the success path to fix the error path). The `required` list that the object form drops is recovered by an `anyOf` refinement in schema metadata: a result must satisfy either the success branch (success fields present, no `error`) or the failure branch (`error` present).
+
+Practical consequence: **do not read the advertised schema as the contract your handler must satisfy.** `output` is still the contract. The widened form is emission only.
+
+`data.reason` inside that envelope stays an unconstrained string. An `errors[]` contract covers what the *handler* throws, but a service it calls can raise its own reason (the SQL gate's `denied_function`, a parser's `yaml_parse_failed`), and that reaches the wire verbatim — an enum of the declared reasons would reject precisely those envelopes, recreating the `-32602` the widening exists to prevent. The declared reasons are emitted as `examples` and spelled out in the description instead.
+
+**`error` is a reserved output field name.** `tool()` throws if `output` or `enrichment` declares one: on the wire a failure *is* `structuredContent.error`, so a success payload using the same key cannot be told apart from a failure. Rename it (`errorText`, `failureDetail`).
 
 ## Tool Response Design
 
@@ -218,7 +267,7 @@ Tool responses are the LLM's only window into what happened. Every response shou
 
 Empty-result notices, the query/filter as the server parsed it, pagination totals — the context an agent *reasons with*, as opposed to the domain payload itself — must reach **both** client surfaces: `structuredContent` (from `output`) and `content[]` (from `format()`). Hand-authored into `format()` text alone, this context reaches `content[]` but is invisible to `structuredContent`-only clients (Claude Code, MCP-SDK API callers).
 
-Declare it as an `enrichment` block — the success-path counterpart to `errors[]` — and populate it via `ctx.enrich(...)` (or the kind-tagged helpers `ctx.enrich.notice()` / `.total()` / `.echo()`). The framework merges enrichment into `structuredContent`, advertises `output.extend(enrichment)` as the tool's `outputSchema`, and mirrors it into a `content[]` trailer — both surfaces, no `format()` entry, never touched by `format-parity`. `ctx.enrich` lives on the base `Context` (like `ctx.log`), so the service layer can populate it too.
+Declare it as an `enrichment` block — the success-path counterpart to `errors[]` — and populate it via `ctx.enrich(...)` (or the kind-tagged helpers `ctx.enrich.notice()` / `.total()` / `.echo()`). The framework merges enrichment into `structuredContent`, folds the block into the tool's advertised `outputSchema` (see [Schemas](#schemas-what-the-framework-stores-vs-what-clients-see)), and mirrors it into a `content[]` trailer — both surfaces, no `format()` entry, never touched by `format-parity`. `ctx.enrich` lives on the base `Context` (like `ctx.log`), so the service layer can populate it too.
 
 ```typescript
 enrichment: {
@@ -673,8 +722,8 @@ return { items: hits };
 - [ ] `auth` scopes declared if the tool needs authorization
 - [ ] `errors: [...]` contract declared for the tool's domain-specific failure modes — or block deleted if no domain failures apply (baseline codes bubble freely)
 - [ ] Error contract declared inline on this tool — not imported from a shared module, even when other tools have near-identical entries
-- [ ] `task: true` added if the tool is long-running
-- [ ] If `task: true`: handler checks `ctx.signal.aborted` in its loop for cancellation support
+- [ ] Long loops check `ctx.signal.aborted` so a cancelled request (or a closed transport) stops the work
+- [ ] If the tool needs caller input it may not have been given: reads `ctx.inputs` first, requests only what is missing via `return ctx.requestInput(...)`, and treats a declined/cancelled response as terminal rather than re-asking
 - [ ] If tool returns unbounded arrays: pagination with total count, or `spillover()` / DataCanvas for *analytical* working sets (an agent would SQL them — not a discovery/search surface). If any tool emits a `canvas_id`, a `dataframe_query` tool is registered in the same server — a token with no query tool is dead output
 - [ ] If tool returns one large *document* (not a row set) that can overflow context: `outlineOnOverflow()` returns a `full | outline` union so the agent re-calls with `sections: [...]` — not one-sided truncation
 - [ ] If tool is feature-gated: evaluated whether `disabledTool()` wrapper is appropriate (present in manifest but uncallable)

package/skills/api-canvas/SKILL.md

@@ -4,7 +4,7 @@ description: >
   DataCanvas primitive reference — a Tier 3 SQL/analytical workspace for tabular MCP servers, backed by DuckDB. Use when registering tables from upstream APIs, running ad-hoc SQL across them, and exporting results. Covers the acquire → register → query → export flow, per-table TTL, the token-sharing pattern for multi-agent collaboration, env config, and Cloudflare Workers fail-closed behavior.
 metadata:
   author: cyanheads
-  version: "2.0"
+  version: "2.1"
   audience: external
   type: reference
 ---
@@ -296,7 +296,7 @@ Most canvas use cases are public-data analytics: fetch from an upstream API, sta
 | Table naming | `spillover()` auto-names the table `spilled_<id>`; pass `tableName` for a stable handle. A dataframe-query surface commonly adds its own `df_<id>` convention. |
 | Access control | Possession of the `canvas_id` is access — unguessable in practice (see [token-sharing model](#the-token-sharing-model)). TTL + the framework rate limiter backstop brute force. |
 | Enable flag | None of your own — canvas presence is the gate (`CANVAS_PROVIDER_TYPE=duckdb`; `getCanvas()` returns `undefined` otherwise). |
-| Tools | A fetcher that spills **plus a `dataframe_query` tool — mandatory once anything emits a `canvas_id`**: a token with no query tool in the same server is dead output (the agent can't reach the staged data). `dataframe_describe` is strongly recommended — it lets the agent discover staged table and column names before writing SQL. `dataframe_drop` is optional. None are framework-provided; you register them. |
+| Tools | A fetcher that spills **plus the dataframe trio — all three ship whenever canvas is integrated**. `dataframe_query` is mandatory once anything emits a `canvas_id`: a token with no query tool in the same server is dead output (the agent can't reach the staged data). `dataframe_describe` is required alongside it — the agent discovers staged table and column names before writing SQL. `dataframe_drop` is implemented but **opt-in via a server env var**: when the flag is off, register it with `disabledTool()` (see `add-tool`) so it stays visible in the manifest with the enable hint while uncallable. None are framework-provided; you register them. |
 | Fetcher output | Two things in one response: the inline preview (answer to the immediate question) and the table handle (escape hatch for follow-up SQL via `dataframe_query`). Neither replaces the other. |
 
 > The `MCP_HTTP_MAX_BODY_BYTES` request-body cap is **inbound-only** — it bounds the JSON-RPC request, not the upstream data a handler stages into the canvas or the rows it returns. Canvas servers send small requests (queries, SQL, canvas IDs) regardless of dataset size, so the cap never constrains canvas ingestion.

package/skills/api-config/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Reference for core and server configuration in `@cyanheads/mcp-ts-core`. Covers env var tables with defaults, priority order, server-specific Zod schema pattern, and Workers lazy-parsing requirement.
 metadata:
   author: cyanheads
-  version: "1.9"
+  version: "1.10"
   audience: external
   type: reference
 ---
@@ -177,16 +177,6 @@ Activated when both `SUPABASE_URL` and `SUPABASE_ANON_KEY` are set.
 
 ---
 
-### Tasks
-
-| Env Var | `AppConfig` field | Default | Notes |
-|:--------|:-----------------|:--------|:------|
-| `TASK_STORE_TYPE` | `tasks.storeType` | `in-memory` | `in-memory` \| `storage`; aliases: `mem`/`memory`→`in-memory`, `persistent`→`storage` |
-| `TASK_STORE_TENANT_ID` | `tasks.tenantId` | `system-tasks` | Tenant ID for task state storage |
-| `TASK_STORE_DEFAULT_TTL_MS` | `tasks.defaultTtlMs` | — | TTL for completed tasks (ms); null = no expiry |
-
----
-
 ### Speech (optional sub-object)
 
 Activated when `SPEECH_TTS_ENABLED` or `SPEECH_STT_ENABLED` is set.

package/skills/api-context/SKILL.md

@@ -1,17 +1,17 @@
 ---
 name: api-context
 description: >
-  Canonical reference for the unified `Context` object passed to every tool and resource handler in `@cyanheads/mcp-ts-core`. Covers the full interface, all sub-APIs (`ctx.log`, `ctx.state`, `ctx.elicit`, `ctx.progress`, `ctx.enrich`, `ctx.content`), and when to use each.
+  Canonical reference for the unified `Context` object passed to every tool and resource handler in `@cyanheads/mcp-ts-core`. Covers the full interface, its `RequestContext` base, all sub-APIs (`ctx.log`, `ctx.state`, `ctx.requestInput`, `ctx.inputs`, `ctx.enrich`, `ctx.content`), and when to use each.
 metadata:
   author: cyanheads
-  version: "1.11"
+  version: "2.0"
   audience: external
   type: reference
 ---
 
 ## Overview
 
-Every tool and resource handler receives a single `Context` (`ctx`) argument. It provides request identity, structured logging, tenant-scoped storage, optional protocol capabilities (elicitation), cancellation, and task progress — all auto-correlated to the current request.
+Every tool and resource handler receives a single `Context` (`ctx`) argument. It provides request identity, structured logging, tenant-scoped storage, multi-round-trip input collection, and cancellation — all auto-correlated to the current request.
 
 The framework auto-instruments every handler call (OTel span, duration, payload metrics). Use `ctx.log` for domain-specific logging and `ctx.state` for storage inside handlers. Use the global `logger` and `StorageService` directly only in lifecycle/background code (`setup()`, services).
 
@@ -22,8 +22,8 @@ The framework auto-instruments every handler call (OTel span, duration, payload
 ```ts
 import type { Context } from '@cyanheads/mcp-ts-core';
 
-interface Context {
-  // Identity & tracing
+interface Context extends RequestContext {
+  // Identity & tracing (inherited from RequestContext — see § RequestContext)
   readonly requestId: string;       // Unique per request, auto-generated
   readonly timestamp: string;       // ISO 8601 request start time
   readonly tenantId?: string;       // JWT 'tid' claim; 'default' for stdio and HTTP+MCP_AUTH_MODE=none
@@ -31,15 +31,19 @@ interface Context {
   readonly traceId?: string;        // OTEL trace ID (present when OTEL enabled)
   readonly spanId?: string;         // OTEL span ID (present when OTEL enabled)
   readonly auth?: AuthContext;      // Parsed auth claims (clientId, scopes, sub)
+  readonly operation?: string;      // Label for the operation this context belongs to
+  readonly extra?: Readonly<Record<string, unknown>>;  // Correlation bag — the one open field
 
-  // Structured logging — auto-includes requestId, traceId, tenantId
+  // Structured logging — auto-includes requestId, traceId, tenantId.
+  // Dual-sink: Pino on the server, plus notifications/message to the client.
   readonly log: ContextLogger;
 
   // Tenant-scoped key-value storage
   readonly state: ContextState;
 
-  // Optional protocol capabilities (undefined when client doesn't support them)
-  readonly elicit?: ElicitFn; // callable (message, schema) for form mode + .url(message, url) — see § ctx.elicit
+  // Multi-round-trip input — always present, both eras (see § ctx.requestInput)
+  readonly requestInput: RequestInputFn;   // (spec) => never — suspends and asks the caller
+  readonly inputs: ContextInputs;          // reader over a retried request's responses
 
   // List-changed / resource-updated notifications — wired in every handler ctx;
   // delivery is request-scoped (see § list-changed notifications)
@@ -51,9 +55,6 @@ interface Context {
   // Cancellation
   readonly signal: AbortSignal;
 
-  // Task progress — present only when tool is defined with task: true
-  readonly progress?: ContextProgress;
-
   // Raw URI — present only for resource handlers
   readonly uri?: URL;
 
@@ -91,10 +92,65 @@ interface Context {
 
 ---
 
+## `RequestContext` — the one canonical request shape
+
+`Context extends RequestContext`. There is a single request-shape type; the handler-facing `Context` adds handler-only surfaces (`log`, `state`, `signal`, `requestInput`, `inputs`, `enrich`, `content`, `uri`) on top of it and redeclares none of the identity fields. A handler's `ctx` is therefore assignable anywhere a `RequestContext` is — services, storage, the framework logger — with no slice helper and no cast.
+
+```ts
+import { requestContextService, withExtra } from '@cyanheads/mcp-ts-core/utils';
+import type { RequestContext } from '@cyanheads/mcp-ts-core/utils';
+
+// A service typed against RequestContext accepts a handler ctx directly.
+async function fetchUser(id: string, ctx: RequestContext) { /* … */ }
+await fetchUser('123', ctx);   // ctx is a Context — no conversion
+```
+
+### Closed by design
+
+`RequestContext` has **no index signature**. Its fields are exactly: `auth`, `extra`, `operation`, `requestId`, `sessionId`, `spanId`, `tenantId`, `timestamp`, `traceId`. A misspelled canonical field (`tenatId`) is a compile error instead of a silently-ignored key.
+
+Operation-specific correlation data goes in **`extra`** — the one deliberate open bag (`Readonly<Record<string, unknown>>`). The logger flattens `extra` into the emitted line, so log output looks the same as a top-level spread.
+
+### Adding correlation data
+
+Three supported ways, most common first:
+
+```ts
+// 1. Per-log-call metadata — the common case. Nothing lands on the context.
+ctx.log.info('Retrying upstream call', { attempt, url });
+
+// 2. A copy of this context carrying extra fields. `withExtra` MERGES into any
+//    bag the parent already had; a hand-written `{ ...ctx, extra: {…} }` replaces it.
+logger.warning('Retrying upstream call', withExtra(ctx, { attempt, url }));
+
+// 3. A derived context for a sub-operation. `additionalContext` lands on `extra`,
+//    merged over whatever the parent already carried.
+const childCtx = requestContextService.createRequestContext({
+  parentContext: ctx,
+  operation: 'processItem',
+  additionalContext: { itemId: item.id },   // → childCtx.extra.itemId
+});
+
+// Reading an ad-hoc key back off a context:
+const itemId = childCtx.extra?.itemId;
+```
+
+`createRequestContext(params)` takes a closed parameter object — `additionalContext`, `operation`, `parentContext`, `tenantId` — and nothing else; a key it doesn't declare is a compile error rather than an arbitrary passthrough.
+
+Never re-open the shape to get past a type error: no index signature, no widening a parameter back to `Record<string, unknown>`, no `as` cast. A `{ ...ctx, someKey }` object literal that fails to compile is the signal to move `someKey` into `extra`, not to loosen the type.
+
+`ErrorContext` (the `ErrorHandler` call's `context`) is `Partial<RequestContext>` and is closed the same way — put ad-hoc keys under `extra` via `withExtra`, or pass them in the `ErrorHandler` call's own `context` field.
+
+`RequestContextLike` is a deprecated alias for `RequestContext`, kept for one minor. Replace every use with `RequestContext`, and collapse any `RequestContextLike | RequestContext` parameter union to plain `RequestContext`.
+
+---
+
 ## `ctx.log`
 
 Request-scoped structured logger. Every log line is automatically annotated with `requestId`, `traceId`, and `tenantId` — no manual spreading needed.
 
+**Dual-sink.** Each call writes to Pino *and* mirrors onto the MCP wire as a `notifications/message` (the framework advertises the `logging` capability, and the SDK filters by the level the client set via `logging/setLevel`). The wire payload is `{ message, ...data }`; `ctx.log.error` adds `error: <message>`. Delivery is fire-and-forget — a client that never upgraded to SSE, set a higher level, or already disconnected drops the notification, and a failed send never fails the handler. Treat `ctx.log` as client-visible: it is no longer a server-only sink, so don't log anything there you wouldn't put in a tool result.
+
 ### Methods
 
 | Method | Level |
@@ -255,71 +311,120 @@ await ctx.state.set(sessionKey, value);
 ### Behavior notes
 
 - **Not a tenant boundary.** `ctx.state` is still tenant-scoped. Building session-scoped state is the consumer's responsibility — prefix with `session/${ctx.sessionId}/` as shown above.
-- **Auto-task tools.** `task: true` handlers run in a detached background context with no session attachment — `ctx.sessionId` is always `undefined` regardless of mode.
+- **Protocol revision.** Sessions belong to the 2025-era arm, which negotiates its revision through `initialize` and carries `Mcp-Session-Id`. The [2026-07-28 revision](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports) has no session at all — it is per-request, selected by the request's own `_meta` envelope — so `ctx.sessionId` is `undefined` for every request served on that leg.
 - **Worker bundle.** Workers use the same HTTP transport plumbing; session behavior matches Node HTTP.
 
 ---
 
-## `ctx.elicit`
+## `ctx.requestInput` / `ctx.inputs`
+
+Always present, on every transport and both protocol eras. A handler that needs something the caller didn't supply **returns** `ctx.requestInput(...)` and is re-entered with the answers on `ctx.inputs` — there is no mid-handler `await` for user input.
 
-Optional — `undefined` when the connected client doesn't advertise the `elicitation` capability (checked per request, after the initialize handshake). Check for presence before calling. A simple truthiness check is enough; no type guards needed.
+`ctx.requestInput(spec)` never returns: it throws an `InputRequiredSignal` that the tool, resource, and prompt handler factories catch and convert into the protocol's [`input_required`](https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/mrtr) result. It bypasses the error classifier entirely — no span, no log, no `isError`.
 
-`ctx.elicit` is an `ElicitFn` (exported from the main entry): directly callable for form-mode elicitation, with a `.url(message, url)` method for URL-mode. On the wire, the Zod schema is converted to the restricted flat JSON Schema the MCP spec requires — handlers never deal with that detail.
+One code path serves both eras. A 2026-07-28 client fulfils the embedded requests and retries the call; for a 2025-era session the SDK's legacy shim fulfils the same returns by issuing real `elicitation/create` / `sampling/createMessage` / `roots/list` round trips and re-entering the handler itself.
 
-### `ctx.elicit` — ask the user for structured input
+### The shape of a multi-round-trip handler
 
-Presents a form to the user via the MCP elicitation protocol. The user fills in a Zod-validated schema and returns an action (`accept`, `decline`, or `cancel`).
+Read `ctx.inputs` first, request only what is still missing, and write the call in return position so TypeScript narrows the line below it.
 
 ```ts
-if (ctx.elicit) {
-  const result = await ctx.elicit(
-    'Which output format do you want?',
-    z.object({
-      format: z.enum(['json', 'csv', 'markdown']).describe('Output format'),
-      includeHeaders: z.boolean().default(true).describe('Include column headers'),
-    }),
-  );
-
-  if (result.action === 'accept') {
-    // result.content is Record<string, string | number | boolean | string[]> | undefined
-    await produceOutput(result.content?.format as string, result.content?.includeHeaders as boolean);
-  } else {
-    // 'decline' or 'cancel' — user opted out
-    throw invalidRequest('User declined input');
-  }
-}
+import { inputRequired, tool, z } from '@cyanheads/mcp-ts-core';
+import { validationError } from '@cyanheads/mcp-ts-core/errors';
+
+const Confirm = z.object({
+  confirm: z.boolean().describe('Whether to proceed with the deletion.'),
+});
+
+export const deletePath = tool('delete_path', {
+  description: 'Delete a path after confirming with the user.',
+  input: z.object({ path: z.string().describe('Path to delete') }),
+  output: z.object({ deleted: z.string().describe('The path that was deleted') }),
+  annotations: { destructiveHint: true },
+
+  handler(input, ctx) {
+    // A declined or cancelled prompt is a dead end, not a round to retry —
+    // re-asking loops until the round budget runs out.
+    const view = ctx.inputs.view('confirm');
+    if (view.kind === 'elicit' && view.action !== 'accept') {
+      throw validationError(`User ${view.action} the confirmation.`);
+    }
+
+    const answer = ctx.inputs.accepted('confirm', Confirm);
+    if (!answer) {
+      return ctx.requestInput({
+        inputRequests: {
+          confirm: inputRequired.elicit({
+            message: `Delete ${input.path}?`,
+            requestedSchema: Confirm,
+          }),
+        },
+      });
+    }
+    // `answer` is narrowed here.
+    if (!answer.confirm) throw validationError('Deletion not confirmed.');
+
+    return { deleted: remove(input.path) };
+  },
+});
 ```
 
-`ElicitResult` (from `@modelcontextprotocol/sdk/types.js`):
+`ctx.requestInput` returns `never`, so `return ctx.requestInput(...)` type-checks against any output type. Calling it as a bare statement works at runtime — and is the only option from a service-layer helper — but TypeScript will not narrow across it.
+
+### Building the embedded requests
+
+`inputRequired` is re-exported from the main entry. Its per-kind constructors build the entries of `inputRequests`:
+
+| Constructor | Wire request | Notes |
+|:---|:---|:---|
+| `inputRequired.elicit({ message, requestedSchema })` | `elicitation/create` (form) | `requestedSchema` accepts a Zod schema; shapes the restricted elicitation JSON Schema can't express throw a `TypeError` before anything is sent |
+| `inputRequired.elicitUrl({ message, url })` | `elicitation/create` (URL) | Authorization flows, hosted forms. On 2026-07-28 URL mode rides the same multi-round-trip flow; the 2025-era `elicitationId` is not part of that shape — correlate with your own identifier inside `requestState` |
+| `inputRequired.createMessage(params)` | `sampling/createMessage` | Ask the client's model |
+| `inputRequired.listRoots()` | `roots/list` | Ask for the client's filesystem roots |
+
+At least one of `inputRequests` or `requestState` must be supplied — the builder throws a `TypeError` otherwise.
+
+### `requestState` — carrying server state across rounds
 
 ```ts
-// Actual SDK type — a flat object, not a discriminated union
-interface ElicitResult {
-  action: 'accept' | 'decline' | 'cancel';
-  // Present when action === 'accept'; values are primitives or string arrays
-  content?: Record<string, string | number | boolean | string[]>;
-}
+return ctx.requestInput({
+  inputRequests: { confirm: inputRequired.elicit({ message, requestedSchema: Confirm }) },
+  requestState: JSON.stringify({ jobId }),
+});
+// Next round:
+const state = ctx.inputs.state<string>();
 ```
 
-> **Note:** `content` is not typed against the Zod schema you pass — it is a `Record` of primitives. Validate `content` against your schema manually (e.g. `MySchema.parse(result.content)`) when `action === 'accept'`.
+`requestState` round-trips **through the client** and comes back as attacker-controlled input. Integrity-protect (HMAC/AEAD) anything that influences authorization, resource access, or business logic, and reject state that fails verification — the SDK does not do this for you.
+
+### `ctx.inputs` — reading a retried request's responses
+
+Empty on the first round; populated on re-entry.
+
+| Member | Returns |
+|:---|:---|
+| `accepted(key, schema?)` | The accepted form-mode content for `key`, or `undefined` when the key is missing, the user declined or cancelled, the response was another kind, or (with a schema) validation failed |
+| `view(key)` | Discriminated view of one entry: `{ kind: 'missing' }` \| `{ kind: 'elicit', action, content? }` \| `{ kind: 'sampling', result }` \| `{ kind: 'roots', roots }` |
+| `state<T>()` | This round's `requestState` — verified value, raw wire string when no verifier is configured, or `undefined` on the first round |
+| `dropped` | Keys the SDK dropped because the client sent a wrapped rather than a bare response object. Re-issue those requests instead of hard-failing |
+| `responses` | The raw response map, for kinds the helpers don't cover |
+
+Two rules follow from what the SDK does *not* do:
+
+- **Responses are never re-validated against the schema the request advertised.** Pass the schema to `accepted(key, schema)` wherever the content matters, and treat every value as untrusted client input.
+- **`undefined` from `accepted()` collapses five different outcomes into one.** Missing, declined, cancelled, wrong response kind, and schema-invalid are indistinguishable through it. Branch on `view(key)` when decline/cancel needs different handling from "not asked yet" — as above, re-issuing a request the user already declined just burns rounds.
 
-### `ctx.elicit.url` — hand the user an external link
+### Testing
 
-URL-mode elicitation (MCP 2025-11-25): instead of an inline form, the client directs the user to an external URL — authorization flows, hosted forms. The framework generates the protocol-required `elicitationId` internally.
+`createMockContext({ inputResponses, requestState })` seeds `ctx.inputs`, so a handler can be driven straight into its second round:
 
 ```ts
-if (ctx.elicit) {
-  const result = await ctx.elicit.url(
-    'Authorize access to your account',
-    'https://example.com/oauth/authorize?state=...',
-  );
-  if (result.action !== 'accept') throw forbidden('Authorization declined');
-}
+const ctx = createMockContext({
+  inputResponses: { confirm: { action: 'accept', content: { confirm: true } } },
+});
 ```
 
-`result.content` is absent in URL mode — the interaction completes out-of-band; only `action` reports the outcome.
-
-**Convention:** Only call `ctx.elicit` from tool handlers, not from services.
+**Convention:** only call `ctx.requestInput` from tool, resource, and prompt handlers — not from services.
 
 ---
 
@@ -342,15 +447,21 @@ A notification fired **from inside a handler** routes through that request's own
 | Fired from | stdio | HTTP / Workers |
 |:-----------|:------|:---------------|
 | A tool / resource handler | ✅ delivered | ✅ delivered (on the request's SSE response stream) |
-| A `task: true` background handler, cron, or any non-request scope | ✅ delivered | ⚠️ dropped — no request scope to route through |
+| A `setup()` hook, cron job, or any non-request scope | ✅ delivered | ⚠️ dropped — no request scope to route through |
+
+The background-under-HTTP gap is a known limitation; a session-scoped notification bus would close it.
+
+### `notifyResourceUpdated` is subscription-scoped
 
-The background-under-HTTP gap is a known limitation; a session-scoped notification bus would close it. `notifyResourceUpdated` routes to the calling request, not to clients that subscribed to the URI — the framework tracks no subscription state.
+The framework advertises `resources: { subscribe: true }` and backs it with real `resources/subscribe` / `resources/unsubscribe` handlers, so `notifyResourceUpdated(uri)` emits only for URIs the connected client actually subscribed to; an unsubscribed URI logs at debug and sends nothing. Both handlers are idempotent — re-subscribing is a no-op, and unsubscribing from a URI that was never subscribed succeeds.
+
+The registry's scope is the `McpServer` instance, which is also the connection: one persistent instance per session on the 2025-era sessionful arm, one per request under per-request serving. On the per-request leg a subscription cannot outlive the request that created it, so a handler-time `ctx.notifyResourceUpdated(uri)` delivers only when that same exchange subscribed first.
 
 ---
 
 ## `ctx.signal`
 
-Standard `AbortSignal`. Present on every context. Set when the client cancels the request or when a task tool is cancelled.
+Standard `AbortSignal`. Present on every context. Fires when the client cancels the request — and when the transport closes, which aborts every in-flight handler.
 
 ```ts
 // Check before expensive operations
@@ -366,55 +477,6 @@ for (const item of items) {
 }
 ```
 
-In task tools (`task: true`), the framework signals `ctx.signal` when the client sends a cancellation request.
-
----
-
-## `ctx.progress`
-
-Present only when the tool definition includes `task: true`. Undefined for standard (non-task) tools and all resource handlers.
-
-### Methods
-
-| Method | Purpose |
-|:-------|:--------|
-| `ctx.progress.setTotal(n)` | Set the total number of steps (enables percentage calculation on client) |
-| `ctx.progress.increment(amount?)` | Advance progress by `amount` (default: 1) |
-| `ctx.progress.update(message)` | Send a descriptive status message without advancing the counter |
-
-### Usage
-
-```ts
-const asyncCountdown = tool('async_countdown', {
-  description: 'Count down from a number with progress updates.',
-  task: true,
-  input: z.object({
-    count: z.number().int().positive().describe('Number to count down from'),
-    delayMs: z.number().default(1000).describe('Delay between counts in ms'),
-  }),
-  output: z.object({
-    finalCount: z.number().describe('Final count value'),
-    message: z.string().describe('Completion message'),
-  }),
-
-  async handler(input, ctx) {
-    await ctx.progress!.setTotal(input.count);
-
-    for (let i = input.count; i > 0; i--) {
-      if (ctx.signal.aborted) break;
-
-      await ctx.progress!.update(`Counting: ${i}`);
-      await new Promise(resolve => setTimeout(resolve, input.delayMs));
-      await ctx.progress!.increment();
-    }
-
-    return { finalCount: 0, message: 'Countdown complete' };
-  },
-});
-```
-
-**Note:** Use the non-null assertion (`ctx.progress!`) when accessing inside a `task: true` handler — the type is `ContextProgress | undefined` even though it's guaranteed present at runtime. TypeScript cannot narrow based on the `task` flag.
-
 ---
 
 ## `ctx.uri`
@@ -548,7 +610,7 @@ The `≥5 words` lint rule on contract `recovery` (validated at lint time) makes
 
 ## `ctx.enrich`
 
-Always present on `Context`. Accumulates agent-facing **success-path** context — empty-result notices, the query/filter as the server parsed it, pagination totals — onto the request. The framework merges it into `structuredContent`, advertises `output.extend(enrichment)` as the tool's `outputSchema`, and mirrors it into a `content[]` trailer. The success-path counterpart to `ctx.fail` / `ctx.recoveryFor`.
+Always present on `Context`. Accumulates agent-facing **success-path** context — empty-result notices, the query/filter as the server parsed it, pagination totals — onto the request. The framework merges it into `structuredContent`, folds the `enrichment` block into the tool's advertised `outputSchema`, and mirrors it into a `content[]` trailer. The success-path counterpart to `ctx.fail` / `ctx.recoveryFor`.
 
 ```ts
 export const search = tool('search', {
@@ -698,21 +760,23 @@ Test content blocks with `getContentBlocks(ctx)` from `@cyanheads/mcp-ts-core/te
 | `ctx.requestId` | `string` | Always |
 | `ctx.timestamp` | `string` | Always |
 | `ctx.tenantId` | `string \| undefined` | Stdio (`'default'`); HTTP+`MCP_AUTH_MODE=none` (`'default'`); HTTP+`jwt`/`oauth` (JWT `tid` claim — undefined if absent) |
-| `ctx.sessionId` | `string \| undefined` | HTTP `stateful` / `auto` mode; stateless HTTP only when `createApp({ context: { exposeStatelessSessionId: true } })`; never in stdio or auto-task handlers |
+| `ctx.sessionId` | `string \| undefined` | HTTP `stateful` / `auto` mode; stateless HTTP only when `createApp({ context: { exposeStatelessSessionId: true } })`; never in stdio or on the session-less 2026-07-28 leg |
 | `ctx.traceId` | `string \| undefined` | OTEL enabled |
 | `ctx.spanId` | `string \| undefined` | OTEL enabled |
 | `ctx.auth` | `AuthContext \| undefined` | Auth enabled |
+| `ctx.operation` | `string \| undefined` | Set by the context that created it (`'HandleToolRequest'` for tool calls) |
+| `ctx.extra` | `Readonly<Record<string, unknown>> \| undefined` | When correlation data was attached — the one open bag on the closed shape |
 | `ctx.log` | `ContextLogger` | Always |
 | `ctx.state` | `ContextState` | Always (throws if `tenantId` missing) |
 | `ctx.signal` | `AbortSignal` | Always |
 | `ctx.enrich` | `Enrich` | Always; typed on `HandlerContext<R, E>` when an `enrichment` block is declared |
 | `ctx.content` | `ContentCollect` | Always — prepends image/audio blocks to `content[]`, never `structuredContent` |
-| `ctx.elicit` | `function \| undefined` | Client supports elicitation |
+| `ctx.requestInput` | `(spec) => never` | Always — suspends the handler and asks the caller for more input |
+| `ctx.inputs` | `ContextInputs` | Always; empty until the request is retried with responses |
 | `ctx.notifyResourceListChanged` | `function \| undefined` | Always in handler ctx; delivery request-scoped (see [§ list-changed notifications](#list-changed-notifications-ctxnotify)) |
-| `ctx.notifyResourceUpdated` | `function \| undefined` | Always in handler ctx; delivery request-scoped |
+| `ctx.notifyResourceUpdated` | `function \| undefined` | Always in handler ctx; delivery request-scoped **and** limited to URIs the client subscribed to |
 | `ctx.notifyPromptListChanged` | `function \| undefined` | Always in handler ctx; delivery request-scoped |
 | `ctx.notifyToolListChanged` | `function \| undefined` | Always in handler ctx; delivery request-scoped |
-| `ctx.progress` | `ContextProgress \| undefined` | Tool defined with `task: true` |
 | `ctx.uri` | `URL \| undefined` | Resource handlers only |
 | `ctx.fail` | `(reason, msg?, data?, opts?) => McpError` | Definition declares `errors[]` contract |
 | `ctx.recoveryFor` | `(reason) => { recovery: { hint } } \| {}` | Always (no-op when no contract); strictly typed on `HandlerContext<R>` |

package/skills/api-linter/SKILL.md

@@ -4,7 +4,7 @@ description: >
   MCP definition linter rules reference. Use when `bun run lint:mcp` or `bun run devcheck` reports a lint error or warning (`format-parity`, `schema-is-object`, `name-format`, `server-json-*`, etc.) and you need to understand the rule, its severity, and how to fix it. Every rule ID the linter emits has an entry in this doc.
 metadata:
   author: cyanheads
-  version: "1.9"
+  version: "1.10"
   audience: external
   type: reference
 ---
@@ -789,7 +789,7 @@ The diagnostic message includes the declared reason(s) for the code so you can c
 
 ## Enrichment rules
 
-Validate the `enrichment` block — the success-path counterpart to `errors[]`. Enrichment fields are merged into `structuredContent` and advertised as `output.extend(enrichment)`, so the linter guards the block's shape and its disjointness from `output`. See `api-context`'s `ctx.enrich` and `add-tool`'s **Tool Response Design**.
+Validate the `enrichment` block — the success-path counterpart to `errors[]`. Enrichment fields are merged into `structuredContent` and folded into the advertised `outputSchema`, so the linter guards the block's shape and its disjointness from `output`. See `api-context`'s `ctx.enrich` and `add-tool`'s **Tool Response Design**.
 
 ### enrichment-type