@tyvm/knowhow 0.0.108-dev.879609c → 0.0.108-dev.c47492f

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tyvm/knowhow",
-  "version": "0.0.108-dev.879609c",
+  "version": "0.0.108-dev.c47492f",
   "description": "ai cli with plugins and agents",
   "main": "ts_build/src/index.js",
   "bin": {
@@ -55,7 +55,7 @@
     "@inquirer/editor": "^4.2.18",
     "@modelcontextprotocol/sdk": "^1.13.3",
     "@simplewebauthn/server": "^13.3.0",
-    "@tyvm/knowhow-tunnel": "0.0.4",
+    "@tyvm/knowhow-tunnel": "0.0.5",
     "commander": "^14.0.0",
     "diff": "^5.2.0",
     "express": "^4.19.2",

package/src/cli.ts

@@ -14,7 +14,8 @@ import { includedTools } from "./agents/tools/list";
 import * as allTools from "./agents/tools";
 import { LazyToolsService, services } from "./services";
 import { login } from "./login";
-import { worker, tunnel } from "./worker";
+import { worker } from "./worker";
+import { TUNNEL_MINIMAL_TOOLS } from "./tunnel";
 import { fileSync } from "./fileSync";
 import { KnowhowSimpleClient } from "./services/KnowhowClient";
 import { ModulesService } from "./services/modules";
@@ -44,23 +45,28 @@ import { CliChatService } from "./chat/CliChatService";
 // Without this, a single failing MCP server (e.g. expired Notion token) will
 // crash the entire CLI with an unhandled rejection.
 process.on("unhandledRejection", (reason: unknown) => {
-  const message =
-    reason instanceof Error ? reason.message : String(reason);
+  const message = reason instanceof Error ? reason.message : String(reason);
   // Only warn — don't exit. The MCP connect errors are recoverable;
   // the server will simply be unavailable but others continue working.
-  console.warn(
-    `⚠ Unhandled MCP/async error (non-fatal): ${message}`
-  );
+  console.warn(`⚠ Unhandled MCP/async error (non-fatal): ${message}`);
 });
 
 async function setupServices() {
-  const { Agents, Mcp, Clients, Tools: OldTools } = services();
+  const {
+    Agents,
+    Mcp,
+    Clients,
+    Tools: AllTools,
+    Embeddings,
+    Plugins,
+    MediaProcessor,
+  } = services();
   const Tools = new LazyToolsService(); // eslint-disable-line no-shadow
 
   // Load modules from config first so module-provided tools/agents/plugins are available
   // We need to wireup the LazyTools to be connected to the same singletons that are in services()
   Tools.setContext({
-    ...OldTools.getContext(),
+    ...AllTools.getContext(),
   });
 
   // Build the AgentContext with the fully-populated LazyToolsService so every
@@ -107,16 +113,17 @@ async function setupServices() {
   const modulesService = new ModulesService();
   await modulesService.loadModulesFromConfig({
     Agents,
-    Embeddings: services().Embeddings,
-    Plugins: services().Plugins,
+    Embeddings,
+    Plugins,
     Clients,
+
     // Use LazyToolsService so module-provided tools are visible to agents and scripts
-    Tools: Tools as any,
-    MediaProcessor: services().MediaProcessor,
+    Tools,
+    MediaProcessor,
   });
 
-  // Return both LazyToolsService (for agents) and OldTools (plain ToolsService with all tools for scripts)
-  return { Tools, Clients, PlainTools: OldTools };
+  // Return both LazyToolsService (for agents) and AllTools (plain ToolsService with all tools for scripts)
+  return { Tools, Clients };
 }
 
 // Utility function to read from stdin
@@ -528,14 +535,25 @@ async function main() {
   program
     .command("cloudworker")
     .description("Create or sync a cloud worker with your local knowhow config")
-    .option("--create", "Create a new cloud worker with synced config and files")
-    .option("--push <uid>", "Push/sync local config and files to an existing cloud worker")
-    .option("--pull <id>", "Pull the latest workerConfigJson from a cloud worker and update local config")
+    .option(
+      "--create",
+      "Create a new cloud worker with synced config and files"
+    )
+    .option(
+      "--push <uid>",
+      "Push/sync local config and files to an existing cloud worker"
+    )
+    .option(
+      "--pull <id>",
+      "Pull the latest workerConfigJson from a cloud worker and update local config"
+    )
     .option("--name <name>", "Name for the cloud worker (used with --create)")
     .option("--dry-run", "Print what would be synced without doing it")
     .action(async (options) => {
       try {
-        const { cloudWorker, pullCloudWorkerConfig } = await import("./cloudWorker");
+        const { cloudWorker, pullCloudWorkerConfig } = await import(
+          "./cloudWorker"
+        );
         if (options.pull) {
           await pullCloudWorkerConfig({ id: options.pull });
         } else {
@@ -550,7 +568,9 @@ async function main() {
   program
     .command("tunnel")
     .description(
-      "Start tunnel-only mode: expose local ports to the cloud without registering any tools"
+      "Start a minimal worker with tunnel enabled: exposes local ports to the cloud. " +
+      "Registers essential tools (unlock, lock, listAllowedPorts) so the backend is aware of the worker and ports. " +
+      "If passkey auth is configured, the tunnel is locked until unlocked via tool call or WebSocket auth protocol."
     )
     .option(
       "--share",
@@ -558,10 +578,14 @@ async function main() {
     )
     .option("--unshare", "Make this tunnel private (only you can use it)")
     .action(async (options) => {
-      await tunnel(options);
+      console.log("🌐 Starting tunnel (minimal worker) mode...");
+      console.log(`   Tools: ${TUNNEL_MINIMAL_TOOLS.join(", ")}`);
+      await worker({
+        ...options,
+        allowedTools: TUNNEL_MINIMAL_TOOLS,
+      });
     });
 
-
   program
     .command("script")
     .description("Run a local tool script file using the executeScript sandbox")

package/src/services/modules/index.ts

@@ -5,20 +5,21 @@ import { services } from "../";
 import * as path from "path";
 
 export class ModulesService {
+  async getDefaultContext() {
+    return { ...services() };
+  }
+
+  async overrideDefaultContext(overrides: Partial<ModuleContext>) {
+    const defaultContext = await this.getDefaultContext();
+    return { ...defaultContext, ...overrides };
+  }
+
   async loadModulesFromConfig(context?: ModuleContext) {
     const config = await getConfig();
 
     // If no context provided, fall back to global singletons
     if (!context) {
-      const { Clients, Plugins, Agents, Tools, Embeddings, MediaProcessor } = services();
-      context = {
-        Agents,
-        Embeddings,
-        Plugins,
-        Clients,
-        Tools,
-        MediaProcessor,
-      };
+      context = { ...(await this.getDefaultContext()) };
     }
 
     // Use the toolsService from context
@@ -43,9 +44,13 @@ export class ModulesService {
         : modulePath;
       const rawModule = require(resolvedPath);
       const importedModule = (rawModule.default || rawModule) as KnowhowModule;
-      console.log(`🔌 Loading module: ${modulePath} (resolved: ${resolvedPath})`);
+      console.log(
+        `🔌 Loading module: ${modulePath} (resolved: ${resolvedPath})`
+      );
       await importedModule.init({ config, cwd: process.cwd(), context });
-      console.log(`✅ Module initialized: ${modulePath} (tools: ${importedModule.tools.length}, agents: ${importedModule.agents.length}, plugins: ${importedModule.plugins.length}, clients: ${importedModule.clients.length})`);
+      console.log(
+        `✅ Module initialized: ${modulePath} (tools: ${importedModule.tools.length}, agents: ${importedModule.agents.length}, plugins: ${importedModule.plugins.length}, clients: ${importedModule.clients.length})`
+      );
 
       for (const agent of importedModule.agents) {
         agentService.registerAgent(agent);
@@ -58,13 +63,12 @@ export class ModulesService {
 
       for (const plugin of importedModule.plugins) {
         const pluginContext = {
-          Agents: agentService,
-          Clients: clients,
-          Tools: toolsService,
-          Plugins: pluginService,
-          ...(context.MediaProcessor ? { MediaProcessor: context.MediaProcessor } : {}),
+          ...context,
         };
-        pluginService.registerPlugin(plugin.name, new plugin.plugin(pluginContext as any));
+        pluginService.registerPlugin(
+          plugin.name,
+          new plugin.plugin(pluginContext as any)
+        );
       }
 
       for (const client of importedModule.clients) {

package/src/tunnel.ts

@@ -0,0 +1,216 @@
+import os from "os";
+import { WebSocket } from "ws";
+import { createTunnelHandler, TunnelHandler } from "@tyvm/knowhow-tunnel";
+import { loadJwt } from "./login";
+import { wait } from "./utils";
+import { getConfig } from "./config";
+import { KNOWHOW_API_URL } from "./services/KnowhowClient";
+import { ModulesService } from "./services/modules";
+import { WorkerPasskeyAuthService } from "./workers/auth/WorkerPasskeyAuth";
+import { WsMiddlewareStack } from "./workers/auth/WsMiddleware";
+import { makeAuthMiddleware } from "./workers/auth/authMiddleware";
+
+/**
+ * Extract the tunnel domain and protocol from the API URL.
+ * e.g., "https://api.knowhow.tyvm.ai" -> { domain: "worker.knowhow.tyvm.ai", useHttps: true }
+ * e.g., "http://localhost:4000" -> { domain: "worker.localhost:4000", useHttps: false }
+ */
+export function extractTunnelDomain(apiUrl: string): {
+  domain: string;
+  useHttps: boolean;
+} {
+  try {
+    const url = new URL(apiUrl);
+    const useHttps = url.protocol === "https:";
+
+    // For localhost, include port; for production, just use hostname
+    if (url.hostname === "localhost" || url.hostname === "127.0.0.1") {
+      return {
+        domain: `worker.${url.hostname}:${url.port || "80"}`,
+        useHttps,
+      };
+    }
+    return { domain: `worker.${url.hostname}`, useHttps };
+  } catch (err) {
+    console.error("Failed to parse API_URL for tunnel domain:", err);
+    return { domain: "worker.localhost:4000", useHttps: false }; // fallback
+  }
+}
+
+/**
+ * Initialize a tunnel handler and load tunnel modules.
+ */
+export async function initTunnelHandler(
+  tunnelConnection: WebSocket,
+  tunnelConfig: Parameters<typeof createTunnelHandler>[1]
+): Promise<TunnelHandler> {
+  const handler = createTunnelHandler(tunnelConnection, tunnelConfig);
+  console.log("🌐 Tunnel handler initialized");
+  console.log(tunnelConfig);
+
+  const tunnelModuleService = new ModulesService();
+  const tunnelContext = await tunnelModuleService.overrideDefaultContext({
+    Tunnel: handler,
+  });
+  tunnelModuleService.loadModulesFromConfig(tunnelContext).catch((err) => {
+    console.error("Failed to load tunnel modules:", err);
+  });
+
+  return handler;
+}
+
+/**
+ * Resolve tunnel local host, log port mapping, and return shared tunnel setup values.
+ * Extracted to avoid duplication between worker() and tunnel().
+ */
+export function resolveTunnelConfig(
+  config: Awaited<ReturnType<typeof getConfig>>,
+  isInsideDocker: boolean
+): { tunnelLocalHost: string; portMapping: Record<string, number> } {
+  // Determine localHost based on environment
+  let tunnelLocalHost = config.worker?.tunnel?.localHost;
+  if (!tunnelLocalHost) {
+    if (isInsideDocker) {
+      tunnelLocalHost = "host.docker.internal";
+      console.log(
+        "🐳 Docker detected: tunnel will use host.docker.internal to reach host services"
+      );
+    } else {
+      tunnelLocalHost = "127.0.0.1";
+    }
+  }
+
+  // Check for port mapping configuration
+  const portMapping = (config.worker?.tunnel?.portMapping || {}) as Record<string, number>;
+  if (Object.keys(portMapping).length > 0) {
+    console.log("🔀 Port mapping configured:");
+    for (const [containerPort, hostPort] of Object.entries(portMapping)) {
+      console.log(`   Container port ${containerPort} → Host port ${hostPort}`);
+    }
+  }
+
+  return { tunnelLocalHost, portMapping };
+}
+
+/**
+ * Options for connectTunnelWebSocket helper.
+ */
+export interface TunnelWebSocketOptions {
+  /** Already-resolved tunnel domain (hostname only, no protocol) */
+  tunnelDomain: string;
+  /** Whether the tunnel should use HTTPS */
+  tunnelUseHttps: boolean;
+  /** Local host to forward tunnel traffic to */
+  tunnelLocalHost: string;
+  /** Port mapping configuration */
+  portMapping: Record<string, number>;
+  /** Worker config (for tunnel sub-config) */
+  config: Awaited<ReturnType<typeof getConfig>>;
+  /** HTTP headers to attach to the WebSocket upgrade request */
+  headers: Record<string, string>;
+  /** Callback invoked with the TunnelHandler once the connection opens */
+  onOpen?: (handler: TunnelHandler) => void;
+  /** Called when the connection closes; receives code + reason string */
+  onClose?: (code: number, reason: string) => void;
+  /** Called on error */
+  onError?: (error: Error) => void;
+  /** Optional passkey auth service — if provided, applies WS middleware to gate tunnel traffic */
+  authService?: WorkerPasskeyAuthService | null;
+}
+
+/**
+ * Create a tunnel WebSocket connection, build the tunnelConfig, and
+ * initialize the tunnel handler.  Returns the WebSocket.
+ *
+ * The caller is responsible for storing a reference to the returned TunnelHandler
+ * (via onOpen) and performing any outer-state cleanup (via onClose / onError).
+ */
+export function connectTunnelWebSocket(
+  options: TunnelWebSocketOptions
+): WebSocket {
+  const {
+    tunnelDomain,
+    tunnelUseHttps,
+    tunnelLocalHost,
+    portMapping,
+    config,
+    headers,
+    onOpen,
+    onClose,
+    onError,
+    authService,
+  } = options;
+
+  const tunnelConnection = new WebSocket(`${KNOWHOW_API_URL}/ws/tunnel`, { headers });
+
+  tunnelConnection.on("open", async () => {
+    console.log("Tunnel WebSocket connected");
+
+    // Apply passkey auth middleware FIRST, before tunnel handler registers its
+    // "message" listener. Node.js EventEmitter fires listeners in registration
+    // order, so our middleware runs first. wrapSocket() also redirects future
+    // ws.on("message", ...) calls to an inner emitter, ensuring the tunnel
+    // handler only receives messages that passed the middleware.
+    if (authService) {
+      const stack = new WsMiddlewareStack();
+      stack.use(makeAuthMiddleware(authService));
+      stack.wrapSocket(tunnelConnection);
+    }
+
+    const allowedPorts = config.worker?.tunnel?.allowedPorts || [];
+
+    // Create URL rewriter callback that returns the hostname (without protocol).
+    // The tunnel package will add the protocol based on the useHttps config.
+    const urlRewriter = (port: number, metadata?: any) => {
+      const workerId = metadata?.workerId;
+      const secret = metadata?.secret;
+      // Examples: secret-p3000.worker.example.com  /  workerId-p3000.worker.example.com
+      const subdomain = secret
+        ? `${secret}-p${port}`
+        : `${workerId}-p${port}`;
+      return `${subdomain}.${tunnelDomain}`;
+    };
+
+    const tunnelConfig = {
+      allowedPorts,
+      maxConcurrentStreams: config.worker?.tunnel?.maxConcurrentStreams || 50,
+      tunnelUseHttps,
+      localHost: tunnelLocalHost,
+      urlRewriter,
+      enableUrlRewriting: config.worker?.tunnel?.enableUrlRewriting !== false,
+      portMapping,
+      logLevel: "debug" as const,
+    };
+
+    const handler = await initTunnelHandler(tunnelConnection, tunnelConfig);
+    onOpen?.(handler);
+  });
+
+  tunnelConnection.on("close", (code, reason) => {
+    console.log(
+      `Tunnel WebSocket closed. Code: ${code}, Reason: ${reason.toString()}`
+    );
+    onClose?.(code, reason.toString());
+  });
+
+  tunnelConnection.on("error", (error) => {
+    console.error("Tunnel WebSocket error:", error);
+    onError?.(error);
+  });
+
+  return tunnelConnection;
+}
+
+/**
+ * The minimal set of tool names that are always registered when running in
+ * tunnel mode. These are the tools the backend and frontend need to interact
+ * with the tunnel worker (port discovery, passkey auth).
+ *
+ * Additional tools can be added here in the future without changing the CLI.
+ */
+export const TUNNEL_MINIMAL_TOOLS = [
+  "listAllowedPorts",
+  "unlock",
+  "lock",
+  "reloadConfig",
+];