@ravefox/space 0.2.0 → 0.3.0

package/src/lib/adapters/pi-mcp-client.mjs

@@ -1,617 +0,0 @@
-/**
- * A minimal MCP client for the pi bridge (pi-commonly-mcp.mjs), over both
- * transports the environment spec admits: stdio (newline-delimited JSON-RPC)
- * and Streamable HTTP.
- *
- * A client for four methods (initialize, tools/list, tools/call, the
- * initialized notification) is smaller than a dependency, and keeping it in a
- * file with no pi imports means the CLI's own jest can test it — `typebox`
- * only resolves inside pi's extension loader, so the extension file stays thin
- * and untested by jest.
- *
- * pi itself has no MCP support by design (its README: "No MCP. … build an
- * extension that adds MCP support"); this bridge IS that extension, so an
- * HTTP MCP server reaches a pi seat only through the client below. A
- * `url`-only entry used to be dropped by the two filters here and in pi.js,
- * which is how a granted pi seat ended up holding the grant broker — a
- * Streamable HTTP server — and getting nothing, silently.
- */
-
-import { spawn } from 'node:child_process';
-import { closeSync, readFileSync, rmSync } from 'node:fs';
-import { isAbsolute } from 'node:path';
-import {
-  MCP_PACKAGE, PIPE_READER_VERSION, describeMcpCommand, versionOlderThan,
-} from '../mcp-server-version.js';
-
-import { CREDENTIAL_FILE_VAR, CREDENTIAL_KEY } from '../credential-file.js';
-
-/**
- * The grant broker's path. Keyed on the PATH and not on the entry's `name`,
- * because the name is whatever the declaration says while the path is the
- * broker's. A url that does not parse is not this predicate's business — the
- * origin rule in `pi.js resolveMcpServers` refuses those before they are
- * carried.
- *
- * F175c: a pi turn carries the broker only when it is confined, which for pi
- * means a public seat in the macOS Seatbelt jail (F113b). Every other pi turn
- * refuses it here as well as at the server's projection and in the daemon's
- * guard — this layer is what holds on deploy skew, when the row names no
- * adapter for the server to key on, and in a backend older than the rule.
- */
-export const GRANT_BROKER_PATH = '/api/mcp/grants/';
-
-/**
- * The reason strings BOTH halves of this refusal use, verbatim from the
- * server's typed refusal (`backend/services/grantBrokerConfinement.ts`: code
- * `grant_broker_unconfined`). wren's ruling (69829): "Same reason string on
- * both halves" — so a daemon log line and the server's `grantBrokerRefusal`
- * field can be read side by side, and neither layer grows a vocabulary the
- * other one does not have. Mirrored rather than imported: this package does not
- * depend on the backend, so the literals are pinned by a test instead.
- *
- * `adapter_cannot_confine` is the adapter-wide refusal the other unproven
- * adapters get. pi's own is `adapter_confines_public_only` (F175c): pi carries a
- * grant on a public macOS seat and refuses it on every other one, and naming the
- * agent on the grant (F94) does not lift it.
- */
-export const GRANT_BROKER_REFUSAL = 'grant_broker_unconfined: adapter_cannot_confine';
-export const GRANT_BROKER_PUBLIC_ONLY_REFUSAL = 'grant_broker_unconfined: adapter_confines_public_only';
-
-/**
- * Is this url the instance's grant broker? Path-keyed, and the comparison is
- * case-INSENSITIVE because the route it mirrors is: express matches paths
- * case-insensitively unless `caseSensitive` is set, so the live API answers
- * `/API/MCP/GRANTS/x` from the same handler as `/api/mcp/grants/x` (measured
- * 2026-09-19: POST both → 401, POST `/api/nothing/x` → 404, i.e. the control is
- * what distinguishes a matched route from a missing one). A case-sensitive
- * predicate therefore refuses the spelled-canonically broker and hands pi the
- * uppercased spelling of it — the real runtime token included. Vera measured
- * exactly that against the running instance (69839).
- *
- * Case is the only spelling the router forgives: `%67rants`, `//`, `./` and
- * `GRANTS%2F` all 404 on the live API, and a trailing slash is already inside
- * the prefix.
- */
-export const isGrantBrokerUrl = (url) => {
-  try {
-    return new URL(url).pathname.toLowerCase().startsWith(GRANT_BROKER_PATH);
-  } catch {
-    return false;
-  }
-};
-
-const PROTOCOL_VERSION = '2024-11-05';
-const MAX_TEXT = 50 * 1024;
-
-const truncate = (text) => (text.length <= MAX_TEXT
-  ? text
-  : `${text.slice(0, MAX_TEXT)}\n… [truncated ${text.length - MAX_TEXT} bytes]`);
-
-/**
- * Connect to one declared server, stdio or Streamable HTTP. `resolveMcpServers`
- * emits exactly one of `command`/`url` per entry, and `readServers` keeps that
- * invariant, so the shape decides; `url` wins if a hand-built entry still
- * carries both, because a server that advertises an endpoint is not a command
- * to spawn.
- */
-export const connectMcp = (server, opts = {}) => (typeof server?.url === 'string' && server.url
-  ? connectHttpMcp(server, opts)
-  : connectStdioMcp(server, opts));
-
-/**
- * The credential channel (TASK-078, ruled 2026-09-19: "take the token out of
- * the environment", inherited pipe).
- *
- * `connectStdioMcp` spawns each declared stdio server with
- * `{...process.env, ...env}`, and the default declaration puts the seat's
- * runtime token in that `env` map. So the token sat in the MCP child's
- * environment, where any same-user process could read it back with
- * `ps eww <pid>` or `/proc/<pid>/environ` — including, on a shared host, a
- * process the seat is not allowed to talk to.
- *
- * Now the token rides an inherited pipe on fd 3 and the child's environment
- * carries only a pointer to it (`COMMONLY_TOKEN_FD=3`) — not a secret. The
- * child end of that pipe is read to EOF.
- *
- * WHERE THE TOKEN COMES FROM. The launcher writes a per-spawn 0600 file and the
- * declaration names it with `${COMMONLY_TOKEN_FILE}` — a PATH, not a secret — so
- * the runtime's own environment never holds the token (TASK-082/083). A
- * declaration that instead carries the literal token in `COMMONLY_AGENT_TOKEN`
- * still works: that is the older channel, and it is the operator's to declare.
- * Whichever named the credential, the child gets it on the pipe and its own
- * environment is left clean.
- *
- * THE PIPE IS ONLY AVAILABLE WHERE WE SPAWN. This is the pi path; claude and
- * codex let their own CLI start the server (claude expands `${VAR}` in its own
- * process env, codex writes a plain `mcp_servers.*.env` entry), so a pipe opened
- * here never reaches that grandchild. Those two deliver the PATH instead, which
- * is what let the token leave their runtime environments too.
- *
- * THE OLD SERVER STILL WORKS. `@commonlyai/mcp` only learned to read the pipe in
- * 0.3.11, and a seat may pin an older one — the five staging seats ran a checkout
- * of 0.3.7 when this was measured (2026-09-19; the doc here said 0.3.4, which was
- * true two weeks earlier) — so a declaration whose command names an older
- * `@commonlyai/mcp` keeps the environment variable AS WELL, with a warning that
- * names the pin. An operator can also opt out explicitly with
- * `COMMONLY_TOKEN_CHANNEL=env` in the entry's own env. Otherwise the token is
- * piped and the environment is left clean.
- */
-export { CREDENTIAL_KEY, CREDENTIAL_FILE_VAR };
-
-export const CREDENTIAL_FD_VAR = 'COMMONLY_TOKEN_FD';
-export const CREDENTIAL_CHANNEL_VAR = 'COMMONLY_TOKEN_CHANNEL';
-export const CREDENTIAL_FD = 3;
-
-/**
- * The only variables a spawned MCP server inherits from us.
- *
- * This list is DERIVED, not guessed: each entry exists because a real child
- * failed without it, and a child that only fails at spawn is the worst failure
- * shape there is (TASK-083). `PATH` runs the command (and, for a seat, carries
- * the seat-launch shim directory prepended, so it must be passed through rather
- * than canonicalised); `HOME` is where `npx` keeps the cache it fetches
- * `@commonlyai/mcp` into, which a cold start needs; `TMPDIR` was measured in a
- * live child on macOS, where /var/folders is not /tmp; the proxy and CA names
- * are absent on this machine, so an operator behind a proxy or a private CA is
- * the case that cannot be exercised here — including them unset costs nothing,
- * and without them that operator's cold `npx` would fail in a way that reads as
- * this change regressing.
- *
- * Deliberately NOT a prefix match: a variable named `COMMONLY_*` is ours to hand
- * over explicitly, and a variable named like a secret is exactly what an
- * allowlist exists to drop.
- */
-export const CHILD_ENV_ALLOWLIST = Object.freeze([
-  'PATH',
-  'HOME',
-  'TMPDIR',
-  'HTTPS_PROXY',
-  'HTTP_PROXY',
-  'NO_PROXY',
-  'NODE_EXTRA_CA_CERTS',
-]);
-
-/**
- * The environment a spawned MCP server gets: the allowlist above, then whatever
- * the entry itself declared, and nothing else. The daemon's environment is not a
- * channel into a child — `...process.env` used to make it one, which is how a
- * third-party server came to hold our seat token and the model key.
- */
-export const buildChildEnv = (parentEnv, declaredEnv) => {
-  const out = {};
-  for (const key of CHILD_ENV_ALLOWLIST) {
-    const value = parentEnv ? parentEnv[key] : undefined;
-    if (value !== undefined) out[key] = value;
-  }
-  return Object.assign(out, declaredEnv || {});
-};
-
-/**
- * The channel predicates live in `../mcp-server-version.js`, because the claude
- * and codex adapters have to answer the same question and a second copy of it
- * would drift silently in one of them.
- */
-export {
-  MCP_PACKAGE, PIPE_READER_VERSION, FILE_READER_VERSION, parseVersion, describeMcpCommand,
-} from '../mcp-server-version.js';
-
-const olderThanPipeReader = (version) => versionOlderThan(version, PIPE_READER_VERSION);
-
-/**
- * Split a declared env map into the child's environment and the credential to
- * hand over the pipe.
- *
- * Returns `{ env, credential, keepInEnv }`. `keepInEnv` is true only when the
- * server cannot read the pipe — it predates the reader, it is somebody else's
- * server, or the declaration opted out explicitly. Everything else gets the
- * pointer variable and no secret.
- */
-export const splitCredential = (env, command, {
-  onWarn = (m) => process.stderr.write(`${m}\n`),
-  readCredentialFile = (path) => readFileSync(path, 'utf8'),
-} = {}) => {
-  const declared = { ...(env || {}) };
-  const declaredFile = declared[CREDENTIAL_FILE_VAR];
-  const requested = String(declared[CREDENTIAL_CHANNEL_VAR] || '').trim().toLowerCase();
-  delete declared[CREDENTIAL_CHANNEL_VAR];
-  let credential = null;
-  let fromFile = false;
-  // A declaration that names a file is using the launcher channel, and that is
-  // the one to honour: if it ALSO carries a literal token, the literal is the
-  // leftover of an older declaration, and preferring it would keep the secret in
-  // the very place this exists to empty.
-  if (declaredFile !== undefined && String(declaredFile).trim() !== '') {
-    // The launcher channel: the declaration names a path, and the credential is
-    // read here so the child never needs the file (or the token) at all.
-    const path = String(declaredFile).trim();
-    let raw;
-    try {
-      raw = readCredentialFile(path);
-    } catch (err) {
-      throw new Error(`the declared credential file could not be read: ${path}: ${err.message}`);
-    }
-    credential = String(raw ?? '').trim();
-    if (!credential) throw new Error(`the declared credential file carried nothing: ${path}`);
-    fromFile = true;
-  } else if (declared[CREDENTIAL_KEY]) {
-    credential = declared[CREDENTIAL_KEY];
-  }
-  if (!credential) {
-    delete declared[CREDENTIAL_KEY];
-    delete declared[CREDENTIAL_FILE_VAR];
-    return { env: declared, credential: null, keepInEnv: false };
-  }
-  if (requested === 'env') {
-    declared[CREDENTIAL_KEY] = credential;
-    delete declared[CREDENTIAL_FILE_VAR];
-    return { env: declared, credential: null, keepInEnv: true };
-  }
-  const server = describeMcpCommand(command);
-  if (!server) {
-    // Not identifiable as @commonlyai/mcp. A declaration that put this key in a
-    // stranger's environment asked for it to be there, and that server has no
-    // reason to know about a pipe; changing its contract is not this change's
-    // business.
-    return { env: declared, credential: null, keepInEnv: true };
-  }
-  if (server.version && olderThanPipeReader(server.version) === true) {
-    onWarn(`[pi-mcp-client] ${command[0]} runs ${MCP_PACKAGE} ${server.version.join('.')}, which predates the pipe channel (0.3.11): keeping the token in the child environment. Unpin it, or set ${CREDENTIAL_CHANNEL_VAR}=env to say so on purpose.`);
-    declared[CREDENTIAL_KEY] = credential;
-    delete declared[CREDENTIAL_FILE_VAR];
-    return { env: declared, credential: null, keepInEnv: true };
-  }
-  delete declared[CREDENTIAL_KEY];
-  // The pipe carries the credential, so the child needs neither the token nor the
-  // path: one declared channel, and it is the fd.
-  delete declared[CREDENTIAL_FILE_VAR];
-  declared[CREDENTIAL_FD_VAR] = String(CREDENTIAL_FD);
-  return { env: declared, credential, keepInEnv: false, fromFile };
-};
-
-/** A minimal MCP stdio client: initialize, tools/list, tools/call. */
-export const connectStdioMcp = ({
-  name, command, env,
-}, {
-  spawnImpl = spawn, timeoutMs = 60_000, onWarn, parentEnv = process.env, readCredentialFile,
-} = {}) => {
-  const [cmd, ...args] = command;
-  const opts = onWarn ? { onWarn } : {};
-  if (readCredentialFile) opts.readCredentialFile = readCredentialFile;
-  const { env: declaredEnv, credential, keepInEnv } = splitCredential(env, command, opts);
-  // The child gets an ALLOWLIST plus its own declaration — never the daemon's
-  // environment. `...process.env` is what let a third-party MCP server inherit
-  // both the seat token and the model key (TASK-083).
-  const childEnv = buildChildEnv(parentEnv, declaredEnv);
-  if (!keepInEnv) delete childEnv[CREDENTIAL_KEY];
-  const stdio = credential ? ['pipe', 'pipe', 'pipe', 'pipe'] : ['pipe', 'pipe', 'pipe'];
-  const proc = spawnImpl(cmd, args, { env: childEnv, stdio });
-  if (credential) {
-    const channel = proc.stdio && proc.stdio[CREDENTIAL_FD];
-    if (!channel) {
-      // Fail loudly rather than fall back: the environment it would fall back to
-      // is the thing this change exists to empty.
-      throw new Error(`${name}: no fd ${CREDENTIAL_FD} pipe to carry the runtime token`);
-    }
-    channel.on('error', () => {});
-    channel.end(credential);
-  }
-  const pending = new Map();
-  let nextId = 1;
-  let buffer = '';
-  proc.stdout.on('data', (chunk) => {
-    buffer += chunk.toString();
-    let nl;
-    while ((nl = buffer.indexOf('\n')) !== -1) {
-      const line = buffer.slice(0, nl).trim();
-      buffer = buffer.slice(nl + 1);
-      if (!line) continue;
-      let msg;
-      try { msg = JSON.parse(line); } catch { continue; }
-      const waiter = msg && msg.id !== undefined ? pending.get(msg.id) : null;
-      if (!waiter) continue;
-      pending.delete(msg.id);
-      clearTimeout(waiter.timer);
-      if (msg.error) waiter.reject(new Error(`${name}: ${msg.error.message || JSON.stringify(msg.error)}`));
-      else waiter.resolve(msg.result);
-    }
-  });
-  proc.on('exit', (code) => {
-    for (const [id, waiter] of pending) {
-      pending.delete(id);
-      clearTimeout(waiter.timer);
-      waiter.reject(new Error(`${name}: MCP server exited (${code}) before answering`));
-    }
-  });
-  const send = (obj) => proc.stdin.write(`${JSON.stringify(obj)}\n`);
-  const request = (method, params) => new Promise((resolve, reject) => {
-    const id = nextId++;
-    const timer = setTimeout(() => { pending.delete(id); reject(new Error(`${name}: ${method} timed out after ${timeoutMs}ms`)); }, timeoutMs);
-    pending.set(id, { resolve, reject, timer });
-    send({ jsonrpc: '2.0', id, method, params: params || {} });
-  });
-  const notify = (method, params) => send({ jsonrpc: '2.0', method, params: params || {} });
-  const initialize = async () => {
-    const result = await request('initialize', {
-      protocolVersion: PROTOCOL_VERSION,
-      capabilities: {},
-      clientInfo: { name: 'commonly-pi-bridge', version: '1.0.0' },
-    });
-    notify('notifications/initialized');
-    return result;
-  };
-  const listTools = async () => (await request('tools/list')).tools || [];
-  const callTool = (toolName, args) => request('tools/call', { name: toolName, arguments: args || {} });
-  const close = () => { try { proc.kill('SIGTERM'); } catch { /* already gone */ } };
-  return { initialize, listTools, callTool, close, proc };
-};
-
-/**
- * Split an SSE body into its `data:` payloads. Streamable HTTP lets a server
- * answer a POST either with one JSON object or with an event stream holding
- * the JSON-RPC messages, so both shapes are parsed.
- */
-const ssePayloads = (text) => text.split(/\r?\n\r?\n/)
-  .map((block) => block.split(/\r?\n/)
-    .filter((line) => line.startsWith('data:'))
-    .map((line) => line.slice(5).trimStart())
-    .join('\n'))
-  .filter(Boolean);
-
-const parseMessages = (text, contentType) => {
-  const body = text.trim();
-  if (!body) return [];
-  if (contentType.includes('text/event-stream')) return ssePayloads(body);
-  // A server MAY answer a request with plain JSON regardless of the request's
-  // `accept`, so the body decides before the header does.
-  if (body.startsWith('{') || body.startsWith('[')) return [body];
-  return ssePayloads(body);
-};
-
-/**
- * A minimal MCP Streamable HTTP client: initialize, tools/list, tools/call.
- *
- * `headers` is where a declared `Authorization` arrives, already substituted
- * with the seat's runtime token by the adapter. The token therefore rides in an
- * HTTP header built from the JSON list the bridge reads off its own fd 3 (see
- * takeServers) — never on argv, and never in this process's environment, which a
- * same-user child of this process can read back whole (`ps eww $PPID`,
- * `/proc/$PPID/environ`) no matter what this process deletes from its own copy.
- */
-export const connectHttpMcp = ({ name, url, headers }, { fetchImpl = globalThis.fetch, timeoutMs = 60_000 } = {}) => {
-  if (typeof fetchImpl !== 'function') throw new Error(`${name}: no fetch implementation for the HTTP MCP transport`);
-  const declared = headers || {};
-  let nextId = 1;
-  let sessionId = null;
-  let protocolVersion = PROTOCOL_VERSION;
-  let negotiated = false;
-  const requestHeaders = () => ({
-    'content-type': 'application/json',
-    // Both, per the spec: a server may answer with JSON or with an event stream.
-    accept: 'application/json, text/event-stream',
-    ...declared,
-    ...(sessionId ? { 'mcp-session-id': sessionId } : {}),
-    // The version header follows NEGOTIATION, not the session. Our own broker is
-    // stateless (`mcpGrants.ts` sets `sessionIdGenerator: undefined`), so it
-    // never mints a session id — gating this on one meant the only broker we
-    // have never received the version it negotiated (Vera, Connectors).
-    ...(negotiated ? { 'mcp-protocol-version': protocolVersion } : {}),
-  });
-  const post = async (payload) => {
-    const controller = new AbortController();
-    let timer;
-    // Race an explicit timer as well as aborting: a client whose fetch ignores
-    // the signal must not leave a seat waiting forever on a dead endpoint.
-    const expired = new Promise((_resolve, reject) => {
-      timer = setTimeout(() => {
-        controller.abort();
-        reject(new Error(`${name}: timed out after ${timeoutMs}ms`));
-      }, timeoutMs);
-    });
-    try {
-      const res = await Promise.race([fetchImpl(url, {
-        method: 'POST',
-        headers: requestHeaders(),
-        body: JSON.stringify(payload),
-        signal: controller.signal,
-        // These requests carry the seat token in a header. A redirect is
-        // allowed to point at another origin, and whether undici strips an
-        // Authorization header when it follows one is not something a seat may
-        // rely on — so no redirect is followed at all.
-        redirect: 'error',
-      }), expired]);
-      const text = await res.text();
-      const header = res.headers?.get?.('mcp-session-id');
-      if (header && !sessionId) sessionId = header;
-      return { res, text, contentType: res.headers?.get?.('content-type') || '' };
-    } catch (error) {
-      if (error?.message?.startsWith(`${name}:`)) throw error;
-      throw new Error(`${name}: ${error?.name === 'AbortError' ? `timed out after ${timeoutMs}ms` : `${payload?.method || 'request'} failed: ${error?.message || error}`}`);
-    } finally {
-      clearTimeout(timer);
-    }
-  };
-  const request = async (method, params) => {
-    const id = nextId++;
-    const { res, text, contentType } = await post({ jsonrpc: '2.0', id, method, params: params || {} });
-    if (!res.ok) throw new Error(`${name}: ${method} failed with HTTP ${res.status}${text ? `: ${truncate(text)}` : ''}`);
-    const messages = parseMessages(text, contentType)
-      .map((raw) => { try { return JSON.parse(raw); } catch { return null; } })
-      .filter(Boolean);
-    const answer = messages.find((m) => m.id === id);
-    if (!answer) throw new Error(`${name}: ${method} returned no JSON-RPC answer (HTTP ${res.status})`);
-    if (answer.error) throw new Error(`${name}: ${answer.error.message || JSON.stringify(answer.error)}`);
-    return answer.result;
-  };
-  const notify = async (method, params) => {
-    const { res, text } = await post({ jsonrpc: '2.0', method, params: params || {} });
-    // The spec answers a notification with 202 and no body; anything else is
-    // an error the seat should see rather than a silent drop.
-    if (!res.ok) throw new Error(`${name}: ${method} failed with HTTP ${res.status}${text ? `: ${truncate(text)}` : ''}`);
-  };
-  const initialize = async () => {
-    const result = await request('initialize', {
-      protocolVersion: PROTOCOL_VERSION,
-      capabilities: {},
-      clientInfo: { name: 'commonly-pi-bridge', version: '1.0.0' },
-    });
-    // The server's answer is authoritative; echo what it negotiated from here on.
-    if (result && typeof result.protocolVersion === 'string') protocolVersion = result.protocolVersion;
-    negotiated = true;
-    await notify('notifications/initialized');
-    return result;
-  };
-  const listTools = async () => (await request('tools/list')).tools || [];
-  const callTool = (toolName, args) => request('tools/call', { name: toolName, arguments: args || {} });
-  const close = () => {
-    if (!sessionId) return;
-    try {
-      const pending = fetchImpl(url, { method: 'DELETE', headers: requestHeaders(), redirect: 'error' });
-      if (pending && typeof pending.catch === 'function') pending.catch(() => {});
-    } catch { /* best effort: the session expires on its own */ }
-  };
-  return { initialize, listTools, callTool, close, sessionId: () => sessionId };
-};
-
-/** MCP `{ content, isError }` → pi tool result. Non-text parts are named, not dropped silently. */
-export const toPiResult = (result) => {
-  const parts = (result?.content || []).map((c) => (c?.type === 'text' ? String(c.text ?? '') : `[${c?.type || 'content'} omitted]`));
-  const text = truncate(parts.join('\n'));
-  return { content: [{ type: 'text', text: result?.isError ? `error: ${text}` : text }], details: { isError: !!result?.isError } };
-};
-
-/**
- * Read the server list off the inherited pipe on `fd` and CONSUME it.
- *
- * The list carries every server's substituted secrets — a stdio server's env and
- * an HTTP server's `Authorization` header, the seat's bearer token among them —
- * and pi's `bash` tool spawns with `{ ...process.env }` (pi's getShellEnv), so it
- * has to arrive by a channel pi's children do not inherit and must not outlive
- * the read. It arrives here as fd 3: a pipe the adapter writes the JSON into and
- * ends at spawn (pi.js runPi). This reads it to EOF and closes the descriptor.
- *
- * WHY NOT THE ENVIRONMENT, which is what this replaced: deleting the variable
- * scrubbed Node's copy only, while the kernel keeps the environment this process
- * was STARTED with, so a same-user child still read the token back with
- * `ps eww $PPID` on macOS and `/proc/$PPID/environ` on Linux. Unsetting it at
- * spawn cannot help either, because this runs inside the pi process that holds
- * it. WHY NOT a 0600 file the bridge unlinks on load: the mode protects nothing
- * against a same-user reader, and that shape needs both the unlink and a close
- * to leave no window, since `/proc/<pid>/fd` on Linux still reaches an unlinked
- * inode. A pipe has neither a path nor a stored copy.
- *
- * THE READ IS WHAT REMOVES THE SECRET, not the close: a pipe is consumed, so a
- * second reader gets nothing. Measured against pi 0.84.1 — after a read to EOF
- * a second read of the same descriptor returned zero bytes, while a 5-byte
- * partial read left the remainder readable. Closing afterwards is hygiene.
- *
- * Two further measurements this rests on, both against pi 0.84.1: pi does not
- * close inherited descriptors before loading extensions, so fd 3 is still open
- * here (this runs at extension load, before the first model turn — and before
- * any bash tool can run); and pi's own spawns (`dist/core/tools/bash.js`,
- * `dist/core/exec.js`) pass a THREE-element stdio list, so a shell tool child
- * does not inherit fd 3 at all.
- *
- * An unreadable descriptor yields no servers rather than throwing: a seat whose
- * bridge cannot read its list should run without Commonly tools, not fail to
- * start. The bridge logs that empty result (pi-commonly-mcp.mjs).
- *
- * The descriptor is closed only after a successful read, and that is not
- * tidiness: on macOS, `closeSync` on the descriptor Node opens for an `'ignore'`
- * stdio entry aborts the process — measured 2026-09-19, Node 20 — with
- * `Assertion failed: (errno == EINTR), function uv__io_poll, file kqueue.c`,
- * where the read itself had already failed harmlessly with `ENXIO`. A close in
- * `finally` therefore turns "no channel" into a SIGABRT in the seat.
- */
-export const takeServers = (fd = 3) => {
-  let raw = null;
-  try {
-    raw = readFileSync(fd, 'utf8');
-  } catch {
-    // Nothing to close: the read failed, so this was not a descriptor we consumed.
-    return [];
-  }
-  try { closeSync(fd); } catch { /* already closed */ }
-  return readServers(raw);
-};
-
-/**
- * Entries with a non-empty `command` and no `url` are stdio; entries with a
- * non-empty `url` and no `command` are Streamable HTTP. The two are mutually
- * exclusive on purpose: `resolveMcpServers` emits exactly one field per entry
- * (the transport decides which), so an entry carrying BOTH did not come from it
- * and is dropped rather than spawned — the adapter is the layer that executes,
- * and a shape it cannot classify is not one it should run. Both the adapter
- * (pi.js resolveMcpServers) and this filter have to agree, or a server reaches
- * the bridge as an unstartable entry.
- */
-export const isStdioServer = (s) => Array.isArray(s?.command) && s.command.length > 0
-  && !(typeof s?.url === 'string' && s.url.length > 0);
-export const isHttpServer = (s) => typeof s?.url === 'string' && s.url.length > 0
-  && !(Array.isArray(s?.command) && s.command.length > 0);
-
-/**
- * The tools the bridge may register for one server: all of them, minus the
- * entry's `withheldTools`. pi.js sets that list per turn on a public seat
- * (publicSeatWithheldTools), so a withheld Commonly tool is never registered with
- * pi at all; pi's own `--exclude-tools` removes the same names as a second
- * layer.
- */
-/**
- * Delete this spawn's credential directory from inside pi, before the session
- * exists (F175c). The factory that calls this is awaited before pi creates the
- * session, so the delete precedes every prompt by construction, which the
- * parent's delete at pi's first JSON line cannot promise: that one runs on the
- * parent's event loop, and a locally declared stdio server on a public seat
- * could read the file for a prompt in the gap.
- *
- * The directory comes on the fd 3 list, on the broker entry, because the list is
- * written by the adapter alone and consumed by the read. It is honoured only on
- * a confined broker entry, and it is not an environment variable: a private pi
- * turn passes the launcher's environment through, and an ambient value must
- * never be able to name a directory to delete.
- *
- * pi logs a factory that throws and carries on without it, so a throw here would
- * reach the prompt with the file on disk. A failed delete stops the process
- * instead, and the adapter reports the line below as the turn's error.
- */
-export const removeSpawnCredential = (servers, {
-  rm = rmSync,
-  exit = process.exit,
-  write = (line) => process.stderr.write(line),
-} = {}) => {
-  const dirs = new Set((Array.isArray(servers) ? servers : [])
-    .filter((s) => s?.confined === true && isHttpServer(s) && isGrantBrokerUrl(s.url)
-      && s.credentialDir !== undefined)
-    .map((s) => s.credentialDir));
-  for (const dir of dirs) {
-    try {
-      if (typeof dir !== 'string' || !isAbsolute(dir)) throw new Error('the path is not absolute');
-      rm(dir, { recursive: true, force: true });
-    } catch (error) {
-      write(`[commonly-pi-bridge] could not delete this turn's connector credential (${dir}): `
-        + `${error?.message || error}; stopping before any prompt runs\n`);
-      exit(1);
-      return false;
-    }
-  }
-  return true;
-};
-
-export const registrableTools = (tools, server) => {
-  const withheld = new Set(Array.isArray(server?.withheldTools) ? server.withheldTools : []);
-  return withheld.size ? tools.filter((tool) => !withheld.has(tool?.name)) : tools;
-};
-
-export const readServers = (raw) => {
-  if (!raw) return [];
-  try {
-    // A broker entry is kept only with the adapter's `confined: true` mark,
-    // which pi.js sets on a public turn alone (the same reason string, see
-    // GRANT_BROKER_PUBLIC_ONLY_REFUSAL): this is the last layer before a client
-    // is started, and the two filters have to agree or a server reaches the
-    // bridge as an entry the adapter would not have carried.
-    return JSON.parse(raw).filter((s) => s?.name
-      && (isStdioServer(s) || (isHttpServer(s) && (!isGrantBrokerUrl(s.url) || s.confined === true))));
-  } catch { return []; }
-};

