@frontmcp/utils 1.10.16 → 1.11.0-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/utils",
-  "version": "1.10.16",
+  "version": "1.11.0-rc.1",
   "description": "Shared helpers for FrontMCP: URI templates, naming, cross-platform crypto and PKCE, key-value storage, file system and environment detection",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",
@@ -33,7 +33,7 @@
     "@noble/hashes": "^2.0.1"
   },
   "peerDependencies": {
-    "@frontmcp/lazy-zod": "1.10.16",
+    "@frontmcp/lazy-zod": "1.11.0-rc.1",
     "@upstash/redis": "^1.34.0",
     "@vercel/kv": "^2.0.0 || ^3.0.0",
     "ioredis": "^5.0.0"
@@ -51,7 +51,7 @@
   },
   "imports": {
     "#crypto-provider": {
-      "worker": "./crypto/node.js",
+      "workerd": "./crypto/node.js",
       "browser": {
         "import": "./esm/crypto/browser.mjs",
         "default": "./crypto/browser.js"
@@ -59,7 +59,7 @@
       "default": "./crypto/node.js"
     },
     "#async-context": {
-      "worker": "./async-context/node-async-context.js",
+      "workerd": "./async-context/node-async-context.js",
       "browser": {
         "import": "./esm/async-context/browser-async-context.mjs",
         "default": "./async-context/browser-async-context.js"
@@ -67,7 +67,7 @@
       "default": "./async-context/node-async-context.js"
     },
     "#event-emitter": {
-      "worker": "./event-emitter/node-event-emitter.js",
+      "workerd": "./event-emitter/node-event-emitter.js",
       "browser": {
         "import": "./esm/event-emitter/browser-event-emitter.mjs",
         "default": "./event-emitter/browser-event-emitter.js"
@@ -75,7 +75,7 @@
       "default": "./event-emitter/node-event-emitter.js"
     },
     "#env": {
-      "worker": "./env/node-env.js",
+      "workerd": "./env/node-env.js",
       "browser": {
         "import": "./esm/env/browser-env.mjs",
         "default": "./env/browser-env.js"
@@ -83,7 +83,7 @@
       "default": "./env/node-env.js"
     },
     "#runtime-context": {
-      "worker": "./env/runtime-context.js",
+      "workerd": "./env/runtime-context.js",
       "browser": {
         "import": "./esm/env/browser-runtime-context.mjs",
         "default": "./env/browser-runtime-context.js"
@@ -91,7 +91,7 @@
       "default": "./env/runtime-context.js"
     },
     "#path": {
-      "worker": "./path/node-path.js",
+      "workerd": "./path/node-path.js",
       "browser": {
         "import": "./esm/path/browser-path.mjs",
         "default": "./path/browser-path.js"
@@ -107,6 +107,22 @@
   "exports": {
     "./package.json": "./package.json",
     ".": {
+      "workerd": {
+        "require": {
+          "types": "./index.d.ts",
+          "default": "./index.js"
+        },
+        "import": {
+          "types": "./index.d.ts",
+          "default": "./esm/index.mjs"
+        }
+      },
+      "browser": {
+        "types": "./index.d.ts",
+        "import": "./browser/index.mjs",
+        "module": "./browser/index.mjs",
+        "default": "./index.js"
+      },
       "require": {
         "types": "./index.d.ts",
         "default": "./index.js"

package/process/child-process.d.ts

@@ -0,0 +1,2 @@
+/** `child_process`, loaded on first use so the browser and edge builds never import it. */
+export declare function getChildProcess(): typeof import('child_process');

package/process/index.d.ts

@@ -0,0 +1,6 @@
+export { processTreeSpawnOptions, signalProcessTree, isProcessTreeAlive, stopProcessTree } from './process-tree';
+export type { ProcessTreeDeps } from './process-tree';
+export { spawnOwned, reapOrphans, OwnedProcessError } from './owned-process';
+export type { SpawnOwnedOptions, OwnedProcess, ReapOrphansOptions } from './owned-process';
+export { watchParent, watchPath } from './process-watch';
+export type { ParentGoneReason, ProcessWatcher, WatchParentOptions, WatchPathOptions } from './process-watch';

package/process/owned-process.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Child processes that carry their owner's mark, so the ones whose owner died can be found and stopped.
+ *
+ * **Node.js only.**
+ */
+import type { ChildProcess, SpawnOptions } from 'child_process';
+import { type ProcessTreeDeps } from './process-tree';
+export declare class OwnedProcessError extends Error {
+    constructor(message: string);
+}
+export interface SpawnOwnedOptions extends SpawnOptions {
+    /** Names the kind of process, for {@link reapOrphans}: up to 64 letters, digits, `.`, `_` and `-`. */
+    marker: string;
+}
+export interface OwnedProcess {
+    readonly child: ChildProcess;
+    /**
+     * Stop the child, with every process it started when it was spawned `detached` (always on Windows), killing what
+     * outlives `graceMs`; resolves `true` once they are gone.
+     */
+    stop(signal?: NodeJS.Signals, graceMs?: number): Promise<boolean>;
+}
+export interface ProcessInfo {
+    pid: number;
+    ppid: number;
+    pgid: number;
+    /** Exited, but not yet collected by its parent: `kill(pid, 0)` still reaches it. */
+    zombie: boolean;
+    command: string;
+}
+export interface ReapOrphansOptions {
+    /** How long the orphans get to exit after `SIGTERM` before they are killed. @default 2000 */
+    graceMs?: number;
+}
+export interface ReapOrphansDeps extends Pick<ProcessTreeDeps, 'platform' | 'kill' | 'sleep'> {
+    listProcesses: () => ProcessInfo[];
+}
+/**
+ * Spawn `command` marked as owned by this process: the child gets `FRONTMCP_OWNER=<marker>:<owner pid>` in its
+ * environment and `--frontmcp-owner=<marker>:<owner pid>` as its last argument, which {@link reapOrphans} finds
+ * with `ps`. The command must take that last argument as an argument: a script run by node does, while
+ * `node -e <code>` reads it as a node option unless the arguments end with `--`.
+ *
+ * @throws OwnedProcessError when the marker is invalid
+ */
+export declare function spawnOwned(command: string, args: readonly string[], options: SpawnOwnedOptions): OwnedProcess;
+/** Parse `ps -o pid=,ppid=,pgid=,stat=,command=` output; lines it cannot read are skipped. */
+export declare function parseProcessList(output: string): ProcessInfo[];
+/**
+ * Stop the processes {@link spawnOwned} marked with `marker` whose owner no longer runs, with every process they
+ * started: `SIGTERM`, then `SIGKILL` for what is still running after `graceMs`. A process whose owner still runs,
+ * or that carries another marker or none, is left alone, and so are this process, its ancestors and the leader of
+ * its process group. Resolves with the pids of the marked orphans it stopped.
+ *
+ * POSIX only: it reads the process table with `ps`. On Windows it does nothing and resolves with `[]`.
+ *
+ * @throws OwnedProcessError when the marker is invalid, or `ps` cannot list the processes
+ */
+export declare function reapOrphans(marker: string, options?: ReapOrphansOptions, deps?: Partial<ReapOrphansDeps>): Promise<number[]>;

package/process/process-tree.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Process-tree lifecycle for long-lived children, such as the ones `frontmcp dev` spawns.
+ *
+ * The process that actually holds the dev server's port is not always our
+ * direct child: `tsx --watch main.ts` forks the server, and the `npx` fallback
+ * puts npm in between as well. Signalling only the direct child let it exit
+ * while the server kept listening — `kill <frontmcp dev pid>` exited 0 and left
+ * the port bound (#679). Ctrl+C worked only because the terminal signals the
+ * whole foreground process group.
+ *
+ * On POSIX every child is therefore started as the leader of its own process
+ * group and shutdown signals the whole group, whoever sits in the middle.
+ *
+ * Windows has no process groups (#731). `taskkill /T` ends a tree, but only
+ * while its root is alive — it walks parent links down from the root. So:
+ *   - a stop first asks the tree to close (`taskkill /T`, no `/F`), and forces
+ *     it (`/T /F`) when taskkill reports failure or the grace period runs out.
+ *     A windowless console process (node) usually only stops when forced;
+ *     checking taskkill's exit status makes that escalation immediate;
+ *   - when the direct child has already exited, the processes it started are
+ *     found by their parent PID (`Get-CimInstance Win32_Process`) and ended one
+ *     tree at a time, and the tree only counts as gone once none is left.
+ * Spawning tools directly with `process.execPath` (the CLI's `tool-command.ts`)
+ * removes the `cmd.exe` shim from the tree, so a dying parent's kill-on-close
+ * job object (libuv puts every non-detached child in one) takes its children
+ * with it; the lookup above covers what is left.
+ *
+ * **Node.js only**: `child_process` is loaded on first use, as the file system helpers load `fs`.
+ */
+import type { ChildProcess, SpawnOptions } from 'child_process';
+export interface ProcessTreeDeps {
+    platform: NodeJS.Platform;
+    /** `process.kill` — injectable for tests. */
+    kill: (pid: number, signal: NodeJS.Signals | 0) => boolean | void;
+    /**
+     * Runs `taskkill /pid <pid> /T` (plus `/F` when `force`) on Windows. Returns
+     * `true` only when taskkill reported success.
+     */
+    taskkill: (pid: number, force: boolean) => boolean;
+    /** PIDs of the running processes whose parent PID is `pid` (Windows). */
+    childPids: (pid: number) => number[];
+    sleep: (ms: number) => Promise<void>;
+}
+/** Runs taskkill and reports whether it succeeded — `spawnSync` itself never throws. */
+export declare function runTaskkill(pid: number, force: boolean): boolean;
+/** Child PIDs of `pid` from `Get-CimInstance Win32_Process`; `[]` when the lookup fails. */
+export declare function queryChildPids(pid: number): number[];
+/** One PID per line; anything else is ignored. */
+export declare function parsePidList(output: string): number[];
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Spawn options that make the child the leader of a new process group (POSIX),
+ * so {@link signalProcessTree} can reach every process it starts. Children in
+ * their own group no longer receive the terminal's Ctrl+C directly — the parent
+ * must forward the signal, which `frontmcp dev` does.
+ */
+export declare function processTreeSpawnOptions(platform?: NodeJS.Platform): Pick<SpawnOptions, 'detached'>;
+/** True while `pid` runs; a process this user may not signal (`EPERM`) counts as running. */
+export declare function isPidRunning(pid: number, d: Pick<ProcessTreeDeps, 'kill'>): boolean;
+/**
+ * Send `signal` to `child` and every process it started. Returns `false` when
+ * nothing was left to signal (or, on Windows, when taskkill failed).
+ *
+ * On Windows `SIGKILL` forces the tree down (`taskkill /T /F`); any other
+ * signal asks it to close (`taskkill /T`).
+ */
+export declare function signalProcessTree(child: ChildProcess | undefined, signal: NodeJS.Signals, deps?: Partial<ProcessTreeDeps>): boolean;
+/**
+ * True while any process of the child's tree is still running. On Windows an
+ * exited child still counts as alive while a process it started runs.
+ */
+export declare function isProcessTreeAlive(child: ChildProcess | undefined, deps?: Partial<ProcessTreeDeps>): boolean;
+/**
+ * Signal the tree and wait until every process in it has exited. After
+ * `graceMs` the tree is killed (`SIGKILL`, or `taskkill /T /F` on Windows);
+ * resolves `true` when the tree is gone.
+ */
+export declare function stopProcessTree(child: ChildProcess | undefined, signal: NodeJS.Signals, graceMs: number, deps?: Partial<ProcessTreeDeps>): Promise<boolean>;

package/process/process-watch.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Watchers that tell a long-lived process its reason to run is gone: its parent exited, its stdin ended, or a
+ * directory it serves was removed. Their timers are unref'd, so they never keep the process alive.
+ *
+ * **Node.js only.**
+ */
+import type { Readable } from 'stream';
+import { type ProcessTreeDeps } from './process-tree';
+export type ParentGoneReason = 'parent-exited' | 'stdin-ended';
+export interface ProcessWatcher {
+    /** Stop watching. Safe to call more than once. */
+    close(): void;
+}
+export interface WatchParentOptions {
+    /** Called once, when the parent is gone. */
+    onGone: (reason: ParentGoneReason) => void;
+    /** How often the parent is checked. @default 1000 */
+    intervalMs?: number;
+    /** A stream whose end also counts as the parent going away, such as `process.stdin` for a stdio server. */
+    stdin?: Readable;
+}
+export interface WatchParentDeps extends Pick<ProcessTreeDeps, 'kill'> {
+    ppid: () => number;
+}
+export interface WatchPathOptions {
+    /** Called once, when the path no longer exists. */
+    onGone: () => void;
+    /** How often the path is checked. @default 1000 */
+    intervalMs?: number;
+}
+/**
+ * Report when this process's parent is gone: this process was handed to another parent (the parent pid changed),
+ * or the parent pid no longer runs (Windows does not reparent). A process started by init has no parent to watch,
+ * so only `stdin` is watched then.
+ */
+export declare function watchParent(options: WatchParentOptions, deps?: Partial<WatchParentDeps>): ProcessWatcher;
+/**
+ * Report when `path` no longer exists, for example a checkout that was deleted. A check that fails for another reason,
+ * such as a folder it may not search or a network file system timing out, is not taken as the path being gone.
+ */
+export declare function watchPath(path: string, options: WatchPathOptions): ProcessWatcher;

package/redaction/index.d.ts

@@ -0,0 +1,2 @@
+export { redactFields, redactJson } from './redaction';
+export type { RedactedFields } from './redaction';

package/redaction/redaction.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Field redaction for structured log entries and recorded calls.
+ *
+ * Replaces the values of sensitive fields with '[REDACTED]'.
+ */
+/** The fields a redaction hides: field names, matched case-insensitively, or a test on each key. */
+export type RedactedFields = readonly string[] | ((key: string) => boolean);
+/**
+ * Redact sensitive fields from an object.
+ *
+ * Performs a shallow clone with redacted values — does not mutate the input.
+ *
+ * @param obj - Object to redact fields from
+ * @param fields - Field names to redact (case-insensitive), or a test on each key
+ * @param maxDepth - Maximum recursion depth (default: 5)
+ * @returns New object with sensitive fields replaced by '[REDACTED]'
+ */
+export declare function redactFields(obj: Record<string, unknown>, fields: RedactedFields, maxDepth?: number): Record<string, unknown>;
+/**
+ * A copy of a JSON value with its sensitive fields redacted at any depth, also inside strings that hold JSON.
+ * In other strings it redacts bearer and basic credentials, JWTs, the credentials of a URL, and a value given to a
+ * sensitive name (`?access_token=…`, `apiKey: "…"`, `TOKEN=…`).
+ */
+export declare function redactJson(value: unknown, fields: RedactedFields): unknown;

package/stdio-bridge/errors.d.ts

@@ -0,0 +1,23 @@
+/**
+ * JSON-RPC error codes emitted by the dev bridge (issue #399).
+ *
+ * Reserved in the implementation-defined `-32099 .. -32000` range so they
+ * never collide with the JSON-RPC 2.0 reserved range. Clients (Claude
+ * Code, etc.) receive these in `error.code` and can render structured
+ * feedback instead of sitting on an indefinite `Calling…` spinner.
+ */
+export declare const DEV_SERVER_UNREACHABLE = -32099;
+export declare const DEV_BUFFER_FULL = -32098;
+export declare const DEV_RELOAD_DEADLINE = -32097;
+/** Human-readable label for each code. Used in the `error.message` field. */
+export declare const DEV_ERROR_MESSAGE: Record<number, string>;
+/** Build a JSON-RPC error response for a given inbound request id. */
+export declare function makeDevError(id: string | number | null, code: number, data?: Record<string, unknown>): {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    error: {
+        code: number;
+        message: string;
+        data?: Record<string, unknown>;
+    };
+};

package/stdio-bridge/index.d.ts

@@ -0,0 +1,9 @@
+export { DEV_BUFFER_FULL, DEV_ERROR_MESSAGE, DEV_RELOAD_DEADLINE, DEV_SERVER_UNREACHABLE, makeDevError, } from './errors';
+export { listChangedNotifications } from './list-changed';
+export { createBridgeStateMachine } from './state-machine';
+export type { BridgeState, BridgeStateMachine, BridgeStateMachineOptions, InflightRequest } from './state-machine';
+export { createStdioFramer } from './stdio-framer';
+export type { JsonRpcFrame, StdioFramer, StdioFramerOptions } from './stdio-framer';
+export type { BridgeLogger } from './types';
+export { createHttpUpstream, createPipeUpstream } from './upstream-client';
+export type { HttpUpstreamClient, HttpUpstreamOptions, PipeUpstreamOptions, UpstreamClient, UpstreamClientOptions, } from './upstream-client';

package/stdio-bridge/list-changed.d.ts

@@ -0,0 +1,3 @@
+import type { JsonRpcFrame } from './stdio-framer';
+/** The `list_changed` notifications the capabilities of a fresh server advertise. */
+export declare function listChangedNotifications(initializeResult: Record<string, unknown> | undefined): JsonRpcFrame[];

package/stdio-bridge/state-machine.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Bridge state machine (issue #399).
+ *
+ *   Idle → Booting → Ready ⇄ Reloading
+ *                           ↓ deadline
+ *                        Degraded
+ *
+ * Owns the request buffer that absorbs inbound JSON-RPC frames while the
+ * upstream child is mid-restart. When buffered requests exceed the
+ * configured cap (default 8), the FSM synthesises an immediate
+ * `dev_buffer_full` response so clients never silently lose frames.
+ *
+ * The FSM is transport-agnostic — `child-supervisor` and `upstream-client`
+ * call into it; this module never touches sockets, child processes, or
+ * file descriptors.
+ */
+import type { JsonRpcFrame } from './stdio-framer';
+import type { BridgeLogger } from './types';
+export type BridgeState = 'Idle' | 'Booting' | 'Ready' | 'Reloading' | 'Degraded' | 'Stopping';
+export interface InflightRequest {
+    /** Original frame (kept for replay if the child dies before responding). */
+    frame: JsonRpcFrame;
+    /** Wall-clock when the bridge forwarded the frame to upstream. */
+    forwardedAt: number;
+}
+export interface BridgeStateMachineOptions {
+    log: BridgeLogger;
+    bufferSize: number;
+    reloadDeadlineMs: number;
+    /** Send a JSON-RPC frame back to the client (stdio out). */
+    respond(frame: JsonRpcFrame): void | Promise<void>;
+    /** Forward a request frame to the upstream child. Implemented by the supervisor. */
+    forward(frame: JsonRpcFrame): void | Promise<void>;
+}
+export interface BridgeStateMachine {
+    readonly state: BridgeState;
+    /** Bridge has begun launching the child — buffer inbound frames. */
+    onBootStart(): void;
+    /** Child reports ready — drain the buffer through `forward`. */
+    onChildReady(): void;
+    /** Child exited unexpectedly. If we were Ready, transition to Reloading. */
+    onChildExit(reason: string): void;
+    /** The upstream went away while its requests in flight still settle on their own: buffer new frames until ready. */
+    onUpstreamLost(reason: string): void;
+    /** Put back a request the upstream never took: sent at once when Ready, otherwise first in the buffer. */
+    requeue(frame: JsonRpcFrame): Promise<void>;
+    /** Watcher fired. Buffer inbound, start reload timer. */
+    onWatcherEvent(trigger: string): void;
+    /** Reload deadline elapsed without a ready signal. */
+    /** `detail` (e.g. why the first boot failed) is added to every buffered request's error data. */
+    onReloadDeadline(detail?: Record<string, unknown>): void;
+    /** Inbound JSON-RPC frame from stdin. Routes to `forward` or buffers. */
+    enqueue(frame: JsonRpcFrame): Promise<void>;
+    /** Outbound JSON-RPC frame from upstream — relay to client. */
+    relayUpstream(frame: JsonRpcFrame): Promise<void>;
+    /** SIGTERM/SIGINT — flush buffer with `dev_server_unreachable` and stop. */
+    stop(): Promise<void>;
+    /** Number of frames currently buffered (testing hook). */
+    bufferDepth(): number;
+}
+export declare function createBridgeStateMachine(options: BridgeStateMachineOptions): BridgeStateMachine;

package/stdio-bridge/stdio-framer.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Newline-delimited JSON-RPC framer for the dev bridge (issue #399).
+ *
+ * Reads `process.stdin` and yields complete JSON-RPC frames. Writes
+ * complete frames to `process.stdout` (atomic per `\n` boundary). Parser
+ * state is preserved across chunks so frames split arbitrarily on the
+ * wire still parse.
+ *
+ * MCP stdio framing per spec is newline-delimited JSON (`\n`-terminated
+ * UTF-8). We do NOT implement LSP-style `Content-Length` framing — it's
+ * not in the MCP spec and adding it would silently shadow real JSON
+ * bodies that happen to start with `C`.
+ */
+import type { Readable, Writable } from 'node:stream';
+import type { BridgeLogger } from './types';
+export interface JsonRpcFrame {
+    jsonrpc: '2.0';
+    id?: string | number | null;
+    method?: string;
+    params?: unknown;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+export interface StdioFramerOptions {
+    input: Readable;
+    output: Writable;
+    log: BridgeLogger;
+    onFrame: (frame: JsonRpcFrame) => void | Promise<void>;
+    /** Called once when the input stream ends or closes (the MCP client went away). */
+    onClose?: () => void;
+}
+export interface StdioFramer {
+    start(): void;
+    /** Write a single frame as a newline-terminated JSON line. Resolves on `'drain'` when backpressure kicks in. */
+    write(frame: JsonRpcFrame): Promise<void>;
+    stop(): void;
+}
+/**
+ * Build a newline-delimited JSON framer bound to the supplied streams.
+ *
+ * Parse errors (malformed JSON between newlines) emit a `-32700` Parse
+ * error response back on the output stream and continue — a malformed
+ * frame must not kill the bridge.
+ */
+export declare function createStdioFramer(options: StdioFramerOptions): StdioFramer;

package/stdio-bridge/types.d.ts

@@ -0,0 +1,10 @@
+/** Where a stdio bridge logs: never stdout, which carries the JSON-RPC frames. */
+export interface BridgeLogger {
+    readonly path: string | undefined;
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+    reloadEvent(kind: string, data?: Record<string, unknown>): void;
+    close(): Promise<void>;
+}

package/stdio-bridge/upstream-client.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Upstream MCP client for the dev bridge (issue #399).
+ *
+ * Two transport variants:
+ *
+ *   - **HTTP mode**: speaks streamable-HTTP JSON-RPC to the child's HTTP
+ *     listener. The session id is the one the SERVER issues on `initialize`
+ *     (`mcp-session-id` response header) and is sent on every later request.
+ *     The bridge used to pin a uuid of its own, which the server never issued,
+ *     so every request after `initialize` answered 404 (#679).
+ *
+ *   - **Pipe mode (--serve)**: forwards JSON-RPC frames over the Node IPC
+ *     channel paired with the child (`FRONTMCP_DEV_STDIO_FD=3`); the SDK serves
+ *     MCP on it. No HTTP layer, no session header.
+ *
+ * A restarted child has no session at all, so the bridge replays the client's
+ * MCP handshake against it (`reinitialize`) before draining buffered requests.
+ * The client keeps its stdio connection and never learns the server restarted.
+ */
+import type { ChildProcess } from 'node:child_process';
+import type { JsonRpcFrame } from './stdio-framer';
+import type { BridgeLogger } from './types';
+export interface UpstreamClient {
+    send(frame: JsonRpcFrame): Promise<void>;
+    /**
+     * Replay the client's handshake on a fresh child: send `initialize` (under a
+     * bridge-private id, its response is not relayed) and, when the client had
+     * sent it, `notifications/initialized`. Resolves with the `initialize` result.
+     */
+    reinitialize(initialize: JsonRpcFrame, initialized: boolean): Promise<Record<string, unknown> | undefined>;
+    /** Stop background tasks (in-flight requests, pipe listener). */
+    close(): Promise<void>;
+}
+export interface UpstreamClientOptions {
+    log: BridgeLogger;
+    /** Called for every frame the upstream child sends back. */
+    onFrame: (frame: JsonRpcFrame) => void | Promise<void>;
+}
+export interface HttpUpstreamOptions extends UpstreamClientOptions {
+    /** Loopback URL of the user-code MCP endpoint. */
+    url: string;
+    /** Sent with every request, such as the credential a shared local server asks for. */
+    headers?: Record<string, string>;
+    /** Sends the requests instead of the global `fetch`, such as one that reaches a Unix socket. */
+    fetch?: typeof fetch;
+}
+export interface HttpUpstreamClient extends UpstreamClient {
+    /** End the MCP session the server issued (`DELETE` with its id); the next `initialize` starts a new one. */
+    endSession(): Promise<void>;
+}
+export declare function createHttpUpstream(options: HttpUpstreamOptions): HttpUpstreamClient;
+export interface PipeUpstreamOptions extends UpstreamClientOptions {
+    /** The spawned child; we write to / read from its IPC channel (FD 3). */
+    child: ChildProcess;
+    /** Called with each batch of dev events the child sends (`{ __frontmcp: 'dev-events', events }`). */
+    onDevEvents?: (events: unknown[]) => void;
+    /** How long a replayed `initialize` may take. */
+    reinitializeTimeoutMs?: number;
+}
+/**
+ * Pipe mode: the child speaks JSON-RPC on FD 3 (set via
+ * `FRONTMCP_DEV_STDIO_FD=3`). We use Node's IPC channel for the same wire
+ * — `child.send(...)` forwards a structured message and `child.on('message', …)`
+ * yields whatever the child writes back.
+ */
+export declare function createPipeUpstream(options: PipeUpstreamOptions): UpstreamClient;

package/storage/adapters/base.d.ts

@@ -70,6 +70,8 @@ export declare abstract class BaseStorageAdapter implements StorageAdapter {
     deleteIfEquals(_key: string, _expectedValue: string): Promise<boolean>;
     /** Default: not supported, for the same reason as {@link deleteIfEquals}. */
     expireIfEquals(_key: string, _expectedValue: string, _ttlSeconds: number): Promise<boolean>;
+    /** Default: not supported, for the same reason as {@link deleteIfEquals}. */
+    setIfEquals(_key: string, _expectedValue: string, _value: string): Promise<boolean>;
     /**
      * Default: pub/sub not supported.
      * Override in adapters that support it.

package/storage/adapters/memory.d.ts

@@ -44,6 +44,7 @@ export declare class MemoryStorageAdapter extends BaseStorageAdapter {
     delete(key: string): Promise<boolean>;
     deleteIfEquals(key: string, expectedValue: string): Promise<boolean>;
     expireIfEquals(key: string, expectedValue: string, ttlSeconds: number): Promise<boolean>;
+    setIfEquals(key: string, expectedValue: string, value: string): Promise<boolean>;
     exists(key: string): Promise<boolean>;
     expire(key: string, ttlSeconds: number): Promise<boolean>;
     ttl(key: string): Promise<number | null>;

package/storage/adapters/redis.d.ts

@@ -39,6 +39,7 @@ export declare class RedisStorageAdapter extends BaseStorageAdapter {
     private connecting?;
     private readonly keyPrefix;
     private readonly subscriptionHandlers;
+    private readonly reconnectListeners;
     private readonly connectionUrl?;
     /** The connection options of a URL this adapter reads itself; undefined for one only ioredis reads. */
     private readonly urlOptions?;
@@ -60,6 +61,7 @@ export declare class RedisStorageAdapter extends BaseStorageAdapter {
     delete(key: string): Promise<boolean>;
     deleteIfEquals(key: string, expectedValue: string): Promise<boolean>;
     expireIfEquals(key: string, expectedValue: string, ttlSeconds: number): Promise<boolean>;
+    setIfEquals(key: string, expectedValue: string, value: string): Promise<boolean>;
     exists(key: string): Promise<boolean>;
     mget(keys: string[]): Promise<(string | null)[]>;
     mset(entries: import('../types').SetEntry[]): Promise<void>;
@@ -73,6 +75,7 @@ export declare class RedisStorageAdapter extends BaseStorageAdapter {
     supportsPubSub(): boolean;
     publish(channel: string, message: string): Promise<number>;
     subscribe(channel: string, handler: MessageHandler): Promise<Unsubscribe>;
+    onPubSubReconnect(listener: () => void): () => void;
     /**
      * Build Redis options from config.
      */

package/storage/change-feed.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Change feed: named topics whose listeners learn that something changed, in this process and in the
+ * other processes that share the storage. A change carries no payload: a listener reads the current state.
+ *
+ * The backend follows what the storage can do:
+ * - `pubsub` (Redis, Upstash, memory): a publish is a message on the topic's channel; when a lost Redis connection
+ *   comes back, every followed topic is told, since its messages were missed meanwhile;
+ * - `poll` (SQLite): a publish increments the topic's counter, and each process polls `PRAGMA data_version`,
+ *   reading the counters of its topics only when another process wrote the file;
+ * - `local` (no pub/sub and no data version): this process only.
+ */
+import type { NamespacedStorage } from './types';
+export type ChangeFeedKind = 'pubsub' | 'poll' | 'local';
+export interface ChangeFeedOptions {
+    /** How often a `poll` feed checks whether another process wrote, in milliseconds. @default 250 */
+    pollIntervalMs?: number;
+    /** Changes of one topic within this window reach its listeners once, in milliseconds. @default 50 */
+    coalesceMs?: number;
+    /** Told of a failed poll or subscription, once until it works again, and of a listener that threw. */
+    onError?: (error: unknown) => void;
+}
+export interface ChangeFeed {
+    readonly kind: ChangeFeedKind;
+    /** Tell the topic's listeners, here and in the other processes, that it changed. */
+    publish(topic: string): Promise<void>;
+    /**
+     * Call `listener` when `topic` changes, and when it may have changed unheard (after a pub/sub reconnect); returns
+     * the function that stops it.
+     */
+    subscribe(topic: string, listener: () => void): () => void;
+    /** Stop every listener and the polling; the storage stays connected. */
+    close(): Promise<void>;
+}
+export declare const DEFAULT_CHANGE_FEED_POLL_INTERVAL_MS = 250;
+export declare const DEFAULT_CHANGE_FEED_COALESCE_MS = 50;
+/**
+ * A change feed over `storage`, with the backend its adapter supports (see the module comment).
+ *
+ * @example
+ * ```typescript
+ * const storage = await createStorage({ type: 'sqlite', sqlite: { path: '/var/lib/app/state.sqlite' } });
+ * const feed = createChangeFeed(storage);
+ * const stop = feed.subscribe('board', () => console.log('board changed'));
+ * await feed.publish('board');
+ * ```
+ */
+export declare function createChangeFeed(storage: NamespacedStorage, options?: ChangeFeedOptions): ChangeFeed;

package/storage/factory.d.ts

@@ -22,6 +22,12 @@ import type { RootStorage, StorageConfig, StorageType } from './types';
  * await store.connect();
  * ```
  *
+ * @example A SQLite file shared by the processes on one machine (needs `@frontmcp/storage-sqlite`)
+ * ```typescript
+ * const store = await createStorage({ type: 'sqlite', sqlite: { path: '/var/lib/my-app/state.sqlite' } });
+ * await store.incr('runs');
+ * ```
+ *
  * @example With namespaces
  * ```typescript
  * const store = await createStorage({ type: 'memory' });