@homeflare/seat-runtime 0.1.0

package/docs/state.md

@@ -0,0 +1,174 @@
+# `SeatState`: Postgres and Valkey, on the `/state` subpath
+
+A seat's durable state is Postgres (runs, resumes, results) and its fast state is Valkey (locks,
+counters, caches). `@homeflare/seat-runtime/state` builds each as the **Effect service that already
+exists for it**, so consumer code is ordinary Effect SQL and Redis:
+
+| store    | service                                                           | from                                   |
+| -------- | ----------------------------------------------------------------- | -------------------------------------- |
+| Postgres | `SqlClient` (and `PgClient`, re-exported as `SeatState.PgClient`) | `@effect/sql-pg` rc.115, its own layer |
+| Valkey   | `Redis` (`send`, `eval`; not `subscribe`)                         | `effect/unstable/persistence/Redis`    |
+
+```ts
+import { Effect, Redacted } from 'effect';
+import * as Redis from 'effect/unstable/persistence/Redis';
+import * as SqlClient from 'effect/unstable/sql/SqlClient';
+import { SeatState } from '@homeflare/seat-runtime/state';
+
+const state = SeatState.layer({
+  postgres: { url: Redacted.make(pgDsn) }, // postgres://user:pass@host:5432/db
+  valkey: { url: Redacted.make(vkUrl) }, // redis://seat:pass@host:6381
+});
+// or, each read from an environment variable: SEAT_POSTGRES_URL and SEAT_VALKEY_URL
+const fromEnv = SeatState.layerFromEnv();
+
+const program = Effect.gen(function* () {
+  const sql = yield* SqlClient.SqlClient;
+  const redis = yield* Redis.Redis;
+  yield* sql`insert into runs (id) values (${id})`;
+  yield* redis.send('SET', `seat:run:${id}`, 'started');
+}).pipe(Effect.provide(state));
+```
+
+`SeatState.postgres`, `postgresFromEnv`, `valkey`, `valkeyFromEnv`, `layer` and `layerFromEnv` are
+the constructors. Each `*FromEnv` takes `{ variable }` to read another name. ⛔ **This package holds
+no host**: every URL is the consumer's, held `Redacted`, and no default points anywhere.
+
+## Building a layer connects
+
+Both layers connect and authenticate when they are built, so a wrong URL, user or password fails at
+**startup** as a typed error (`SqlError`, `RedisError`, or `ConfigError` for a missing variable), not
+at the first query. Postgres runs `select 1`; Valkey runs `connect()`. Each is bounded:
+`connectTimeout` (Postgres) and `connectionTimeout` (Valkey), 5 s by default. A Valkey server that is
+down is retried until that timeout, so one that is a moment late is waited for.
+
+## A Valkey that goes away, and comes back
+
+Commands fail **at once** while the connection is down (`RedisError`, the offline queue is off), and
+the seat retries in Effect, where an attempt is a span. What makes that retry worth anything is that
+**the layer reconnects itself**: 🔴 measured 2026-09-29 (Bun 1.4.0, default `maxRetries` 20), a
+`Bun.RedisClient` retries on its own for about 31 s of outage and then GIVES UP, after which it stays
+dead (`Connection has failed`) even when the server is back, until `connect()` is called again. The
+review that found it measured the same cliff between 30 s (recovered) and 45 s (not). So a seat whose
+Valkey restarted for a minute lost it until the process restarted.
+
+Off Bun's `onclose` the layer now calls `connect()` again: one attempt at a time, each bounded by
+`connectionTimeout`, pausing 250 ms doubling to 5 s between attempts, with one `valkey reconnect`
+span per attempt, a warning when it starts and an info line when it succeeds. It stops with the
+layer's scope. `maxRetries` (option) sets when this loop takes over from Bun's. Measured through the
+layer with the DEFAULT budget (scratch server, `connectionTimeout` 3 s): after a 45 s outage the first
+`PING` was answered 1.5 s after the server returned, after a 75 s outage 1.8 s. The test suite uses
+`maxRetries: 2`, which makes Bun give up after about 0.3 s.
+
+- ⛔ `onclose` also runs for every failed `connect()` and for the client's own `close()`, so it is a
+  hint: the loop runs only while `client.connected` is false.
+- 🔴 **`client.onclose = null` breaks `close()`.** Bun accepts it, and `close()` then calls the null
+  and throws `TypeError: ... is not a function` (worded with whatever call site is on the stack).
+  The layer assigns a no-op instead.
+
+## The typed error for an out-of-prefix write
+
+Every Valkey failure is Effect's `RedisError` (`_tag: 'RedisError'`, so `Effect.catchTag` works).
+`SeatState.isPermissionDenied(error)` says whether it is the server's `NOPERM`: a key outside the
+seat user's prefix, or a command outside its categories. Measured 2026-09-29 against a scratch
+Valkey 9.1.1 with `user default off` and `user seat on >… ~seat:* +@all -@dangerous`:
+
+| call                         | result                                                                            |
+| ---------------------------- | --------------------------------------------------------------------------------- |
+| no credentials               | layer build fails, `NOAUTH` (`ERR_REDIS_AUTHENTICATION_FAILED`)                   |
+| wrong password               | layer build fails, `Connection closed` (Bun's text for a server that is down too) |
+| `SET seat:a` / `GET seat:a`  | ok                                                                                |
+| `SET other:a`, `GET other:a` | `RedisError`, `NOPERM No permissions to access a key`                             |
+| `FLUSHALL`                   | `RedisError`, `NOPERM User seat has no permissions to run the 'flushall' command` |
+
+The layer stays usable after a denied call. The URL carries the user and password, percent-encoded
+(`redis://seat:p%40ss@host:6381`); `rediss://` is TLS (not tested).
+
+## In the trace
+
+- **Postgres:** `@effect/sql-pg` makes one `sql.execute` client span per statement, with
+  `db.system.name=postgresql`, `db.namespace`, `server.address`, `server.port` and `db.query.text`.
+  The text holds `$1` placeholders, never a parameter value (asserted).
+- **Valkey:** one client span per command, named `valkey <COMMAND>`, with `db.system.name=redis`
+  (the OpenTelemetry registry has `redis` and no `valkey`, read 2026-09-29), `db.operation.name`,
+  `server.address`, `server.port` and the database index as `db.namespace`. ⛔ The span's ATTRIBUTES
+  never hold a key, a value or the URL's user or password (asserted in process and in the exported
+  OTLP payload).
+
+🔴 **A failed span is not only its attributes.** `OtlpTracer` exports the error a failed span ended
+with as `exception.message` and `exception.stacktrace`, with the whole `cause` chain, so an error
+text that quotes an argument carries it into the trace. Measured 2026-09-29 with canary values, in
+the exported payload:
+
+- **Valkey** quotes them in `ERR unknown command 'JSON.SET', with args beginning with: '<key>'
+'<value>'` and `ERR unknown subcommand '<key>'`. ✅ **Scrubbed:** the error that leaves the layer is
+  a new `Error` with the arguments cut (`src/state-valkey-scrub.ts`), asserted on the wire.
+- **Postgres** quotes them in `invalid input syntax for type integer: "<value>"`, which rides in the
+  `[cause]` of the exported stack. ⚠️ **Not scrubbed:** `@effect/sql-pg` builds the span and the error
+  itself and has no hook, so a test pins the leak (`tests/state-error-text.test.ts`).
+
+A Valkey text that echoes an argument without quotes, and the text a Lua script raises itself
+(`error(...)` comes back as `ERR user_script:1: <text>`), are not covered. For Postgres, do not put a
+secret in a parameter whose type the server can reject, or keep the exporter's destination one you
+trust with seat data; a scrub in `SeatObs` would cover it and was not built (it would change every span).
+
+Both spans join the trace of the run that made the call, and `SeatObs` exports them: asserted against
+the stub's OTLP payload (`db.system.name` with `postgresql` or `redis`, the span names, no secret in a
+SUCCESSFUL call). Ingest by the live VictoriaTraces is not measured, as for the rest of this package.
+
+## Measured traps, and what this package does about each
+
+Measured 2026-09-29, Bun 1.4.0, `@effect/sql-pg` rc.115, Valkey 9.1.1, Postgres 18.6.
+
+- 🔴 **A DSN that will not parse leaks through the driver's error.** `@effect/sql-pg` fails it as
+  `SqlError` whose `cause` is the URL `TypeError`, and that carries the whole string, password
+  included: three of six bad DSNs tried leaked through `JSON.stringify` and `Bun.inspect`. `postgres`
+  parses the URL first, and a string `new URL` rejects fails with a message that names the reason.
+- 🔴 **The driver ignores the URL when it labels spans.** From `url` alone every query says
+  `server.address: localhost`, `server.port: 5432`, `db.namespace: postgres`. `postgres` passes the
+  URL's host, port, database and user as discrete fields too (except when a `?host=`, `?port=`,
+  `?user=` or `?dbname=` in the URL overrides them, where the driver's reading stands).
+- 🔴 **A `Bun.RedisClient` on its defaults waits forever for a server that is gone.** A command sent
+  to a dead port sat unresolved past 8 s. The layer turns the offline queue off (through the layer, a
+  command after the server was killed failed in 1 ms, and the first one after a restart succeeded
+  within 0.5 s; `tests/state-valkey.test.ts` holds it) and
+  gives every command a deadline (`commandTimeout`, 10 s) against a server that holds the socket
+  open and says nothing. Past Bun's retry budget it reconnects itself (above).
+- 🔴 **`connectionTimeout` does not bound DNS.** A name that does not resolve took 31 s with
+  `connectionTimeout: 700`; the layer wraps `connect()` in an Effect timeout of the same length.
+- ⚠️ **Not `BunRedis` from `@effect/platform-bun`.** Rc.115 ships one, but depending on
+  `@effect/platform-bun` puts the `platform-node-shared` trap ([pairing.md](./pairing.md)) on every
+  consumer. This is the same `send` over `client.send`, plus the two things above.
+- ⚠️ **`sql-pg` rc.115 has no driver package**: it speaks the wire protocol over `node:net`, one peer
+  (`effect`), no dependency. The Postgres half runs under Bun and Node; the Valkey half needs Bun
+  (`Bun.RedisClient`), and building it under Node fails as `RedisError` saying so.
+- ⚠️ **A consumer typechecking with `skipLibCheck: false` needs `@types/node`** for `/state`: `sql-pg`'s
+  own `.d.ts` names `node:stream` and `node:tls` (4 `TS2591` errors, upstream's; `scripts/smoke.ts`
+  allows exactly those).
+
+## What is not here
+
+- **No `subscribe`.** `Redis.subscribe` fails with `RedisError`: a subscriber needs a connection of
+  its own. (`BunRedis` opens one, without reconnect.)
+- ⚠️ **`commandTimeout` (10 s) applies to every command**, a blocking one (`BLPOP`, `XREAD BLOCK`)
+  included: raise it, or such a call fails as `RedisError` at the deadline.
+- No migrations, no schema, no key-prefix helper (the server's ACL is the enforcement), no metrics
+  of its own (the spans are the signal).
+- **UNVERIFIED:** `rediss://` TLS; a password rotated while the server was down (the loop would
+  retry an authentication that fails, one `valkey reconnect` span per attempt, and never stop); and
+  the seats' real stores: `valkey-seats :6381` was not listening on CT100 (`ss`, 2026-09-29) and no
+  test used the `hf_agent` role. Everything above ran against scratch stores. The Postgres suite ran
+  twice: once against a scratch database on CT100 (trust auth, through an ssh tunnel), once against a
+  local scram-sha-256 Postgres 18 (which is what runs the wrong-password test).
+
+## The tests, and running them
+
+`bun test packages/seat-runtime` runs everything that needs no server (DSN parsing, the failures, the
+command deadline, the spans against a fake client). Two suites need a store and **skip, loudly, when
+it is missing** (CI has neither); `SEAT_RUNTIME_REQUIRE_SERVERS=1` makes a missing store a failure.
+
+- **Valkey:** a `valkey-server` (or `redis-server`) on `PATH`. The tests start it on a loopback port
+  with `user default off` and one `seat` user on `~seat:*`, with a per-run password.
+- **Postgres:** `SEAT_RUNTIME_TEST_POSTGRES_URL` naming a **scratch** database. The tests create one
+  table with a per-run name and drop it. A URL with a password (scram-sha-256) also runs the
+  wrong-password test; a trust-auth one skips it.

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@homeflare/seat-runtime",
+  "version": "0.1.0",
+  "description": "One Effect AI model layer and one OTLP layer for HomeFlare's coding seats: LiteLLM tags, no-cache and no-retry per request, traces, logs and metrics to VictoriaMetrics on CT100.",
+  "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/seat-runtime#readme",
+  "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
+  "license": "MIT",
+  "author": "Timothy Schneider",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taslabs-net/homeflare-kit.git",
+    "directory": "packages/seat-runtime"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./state": {
+      "types": "./dist/state.d.ts",
+      "default": "./dist/state.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@effect/ai-openai-compat": "4.0.0-rc.115",
+    "@effect/sql-pg": "4.0.0-rc.115",
+    "@modelcontextprotocol/sdk": "1.31.0"
+  },
+  "peerDependencies": {
+    "effect": "4.0.0-rc.115"
+  }
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+/**
+ * @homeflare/seat-runtime — what every HomeFlare coding seat shares: the model and telemetry
+ * layers, the round loop, and MCP servers as a toolkit.
+ *
+ * ⛔ RUNTIME-NEUTRAL: nothing here imports `bun:*` or `node:*`. It rides `fetch`, so it runs
+ *   under Bun, Node and workerd alike. ⚠️ That includes the MCP SDK's client entry: bundled with
+ *   workerd's resolution conditions, this entrypoint and the SDK's client hold no `node:`, `bun:`
+ *   or bare builtin import (tests/sdk-neutral.test.ts), but its default JSON Schema validator is
+ *   `ajv`, which needs `new Function`, so workerd itself is untested for `mcpToolkit`.
+ */
+export * as SeatModel from './seat-model.ts';
+export * as SeatObs from './seat-obs.ts';
+export { runRounds } from './rounds.ts';
+export type { Round, RoundsOptions, RoundsResult } from './rounds.ts';
+export { mcpToolkit } from './mcp-toolkit.ts';
+export type { McpHeaders } from './mcp-connect.ts';
+export type {
+  McpResource,
+  McpResourceContent,
+  McpToolkit,
+  McpToolkitOptions,
+  McpTools,
+} from './mcp-toolkit.ts';
+export { McpToolkitError } from './mcp-error.ts';
+export { VERSION } from './version.ts';

