@crossgen-ai/praxis-connectors 0.1.2

package/README.md

@@ -0,0 +1,11 @@
+# @crossgen-ai/praxis-connectors
+
+An MCP connector engine for the Praxis platform.
+
+This is an internal package published for use by CrossGen-AI's own
+applications. It is not intended for general use, and its API may change
+without notice.
+
+## License
+
+MIT

package/extension/index.js

@@ -0,0 +1,99 @@
+// The pi extension face: registers every
+// cached connector tool as mcp__<connector>__<tool>. Loadable two ways —
+//   · a harness session lists it via settings.json extensions[] (through a
+//     shim that keeps the worker gate), and
+//   · a scheduled run gets it via an explicit `pi -e <this file>`.
+// Tool lists come from the store's cache, so a cold connector never blocks
+// the spawn; connections open lazily on first call.
+//
+// Scoping: PRAXIS_CONNECTORS_ONLY (comma-separated ids) narrows a run to
+// its task's connector list — the driver sets it per spawn.
+'use strict';
+
+const { ConnectorsEngine } = require('../lib/engine');
+
+// The name mint mirrors the harness bridge's so the content-guard
+// mcp__ scanning lattice applies to connector tools unchanged.
+function toolName(connectorId, tool) {
+  const clean = (s) => String(s).replace(/[^A-Za-z0-9_-]/g, '_');
+  return `mcp__${clean(connectorId)}__${clean(tool)}`;
+}
+
+// Content-guard's registration-time channels listen
+// on this event; emitting it costs nothing under bare pi. The literal string
+// is the public contract — importing harness code here would break the seam.
+const MCP_TOOL_DISCOVERED_EVENT = 'praxis.mcp.tool.discovered';
+
+function scopedIds() {
+  const only = String(process.env.PRAXIS_CONNECTORS_ONLY || '').trim();
+  if (!only) return null;
+  return new Set(only.split(',').map((s) => s.trim()).filter(Boolean));
+}
+
+// Under pi, typebox is aliased to the running agent's copy and Type.Unsafe
+// is the sanctioned wrapper for raw JSON schema (the bridge does the same).
+// Under plain node (this package's tests), typebox may be absent — the raw
+// schema object is the same shape minus TypeBox's kind marker.
+let wrapSchema = (schema) => schema;
+try {
+  // eslint-disable-next-line global-require
+  const { Type } = require('typebox');
+  wrapSchema = (schema) => Type.Unsafe(schema);
+} catch { /* raw JSON schema */ }
+
+function connectorsExtension(pi) {
+  const engine = new ConnectorsEngine({
+    onLog: (line) => process.stderr.write(`[connectors] ${line}\n`),
+  });
+  const scope = scopedIds();
+  let registered = 0;
+
+  for (const entry of engine.list()) {
+    if (scope && !scope.has(entry.id)) continue;
+    for (const tool of engine.cachedTools(entry.id)) {
+      const name = toolName(entry.id, tool.name);
+      const inputSchema = tool.inputSchema || { type: 'object' };
+      pi.events?.emit?.(MCP_TOOL_DISCOVERED_EVENT, {
+        plugin: 'connectors',
+        server: entry.id,
+        tool: tool.name,
+        registeredName: name,
+        description: tool.description,
+        inputSchema,
+      });
+      try {
+        pi.registerTool({
+          name,
+          label: `${entry.name}: ${tool.name}`,
+          description: tool.description || `${tool.name} on the ${entry.name} connector`,
+          parameters: wrapSchema({ ...inputSchema, type: 'object' }),
+          execute: async (_toolCallId, params) => {
+            const result = await engine.callTool(entry.id, tool.name, params ?? {});
+            return {
+              content: [{ type: 'text', text: result.text }],
+              details: {},
+              isError: result.isError,
+            };
+          },
+        });
+        registered += 1;
+      } catch (err) {
+        process.stderr.write(`[connectors] could not register ${name}: ${String(err?.message || err)}\n`);
+      }
+    }
+  }
+
+  if (registered > 0) {
+    process.stderr.write(`[connectors] ${registered} connector tool${registered === 1 ? '' : 's'} available\n`);
+  }
+
+  pi.on?.('session_shutdown', async () => {
+    await engine.close();
+  });
+}
+
+module.exports = connectorsExtension;
+// The mint is exported so the harness gate can pin it against the plugins
+// bridge's (they must agree for content-guard's mcp__ lattice to be one).
+module.exports.toolName = toolName;
+module.exports.MCP_TOOL_DISCOVERED_EVENT = MCP_TOOL_DISCOVERED_EVENT;