package/src/lib/adapters/pi-shell-env.mjs

@@ -1,41 +0,0 @@
-/**
- * Keep the provider key available to pi's per-call auth resolver, but out of
- * shells started by its model bash tool and by manual ! / !! commands.
- * This limits environment inheritance; pi itself is not an OS sandbox.
- */
-import { createBashTool, createLocalBashOperations } from '@earendil-works/pi-coding-agent';
-
-export default function commonlyShellEnvironment(pi) {
-  const providerKey = process.env.COMMONLY_PI_PROVIDER_KEY_ENV;
-  if (!providerKey) throw new Error('pi adapter: missing provider key environment name');
-  const excluded = new Set([
-    providerKey, 'COMMONLY_LITELLM_KEY', 'COMMONLY_PI_PROVIDER_KEY', 'COMMONLY_PI_PROVIDER_KEY_ENV',
-  ].map((key) => key.toUpperCase()));
-  const cleanEnv = (env) => {
-    const clean = { ...env };
-    // Windows environment lookup ignores case; spreading it loses that behavior.
-    for (const key of Object.keys(clean)) {
-      if (excluded.has(key.toUpperCase())) delete clean[key];
-    }
-    return clean;
-  };
-  const spawnHook = (context) => ({ ...context, env: cleanEnv(context.env) });
-  const bash = createBashTool(process.cwd(), { spawnHook });
-  pi.registerTool({
-    ...bash,
-    execute(id, params, signal, onUpdate, ctx) {
-      return createBashTool(ctx.cwd, { spawnHook }).execute(id, params, signal, onUpdate, ctx);
-    },
-  });
-  const local = createLocalBashOperations();
-  pi.on('user_bash', () => ({
-    operations: {
-      exec(command, cwd, options) {
-        return local.exec(command, cwd, {
-          ...options,
-          env: cleanEnv(options.env ?? process.env),
-        });
-      },
-    },
-  }));
-}