package/src/mcp-connect.ts

@@ -0,0 +1,172 @@
+/**
+ * Connect to a Streamable HTTP MCP server with the official SDK client: the transport, the
+ * caller's headers on every request, and the WHOLE handshake (`initialize` and the
+ * `notifications/initialized` that follows it) bounded in time and interruptible.
+ *
+ * ⛔ HEADERS ARE CREDENTIALS. They ride `requestInit` to the server and nowhere else: not in an
+ *   error, a span or a log (mcp-error.ts). A `Redacted` value is unwrapped only here, at the
+ *   moment the transport is built.
+ */
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import * as Effect from 'effect/Effect';
+import * as Redacted from 'effect/Redacted';
+import type * as Scope from 'effect/Scope';
+import { McpToolkitError, type Redact } from './mcp-error.ts';
+import { VERSION } from './version.ts';
+
+/** Header values; a `Redacted` is unwrapped only at the moment the transport is built. */
+export type McpHeaders = Readonly<Record<string, string | Redacted.Redacted<string>>>;
+
+export const DEFAULT_CONNECT_TIMEOUT_MS = 15_000;
+
+/**
+ * The longest a timer can run: `setTimeout` takes a 32-bit signed delay, and a larger one (like
+ * one below 1) is set to 1 ms. Node documents that; Bun does the same (measured, see below).
+ */
+export const MAX_TIMEOUT_MS: number = 2 ** 31 - 1;
+
+/**
+ * ⛔ A timeout that is not a finite number of milliseconds in `(0, MAX_TIMEOUT_MS]` is a
+ *   programming error, and dies with a `RangeError` before any request, as `maxRounds` does.
+ *   The budget feeds two timers (ours and the SDK's per request), and an out-of-range value made
+ *   them disagree: measured 2026-09-29 (review of PR 328) against a healthy local stub,
+ *   `Infinity` failed at once ("did not finish within Infinity ms") while `0`, `-1`, `NaN` and
+ *   `2 ** 31` each happened to succeed, because the timer clamped to 1 ms and the handshake won
+ *   the race. A real handshake takes longer than that 1 ms (not measured remotely), so those
+ *   would lose it.
+ */
+export const validateTimeout = (timeout: number): Effect.Effect<number> =>
+  Number.isFinite(timeout) && timeout > 0 && timeout <= MAX_TIMEOUT_MS
+    ? Effect.succeed(timeout)
+    : Effect.die(
+        new RangeError(
+          `connectTimeoutMs must be a finite number of milliseconds above 0 and at most ${String(MAX_TIMEOUT_MS)}, got ${String(timeout)}`,
+        ),
+      );
+
+const plainHeaders = (headers: McpHeaders | undefined): Record<string, string> =>
+  Object.fromEntries(
+    Object.entries(headers ?? {}).map(([name, value]) => [
+      name,
+      Redacted.isRedacted(value) ? Redacted.value(value) : value,
+    ]),
+  );
+
+/**
+ * The header values as plain strings, for `redactor` and for nothing else: a value an error
+ * message must never repeat is exactly a value the redactor has to know. Kept here so that a
+ * `Redacted` is unwrapped in this file only.
+ */
+export function headerValues(headers: McpHeaders | undefined): string[] {
+  return Object.values(plainHeaders(headers));
+}
+
+/**
+ * ★ THE BUDGET COVERS THE WHOLE HANDSHAKE, NOT ONE REQUEST. SDK 1.31.0 `Client.connect` sends
+ *   `initialize` (bounded by its `timeout` option) and then AWAITS a `notifications/initialized`
+ *   POST that carries no timeout at all: only the transport's own abort signal ends it. Measured
+ *   2026-09-29 (review of PR 328): a server that answered `initialize` and held the second POST
+ *   left a caller's `Effect.timeout('2 seconds')` unsettled at 8 s. So a timer here closes the
+ *   client when the budget is spent, and `close` aborts the transport's fetch, which is the only
+ *   thing that cancels that pending POST.
+ * ★ THE CALLER'S `signal` CLOSES IT TOO. It fires when the fiber is interrupted (a seat shutting
+ *   down, an `Effect.timeout`), which only means something because `connectAndBuild` runs the handshake
+ *   in the `restore`d, interruptible part of its mask: a handshake inside `acquireRelease`'s
+ *   uninterruptible acquire would ignore it (that was the first version of this timeout).
+ * ⚠️ Whatever the SDK rejects with after the budget is spent (an `AbortError` from the cancelled
+ *   fetch, or its own `Request timed out`) is an artefact of the close, so it is replaced by one
+ *   message that says what happened.
+ */
+async function handshake(
+  client: Client,
+  url: URL,
+  headers: McpHeaders | undefined,
+  timeout: number,
+  signal: AbortSignal,
+): Promise<void> {
+  const transport = new StreamableHTTPClientTransport(url, {
+    requestInit: { headers: plainHeaders(headers) },
+  });
+  const budget = new AbortController();
+  const stop = AbortSignal.any([signal, budget.signal]);
+  const timer = setTimeout(() => budget.abort(), timeout);
+  const close = (): void => void client.close().catch(() => undefined);
+  stop.addEventListener('abort', close, { once: true });
+  try {
+    // ⚠️ The SDK's own `sessionId?: string` reads as `string | undefined` against its own
+    //   `Transport` under `exactOptionalPropertyTypes` (this repo's baseline), so the two
+    //   of its types do not line up here. Upstream's typing, not a wrong argument: the
+    //   class IS the transport, and nothing of it reaches this package's declarations.
+    await client.connect(transport as Transport, { signal: stop, timeout });
+  } catch (error) {
+    // A failure AFTER the transport starts (a refused `initialize`) leaves the client holding
+    // an open transport: close it here rather than wait for the scope.
+    await client.close().catch(() => undefined);
+    const spent = budget.signal.aborted;
+    const sdkTimeout = error instanceof McpError && error.code === ErrorCode.RequestTimeout;
+    throw (spent || sdkTimeout) && !signal.aborted
+      ? new Error(`the MCP handshake did not finish within ${String(timeout)} ms`)
+      : error;
+  } finally {
+    clearTimeout(timer);
+    stop.removeEventListener('abort', close);
+  }
+}
+
+/**
+ * Connect, handshake and BUILD whatever the caller needs from the client (`build`: for
+ * `mcpToolkit`, listing the tools and making the toolkit). The client lives as long as the
+ * surrounding `Scope`, and only when ALL of that worked.
+ *
+ * ★ THE FINALIZER IS REGISTERED LAST: after the handshake AND after `build`. A scoped constructor
+ *   that fails must leave nothing in the caller's scope, and this one has been wrong twice:
+ *   - it used to register the `Client`'s `close` before the handshake. Each `Client` carries its
+ *     own JSON Schema validator (SDK client/index.js), so a seat retrying `mcpToolkit` through a
+ *     gateway outage held one per failed attempt until its scope closed: measured 2026-09-29
+ *     (review of PR 328), 64.7 MB against 10.6 MB after 3 001 refused attempts in one scope,
+ *     about 18 KB each. `handshake` closes the client on every failure, so a refused handshake
+ *     has nothing left to release.
+ *   - it then registered it right after the handshake, BEFORE the `tools/list` that `build` does,
+ *     and that listing can fail too: a JSON-RPC error, a page held past `connectTimeoutMs`, a
+ *     caller who interrupts. Measured 2026-09-29 (review of PR 328, later round), a loopback
+ *     server that completed the handshake: 20 attempts whose listing errored left 20 finalizers
+ *     and 20 open SSE streams in one scope; 10 whose listing was held left 10 finalizers, 10
+ *     streams and 10 `tools/list` POSTs still open (the SDK's per-request timeout rejects the
+ *     promise and does not abort the fetch). A seat retrying once a second against a slow gateway
+ *     is about 3 600 sessions and sockets an hour, held for the life of the seat.
+ *   `close` aborts the transport's fetches (the SSE stream and a held POST alike), which is why
+ *   closing the client is what releases them.
+ * ⚠️ `uninterruptibleMask` keeps the gaps between the steps from being interruption points (a
+ *   client opened and never closed); only the handshake and `build` are restored to
+ *   interruptible, and each has an `onError` that closes the client when it fails OR is
+ *   interrupted, so the SDK's own close-on-abort is not the only line of defence. `onError` runs
+ *   uninterruptibly, so the close itself cannot be cut off.
+ * ★ THE `seat.mcp.connect` SPAN IS THE HANDSHAKE ONLY, not `build`: it is what a slow or refused
+ *   connect looks like in a trace, and the listing is not that.
+ */
+export const connectAndBuild = <A>(
+  url: URL,
+  headers: McpHeaders | undefined,
+  server: string,
+  timeout: number,
+  redact: Redact,
+  build: (client: Client) => Effect.Effect<A, McpToolkitError>,
+): Effect.Effect<A, McpToolkitError, Scope.Scope> =>
+  Effect.uninterruptibleMask((restore) =>
+    Effect.gen(function* () {
+      const client = new Client({ name: '@homeflare/seat-runtime', version: VERSION });
+      const close = Effect.ignore(Effect.tryPromise(() => client.close()));
+      yield* restore(
+        Effect.tryPromise({
+          try: (signal) => handshake(client, url, headers, timeout, signal),
+          catch: (cause) => new McpToolkitError({ operation: 'connect', server, cause, redact }),
+        }).pipe(Effect.withSpan('seat.mcp.connect', { attributes: { 'server.address': server } })),
+      ).pipe(Effect.onError(() => close));
+      const built = yield* restore(build(client)).pipe(Effect.onError(() => close));
+      yield* Effect.addFinalizer(() => close);
+      return built;
+    }),
+  );