package/lib/catalog.js

@@ -0,0 +1,68 @@
+// The shipped starter catalog: the
+// Google family rides Google's official Workspace remote MCP endpoints
+// (OAuth 2.0 — Google issues no dynamic client registration, so sign-in
+// needs the user's own OAuth client, entered once per box); the Microsoft
+// family rides the ms-365 stdio server ON the box (no official Microsoft
+// remote MCP exists as of 2026-08), which owns its own Microsoft login.
+// Two OAuth families by design — v1 proves the relay against both shapes.
+'use strict';
+
+const CATALOG = [
+  {
+    key: 'gmail',
+    name: 'Gmail',
+    transport: 'http',
+    url: 'https://gmailmcp.googleapis.com/mcp/v1',
+    family: 'google',
+    authNote: 'Google OAuth — needs your own OAuth client (Google Cloud console); no dynamic registration.',
+  },
+  {
+    key: 'google_calendar',
+    name: 'Google Calendar',
+    transport: 'http',
+    url: 'https://calendarmcp.googleapis.com/mcp/v1',
+    family: 'google',
+    authNote: 'Google OAuth — needs your own OAuth client (Google Cloud console); no dynamic registration.',
+  },
+  {
+    key: 'google_drive',
+    name: 'Google Drive',
+    transport: 'http',
+    url: 'https://drivemcp.googleapis.com/mcp/v1',
+    family: 'google',
+    authNote: 'Google OAuth — needs your own OAuth client (Google Cloud console); no dynamic registration.',
+  },
+  {
+    key: 'outlook_mail',
+    name: 'Outlook Mail',
+    transport: 'stdio',
+    command: 'npx',
+    args: ['-y', '@softeria/ms-365-mcp-server', '--enabled-tools', 'mail'],
+    family: 'microsoft',
+    authNote: 'Runs on the box; signs in to Microsoft with its own login tool on first use.',
+  },
+  {
+    key: 'microsoft_calendar',
+    name: 'Microsoft Calendar',
+    transport: 'stdio',
+    command: 'npx',
+    args: ['-y', '@softeria/ms-365-mcp-server', '--enabled-tools', 'calendar'],
+    family: 'microsoft',
+    authNote: 'Runs on the box; signs in to Microsoft with its own login tool on first use.',
+  },
+  {
+    key: 'onedrive',
+    name: 'OneDrive',
+    transport: 'stdio',
+    command: 'npx',
+    args: ['-y', '@softeria/ms-365-mcp-server', '--enabled-tools', 'files'],
+    family: 'microsoft',
+    authNote: 'Runs on the box; signs in to Microsoft with its own login tool on first use.',
+  },
+];
+
+function catalogEntry(key) {
+  return CATALOG.find((c) => c.key === key) || null;
+}
+
+module.exports = { CATALOG, catalogEntry };

package/lib/engine.js

