@jini-ai/mcp 0.3.4 → 0.4.0

package/dist/federation/stdio/adapter.stdio.d.ts

@@ -0,0 +1,157 @@
+import type { FederationMessages } from "../messages.js";
+import type { McpSessionPort, McpStdioChannel, McpClientInfo } from "../ports.js";
+import type { ResolvedStdioLaunch } from "./stdio-launch-resolver.js";
+/**
+ * The working directory one stdio child is spawned in.
+ *
+ * An explicit `cwd` always wins. Otherwise a package runner gets a neutral directory instead of the
+ * daemon's own cwd, because npm reads the cwd's project tree BEFORE it runs anything: in this dev
+ * checkout that tree links `@jini-ai/*` to a pnpm monorepo whose `workspace:*` ranges npm cannot
+ * parse, so `npx -y namecom-mcp@latest` died with `EUNSUPPORTEDPROTOCOL` on every daemon boot
+ * (2026-09-29) while the same command worked from any other directory. A package fetched by name
+ * never needs host app's project directory; a host's own `package.json` is the wrong input for it.
+ *
+ * Anything else keeps inheriting the daemon's cwd exactly as before — a relative `command` (a
+ * package runner given as `./node_modules/.bin/npx` included) or a server that reads files relative
+ * to where it was started depends on it.
+ *
+ * @complexity O(1).
+ */
+export declare function resolveStdioChildCwd({ resolved }: {
+    resolved: ResolvedStdioLaunch;
+}, { neutralDir }?: {
+    neutralDir?: string | undefined;
+}): string | undefined;
+/**
+ * Appends one stderr chunk and keeps only the last {@link STDERR_TAIL_CHARS} characters.
+ * @complexity O(n) in the chunk length.
+ */
+export declare function keepStderrTail({ tail, chunk }: {
+    tail: string;
+    chunk: string;
+}): string;
+/**
+ * A child's stderr tail that is redacted BEFORE it is truncated.
+ *
+ * Truncating first cut a token printed just before ~600 characters of diagnostics in half, leaving a
+ * fragment no exact-value replacement can match (codex review 2026-09-29). So each chunk is redacted
+ * as it arrives, and the last `longest secret - 1` characters are held back from the kept tail until
+ * the next chunk — they may be the start of a secret split across chunks. Only redacted text is
+ * ever truncated, so the kept tail can begin mid-`[redacted]` but never mid-secret.
+ *
+ * @param secretValues - The child's own `env` values, as spawned.
+ * @complexity O(c · v) per chunk of length c.
+ */
+export declare function createStderrTail({ secretValues }: {
+    secretValues: readonly string[];
+}): {
+    append(required: {
+        chunk: string;
+    }): void;
+    text(): string;
+};
+/**
+ * The close reason for a child that exited: code and signal, plus what it last printed to stderr.
+ *
+ * Every value of the connection's own `env` is replaced with `[redacted]` first. That env holds the
+ * row's unsealed credentials, and a server that echoes its config on failure would otherwise carry a
+ * token into `connectFailures` — which the admissions route serves to the admin UI and whose contract
+ * (`bootstrap.ts`) is "never a raw env value or secret".
+ *
+ * @param secretValues - The child's own `env` values, as spawned.
+ * @complexity O(s · v) in stderr length and env value count.
+ */
+export declare function describeChildExit({ code, signal, stderrTail, secretValues }: {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    stderrTail: string;
+    secretValues: readonly string[];
+}): string;
+/**
+ * Performs the MCP handshake over `channel` and returns the connected session.
+ *
+ * @param deps.channel - The transport seam. `spawnMcpStdioChannel` in production, a scripted
+ * double in tests.
+ * @param deps.requestTimeoutMs - Per-request ceiling, applied to the handshake too.
+ * @throws {Error} If `initialize` fails, times out, or the channel dies during it.
+ * @complexity O(1) beyond the remote's round-trip.
+ */
+export declare function connectMcpStdioSession(deps: {
+    channel: McpStdioChannel;
+    requestTimeoutMs: number;
+    clientInfo: McpClientInfo;
+    messages: FederationMessages;
+}): Promise<McpSessionPort>;
+/**
+ * The production {@link McpStdioChannel}: a child process, its stdin, and newline-framed stdout.
+ *
+ * Deliberately logic-free — reassembly and nothing else — because everything above it is already
+ * under test through the channel seam, and code that only runs when a real process exists is code
+ * that only fails in production.
+ *
+ * `env` REPLACES rather than extends the parent environment, which is the security-relevant choice:
+ * the daemon's own `process.env` holds `host daemon credential` (`daemon-auth.ts`), and handing
+ * that to a third-party vendor's child process would give it host app's own daemon credential — the
+ * exact inversion of the `mcp-injection.ts` grant, and a far worse one. A federated server receives
+ * what `config.ts` explicitly puts in `env`, plus what {@link buildMcpChildEnv} inherits and nothing else.
+ *
+ * Takes a {@link ResolvedStdioLaunch} rather than an {@link McpStdioLaunchSpec} (S2 of the
+ * desktop-npx plan): the launch has already passed through the injected `McpStdioLaunchResolver`
+ * by the time it gets here, so `resolved.command`/`resolved.args` are already whatever the resolver
+ * decided to run, and `resolved.launchEnv` is threaded into {@link buildMcpChildEnv} alongside the
+ * connection's own `env`. On every non-desktop deployment `resolved` is the identity resolver's
+ * output — `command`/`args`/`env` unchanged, `launchEnv: {}` — so this stays byte-identical to
+ * before the resolver existed.
+ *
+ * @complexity O(n) in bytes received.
+ */
+export declare function spawnMcpStdioChannel(resolved: ResolvedStdioLaunch & {
+    messages: FederationMessages;
+}): McpStdioChannel;
+/** {@link buildMcpChildEnv}'s input. Everything past `specEnv` is a test seam that defaults to the
+ *  real process; production passes only `command` and `specEnv`. */
+interface McpChildEnvInput {
+    /** The child's `command`, compared against `execPath` on win32. */
+    readonly command: string;
+    /** The connection's own `env`, which wins over anything inherited AND over `launchEnv`. */
+    readonly specEnv: Readonly<Record<string, string>>;
+    /**
+     * The stdio launch resolver's own additions (S2 of the desktop-npx plan) — `ELECTRON_RUN_AS_NODE`,
+     * `PATH`, `npm_config_*` — from `stdio-launch-resolver.ts`'s {@link ResolvedStdioLaunch.launchEnv}.
+     * Layered between the inherited allowlist and `specEnv`: it can add variables the parent process
+     * never had, but the connection's own `env` still wins over it, including an explicit `PATH` that
+     * deliberately drops the toolchain shims — the user's own call, per plan §4. Defaults to `{}`, so
+     * omitting it (every caller before this parameter existed, and every non-desktop deployment today)
+     * leaves the result byte-identical.
+     */
+    readonly launchEnv?: Readonly<Record<string, string>> | undefined;
+    readonly platform?: NodeJS.Platform | undefined;
+    readonly parentEnv?: NodeJS.ProcessEnv | undefined;
+    readonly execPath?: string | undefined;
+}
+/**
+ * The complete environment one federated MCP child is spawned with.
+ *
+ * On every platform: {@link INHERITED_ENV_VARS} from the parent, then `launchEnv`, then the
+ * connection's own `env` over the top of both. On darwin and linux, with `launchEnv` empty (every
+ * non-desktop deployment), that is ALL — byte-identical to what this adapter has always sent.
+ *
+ * On win32, two further additions:
+ *
+ * 1. {@link WIN32_INHERITED_ENV_VARS}, which Windows programs need to start.
+ * 2. `ELECTRON_RUN_AS_NODE`, but ONLY when the child's `command` is this process's own executable
+ *    and this process itself runs with it set. host app Desktop registers its own Electron binary as the
+ *    command of its `host-desktop` connection on win32, where no launcher script can be exec'd, and
+ *    without this variable that binary opens a second GUI app instead of running the bridge script.
+ *    Carrying it here rather than in the connection's `env` matters: a row's `env` is sealed with the
+ *    site's root key, so a flag in it fails the whole save with `SECRET_STORE_UNCONFIGURED` on a
+ *    site that has none. The rule is narrow on purpose — "a child that is this very binary runs in
+ *    the mode this binary runs in" — so no third-party child ever has its runtime mode changed.
+ *
+ * Empty parent values are skipped, as they always were.
+ *
+ * @complexity O(k) in the number of inherited names.
+ */
+export declare function buildMcpChildEnv({ command, specEnv, }: Pick<McpChildEnvInput, "command" | "specEnv">, { launchEnv, platform, parentEnv, execPath, }?: Omit<McpChildEnvInput, "command" | "specEnv">): Record<string, string>;
+export {};
+//# sourceMappingURL=adapter.stdio.d.ts.map