package/src/mcp-error.ts

@@ -0,0 +1,150 @@
+/**
+ * `mcpToolkit`'s typed failure, and the one place an MCP server's address is spelled for a
+ * message or a span.
+ *
+ * ⛔ THE ADDRESS IS ORIGIN AND PATH ONLY. A query string is where a token lands when a server
+ *   wants one there, and the headers a caller passes are bearer credentials: neither may reach
+ *   an error message, a log line or a span attribute. Header NAMES and the header map are never
+ *   read here; a header VALUE is read only to be redacted (`redactor`).
+ * 🔴 A SERVER ECHOES A VALUE ON ITS OWN. Redacting the query STRING and the address is not
+ *   enough: a server that answers "rejected key QVALUE" prints the value alone, and one that says
+ *   "bad credential Bearer HVALUE" prints a header's. Measured 2026-09-29 (review of PR 328,
+ *   round 2): both reached `McpToolkitError.message`. So `redactor` also takes out each query
+ *   value and each header value the caller passed (`MIN_SECRET_LENGTH` and up). What it cannot
+ *   catch: a value the server TRANSFORMS (hashed, base64, truncated), and one under the minimum.
+ * 🔴 THE `cause` IS A COPY, NEVER THE ORIGINAL. Measured 2026-09-29 (review of PR 328): under Bun a
+ *   refused fetch is a `TypeError` whose own `path` field is the FULL URL, query string included,
+ *   so attaching it as `cause` printed the token through `Bun.inspect`, `console.error`, an
+ *   uncaught rejection and the default `Effect.logError` — while `error.message` was clean, which
+ *   is all the first tests looked at. `scrubCause` rebuilds the chain from name, message, stack
+ *   and a string or numeric `code` only, so no other field (`path`, `url`, `data`, `body`) is
+ *   carried, and `redactor` takes the query string, fragment and password out of what remains.
+ *   The price: `cause instanceof McpError` no longer holds; read `cause.code` instead.
+ */
+/** Which call failed. `connect` covers the transport and the whole handshake (mcp-connect.ts). */
+export type McpOperation = 'connect' | 'listTools' | 'listResources' | 'readResource';
+
+/** A server address safe to print: `https://host:port/path`, no credentials, query or fragment. */
+export function serverLabel(url: URL): string {
+  return `${url.origin}${url.pathname}`;
+}
+
+/** Text with a server's query string, fragment and password taken out of it. */
+export type Redact = (text: string) => string;
+
+/**
+ * The shortest value `redactor` treats as a secret ON ITS OWN. Redacting every occurrence of a
+ * value costs legible messages (a `?v=1` would blank every "1"), and a value this short is not
+ * a credential anyone relies on. The query STRING, fragment and password are redacted whole
+ * whatever their length.
+ */
+export const MIN_SECRET_LENGTH = 6;
+
+/** The values in a raw query string, as written (percent-encoded) and as decoded. */
+function queryValues(url: URL): string[] {
+  const raw = url.search
+    .slice(1)
+    .split('&')
+    .map((pair) => pair.slice(pair.indexOf('=') + 1));
+  return [...raw, ...url.searchParams.values()];
+}
+
+/**
+ * A header value, and its credential when it has a scheme: `Bearer abc` is echoed whole or as
+ * `abc`, and "Bearer" alone is not a secret.
+ */
+function headerParts(value: string): string[] {
+  const token = value.trim().split(/\s+/).at(-1) ?? '';
+  return [value, token];
+}
+
+/**
+ * A `Redact` for one server address, plus any header values the caller passes. The whole URL
+ * becomes `serverLabel`; a bare query string, fragment or password left over, each query value
+ * and each header value (`MIN_SECRET_LENGTH` and up, longest first) becomes `[redacted]`: a
+ * server can echo the address or a value back in an error body, and a fetch failure can print it.
+ */
+export function redactor(url: URL, headerValues: ReadonlyArray<string> = []): Redact {
+  const label = serverLabel(url);
+  const whole = [
+    url.search.length > 1 ? url.search : '',
+    url.hash.length > 1 ? url.hash : '',
+    url.password,
+  ];
+  const parts = [...queryValues(url), ...headerValues.flatMap(headerParts)];
+  const secrets = [
+    ...whole,
+    ...[...new Set(parts)]
+      .filter((part) => part.length >= MIN_SECRET_LENGTH)
+      .sort((a, b) => b.length - a.length),
+  ].filter((secret) => secret !== '');
+  return (text) => {
+    let out = text.split(url.href).join(label);
+    for (const secret of secrets) out = out.split(secret).join('[redacted]');
+    return out;
+  };
+}
+
+/** How many `cause` links `scrubCause` follows: a cycle or a deep chain ends here. */
+const MAX_CAUSE_DEPTH = 5;
+
+/**
+ * A copy of `cause` that is safe to print. ⚠️ An allowlist, not a denylist: an Error is rebuilt
+ * from its name, message, stack and `code` (a string or number) and its own `cause`, each run
+ * through `redact`; every other own field is left behind, whatever it is called. See the header.
+ */
+export function scrubCause(cause: unknown, redact: Redact, depth = 0): unknown {
+  if (!(cause instanceof Error)) return redact(String(cause));
+  const inner = depth < MAX_CAUSE_DEPTH && cause.cause !== undefined;
+  const copy = new Error(
+    redact(cause.message),
+    inner ? { cause: scrubCause(cause.cause, redact, depth + 1) } : undefined,
+  );
+  copy.name = redact(cause.name);
+  if (typeof cause.stack === 'string') copy.stack = redact(cause.stack);
+  const code: unknown = (cause as { code?: unknown }).code;
+  if (typeof code === 'string') Object.assign(copy, { code: redact(code) });
+  else if (typeof code === 'number') Object.assign(copy, { code });
+  return copy;
+}
+
+/** The message of whatever a promise rejected with; an SDK `McpError` carries the JSON-RPC text. */
+export function describeCause(cause: unknown): string {
+  return cause instanceof Error ? cause.message : String(cause);
+}
+
+/**
+ * The connection, a listing or a resource read failed.
+ *
+ * ★ A PLAIN `Error` WITH A `_tag`, NOT `Data.TaggedError`. `class X extends Data.TaggedError(…)<…>`
+ *   is TS9021 under `isolatedDeclarations` ("extends clause can't contain an expression"; measured
+ *   2026-09-15, see packages/alchemy/tsconfig.json), and this package keeps that flag on. The
+ *   `_tag` is all `Effect.catchTag('McpToolkitError', …)` reads.
+ */
+export class McpToolkitError extends Error {
+  readonly _tag = 'McpToolkitError' as const;
+  readonly operation: McpOperation;
+  /** `serverLabel` of the server: never a header, never a query string. */
+  readonly server: string;
+
+  constructor(fields: {
+    readonly operation: McpOperation;
+    readonly server: string;
+    /**
+     * What the SDK threw: an `McpError` (a JSON-RPC error), a `StreamableHTTPError`, a fetch
+     * failure. Never stored as given: `cause` on the error is `scrubCause` of it.
+     */
+    readonly cause: unknown;
+    /** `redactor` of the server's URL. Left out, only the structural scrub of `cause` applies. */
+    readonly redact?: Redact | undefined;
+  }) {
+    const redact = fields.redact ?? ((text: string) => text);
+    super(
+      `MCP ${fields.operation} against ${fields.server} failed: ${redact(describeCause(fields.cause))}`,
+      { cause: scrubCause(fields.cause, redact) },
+    );
+    this.name = 'McpToolkitError';
+    this.operation = fields.operation;
+    this.server = fields.server;
+  }
+}

