@vibesdotdev/mcp 0.0.0-stage → 1.0.0-rc.1

package/dist/adapters/mcp/stdio-relay.d.ts

@@ -0,0 +1,232 @@
+import type { PurposePreset } from '@vibesdotdev/tools/schemas/presets/schema';
+/**
+ * Relay a stdio MCP connection to the workspace's shared host.
+ *
+ * WHAT THIS SAVES, measured on this machine 2026-08-21:
+ *
+ *   10 `vibes dev mcp serve` processes, ALL serving one workspace, 51.3 GB
+ *   resident. Eight had byte-identical arguments. Every one had booted its own
+ *   full runtime to answer the same questions about the same files.
+ *
+ * Each client spawns its own stdio server, and each stdio server booted its
+ * own full MCP runtime, ~6 GB. Nothing was wrong with any individual decision;
+ * the cost only exists in the sum, which no single process is in a position to
+ * see.
+ *
+ * THE RELAY MUST SHORT-CIRCUIT BEFORE THE SERVE BODY. A relay that boots a
+ * runtime and then forwards has moved the work without removing it — it would
+ * look like a fix in every log line and change nothing on the memory graph.
+ *
+ * OPEN (RC02): `dev mcp serve` is a serve command, so the CLI boots its serve
+ * host through the one entry — compose and discover — BEFORE the
+ * action that calls this relay runs (rc02-rc03 §2.3). The relay still skips
+ * the adapter, session, hot-reload and indexing work, but no longer the host
+ * boot itself. Recovering that saving is a design decision (the relay is not a
+ * serve host). Relay activation is deferred by its descriptor so autonomous
+ * work belongs to the remote serving body, not to each forwarding process.
+ *
+ * TRANSPARENT PASSTHROUGH, deliberately. This bridges raw JSON-RPC messages
+ * rather than instantiating a Client/Server pair and re-implementing methods.
+ * A proxy that enumerates the methods it understands silently breaks every
+ * method added after it was written, and the failure looks like the feature
+ * simply not existing. Forwarding whole messages means new MCP methods, and
+ * capabilities this file has never heard of, work with no change here.
+ */
+import { type JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+import type { LoggerImplementation } from '@vibesdotdev/logging';
+import { type CaughtFailure, type RuntimeLifecycle, type RuntimeRef } from '@vibesdotdev/kernel';
+import { type HostClaimRoots, type HostLookup, type HostProcessProbe, type McpHostClaim } from './host-registry.ts';
+export interface RelayResult {
+    /** Did we attach to a host and take over the process's stdio? */
+    relayed: boolean;
+    /** Why not, when we did not. Reported to the caller, never swallowed. */
+    reason?: 'no-host' | 'stale-host' | 'unreachable' | 'disabled' | 'identity-mismatch' | 'transport-unavailable';
+    /** Captured attachment failure, retained for the startup refusal. */
+    failure?: CaughtFailure;
+    /** What the host serves vs what this client asked for, when they differ. */
+    mismatch?: {
+        hostPreset?: string;
+        wantedPreset?: string;
+    };
+    /** Present when `reason` is `stale-host`, for an honest message. */
+    staleReason?: 'dead-process' | 'workspace-mismatch';
+    /**
+     * The claim discovery read, when it read one. Carried so the caller can name
+     * the process it refused (pid, port, when it started) instead of "a host".
+     */
+    claim?: McpHostClaim;
+    /** The host we attached to, for logging. */
+    url?: string;
+    /**
+     * Resolves when the relay closes, and ONLY set when `relayed` is true.
+     *
+     * The caller must await this. `start()` returns as soon as the pipe is wired,
+     * not when it is finished — returning from the command at that point would
+     * exit the process and kill the agent's session the instant it connected.
+     */
+    done?: Promise<void>;
+}
+export interface RelayOptions {
+    /**
+     * The relaying runtime's lifecycle (`runtime.lifecycle`): every deadline,
+     * probe timer, restore jitter and reconnect hold-off is its, so disposing
+     * the runtime ends them all (RC07).
+     */
+    lifecycle: RuntimeLifecycle;
+    /**
+     * The relaying runtime's logger (`getLogger('mcp.stdio-relay', runtime)`):
+     * every probe, claim and transport failure the relay reports lands here.
+     */
+    logger: LoggerImplementation;
+    workspaceRoot: string;
+    /** The caller's runtime path roots (`getPathRoots(runtime)`): host claims live under its `vibesHome`. */
+    roots: HostClaimRoots;
+    /** How a claim's pid is checked: `await hostProcessProbe(runtime)` in production. */
+    processProbe: HostProcessProbe;
+    /** Identity this client asked for; forwarded so the host can scope it. */
+    identity: {
+        preset?: string;
+        toolPatterns?: string[];
+        agent?: string;
+        harness?: string;
+        /** Stable conversation/body identity; distinct from the transient HTTP transport id. */
+        harnessSessionId?: string;
+        /** Durable `tools/agent/instance` system id. */
+        agentSystemId?: string;
+        /** Projects the client's checkout is bound to (ProjectRef marker). */
+        projectIds?: readonly string[];
+        /** The owner this agent calls home; the id comes from the host's principal. */
+        home?: 'user' | 'organization' | 'team';
+        client?: string;
+    };
+    /** Overrides discovery. Set by VIBES_MCP_HOST_URL. */
+    hostUrl?: string;
+    /** Injected in tests. */
+    lookup?: (workspaceRoot: string) => HostLookup | Promise<HostLookup>;
+    /** Injected only by the relay lifecycle falsifier. */
+    transports?: RelayTransportFactory;
+    /** Injected only by held-host liveness falsifiers. */
+    probeHost?: (mcpUrl: URL) => Promise<boolean>;
+    /**
+     * The relaying runtime (required, so no attach path lacks it): the host
+     * attestation claim is read through its `filesystem/adapter` on the first
+     * attach and on every re-attach.
+     */
+    runtime: RuntimeRef;
+    /** Injected in tests: the bearer this relay presents, in place of reading the host's attestation claim. */
+    readAttestation?: () => Promise<string | undefined>;
+    /**
+     * The client pipe the downstream stdio transport reads. Defaults to
+     * `process.stdin` whenever this relay owns the process's stdio (no injected
+     * transports). Injected only by the client-disconnect falsifier.
+     */
+    clientInput?: ClientInputStream;
+    /** Reconnect timing. Production uses a bounded backoff; tests use zero. */
+    reconnect?: {
+        initialDelayMs?: number;
+        maxDelayMs?: number;
+        /**
+         * Spread durable session restores after a host restart. Every relay can
+         * initialize immediately; only the storage-heavy bind receipt replay is
+         * jittered so hundreds of existing bodies do not stampede Session authority.
+         */
+        bindRestoreJitterWindowMs?: number;
+        /** Deterministic jitter seam for the relay recovery falsifier. */
+        random?: () => number;
+        /** How often a pending request proves the host event loop still responds. */
+        healthProbeIntervalMs?: number;
+        /** Timeout for the independent HTTP health proof. */
+        healthProbeTimeoutMs?: number;
+    };
+}
+/**
+ * The half of a readable stream this relay needs to observe end-of-input.
+ *
+ * Narrow on purpose: the relay must not read, pause, or resume the client pipe
+ * — the SDK's stdio transport owns that — it only needs to know when the pipe
+ * is done.
+ */
+export interface ClientInputStream {
+    once(event: 'end' | 'close', listener: () => void): void;
+    off(event: 'end' | 'close', listener: () => void): void;
+}
+export interface RelayTransport {
+    onmessage?: (message: JSONRPCMessage) => void;
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+    start(): Promise<void>;
+    send(message: JSONRPCMessage): Promise<void>;
+    close(): Promise<void>;
+}
+export interface RelayTransportFactory {
+    /** `authorization`, when present, is presented on every request to the host. */
+    createUpstream(url: URL, authorization?: string): RelayTransport;
+    createDownstream(): RelayTransport;
+}
+/**
+ * The host is up but no longer holds this relay's HTTP session: it answered
+ * 404, the protocol's "start a new session" (a session it reclaimed), or 400
+ * "No valid session ID provided" (an id it never knew). That is not a lost
+ * host: the relay opens a fresh session, replays its state and resends the
+ * calls in flight.
+ */
+export declare function isHostSessionExpired(error: CaughtFailure): boolean;
+/** The host's protocol refusal, or null when the transport session was lost. */
+export declare function hostRefusalFromTransportError(error: unknown, log: Pick<LoggerImplementation, 'debug'>, beforeInitialize?: boolean): {
+    code: number;
+    message: string;
+    data?: unknown;
+} | null;
+/**
+ * How the relay lost its host: `restarted` when the host claim now names
+ * another process (pid or start changed, or no live claim at all), and
+ * `unresponsive` when the same process still holds the claim — the connection
+ * failed or timed out, but nothing restarted. The two are reported apart so a
+ * busy host is never announced as a restart.
+ */
+export type HostLoss = 'restarted' | 'unresponsive';
+/**
+ * Whether the host the relay attached to (`attached`, its claim at attach) was
+ * replaced: the advertised claim is gone or names another pid or start. With
+ * no claim at attach (an explicit host URL) a replacement cannot be observed.
+ */
+export declare function observeHostLoss(options: RelayOptions, attached: McpHostClaim | undefined): Promise<HostLoss>;
+/**
+ * Decide whether a host is available, WITHOUT connecting.
+ *
+ * Split out from the connect path so the decision is testable on its own — the
+ * interesting cases here (dead pid, wrong workspace, no claim) are precisely the
+ * ones that are awkward to stage against a live socket.
+ */
+/**
+ * The catalog id a client's identity resolves to, through the same resolver
+ * the host used when it wrote its claim. `undefined` when the client named no
+ * preset — it takes whatever the host serves.
+ */
+export declare function canonicalWantedPreset(identity: RelayOptions['identity'], customPresets?: Record<string, PurposePreset>): string | undefined;
+/** A host claim's catalog id in canonical form (`mcp:`-prefixed), or undefined. */
+export declare function canonicalServedPreset(presetId: string | undefined): string | undefined;
+export declare function resolveHostUrl(options: RelayOptions): Promise<RelayResult>;
+/**
+ * The identity a relayed client asked for, as `initialize` params.
+ *
+ * The host serves many clients, and they do NOT all want the same tools — on
+ * this machine eight clients asked for `full` and one asked for `cursor`. If the
+ * relay does not carry identity, every client silently inherits whichever
+ * catalog the host happened to boot with. That is not a crash; it is an agent
+ * quietly holding the wrong tools, which is worse.
+ */
+export declare function relayInitializeMeta(identity: RelayOptions['identity']): import("@vibesdotdev/kernel/schemas/json").JsonObject;
+/** Stamp relay identity onto an outbound `initialize` request, in place. */
+export declare function applyRelayIdentity(message: JSONRPCMessage, identity: RelayOptions['identity']): JSONRPCMessage;
+/**
+ * Attach this process's stdio to the shared host and pipe until it closes.
+ *
+ * Returns `{relayed:false}` when there is no usable host. It NEVER throws for a
+ * missing host: it reports WHAT it found (`reason`, `staleReason`, `mismatch`,
+ * `claim`, `url`) and leaves the decision to the caller. Today that caller is
+ * `startStdioMcp`, which turns the receipt into a specific error — never a
+ * silent private runtime — so every field here is a sentence someone reads.
+ */
+export declare function relayStdioToHost(options: RelayOptions): Promise<RelayResult>;
+//# sourceMappingURL=stdio-relay.d.ts.map

package/dist/adapters/mcp/stdio-relay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio-relay.d.ts","sourceRoot":"","sources":["../../../src/adapters/mcp/stdio-relay.ts"],"names":[],"mappings":"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"}