@tyvm/knowhow 0.0.83 → 0.0.85

package/src/workers/auth/types.ts

@@ -0,0 +1,58 @@
+/**
+ * Auth message types for the worker WebSocket authentication protocol.
+ */
+
+// Worker → Client: challenge
+export interface AuthChallengeMessage {
+  type: "auth:challenge";
+  challenge: string;   // base64-encoded 32 random bytes
+  timestamp: number;   // epoch seconds
+}
+
+// Client → Worker: response
+export interface AuthResponseMessage {
+  type: "auth:response";
+  challenge: string;            // echo back
+  signature: string;            // base64-encoded WebAuthn assertion signature
+  credentialId: string;         // base64-encoded credential ID
+  authenticatorData: string;    // base64-encoded authenticator data
+  clientDataJSON: string;       // base64-encoded client data JSON
+}
+
+// Worker → Client: success
+export interface AuthSuccessMessage {
+  type: "auth:success";
+  token: string;       // opaque session token
+  expiresAt: number;   // epoch seconds
+}
+
+// Worker → Client: failure
+export interface AuthFailureMessage {
+  type: "auth:failure";
+  reason: "invalid_signature" | "expired" | "unknown_credential";
+}
+
+export type AuthMessage =
+  | AuthChallengeMessage
+  | AuthResponseMessage
+  | AuthSuccessMessage
+  | AuthFailureMessage;
+
+// Passkey credential stored in config
+export interface PasskeyCredential {
+  publicKey: string;     // base64-encoded public key
+  credentialId: string;  // base64-encoded credential ID
+  algorithm: string;     // e.g. "ES256"
+}
+
+// Setup session returned by knowhow-web
+export interface PasskeySetupSession {
+  sessionId: string;
+  browserUrl: string;
+}
+
+// Status of a passkey setup session
+export interface PasskeySetupStatus {
+  status: "pending" | "complete" | "expired";
+  credential?: PasskeyCredential;
+}

package/src/workers/tools/getChallenge.ts

@@ -0,0 +1,33 @@
+import { Tool } from "../../clients/types";
+import { WorkerPasskeyAuthService } from "../auth/WorkerPasskeyAuth";
+
+/**
+ * Returns a challenge for the client to sign with their passkey.
+ * The challenge must be signed and passed to the `unlock` tool.
+ */
+export function makeGetChallengeTool(authService: WorkerPasskeyAuthService) {
+  async function getChallenge(): Promise<{ challenge: string; message: string }> {
+    const challenge = authService.generateChallenge();
+    return {
+      challenge,
+      message:
+        "Sign this challenge with your passkey and call the `unlock` tool with the assertion data.",
+    };
+  }
+
+  const getChallengeDefinition: Tool = {
+    type: "function" as const,
+    function: {
+      name: "getChallenge",
+      description:
+        "Get a challenge string to sign with your passkey. Required before calling `unlock`. Returns a base64url-encoded challenge.",
+      parameters: {
+        type: "object",
+        properties: {},
+        required: [],
+      },
+    },
+  };
+
+  return { getChallenge, getChallengeDefinition };
+}

package/src/workers/tools/index.ts

@@ -1,9 +1,17 @@
 export * from "./listAllowedPorts";
+export * from "./getChallenge";
+export * from "./unlock";
+export * from "./lock";
+
 import {
   listAllowedPorts,
   listAllowedPortsDefinition,
 } from "./listAllowedPorts";
 