@@ -0,0 +1,386 @@
+// The connectors engine: everything both faces
+// share — connect over stdio or streamable HTTP via the official MCP SDK
+// (automatic version negotiation buys both protocol eras), OAuth through the
+// store-backed provider, cached tool lists so a cold connector never blocks
+// anything, and polite declines for mid-run elicitation.
+'use strict';
+
+const {
+  Client, StreamableHTTPClientTransport, UnauthorizedError, auth,
+} = require('@modelcontextprotocol/client');
+const { StdioClientTransport } = require('@modelcontextprotocol/client/stdio');
+const { ConnectorsStore } = require('./store');
+const { StoreOAuthProvider } = require('./oauth');
+const { CATALOG, catalogEntry } = require('./catalog');
+
+const CLIENT_INFO = { name: 'praxis-connectors', version: '0.1.0' };
+const CONNECT_TIMEOUT_MS = 20_000;
+const CALL_TIMEOUT_MS = 60_000;
+// Refresh ahead of expiry by this much (the host's proactive refresh loop).
+const REFRESH_WINDOW_MS = 10 * 60_000;
+
+// Secrets never ride env into spawned connector servers, so every face
+// spawns identically.
+const SECRET_ENV_PATTERN = /KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL/i;
+
+function filteredEnv(source = process.env) {
+  const env = {};
+  for (const [name, value] of Object.entries(source)) {
+    if (value === undefined) continue;
+    if (SECRET_ENV_PATTERN.test(name)) continue;
+    env[name] = value;
+  }
+  return env;
+}
+
+function withTimeout(promise, ms, what) {
+  let timer;
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new Error(`${what} timed out after ${Math.round(ms / 1000)}s`)), ms);
+      timer.unref?.();
+    }),
+  ]).finally(() => clearTimeout(timer));
+}
+
+/** Plain-language classification for the UI's three states. */
+function classifyError(err) {
+  if (err instanceof UnauthorizedError || err?.name === 'UnauthorizedError') {
+    return { status: 'needs-signin', detail: 'this connector needs a sign-in' };
+  }
+  return { status: 'unreachable', detail: String(err?.message || err) };
+}
+
+function contentToText(content) {
+  return (content || [])
+    .map((c) => {
+      if (c.type === 'text') return c.text;
+      if (c.type === 'image') return '[image content]';
+      if (c.type === 'resource_link') return `[resource: ${c.uri}]`;
+      return `[${c.type} content]`;
+    })
+    .filter(Boolean)
+    .join('\n');
+}
+
+class ConnectorsEngine {
+  /**
+   * @param {object} [opts]
+   * @param {string} [opts.home]     store root (default $PRAXIS_CONNECTORS_HOME)
+   * @param {(line: string) => void} [opts.onLog]
+   * @param {typeof fetch} [opts.fetchFn]  test seam for OAuth traffic
+   * @param {number} [opts.connectTimeoutMs]
+   */
+  constructor({ home, onLog, fetchFn, connectTimeoutMs } = {}) {
+    this.store = new ConnectorsStore(home);
+    this.onLog = onLog || (() => {});
+    this.fetchFn = fetchFn;
+    this.connectTimeoutMs = connectTimeoutMs ?? CONNECT_TIMEOUT_MS;
+    this._live = new Map(); // id → { client, transport }
+  }
+
+  /* ---------------- registry ---------------- */
+
+  catalog() {
+    return CATALOG;
+  }
+
+  /**
+   * Disk-only listing (never connects): registry + cached tools + last
+   * known status. Status is 'unknown' until something has probed.
+   */
+  list() {
+    return this.store.list().map((entry) => {
+      const cache = this.store.readCache(entry.id);
+      const authState = this.store.readAuth(entry.id);
+      return {
+        ...entry,
+        status: cache?.status || 'unknown',
+        statusDetail: cache?.statusDetail || null,
+        toolCount: cache?.tools?.length ?? 0,
+        listedAt: cache?.listedAt || null,
+        signedIn: Boolean(authState.tokens),
+        pendingAuthUrl: authState.pendingAuth?.url || null,
+      };
+    });
+  }
+
+  /**
+   * Add a connector: either from the shipped catalog ({ catalogKey }) or
+   * free-form ({ id, name, transport, command/args | url }).
+   */
+  add(spec = {}) {
+    let entry = spec;
+    if (spec.catalogKey) {
+      const cat = catalogEntry(spec.catalogKey);
+      if (!cat) throw new Error(`no catalog entry named ${JSON.stringify(spec.catalogKey)}`);
+      entry = {
+        id: spec.id || cat.key,
+        name: spec.name || cat.name,
+        transport: cat.transport,
+        command: cat.command,
+        args: cat.args,
+        url: cat.url,
+        catalog: cat.key,
+        addedBy: spec.addedBy,
+      };
+    }
+    const added = this.store.upsert(entry);
+    this.onLog(`connector ${added.id} added (${added.transport})`);
+    return added;
+  }
+
+  remove(id) {
+    this._dropLive(id);
+    const removed = this.store.remove(id);
+    if (removed) this.onLog(`connector ${id} removed`);
+    return removed;
+  }
+
+  /* ---------------- connections ---------------- */
+
+  _requireEntry(id) {
+    const entry = this.store.get(id);
+    if (!entry) throw new Error(`no connector named ${JSON.stringify(id)}`);
+    return entry;
+  }
+
+  _makeTransport(entry) {
+    if (entry.transport === 'stdio') {
+      return new StdioClientTransport({
+        command: entry.command,
+        args: entry.args || [],
+        env: filteredEnv(),
+        stderr: 'ignore',
+      });
+    }
+    // Plain bearer reads only: a probe or tool call must never launch an
+    // OAuth flow of its own (a scheduled run has no human). Missing or
+    // stale tokens surface as UnauthorizedError → 'needs-signin'; the
+    // interactive flow lives in authStart/authFinish, and refresh in
+    // refreshDueTokens — all through the full store-backed provider.
+    return new StreamableHTTPClientTransport(new URL(entry.url), {
+      authProvider: {
+        token: async () => this.store.readAuth(entry.id).tokens?.access_token,
+      },
+      ...(this.fetchFn ? { fetch: this.fetchFn } : {}),
+    });
+  }
+
+  _makeClient(entry) {
+    const client = new Client(CLIENT_INFO, {
+      capabilities: { elicitation: {} },
+      versionNegotiation: { mode: 'auto' },
+    });
+    // A headless run answers elicitation with a well-formed
+    // decline and a log line; relaying to the app is a follow-up.
+    client.setRequestHandler('elicitation/create', async () => {
+      this.onLog(`connector ${entry.id}: declined an input request (no one is watching this run)`);
+      return { action: 'decline' };
+    });
+    return client;
+  }
+
+  async _connect(id) {
+    const live = this._live.get(id);
+    if (live) return live;
+    const entry = this._requireEntry(id);
+    const transport = this._makeTransport(entry);
+    const client = this._makeClient(entry);
+    try {
+      await withTimeout(client.connect(transport), this.connectTimeoutMs, `connecting to ${id}`);
+    } catch (err) {
+      try { await transport.close?.(); } catch { /* already down */ }
+      throw err;
+    }
+    const opened = { client, transport };
+    this._live.set(id, opened);
+    return opened;
+  }
+
+  _dropLive(id) {
+    const live = this._live.get(id);
+    if (!live) return;
+    this._live.delete(id);
+    Promise.resolve(live.client.close?.() ?? live.transport.close?.()).catch(() => {});
+  }
+
+  async close() {
+    for (const id of [...this._live.keys()]) this._dropLive(id);
+  }
+
+  /* ---------------- tools ---------------- */
+
+  /**
+   * Connect, list tools, refresh the cache and status. The one operation
+   * that talks to the server on purpose.
+   */
+  async probe(id) {
+    this._dropLive(id); // a probe is always a fresh look
+    try {
+      const { client } = await this._connect(id);
+      const { tools } = await withTimeout(client.listTools(), this.connectTimeoutMs, `listing tools on ${id}`);
+      const slim = (tools || []).map((t) => ({
+        name: t.name,
+        description: t.description || '',
+        inputSchema: t.inputSchema || { type: 'object' },
+      }));
+      this.store.writeCache(id, { tools: slim, status: 'connected' });
+      return { status: 'connected', tools: slim };
+    } catch (err) {
+      const { status, detail } = classifyError(err);
+      this.store.writeStatus(id, status, detail);
+      return { status, detail, tools: this.store.readCache(id)?.tools || [] };
+    }
+  }
+
+  /** Cached tools only — never connects. */
+  cachedTools(id) {
+    return this.store.readCache(id)?.tools || [];
+  }
+
+  async callTool(id, toolName, args = {}, { timeoutMs = CALL_TIMEOUT_MS } = {}) {
+    try {
+      const { client } = await this._connect(id);
+      const result = await client.callTool(
+        { name: toolName, arguments: args },
+        { timeout: timeoutMs },
+      );
+      return {
+        text: contentToText(result.content) || '(no output)',
+        isError: Boolean(result.isError),
+      };
+    } catch (err) {
+      // A dead child/socket poisons the pooled connection — drop it so the
+      // next call reconnects instead of failing forever.
+      this._dropLive(id);
+      const { status, detail } = classifyError(err);
+      this.store.writeStatus(id, status, detail);
+      const reason = status === 'needs-signin'
+        ? `connector ${id} needs a sign-in before its tools can run`
+        : `connector ${id} is unreachable: ${detail}`;
+      return { text: reason, isError: true };
+    }
+  }
+
+  /* ---------------- sign-in (the relay) ---------------- */
+
+  /**
+   * Start the OAuth flow box-side. Returns { authorizationUrl } for the app
+   * to hand to a human, or { authorized: true } when a refresh (or an AS
+   * with no interactive step) finished without one.
+   */
+  async authStart(id, { redirectUrl, scope } = {}) {
+    const entry = this._requireEntry(id);
+    if (entry.transport !== 'http') {
+      throw new Error(`connector ${id} runs on this machine and manages its own sign-in — no relay needed`);
+    }
+    const provider = new StoreOAuthProvider(this.store, id, { redirectUrl });
+    const result = await auth(provider, {
+      serverUrl: entry.url,
+      ...(scope ? { scope } : {}),
+      ...(this.fetchFn ? { fetchFn: this.fetchFn } : {}),
+    });
+    if (result === 'REDIRECT') {
+      return { authorizationUrl: provider.capturedAuthorizationUrl };
+    }
+    await this.probe(id);
+    return { authorized: true };
+  }
+
+  /**
+   * Finish the flow with the code — however it arrived (serve's callback
+   * route or the paste-back field). Tokens are exchanged and stored
+   * box-side; on success the tool cache warms.
+   */
+  async authFinish(id, { code, iss } = {}) {
+    const entry = this._requireEntry(id);
+    if (!code || !String(code).trim()) throw new Error('an authorization code is required');
+    const provider = new StoreOAuthProvider(this.store, id);
+    const result = await auth(provider, {
+      serverUrl: entry.url,
+      authorizationCode: String(code).trim(),
+      ...(iss ? { iss } : {}),
+      ...(this.fetchFn ? { fetchFn: this.fetchFn } : {}),
+    });
+    if (result !== 'AUTHORIZED') {
+      throw new Error('the sign-in did not complete — try starting it again');
+    }
+    this.onLog(`connector ${id}: signed in`);
+    return this.probe(id);
+  }
+
+  /** The callback route's router: which connector does this state belong to? */
+  findPendingByState(state) {
+    if (!state) return null;
+    for (const entry of this.store.list()) {
+      const pending = this.store.readAuth(entry.id).pendingAuth;
+      if (pending?.state && pending.state === state) return entry.id;
+    }
+    return null;
+  }
+
+  /**
+   * Pre-seed OAuth client credentials for authorization servers that issue
+   * no dynamic registration (the Google family): the user pastes their own
+   * client id/secret once per box; it lands in auth/<id>.json like every
+   * other credential.
+   */
+  setClientCredentials(id, { clientId, clientSecret } = {}) {
+    this._requireEntry(id);
+    if (!clientId) throw new Error('a client id is required');
+    this.store.patchAuth(id, {
+      clientInfo: {
+        client_id: String(clientId),
+        ...(clientSecret ? { client_secret: String(clientSecret) } : {}),
+      },
+    });
+  }
+
+  /* ---------------- proactive refresh ---------------- */
+
+  /**
+   * Refresh every signed-in http connector whose token expires within the
+   * window. Serve calls this on a timer — it is the long-lived process, so
+   * routes stay warm with the Mac off.
+   */
+  async refreshDueTokens({ windowMs = REFRESH_WINDOW_MS, now = Date.now() } = {}) {
+    const report = [];
+    for (const entry of this.store.list()) {
+      if (entry.transport !== 'http') continue;
+      const authState = this.store.readAuth(entry.id);
+      const { tokens, tokensSavedAt } = authState;
+      if (!tokens?.refresh_token || !tokens.expires_in || !tokensSavedAt) continue;
+      const expiresAt = new Date(tokensSavedAt).getTime() + tokens.expires_in * 1000;
+      if (expiresAt - now > windowMs) continue;
+      try {
+        const provider = new StoreOAuthProvider(this.store, entry.id);
+        const result = await auth(provider, {
+          serverUrl: entry.url,
+          ...(this.fetchFn ? { fetchFn: this.fetchFn } : {}),
+        });
+        if (result === 'AUTHORIZED') {
+          report.push({ id: entry.id, refreshed: true });
+          this.onLog(`connector ${entry.id}: token refreshed ahead of expiry`);
+        } else {
+          // The AS rejected the refresh token and the SDK fell back to a
+          // fresh interactive flow — only a human can finish that.
+          report.push({ id: entry.id, refreshed: false });
+          this.store.writeStatus(entry.id, 'needs-signin', 'the sign-in expired and could not be renewed');
+          this.onLog(`connector ${entry.id}: sign-in expired — needs a fresh sign-in`);
+        }
+      } catch (err) {
+        report.push({ id: entry.id, refreshed: false, error: String(err?.message || err) });
+        this.store.writeStatus(entry.id, 'needs-signin', 'the sign-in expired and could not be renewed');
+        this.onLog(`connector ${entry.id}: token refresh failed (${String(err?.message || err)})`);
+      }
+    }
+    return report;
+  }
+}
+
+module.exports = {
+  ConnectorsEngine, filteredEnv, contentToText, classifyError,
+  SECRET_ENV_PATTERN, REFRESH_WINDOW_MS,
+};

package/lib/index.js

@@ -0,0 +1,24 @@
+// @crossgen-ai/praxis-connectors — the engine face.
+// A host process links this as a library; the harness loads
+// ./extension as a pi extension; both share one box-local store.
+'use strict';
+
+const { ConnectorsEngine, filteredEnv, contentToText, SECRET_ENV_PATTERN, REFRESH_WINDOW_MS } = require('./engine');
+const { ConnectorsStore, resolveHome, validateId, ID_PATTERN } = require('./store');
+const { StoreOAuthProvider } = require('./oauth');
+const { CATALOG, catalogEntry } = require('./catalog');
+
+module.exports = {
+  ConnectorsEngine,
+  ConnectorsStore,
+  StoreOAuthProvider,
+  CATALOG,
+  catalogEntry,
+  resolveHome,
+  validateId,
+  ID_PATTERN,
+  filteredEnv,
+  contentToText,
+  SECRET_ENV_PATTERN,
+  REFRESH_WINDOW_MS,
+};