package/src/mcp-pages.ts

@@ -0,0 +1,37 @@
+/**
+ * MCP's cursor pagination, followed to the end — but not forever.
+ *
+ * ⛔ THE PAGE COUNT IS CAPPED. A server that answers every page with another `nextCursor` (a
+ *   bug, or a hostile one) would otherwise hold a seat in a listing loop before its first
+ *   model call. A hundred pages is far past any estate server's tool list; the cap fails the
+ *   listing loudly instead of truncating it quietly.
+ */
+import * as Effect from 'effect/Effect';
+import { type McpOperation, McpToolkitError, type Redact } from './mcp-error.ts';
+
+export const MAX_PAGES = 100;
+
+export type Page<T> = { readonly items: ReadonlyArray<T>; readonly next: string | undefined };
+
+/** Every item of a paged listing, or an `McpToolkitError` for `operation`. Interruption aborts the request in flight. */
+export function collect<T>(
+  operation: McpOperation,
+  server: string,
+  page: (cursor: string | undefined, signal: AbortSignal) => Promise<Page<T>>,
+  redact?: Redact | undefined,
+): Effect.Effect<ReadonlyArray<T>, McpToolkitError> {
+  return Effect.tryPromise({
+    try: async (signal) => {
+      const items: T[] = [];
+      let cursor: string | undefined;
+      for (let pages = 0; pages < MAX_PAGES; pages += 1) {
+        const next = await page(cursor, signal);
+        items.push(...next.items);
+        if (next.next === undefined) return items;
+        cursor = next.next;
+      }
+      throw new Error(`the server returned more than ${String(MAX_PAGES)} pages`);
+    },
+    catch: (cause) => new McpToolkitError({ operation, server, cause, redact }),
+  });
+}