@tyvm/knowhow 0.0.156 → 0.0.158

package/src/login.ts

@@ -8,6 +8,16 @@ import { KNOWHOW_API_URL } from "./services/KnowhowClient";
 import { BrowserLoginService } from "./auth/browserLogin";
 import { authenticateWithKey, hasKeyPair, registerPublicKey } from "./auth/keyAuth";
 import { getDefaultPrivateKeyPath, getOrCreatePublicKey } from "./auth/keyManager";
+import { storeJwtForApi } from "./auth/jwtStore";
+import { getOrgIdForApi, setOrgIdForApi } from "./auth/environmentAuth";
+import {
+  createRemote,
+  findRemoteForApi,
+  inferRemoteName,
+  registerRemote,
+  resolveJwtPath,
+} from "./remotes";
+import { KnowhowRemote } from "./types";
 
 /**
  * Log in to Knowhow.
@@ -23,37 +33,31 @@ import { getDefaultPrivateKeyPath, getOrCreatePublicKey } from "./auth/keyManage
  * @param jwtFlag      True when --jwt flag is passed.
  * @param identityPath Optional path to a specific private key file (--identity flag).
  */
-export async function login(jwtFlag?: boolean, identityPath?: string): Promise<void> {
-  if (!KNOWHOW_API_URL) {
-    throw new Error("Error: KNOWHOW_API_URL environment variable not set.");
-  }
+export async function login(
+  jwtFlag?: boolean,
+  identityPath?: string,
+  apiUrl: string = KNOWHOW_API_URL,
+  remoteName?: string
+): Promise<void> {
+  const config = await getConfig();
+  const remote = findRemoteForApi(config, apiUrl) ??
+    createRemote(remoteName ?? inferRemoteName(apiUrl), apiUrl);
 
   if (jwtFlag) {
     const jwt = await ask("Enter your JWT: ");
-
-    const configDir = path.join(process.cwd(), ".knowhow");
-    const jwtFile = path.join(configDir, ".jwt");
-
-    if (!fs.existsSync(configDir)) {
-      fs.mkdirSync(configDir, { recursive: true });
-    }
-    fs.writeFileSync(jwtFile, jwt);
-    fs.chmodSync(jwtFile, 0o600);
-    console.log("JWT updated successfully.");
+    const jwtFile = storeJwtForApi(jwt, remote.apiUrl, remote.jwtPath);
+    console.log(`JWT updated successfully in ${path.relative(process.cwd(), jwtFile)}.`);
   } else {
     const selectedIdentityPath = identityPath ?? getDefaultPrivateKeyPath();
-    const config = await getConfig();
-    const orgId = config.orgId;
+    const orgId = getOrgIdForApi(config, remote.apiUrl);
 
-    // A local key is not proof of registration. Let the selected environment
-    // check it, but only when an organization is available to bind the attempt.
     if (orgId && hasKeyPair(selectedIdentityPath)) {
       console.log("Found CLI identity — authenticating with public key...");
       try {
-        const success = await authenticateWithKey(orgId, KNOWHOW_API_URL, selectedIdentityPath);
+        const success = await authenticateWithKey(orgId, remote.apiUrl, selectedIdentityPath);
         if (success) {
           console.log("✅ Successfully authenticated via public key!");
-          return await postLoginConfigUpdate(selectedIdentityPath);
+          return await postLoginConfigUpdate(remote, selectedIdentityPath);
         }
         console.warn("Key authentication returned no JWT, falling back to browser login...");
       } catch (error: unknown) {
@@ -62,30 +66,31 @@ export async function login(jwtFlag?: boolean, identityPath?: string): Promise<v
       }
     }
 
-    // Fall back when no org/key is configured or when key auth is unavailable.
-    await doBrowserLogin(selectedIdentityPath);
+    await doBrowserLogin(remote, selectedIdentityPath, orgId);
     identityPath = selectedIdentityPath;
   }
 
-  await postLoginConfigUpdate(identityPath);
+  await postLoginConfigUpdate(remote, identityPath);
 }
 
 /** Complete browser PKCE, then best-effort bootstrap the selected identity. */
-async function doBrowserLogin(identityPath?: string): Promise<void> {
+async function doBrowserLogin(
+  remote: KnowhowRemote,
+  identityPath?: string,
+  orgId?: string
+): Promise<void> {
   console.log("Starting browser-based authentication...");
   try {
-    const existingConfig = await getConfig();
-    const existingOrgId = existingConfig?.orgId;
-    const browserLoginService = new BrowserLoginService(undefined, existingOrgId);
+    const browserLoginService = new BrowserLoginService(remote.apiUrl, orgId);
     await browserLoginService.login();
     console.log("✅ Successfully authenticated via browser!");
 
     try {
       const keyPair = getOrCreatePublicKey(identityPath);
       await registerPublicKey(
-        await loadJwt(),
+        await loadJwt(remote),
         keyPair.publicKeyBase64,
-        KNOWHOW_API_URL
+        remote.apiUrl
       );
       console.log(`Registered CLI identity ${keyPair.fingerprint}`);
     } catch (registrationError: unknown) {
@@ -114,10 +119,13 @@ function isTemporaryIdentityPath(identityPath: string): boolean {
 }
 
 /** After any successful login, update the local config with the current user/org. */
-async function postLoginConfigUpdate(identityPath?: string): Promise<void> {
+async function postLoginConfigUpdate(
+  remote: KnowhowRemote,
+  identityPath?: string
+): Promise<void> {
   try {
-    const storedJwt = await loadJwt();
-    const { user, currentOrg } = await checkJwt(storedJwt);
+    const storedJwt = await loadJwt(remote);
+    const { user, currentOrg } = await checkJwt(storedJwt, remote.apiUrl);
     const orgId = currentOrg?.organizationId;
 
     console.log(
@@ -137,8 +145,10 @@ async function postLoginConfigUpdate(identityPath?: string): Promise<void> {
       config.modelProviders.push({ provider: "knowhow" });
     }
 
+    registerRemote(config, orgId ? { ...remote, orgId } : remote);
+    config.activeRemote = remote.name;
     if (orgId) {
-      config.orgId = orgId;
+      setOrgIdForApi(config, remote.apiUrl, orgId);
     }
 
     if (identityPath && !isTemporaryIdentityPath(identityPath)) {
@@ -164,23 +174,25 @@ async function postLoginConfigUpdate(identityPath?: string): Promise<void> {
   }
 }
 
-export async function loadJwt(): Promise<string> {
-  const jwtFile = path.join(process.cwd(), ".knowhow", ".jwt");
-  if (!fs.existsSync(jwtFile)) {
-    throw new Error("Error: JWT file not found.");
-  }
-
-  const jwt = fs.readFileSync(jwtFile, "utf-8").trim();
+export async function loadJwt(remote?: KnowhowRemote): Promise<string> {
+  const selectedRemote = remote ??
+    findRemoteForApi(await getConfig(), KNOWHOW_API_URL) ??
+    createRemote(inferRemoteName(KNOWHOW_API_URL), KNOWHOW_API_URL);
+  const jwtFile = resolveJwtPath(selectedRemote.jwtPath);
+  const jwt = fs.existsSync(jwtFile) ? fs.readFileSync(jwtFile, "utf8").trim() : "";
 
   if (!jwt) {
+    if (!fs.existsSync(jwtFile)) {
+      throw new Error(`Error: JWT file not found: ${jwtFile}`);
+    }
     throw new Error("Error: JWT is empty. Re-login with knowhow login --jwt.");
   }
 
   return jwt;
 }
 
-export async function checkJwt(storedJwt: string) {
-  const response = await http.get(`${KNOWHOW_API_URL}/api/users/me`, {
+export async function checkJwt(storedJwt: string, apiUrl: string = KNOWHOW_API_URL) {
+  const response = await http.get(`${apiUrl}/api/users/me`, {
     headers: {
       Authorization: `Bearer ${storedJwt}`,
     },

package/src/remotes.ts

@@ -0,0 +1,110 @@
+import fs from "fs";
+import path from "path";
+import { Config, KnowhowRemote } from "./types";
+
+export const DEFAULT_REMOTE_NAME = "origin";
+export const DEFAULT_API_URL = "https://api.knowhow.tyvm.ai";
+
+export function normalizeApiUrl(apiUrl: string): string {
+  const trimmed = apiUrl.trim().replace(/\/+$/, "");
+  const url = new URL(trimmed);
+  if (!/^https?:$/.test(url.protocol)) {
+    throw new Error(`Remote URL must use http or https: ${apiUrl}`);
+  }
+  return url.toString().replace(/\/$/, "");
+}
+
+export function defaultJwtPath(apiUrl: string): string {
+  const normalized = normalizeApiUrl(apiUrl);
+  if (normalized === DEFAULT_API_URL) return ".knowhow/.jwt";
+  const { hostname, port } = new URL(normalized);
+  let suffix: string;
+  if (hostname === "localhost" || hostname === "::1" || hostname.startsWith("127.")) {
+    suffix = "local";
+  } else if (hostname === "api.dev.knowhow.tyvm.ai" || hostname.includes(".dev.")) {
+    suffix = "dev";
+  } else {
+    suffix = `${hostname}${port ? `-${port}` : ""}`
+      .toLowerCase()
+      .replace(/[^a-z0-9.-]+/g, "-")
+      .replace(/^-+|-+$/g, "");
+  }
+  return `.knowhow/.jwt.${suffix}`;
+}
+
+export function createRemote(name: string, apiUrl: string): KnowhowRemote {
+  if (!/^[a-zA-Z0-9._-]+$/.test(name)) {
+    throw new Error("Remote names may only contain letters, numbers, '.', '_' and '-'.");
+  }
+  const normalizedUrl = normalizeApiUrl(apiUrl);
+  return { name, apiUrl: normalizedUrl, jwtPath: defaultJwtPath(normalizedUrl) };
+}
+
+export function getConfiguredRemotes(config: Config): Record<string, KnowhowRemote> {
+  return config.remotes ?? {};
+}
+
+export function findRemoteForApi(config: Config, apiUrl: string): KnowhowRemote | undefined {
+  const normalizedUrl = normalizeApiUrl(apiUrl);
+  return Object.values(getConfiguredRemotes(config)).find(
+    (remote) => normalizeApiUrl(remote.apiUrl) === normalizedUrl
+  );
+}
+
+export function findRemoteForApiSync(apiUrl: string): KnowhowRemote | undefined {
+  try {
+    const config = JSON.parse(
+      fs.readFileSync(path.join(process.cwd(), ".knowhow", "knowhow.json"), "utf8")
+    ) as Config;
+    return findRemoteForApi(config, apiUrl);
+  } catch {
+    return undefined;
+  }
+}
+
+export function getActiveRemote(config: Config): KnowhowRemote {
+  const envUrl = process.env.KNOWHOW_API_URL;
+  if (envUrl) {
+    return findRemoteForApi(config, envUrl) ?? createRemote(inferRemoteName(envUrl), envUrl);
+  }
+  const name = config.activeRemote ?? DEFAULT_REMOTE_NAME;
+  return config.remotes?.[name] ?? createRemote(DEFAULT_REMOTE_NAME, DEFAULT_API_URL);
+}
+
+export function getActiveRemoteSync(): KnowhowRemote {
+  try {
+    const config = JSON.parse(
+      fs.readFileSync(path.join(process.cwd(), ".knowhow", "knowhow.json"), "utf8")
+    ) as Config;
+    return getActiveRemote(config);
+  } catch {
+    const apiUrl = process.env.KNOWHOW_API_URL ?? DEFAULT_API_URL;
+    return createRemote(inferRemoteName(apiUrl), apiUrl);
+  }
+}
+
+export function registerRemote(config: Config, remote: KnowhowRemote): void {
+  const migratedRemotes: Record<string, KnowhowRemote> = {};
+  for (const [apiUrl, orgId] of Object.entries(config.orgIds ?? {})) {
+    const name = inferRemoteName(apiUrl);
+    migratedRemotes[name] = {
+      ...createRemote(name, apiUrl),
+      orgId,
+    };
+  }
+  config.remotes = { ...migratedRemotes, ...(config.remotes ?? {}), [remote.name]: remote };
+  delete config.orgIds;
+}
+
+export function inferRemoteName(apiUrl: string): string {
+  const normalized = normalizeApiUrl(apiUrl);
+  if (normalized === DEFAULT_API_URL) return DEFAULT_REMOTE_NAME;
+  const { hostname } = new URL(normalized);
+  if (hostname === "localhost" || hostname === "::1" || hostname.startsWith("127.")) return "local";
+  if (hostname === "api.dev.knowhow.tyvm.ai" || hostname.includes(".dev.")) return "dev";
+  return hostname.toLowerCase().replace(/[^a-z0-9.-]+/g, "-");
+}
+
+export function resolveJwtPath(jwtPath: string): string {
+  return path.resolve(process.cwd(), jwtPath);
+}

package/src/services/KnowhowClient.ts

@@ -5,8 +5,10 @@ import fs from "fs";
 import { getConfigSync } from "../config";
 import { exchangeAvailablePublicKeyJwt, storeJwt } from "../auth/keyAuth";
 import { keyPairExists } from "../auth/keyManager";
+import { getOrgIdForApi } from "../auth/environmentAuth";
+import { loadJwtFromDisk } from "../auth/jwtStore";
+import { getActiveRemoteSync } from "../remotes";
 import { Message } from "../clients/types";
-import path from "path";
 import {
   CompletionOptions,
   CompletionResponse,
@@ -125,7 +127,7 @@ export interface GitCredentialResponse {
   expiresAt: string | null;
 }
 
-export function loadKnowhowJwt(): string {
+export function loadKnowhowJwt(apiUrl: string = KNOWHOW_API_URL): string {
   // Check env var first — this is how cloud workers/CI runners get auth
   // (injected via KNOWHOW_JWT env var in the runner's .env file by GithubRunnerService).
   // This avoids depending on a potentially stale .knowhow/.jwt file from the snapshot.
@@ -133,17 +135,10 @@ export function loadKnowhowJwt(): string {
     return process.env.KNOWHOW_JWT;
   }
 
-  const jwtFile = path.join(process.cwd(), ".knowhow", ".jwt");
-  if (!fs.existsSync(jwtFile)) {
-    return "";
-  }
-  const jwt = fs.readFileSync(jwtFile, "utf-8").trim();
-
-  return jwt;
+  return loadJwtFromDisk(apiUrl);
 }
 
-export const KNOWHOW_API_URL =
-  process.env.KNOWHOW_API_URL || "https://api.knowhow.tyvm.ai";
+export const KNOWHOW_API_URL = getActiveRemoteSync().apiUrl;
 
 @TraceAll()
 export class KnowhowSimpleClient {
@@ -159,7 +154,7 @@ export class KnowhowSimpleClient {
     // Explicit tokens (including KNOWHOW_JWT worker credentials) have no
     // corresponding local identity and must never trigger interactive renewal.
     this.canRefreshJwt = jwt === undefined && !process.env.KNOWHOW_JWT;
-    this.jwt = jwt ?? loadKnowhowJwt();
+    this.jwt = jwt ?? loadKnowhowJwt(this.baseUrl);
     this.setJwt(this.jwt);
     if (this.canRefreshJwt) {
       Object.defineProperty(this.headers, HTTP_UNAUTHORIZED_HANDLER, {
@@ -175,7 +170,7 @@ export class KnowhowSimpleClient {
    * Reload the JWT from disk (useful after login refreshes the token).
    */
   refreshJwt() {
-    const freshJwt = loadKnowhowJwt();
+    const freshJwt = loadKnowhowJwt(this.baseUrl);
     if (freshJwt) {
       this.setJwt(freshJwt);
       this.jwtValidated = false;
@@ -206,12 +201,13 @@ export class KnowhowSimpleClient {
     this.refreshPromise = (async () => {
       const config = getConfigSync();
       const identityPath = config.cliIdentityPath;
-      if (!config.orgId || (!keyPairExists(identityPath) && !keyPairExists())) {
+      const orgId = getOrgIdForApi(config, this.baseUrl);
+      if (!orgId || (!keyPairExists(identityPath) && !keyPairExists())) {
         throw new Error("JWT expired and the CLI identity is unavailable. Please run `knowhow login` again.");
       }
       try {
-        const freshJwt = await exchangeAvailablePublicKeyJwt(config.orgId, this.baseUrl, identityPath);
-        storeJwt(freshJwt);
+        const freshJwt = await exchangeAvailablePublicKeyJwt(orgId, this.baseUrl, identityPath);
+        storeJwt(freshJwt, this.baseUrl);
         this.setJwt(freshJwt);
         this.jwtValidated = true;
       } catch (error) {

package/src/services/Mcp.ts

@@ -1,11 +1,14 @@
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import Anthropic from "@anthropic-ai/sdk";
+import { spawn } from "child_process";
 
 import fs from "fs";
+import path from "path";
 import { McpConfig } from "../types";
 import { Tool } from "../clients";
 import { getConfig } from "../config";
+import { loadJwtFromDisk } from "../auth/jwtStore";
 import { TraceAll } from "../util/Trace";
 import { ToolsService } from "./Tools";
 import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
@@ -30,6 +33,84 @@ export const knowhowConfig = {
 export * from "./McpServer";
 export * from "./McpWebsocketTransport";
 
+/*
+ * Returns true if the given URL string points to localhost / 127.x / ::1.
+ */
+function isLocalhostUrl(url: string): boolean {
+  try {
+    const parsed = new URL(url);
+    const host = parsed.hostname;
+    return (
+      host === "localhost" ||
+      host === "127.0.0.1" ||
+      host === "::1" ||
+      /^127\./.test(host)
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a URL is reachable by making a simple HTTP GET/HEAD request.
+ * Resolves true if we get any HTTP response (even 4xx), false on network error.
+ */
+async function isUrlReachable(url: string, timeoutMs = 2000): Promise<boolean> {
+  return new Promise((resolve) => {
+    const parsed = new URL(url);
+    const lib = parsed.protocol === "https:" ? require("https") : require("http");
+    const req = lib.request(
+      { hostname: parsed.hostname, port: parsed.port || (parsed.protocol === "https:" ? 443 : 80), path: parsed.pathname || "/", method: "GET", timeout: timeoutMs },
+      () => { resolve(true); req.destroy(); }
+    );
+    req.on("error", () => resolve(false));
+    req.on("timeout", () => { req.destroy(); resolve(false); });
+    req.end();
+  });
+}
+
+/**
+ * If an MCP config has both a localhost `url` and a `command`, this function
+ * ensures the server is running: checks reachability, and if not up, spawns
+ * the command and waits until the URL is reachable (or timeout expires).
+ */
+async function ensureLocalServer(mcp: McpConfig): Promise<void> {
+  if (!mcp.url || !mcp.command || !isLocalhostUrl(mcp.url)) return;
+
+  const alreadyUp = await isUrlReachable(mcp.url);
+  if (alreadyUp) {
+    console.log(`MCP '${mcp.name}': server already running at ${mcp.url}`);
+    return;
+  }
+
+  console.log(`MCP '${mcp.name}': starting server with command: ${mcp.command} ${(mcp.args || []).join(" ")}`);
+
+  const child = spawn(mcp.command, mcp.args || [], {
+    detached: true,
+    stdio: "ignore",
+    env: mcp.env ? { ...process.env, ...mcp.env } : process.env,
+  });
+  child.unref(); // don't keep the knowhow process alive just for this child
+
+  // Wait up to 30s for the server to become reachable
+  const maxWait = 30_000;
+  const interval = 500;
+  const started = Date.now();
+
+  while (Date.now() - started < maxWait) {
+    await new Promise((r) => setTimeout(r, interval));
+    const up = await isUrlReachable(mcp.url!);
+    if (up) {
+      console.log(`MCP '${mcp.name}': server is up at ${mcp.url}`);
+      return;
+    }
+  }
+
+  throw new Error(
+    `MCP '${mcp.name}': timed out waiting for server to start at ${mcp.url} (command: ${mcp.command} ${(mcp.args || []).join(" ")})`
+  );
+}
+
 /*
  *
  * McpService is a service that manages connections to multiple MCP servers.
@@ -53,7 +134,7 @@ export class McpService {
     }
 
     this.config = mcpServers;
-    this.transports = mcpServers.map((mcp) => this.createTransport(mcp));
+    this.transports = await Promise.all(mcpServers.map((mcp) => this.createTransport(mcp)));
     this.clients = this.transports.map(() => new Client(knowhowMcpClient, knowhowConfig));
 
     return this.clients;
@@ -64,8 +145,9 @@ export class McpService {
    * Re-reads authorization_token_file every time so that token refreshes
    * are picked up without restarting the agent process.
    */
-  createTransport(mcp: McpConfig): Transport {
-    if (mcp.command) {
+  async createTransport(mcp: McpConfig): Promise<Transport> {
+    await ensureLocalServer(mcp);
+    if (mcp.command && !mcp.url) {
       const stdioParams: StdioServerParameters = {
         command: mcp.command,
         args: mcp.args,
@@ -79,8 +161,13 @@ export class McpService {
     if (mcp.url) {
       // Always re-read the token file so refreshed tokens are picked up
       if (mcp.authorization_token_file) {
-        const token = fs.readFileSync(mcp.authorization_token_file, "utf-8");
-        mcp.authorization_token = token.trim();
+        if (path.basename(mcp.authorization_token_file) === ".jwt") {
+          const apiUrl = process.env.KNOWHOW_API_URL || "https://api.knowhow.tyvm.ai";
+          mcp.authorization_token = loadJwtFromDisk(apiUrl, mcp.authorization_token_file);
+        } else {
+          const token = fs.readFileSync(mcp.authorization_token_file, "utf-8");
+          mcp.authorization_token = token.trim();
+        }
       }
       const scheme = mcp.authorization_scheme === "basic" ? "Basic" : "Bearer";
       const transport = new StreamableHTTPClientTransport(new URL(mcp.url), {
@@ -216,7 +303,7 @@ export class McpService {
       // Always create a fresh transport + client before connecting.
       // This handles cases where a previous connection attempt failed and left
       // the transport in a started-but-not-connected state.
-      this.transports[index] = this.createTransport(this.config[index]);
+      this.transports[index] = await this.createTransport(this.config[index]);
       this.clients[index] = new Client(knowhowMcpClient, knowhowConfig);
 
       const client = this.clients[index];
@@ -315,7 +402,7 @@ export class McpService {
       // Replace with a fresh transport + client so connectSingle() can reconnect
       // without hitting "StreamableHTTPClientTransport already started".
       // createTransport() re-reads authorization_token_file, picking up refreshed tokens.
-      this.transports[index] = this.createTransport(this.config[index]);
+      this.transports[index] = await this.createTransport(this.config[index]);
       this.clients[index] = new Client(knowhowMcpClient, knowhowConfig);
 
       // Remove tools from cache

package/src/services/McpWebsocketTransport.ts

@@ -1,4 +1,3 @@
-import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import {
   JSONRPCMessage,
   JSONRPCMessageSchema,
@@ -9,6 +8,7 @@ import { WebSocket } from "ws";
 export class MCPWebSocketTransport implements Transport {
   protected _socket: WebSocket;
   onmessage?: (message: JSONRPCMessage) => void;
+  onrawmessage?: (message: unknown) => boolean | Promise<boolean>;
   onerror?: (error: Error) => void;
   onclose?: () => void;
 
@@ -27,15 +27,19 @@ export class MCPWebSocketTransport implements Transport {
         } else {
           parsed = JSON.parse(data.toString());
         }
-        console.log("MCPW Message received", JSON.stringify(parsed));
-        const message = JSONRPCMessageSchema.parse(parsed);
-        // Process message asynchronously to avoid blocking the WebSocket
-        // event loop while a long-running tool call is in progress.
-        // Without this, all subsequent messages are queued until the
-        // current tool call completes.
-        setImmediate(() => {
-          this.onmessage?.(message);
-        });
+        Promise.resolve(this.onrawmessage?.(parsed) ?? false)
+          .then((consumed) => {
+            if (consumed) return;
+            const message = JSONRPCMessageSchema.parse(parsed);
+            // Process message asynchronously to avoid blocking the WebSocket
+            // event loop while a long-running tool call is in progress.
+            // Without this, all subsequent messages are queued until the
+            // current tool call completes.
+            setImmediate(() => {
+              this.onmessage?.(message);
+            });
+          })
+          .catch((error) => this.onerror?.(error as Error));
       } catch (error) {
         this.onerror?.(error as Error);
       }
@@ -53,7 +57,6 @@ export class MCPWebSocketTransport implements Transport {
   async send(message: JSONRPCMessage): Promise<void> {
     return new Promise((resolve, reject) => {
       const json = JSON.stringify(message);
-      console.log("MCPWs sending", json);
 
       if (this._socket.readyState !== WebSocket.OPEN) {
         return reject(

package/src/types.ts

@@ -70,11 +70,23 @@ export type EmbedSource = {
   minLength?: number;
 };
 
+export type KnowhowRemote = {
+  name: string;
+  apiUrl: string;
+  jwtPath: string;
+  orgId?: string;
+};
+
 export type Config = {
   openaiBaseUrl?: string;
   promptsDir: string;
   lintCommands?: { [fileExtension: string]: string };
+  /** Legacy organization field; migrated into the selected remote on login. */
   orgId?: string;
+  /** Legacy environment map retained for reading pre-remote configurations. */
+  orgIds?: Record<string, string>;
+  remotes?: Record<string, KnowhowRemote>;
+  activeRemote?: string;
   /** Private Ed25519 identity selected with `knowhow login --identity`. */
   cliIdentityPath?: string;
   syncRemote?: boolean;

package/tests/unit/McpWebsocketTransport.test.ts

@@ -0,0 +1,56 @@
+import { EventEmitter } from "events";
+import { WebSocket } from "ws";
+import { MCPWebSocketTransport } from "../../src/services/McpWebsocketTransport";
+
+class TestSocket extends EventEmitter {
+  readyState = WebSocket.OPEN;
+  // Simulate send() calling the callback immediately (required by MCPWebSocketTransport.send())
+  send = jest.fn((data: string, cb?: (err?: Error) => void) => { cb?.(); });
+  close = jest.fn();
+}
+
+const flush = () => new Promise<void>((resolve) => setImmediate(resolve));
+
+describe("MCPWebSocketTransport", () => {
+  it("delivers valid JSON-RPC frames to onmessage", async () => {
+    const socket = new TestSocket();
+    const transport = new MCPWebSocketTransport(socket as unknown as WebSocket);
+    const response = { jsonrpc: "2.0", id: 1, result: {} };
+    transport.onmessage = jest.fn();
+    transport.onerror = jest.fn();
+
+    await transport.start();
+    socket.emit("message", JSON.stringify(response));
+    await flush();
+    await flush();
+
+    expect(transport.onmessage).toHaveBeenCalledWith(response);
+    expect(transport.onerror).not.toHaveBeenCalled();
+  });
+
+  it("calls onerror for invalid JSON-RPC frames", async () => {
+    const socket = new TestSocket();
+    const transport = new MCPWebSocketTransport(socket as unknown as WebSocket);
+    const invalid = { notJsonRpc: true };
+    transport.onmessage = jest.fn();
+    transport.onerror = jest.fn();
+
+    await transport.start();
+    socket.emit("message", JSON.stringify(invalid));
+    await flush();
+
+    expect(transport.onmessage).not.toHaveBeenCalled();
+    expect(transport.onerror).toHaveBeenCalled();
+  });
+
+  it("sends serialized JSON over the socket", async () => {
+    const socket = new TestSocket();
+    const transport = new MCPWebSocketTransport(socket as unknown as WebSocket);
+    await transport.start();
+
+    const msg = { jsonrpc: "2.0" as const, method: "ping", id: 42 };
+    await transport.send(msg);
+
+    expect(socket.send).toHaveBeenCalledWith(JSON.stringify(msg), expect.any(Function));
+  });
+});