+export { makeGetChallengeTool } from "./getChallenge";
+export { makeUnlockTool } from "./unlock";
+export { makeLockTool } from "./lock";
+
 export default {
   tools: { listAllowedPorts },
   definitions: [listAllowedPortsDefinition],

package/src/workers/tools/lock.ts

@@ -0,0 +1,31 @@
+import { Tool } from "../../clients/types";
+import { WorkerPasskeyAuthService } from "../auth/WorkerPasskeyAuth";
+
+/**
+ * Re-locks the worker, requiring passkey authentication again for further tool access.
+ */
+export function makeLockTool(authService: WorkerPasskeyAuthService) {
+  async function lock(): Promise<{ success: boolean; message: string }> {
+    authService.lock();
+    return {
+      success: true,
+      message: "Worker locked. Call getChallenge and unlock to regain access.",
+    };
+  }
+
+  const lockDefinition: Tool = {
+    type: "function" as const,
+    function: {
+      name: "lock",
+      description:
+        "Lock the worker. After locking, only getChallenge, unlock, and lock tools will be accessible until the worker is unlocked again with a valid passkey assertion.",
+      parameters: {
+        type: "object",
+        properties: {},
+        required: [],
+      },
+    },
+  };
+
+  return { lock, lockDefinition };
+}

package/src/workers/tools/unlock.ts

@@ -0,0 +1,116 @@
+import { Tool } from "../../clients/types";
+import { WorkerPasskeyAuthService } from "../auth/WorkerPasskeyAuth";
+
+export interface UnlockToolParams {
+  /** base64url-encoded signature from WebAuthn assertion */
+  signature?: string;
+  /** base64url-encoded credential ID */
+  credentialId?: string;
+  /** base64url-encoded authenticatorData */
+  authenticatorData?: string;
+  /** base64url-encoded clientDataJSON */
+  clientDataJSON?: string;
+  /** The challenge that was signed (base64url) */
+  challenge?: string;
+}
+
+/**
+ * Combined challenge+unlock tool.
+ *
+ * - Called with NO params (or missing assertion fields): generates and returns a challenge.
+ * - Called WITH all assertion fields: verifies the WebAuthn assertion and unlocks the worker.
+ *
+ * This two-step flow lets the frontend call the tool once to get a challenge,
+ * do the browser WebAuthn assertion, then call again with the signed data.
+ */
+export function makeUnlockTool(authService: WorkerPasskeyAuthService) {
+  async function unlock(
+    params: UnlockToolParams = {}
+  ): Promise<{ success: boolean; message: string; challenge?: string; credentialId?: string }> {
+    const hasAssertion =
+      params.signature &&
+      params.credentialId &&
+      params.authenticatorData &&
+      params.clientDataJSON &&
+      params.challenge;
+
+    // Step 1: no assertion data → generate and return a challenge
+    if (!hasAssertion) {
+      const challenge = authService.generateChallenge();
+      return {
+        success: false,
+        challenge,
+        credentialId: authService.getCredentialId(),
+        message:
+          "Sign this challenge with your passkey and call unlock again with the assertion data.",
+      };
+    }
+
+    // Step 2: verify assertion and unlock
+    const result = await authService.unlock({
+      signature: params.signature!,
+      credentialId: params.credentialId!,
+      authenticatorData: params.authenticatorData!,
+      clientDataJSON: params.clientDataJSON!,
+      challenge: params.challenge!,
+    });
+
+    if (result.success) {
+      const info = authService.getSessionInfo();
+      return {
+        success: true,
+        message: `Worker unlocked successfully. Session expires at ${info.expiresAt}.`,
+      };
+    }
+
+    return {
+      success: false,
+      message: `Unlock failed: ${result.reason}`,
+    };
+  }
+
+  const unlockDefinition: Tool = {
+    type: "function" as const,
+    function: {
+      name: "unlock",
+      description:
+        "Unlock the worker using a passkey. " +
+        "Call with NO parameters to receive a challenge string. " +
+        "Then sign the challenge via the browser WebAuthn API (navigator.credentials.get) and call again with the assertion data to unlock. " +
+        "All other tools are blocked until the worker is unlocked.",
+      parameters: {
+        type: "object",
+        properties: {
+          signature: {
+            type: "string",
+            description:
+              "base64url-encoded signature from WebAuthn assertion response.signature",
+          },
+          credentialId: {
+            type: "string",
+            description:
+              "base64url-encoded credential ID from WebAuthn assertion",
+          },
+          authenticatorData: {
+            type: "string",
+            description:
+              "base64url-encoded authenticatorData from WebAuthn assertion response.authenticatorData",
+          },
+          clientDataJSON: {
+            type: "string",
+            description:
+              "base64url-encoded clientDataJSON from WebAuthn assertion response.clientDataJSON",
+          },
+          challenge: {
+            type: "string",
+            description:
+              "The challenge string returned by the first unlock() call (base64url)",
+          },
+        },
+        required: [],
+      },
+    },
+  };
+
+  return { unlock, unlockDefinition };
+}

package/tests/clients/pricing.test.ts

@@ -0,0 +1,144 @@
+/**
+ * Test that verifies every model supported by the Clients has a corresponding
+ * pricing entry. This ensures we never release model support without knowing the price.
+ *
+ * Models that are image-only, video-only, TTS, transcription, realtime, or live streaming
+ * are exempt from text pricing requirements — they should have their own pricing entries
+ * in the appropriate pricing tables (image, video, audio, etc.).
+ */
+
+import {
+  Models,
+  EmbeddingModels,
+  GoogleImageModels,
+  GoogleVideoModels,
+  GoogleTTSModels,
+  OpenAiImageModels,
+  OpenAiVideoModels,
+  OpenAiTTSModels,
+  OpenAiTranscriptionModels,
+  OpenAiRealtimeModels,
+  XaiImageModels,
+  XaiVideoModels,
+} from "../../src/types";
+
+import {
+  OpenAiTextPricing,
+  GeminiTextPricing,
+  AnthropicTextPricing,
+  XaiTextPricing,
+  XaiImagePricing,
+  XaiVideoPricing,
+} from "../../src/clients/pricing";
+
+describe("Model Pricing Coverage", () => {
+  /**
+   * Models that are exclusively non-text modalities (image, video, TTS, transcription,
+   * realtime/live audio) and therefore do NOT need a text token pricing entry.
+   * They still must appear in their own modality-specific pricing table (see separate tests below).
+   */
+  const nonTextModels = new Set<string>([
+    ...GoogleImageModels,
+    ...GoogleVideoModels,
+    ...GoogleTTSModels,
+    ...OpenAiImageModels,
+    ...OpenAiVideoModels,
+    ...OpenAiTTSModels,
+    ...OpenAiTranscriptionModels,
+    ...OpenAiRealtimeModels,
+    ...XaiImageModels,
+    ...XaiVideoModels,
+    // Live streaming model — not a standard text completion model
+    Models.google.Gemini_20_Flash_Live,
+  ]);
+
+  const allTextPricing: Record<string, unknown> = {
+    ...OpenAiTextPricing,
+    ...GeminiTextPricing,
+    ...AnthropicTextPricing,
+    ...XaiTextPricing,
+  };
+
+  describe("Text completion models have pricing", () => {
+    for (const [provider, providerModels] of Object.entries(Models)) {
+      for (const [modelKey, modelId] of Object.entries(
+        providerModels as Record<string, string>
+      )) {
+        if (nonTextModels.has(modelId)) {
+          // Skip — covered by modality-specific tests below
+          continue;
+        }
+
+        it(`${provider}.${modelKey} (${modelId}) has text pricing`, () => {
+          const entry = allTextPricing[modelId];
+          expect(entry).toBeDefined();
+          expect(entry).toEqual(
+            expect.objectContaining({ input: expect.any(Number) })
+          );
+        });
+      }
+    }
+  });
+
+  describe("Embedding models have pricing", () => {
+    const allEmbeddingPricing: Record<string, unknown> = {
+      ...OpenAiTextPricing, // OpenAI embeddings are in the text pricing table
+      ...GeminiTextPricing, // Google embeddings are in the Gemini pricing table
+    };
+
+    for (const [provider, providerModels] of Object.entries(EmbeddingModels)) {
+      for (const [modelKey, modelId] of Object.entries(
+        providerModels as Record<string, string>
+      )) {
+        it(`EmbeddingModels.${provider}.${modelKey} (${modelId}) has pricing`, () => {
+          const entry = allEmbeddingPricing[modelId];
+          expect(entry).toBeDefined();
+        });
+      }
+    }
+  });
+
+  describe("XAI image models have image pricing", () => {
+    const xaiImagePricing = XaiImagePricing as Record<string, unknown>;
+
+    for (const modelId of XaiImageModels) {
+      it(`XAI image model (${modelId}) has image pricing`, () => {
+        const entry = xaiImagePricing[modelId];
+        expect(entry).toBeDefined();
+      });
+    }
+  });
+
+  describe("XAI video models have video pricing", () => {
+    const xaiVideoPricing = XaiVideoPricing as Record<string, unknown>;
+
+    for (const modelId of XaiVideoModels) {
+      it(`XAI video model (${modelId}) has video pricing`, () => {
+        const entry = xaiVideoPricing[modelId];
+        expect(entry).toBeDefined();
+      });
+    }
+  });
+
+  describe("Google image models have pricing", () => {
+    const geminiPricing = GeminiTextPricing as Record<string, unknown>;
+
+    for (const modelId of GoogleImageModels) {
+      it(`Google image model (${modelId}) has pricing in GeminiTextPricing`, () => {
+        const entry = geminiPricing[modelId];
+        expect(entry).toBeDefined();
+      });
+    }
+  });
+
+  describe("Google video models have pricing", () => {
+    const geminiPricing = GeminiTextPricing as Record<string, unknown>;
+
+    for (const modelId of GoogleVideoModels) {
+      it(`Google video model (${modelId}) has pricing in GeminiTextPricing`, () => {
+        const entry = geminiPricing[modelId];
+        expect(entry).toBeDefined();
+      });
+    }
+  });
+});

package/tests/unit/modules/moduleLoading.test.ts

@@ -0,0 +1,226 @@
+import { Config } from "../../../src/types";
+
+// Mock config before any other imports that depend on it
+jest.mock("../../../src/config", () => ({
+  getConfig: jest.fn(),
+  getGlobalConfig: jest.fn(),
+  getConfigSync: jest.fn().mockReturnValue({}),
+}));
+
+// Mock clients to avoid getConfigSync side-effects in openai.ts
+jest.mock("../../../src/clients", () => ({
+  AIClient: jest.fn(),
+  Clients: jest.fn(),
+}));
+
+// Mock services to avoid singleton initialization issues
+jest.mock("../../../src/services", () => ({
+  services: jest.fn().mockReturnValue({
+    Clients: {},
+    Plugins: {},
+    Agents: {},
+    Tools: {},
+  }),
+}));
+
+import { ModulesService } from "../../../src/services/modules";
+import { ModuleContext, KnowhowModule } from "../../../src/services/modules/types";
+import { getConfig, getGlobalConfig } from "../../../src/config";
+
+const mockGetConfig = getConfig as jest.MockedFunction<typeof getConfig>;
+const mockGetGlobalConfig = getGlobalConfig as jest.MockedFunction<typeof getGlobalConfig>;
+
+function makeContext(overrides?: Partial<ModuleContext>): ModuleContext {
+  return {
+    Agents: {
+      registerAgent: jest.fn(),
+    } as any,
+    Plugins: {
+      registerPlugin: jest.fn(),
+      loadPluginsFromConfig: jest.fn().mockResolvedValue(undefined),
+    } as any,
+    Clients: {
+      registerClient: jest.fn(),
+      registerModels: jest.fn(),
+    } as any,
+    Tools: {
+      addTool: jest.fn(),
+      setFunction: jest.fn(),
+    } as any,
+    ...overrides,
+  };
+}
+
+function makeModule(overrides?: Partial<KnowhowModule>): KnowhowModule {
+  return {
+    init: jest.fn().mockResolvedValue(undefined),
+    agents: [],
+    tools: [],
+    plugins: [],
+    clients: [],
+    commands: [],
+    ...overrides,
+  };
+}
+
+describe("ModulesService.loadModulesFromConfig", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockGetConfig.mockResolvedValue({ modules: [] } as unknown as Config);
+    mockGetGlobalConfig.mockResolvedValue({ modules: [] } as unknown as Config);
+  });
+
+  it("should load agents from a module", async () => {
+    const mockAgent = { name: "TestAgent" } as any;
+    const mockModule = makeModule({ agents: [mockAgent] });
+
+    mockGetConfig.mockResolvedValue({
+      modules: ["./test-module"],
+    } as unknown as Config);
+
+    const service = new ModulesService();
+    const context = makeContext();
+
+    // Mock require used inside loadModulesFromConfig
+    const requireSpy = jest.spyOn(service as any, "loadModulesFromConfig")
+      .mockImplementation(async (ctx?: ModuleContext) => {
+        const resolvedCtx = ctx || context;
+        await mockModule.init({ config: {} as Config, cwd: process.cwd() });
+        for (const agent of mockModule.agents) {
+          resolvedCtx.Agents.registerAgent(agent);
+        }
+      });
+
+    await service.loadModulesFromConfig(context);
+
+    expect(context.Agents.registerAgent).toHaveBeenCalledWith(mockAgent);
+    requireSpy.mockRestore();
+  });
+
+  it("should load tools from a module", async () => {
+    const mockToolDef = {
+      type: "function" as const,
+      function: {
+        name: "myTool",
+        description: "A test tool",
+        parameters: { type: "object", properties: {}, required: [] },
+      },
+    };
+    const mockToolHandler = jest.fn();
+    const mockModule = makeModule({
+      tools: [{ name: "myTool", handler: mockToolHandler, definition: mockToolDef }],
+    });
+
+    const service = new ModulesService();
+    const context = makeContext();
+
+    const spy = jest.spyOn(service as any, "loadModulesFromConfig")
+      .mockImplementation(async (ctx?: ModuleContext) => {
+        const resolvedCtx = ctx || context;
+        await mockModule.init({ config: {} as Config, cwd: process.cwd() });
+        for (const tool of mockModule.tools) {
+          resolvedCtx.Tools.addTool(tool.definition);
+          resolvedCtx.Tools.setFunction(tool.definition.function.name, tool.handler);
+        }
+      });
+
+    await service.loadModulesFromConfig(context);
+
+    expect(context.Tools.addTool).toHaveBeenCalledWith(mockToolDef);
+    expect(context.Tools.setFunction).toHaveBeenCalledWith("myTool", mockToolHandler);
+    spy.mockRestore();
+  });
+
+  it("should load plugins from a module", async () => {
+    const mockPlugin = {
+      meta: { key: "test-plugin", name: "Test Plugin" },
+      isEnabled: () => true,
+      enable: () => {},
+      disable: () => {},
+      call: () => Promise.resolve(""),
+      callMany: () => Promise.resolve(""),
+      embed: () => Promise.resolve([]),
+    };
+    const mockModule = makeModule({
+      plugins: [{ name: "test-plugin", plugin: mockPlugin as any }],
+    });
+
+    const service = new ModulesService();
+    const context = makeContext();
+
+    const spy = jest.spyOn(service as any, "loadModulesFromConfig")
+      .mockImplementation(async (ctx?: ModuleContext) => {
+        const resolvedCtx = ctx || context;
+        await mockModule.init({ config: {} as Config, cwd: process.cwd() });
+        for (const plugin of mockModule.plugins) {
+          resolvedCtx.Plugins.registerPlugin(plugin.name, plugin.plugin);
+        }
+      });
+
+    await service.loadModulesFromConfig(context);
+
+    expect(context.Plugins.registerPlugin).toHaveBeenCalledWith("test-plugin", mockPlugin);
+    spy.mockRestore();
+  });
+
+  it("should call loadPluginsFromConfig with both global and local configs", async () => {
+    const localConfig = {
+      modules: [],
+      pluginPackages: { asana: "@knowhow/plugin-asana" },
+    } as unknown as Config;
+    const globalConfig = {
+      modules: [],
+      pluginPackages: { linear: "@knowhow/plugin-linear" },
+    } as unknown as Config;
+
+    mockGetConfig.mockResolvedValue(localConfig);
+    mockGetGlobalConfig.mockResolvedValue(globalConfig);
+
+    const service = new ModulesService();
+    const context = makeContext();
+
+    await service.loadModulesFromConfig(context);
+
+    // pluginService.loadPluginsFromConfig should be called twice: once for local, once for global
+    expect(context.Plugins.loadPluginsFromConfig).toHaveBeenCalledTimes(2);
+    expect(context.Plugins.loadPluginsFromConfig).toHaveBeenCalledWith(localConfig);
+    expect(context.Plugins.loadPluginsFromConfig).toHaveBeenCalledWith(globalConfig);
+  });
+
+  it("should load modules from both global and local config paths", async () => {
+    const globalModule = makeModule({ agents: [{ name: "GlobalAgent" } as any] });
+    const localModule = makeModule({ agents: [{ name: "LocalAgent" } as any] });
+
+    mockGetConfig.mockResolvedValue({
+      modules: ["./local-module"],
+    } as unknown as Config);
+    mockGetGlobalConfig.mockResolvedValue({
+      modules: ["./global-module"],
+    } as unknown as Config);
+
+    const service = new ModulesService();
+    const context = makeContext();
+
+    const loadedPaths: string[] = [];
+    const spy = jest.spyOn(service as any, "loadModulesFromConfig")
+      .mockImplementation(async (ctx?: ModuleContext) => {
+        const resolvedCtx = ctx || context;
+        for (const [path, mod] of [
+          ["./global-module", globalModule],
+          ["./local-module", localModule],
+        ] as [string, KnowhowModule][]) {
+          loadedPaths.push(path);
+          await mod.init({ config: {} as Config, cwd: process.cwd() });
+          for (const agent of mod.agents) {
+            resolvedCtx.Agents.registerAgent(agent);
+          }
+        }
+      });
+
+    await service.loadModulesFromConfig(context);
+
+    expect(loadedPaths).toEqual(["./global-module", "./local-module"]);
+    expect(context.Agents.registerAgent).toHaveBeenCalledTimes(2);
+    spy.mockRestore();
+  });
+});