@tyvm/knowhow 0.0.145 → 0.0.147

package/src/commands/services.ts

@@ -1,6 +1,6 @@
 import { includedTools } from "../agents/tools/list";
 import * as allTools from "../agents/tools";
-import { LazyToolsService, services, MinimalToolsService } from "../services";
+import { LazyToolsService, services, MinimalToolsService, TracingService } from "../services";
 import { agents } from "../agents";
 import { ModulesService } from "../services/modules";
 import { getConfig } from "../config";
@@ -19,8 +19,10 @@ export async function setupServices() {
     Events,
     MediaProcessor,
     Behaviors,
+    RuntimeReload,
   } = services();
 
+  await Plugins.refreshConfiguredState();
   // cli uses LazyTools to keep context slim
   const Tools = new LazyToolsService();
   await Behaviors.initFromConfig();
@@ -80,7 +82,7 @@ export async function setupServices() {
 
   console.log("📦 Loading modules from config...");
   const modulesService = new ModulesService();
-  await modulesService.loadModulesFromConfig({
+  const moduleContext = {
     Agents,
     Embeddings,
     Plugins,
@@ -89,7 +91,51 @@ export async function setupServices() {
     MediaProcessor,
     Behaviors,
     Events,
+    Tracing: TracingService,
+  };
+
+  // Call destroy() on all modules when the process is shutting down so they
+  // can flush buffers (e.g. OTEL spans), close connections, etc.
+  const destroyAll = async () => {
+    await modulesService.destroyModules();
+  };
+  process.on("beforeExit", destroyAll);
+  process.on("SIGINT", async () => {
+    await destroyAll();
+    process.exit(0);
+  });
+  await modulesService.loadModulesFromConfig(moduleContext);
+
+  RuntimeReload.configure(async () => {
+    await modulesService.destroyModules();
+    await Plugins.refreshConfiguredState();
+    await Mcp.closeAll();
+
+    Tools.resetTools();
+    Tools.defineTools(includedTools, allTools);
+    try {
+      const agentCallDef = AllTools.getTool?.("agentCall");
+      const agentCallFn = AllTools.getFunction?.("agentCall");
+      if (agentCallDef) Tools.addTool(agentCallDef);
+      if (agentCallFn) Tools.setFunction("agentCall", agentCallFn);
+    } catch (_) {}
+
+    await Behaviors.initFromConfig();
+    await Mcp.connectToConfigured(Tools);
+    await Clients.registerConfiguredModels();
+    await modulesService.loadModulesFromConfig(moduleContext);
+
+    const config = await getConfig();
+    return {
+      tools: Tools.getTools().length,
+      mcps: (config.mcps || []).length,
+      modules: (config.modules || []).length,
+    };
+  });
+  process.on("SIGTERM", async () => {
+    await destroyAll();
+    process.exit(0);
   });
 
-  return { Tools, Clients };
+  return { Tools, Clients, modulesService };
 }

package/src/login.ts

@@ -1,13 +1,28 @@
 import http from "./utils/http";
 import fs from "fs";
 import path from "path";
-import { chmod } from "fs/promises";
 import { ask } from "./utils";
 import { getConfig, updateConfig } from "./config";
 import { KNOWHOW_API_URL } from "./services/KnowhowClient";
 import { BrowserLoginService } from "./auth/browserLogin";
-
-export async function login(jwtFlag?: boolean): Promise<void> {
+import { authenticateWithKey, hasKeyPair, registerPublicKey } from "./auth/keyAuth";
+import { getOrCreatePublicKey } from "./auth/keyManager";
+
+/**
+ * Log in to Knowhow.
+ *
+ * Strategy (in order):
+ *   1. `--jwt`   flag: prompt for a raw JWT and write it to disk.
+ *   2. Key auth: if an Ed25519 key and configured organization exist, sign a
+ *                server challenge and exchange it for an organization-bound JWT.
+ *   3. Browser:  open the browser approval flow (first-time login or key not yet registered).
+ *
+ * After any successful login the local config is updated with the current user's orgId.
+ *
+ * @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.");
   }
@@ -15,9 +30,8 @@ export async function login(jwtFlag?: boolean): Promise<void> {
   if (jwtFlag) {
     const jwt = await ask("Enter your JWT: ");
 
-    // Update the JWT file
     const configDir = path.join(process.cwd(), ".knowhow");
-    const jwtFile = path.join(process.cwd(), ".knowhow", ".jwt");
+    const jwtFile = path.join(configDir, ".jwt");
 
     if (!fs.existsSync(configDir)) {
       fs.mkdirSync(configDir, { recursive: true });
@@ -26,23 +40,69 @@ export async function login(jwtFlag?: boolean): Promise<void> {
     fs.chmodSync(jwtFile, 0o600);
     console.log("JWT updated successfully.");
   } else {
-    // Use browser login as default method
-    console.log("Starting browser-based authentication...");
+    const config = await getConfig();
+    const orgId = config.orgId;
+
+    // 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(identityPath)) {
+      console.log("Found CLI identity — authenticating with public key...");
+      try {
+        const success = await authenticateWithKey(orgId, KNOWHOW_API_URL, identityPath);
+        if (success) {
+          console.log("✅ Successfully authenticated via public key!");
+          return await postLoginConfigUpdate(identityPath);
+        }
+        console.warn("Key authentication returned no JWT, falling back to browser login...");
+      } catch (error: unknown) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`Key authentication failed (${message}), falling back to browser login...`);
+      }
+    }
+
+    // Fall back when no org/key is configured or when key auth is unavailable.
+    await doBrowserLogin(identityPath);
+  }
+
+  await postLoginConfigUpdate(identityPath);
+}
+
+/** Complete browser PKCE, then best-effort bootstrap the selected identity. */
+async function doBrowserLogin(identityPath?: string): Promise<void> {
+  console.log("Starting browser-based authentication...");
+  try {
+    const existingConfig = await getConfig();
+    const existingOrgId = existingConfig?.orgId;
+    const browserLoginService = new BrowserLoginService(undefined, existingOrgId);
+    await browserLoginService.login();
+    console.log("✅ Successfully authenticated via browser!");
+
     try {
-      // Pass existing orgId from config (if any) so the browser pre-selects the right org
-      const existingConfig = await getConfig();
-      const existingOrgId = existingConfig?.orgId;
-      const browserLoginService = new BrowserLoginService(undefined, existingOrgId);
-      await browserLoginService.login();
-      console.log("Successfully authenticated via browser!");
-    } catch (error) {
-      console.error("Browser authentication failed:", error.message);
-      console.log("You can try manual JWT login with: knowhow login --jwt");
-      throw error;
+      const keyPair = getOrCreatePublicKey(identityPath);
+      await registerPublicKey(
+        await loadJwt(),
+        keyPair.publicKeyBase64,
+        KNOWHOW_API_URL
+      );
+      console.log(`Registered CLI identity ${keyPair.fingerprint}`);
+    } catch (registrationError: unknown) {
+      // Browser login remains valid when key registration is unavailable (for
+      // example during a rolling backend deployment or for a partial identity).
+      const message = registrationError instanceof Error
+        ? registrationError.message
+        : String(registrationError);
+      console.warn(`Could not register CLI identity (${message}). Browser login is still active.`);
     }
+  } catch (error: unknown) {
+    const msg = error instanceof Error ? error.message : String(error);
+    console.error("Browser authentication failed:", msg);
+    console.log("You can try manual JWT login with: knowhow login --jwt");
+    throw error;
   }
+}
 
-  // Get current user/org information
+/** After any successful login, update the local config with the current user/org. */
+async function postLoginConfigUpdate(identityPath?: string): Promise<void> {
   try {
     const storedJwt = await loadJwt();
     const { user, currentOrg } = await checkJwt(storedJwt);
@@ -59,25 +119,26 @@ export async function login(jwtFlag?: boolean): Promise<void> {
     }
 
     const hasProvider = config.modelProviders.find(
-      (provider) => provider.provider === "knowhow"
+      (provider: { provider: string }) => provider.provider === "knowhow"
     );
     if (!hasProvider) {
-      config.modelProviders.push({
-        provider: "knowhow",
-      });
+      config.modelProviders.push({ provider: "knowhow" });
     }
-    // Save orgId to config so sync:remote and other features use the correct org
+
     if (orgId) {
       config.orgId = orgId;
     }
 
+    if (identityPath) {
+      config.cliIdentityPath = path.resolve(identityPath);
+    }
+
     await updateConfig(config);
-  } catch (error) {
+  } catch (error: unknown) {
     if (http.isHttpError(error) && error.response) {
-      // error.body is the parsed JSON response body (set by http.ts when response is not ok)
-      const errData = error.body ?? { message: "Unknown error" };
+      const errData = (error as any).body ?? { message: "Unknown error" };
       throw new Error(
-        `Error: ${error.status} - ${errData?.message || "Unknown error"}`
+        `Error: ${(error as any).status} - ${errData?.message || "Unknown error"}`
       );
     }
     console.log(
@@ -112,7 +173,7 @@ export async function checkJwt(storedJwt: string) {
   const orgs = user.orgs;
   const orgId = response.data.orgId;
 
-  const currentOrg = orgs.find((org) => {
+  const currentOrg = orgs.find((org: { organizationId: string }) => {
     return org.organizationId === orgId;
   });
 

package/src/plugins/plugins.ts

@@ -52,6 +52,22 @@ export class PluginService {
     return true;
   }
 
+  /** Apply the enabled/disabled state from the current Knowhow config. */
+  async refreshConfiguredState(): Promise<void> {
+    const config = await getConfig();
+    const disabled = new Set(getDisabledPlugins(config.plugins));
+
+    for (const [key, plugin] of this.pluginMap) {
+      if (disabled.has(key)) {
+        plugin.disable();
+      } else {
+        // Configuration is authoritative when services start or reload. This
+        // also re-enables a plugin after it is removed from `disabled`.
+        plugin.enable();
+      }
+    }
+  }
+
   /* -------- existing public API (updated for compatibility) ---------------------- */
 
   listPlugins() {

package/src/processors/TokenCompressor.ts

@@ -7,6 +7,7 @@ import {
   CompressionMetadata,
   JsonCompressorStorage,
 } from "./JsonCompressor";
+import { paginateToolResponse } from "./tools/boundedToolResponse";
 
 export interface KeyInfo {
   key: string;
@@ -419,15 +420,25 @@ export class TokenCompressor implements JsonCompressorStorage {
     if (toolsService) {
       toolsService.addTools([expandTokensDefinition]);
       toolsService.addFunctions({
-        [this.toolName]: (key: string, fromLine?: number, toLine?: number) => {
+        [this.toolName]: (
+          key: string,
+          fromLine?: number,
+          toLine?: number,
+          characterOffset?: number,
+          maxCharacters?: number
+        ) => {
           // Auto-stitch: follow any NEXT_CHUNK_KEY chain and return the full,
           // reassembled content so the agent never has to chase nested keys.
           const data = this.retrieveFullString(key);
 
           if (data === null) {
-            return `Error: No data found for key "${key}". Available keys: ${this.getStorageKeys().join(
-              ", "
-            )}`;
+            return paginateToolResponse(
+              `Error: No data found for key "${key}". Available keys: ${this.getStorageKeys().join(
+                ", "
+              )}`,
+              { characterOffset, maxCharacters },
+              "available-key list"
+            );
           }
 
           // Optional ranged read: return only the requested 1-based, inclusive
@@ -435,7 +446,11 @@ export class TokenCompressor implements JsonCompressorStorage {
           const hasRange =
             typeof fromLine === "number" || typeof toLine === "number";
           if (!hasRange) {
-            return data;
+            return paginateToolResponse(
+              data,
+              { characterOffset, maxCharacters },
+              `expanded value for ${key}`
+            );
           }
 
           const lines = data.split("\n");
@@ -447,14 +462,22 @@ export class TokenCompressor implements JsonCompressorStorage {
           );
 
           if (start > end) {
-            return `Error: Invalid line range for key "${key}": fromLine (${start}) is greater than toLine (${end}). Content has ${totalLines} lines.`;
+            return paginateToolResponse(
+              `Error: Invalid line range for key "${key}": fromLine (${start}) is greater than toLine (${end}). Content has ${totalLines} lines.`,
+              { characterOffset, maxCharacters },
+              "line-range error"
+            );
           }
 
           const numbered: string[] = [];
           for (let i = start; i <= end; i++) {
             numbered.push(`${i}: ${lines[i - 1]}`);
           }
-          return numbered.join("\n");
+          return paginateToolResponse(
+            numbered.join("\n"),
+            { characterOffset, maxCharacters },
+            `expanded lines ${start}-${end} for ${key}`
+          );
         },
       });
     }
@@ -559,7 +582,7 @@ export const expandTokensDefinition: Tool = {
   function: {
     name: "expandTokens",
     description:
-      "Retrieve compressed data that was stored during message processing. The full content is automatically reassembled (any chunk chain is followed for you, so you never need to chase NEXT_CHUNK_KEY references). Optionally pass fromLine/toLine (1-based, inclusive) to return just a range of lines, prefixed with real line numbers. NOTE: Can also use jqToolResponse, grepToolResponse, tailToolResponse to access/filter/search compressed content without needing to expand all tokens.",
+      "Retrieve a bounded page of compressed data. Chunk chains are automatically reassembled, but output is limited to 20,000 characters by default. Use characterOffset to continue, or fromLine/toLine for line-based selection. Prefer jqToolResponse, grepToolResponse, or tailToolResponse when possible.",
     parameters: {
       type: "object",
       positional: true,
@@ -578,6 +601,15 @@ export const expandTokensDefinition: Tool = {
           description:
             "Optional 1-based end line (inclusive). Defaults to the end of the content when omitted.",
         },
+        characterOffset: {
+          type: "number",
+          description:
+            "Optional zero-based character offset within the expanded value or selected line range.",
+        },
+        maxCharacters: {
+          type: "number",
+          description: "Response size (default 20000, hard maximum 50000).",
+        },
       },
       required: ["key"],
     },

package/src/processors/ToolResponseCache.ts

@@ -5,6 +5,7 @@ import { JsonCompressor } from "./JsonCompressor";
 import {
   jqToolResponseDefinition,
   executeJqQuery,
+  JqOptions,
   grepToolResponseDefinition,
   executeGrep,
   GrepOptions,
@@ -13,6 +14,7 @@ import {
   TailOptions,
   listStoredToolResponsesDefinition,
   executeListStoredToolResponses,
+  ListStoredToolResponsesOptions,
 } from "./tools";
 
 interface ToolResponseStorage {
@@ -196,11 +198,12 @@ export class ToolResponseCache {
    */
   async queryToolResponse(
     toolCallId: string,
-    jqQuery: string
+    jqQuery: string,
+    options?: JqOptions
   ): Promise<string> {
     const data = this.storage[toolCallId];
     const availableIds = Object.keys(this.storage);
-    return executeJqQuery(data, toolCallId, jqQuery, availableIds, this.toolNameMap);
+    return executeJqQuery(data, toolCallId, jqQuery, availableIds, this.toolNameMap, options);
   }
 
   /**
@@ -231,11 +234,14 @@ export class ToolResponseCache {
   /**
    * List all stored tool responses with metadata
    */
-  async listStoredToolResponses(): Promise<string> {
+  async listStoredToolResponses(
+    options?: ListStoredToolResponsesOptions
+  ): Promise<string> {
     return executeListStoredToolResponses(
       this.storage,
       this.metadataStorage,
-      this.toolNameMap
+      this.toolNameMap,
+      options
     );
   }
 
@@ -281,9 +287,10 @@ export class ToolResponseCache {
     toolsService.addFunctions({
       [jqToolResponseDefinition.function.name]: async (
         toolCallId: string,
-        jqQuery: string
+        jqQuery: string,
+        options?: JqOptions
       ) => {
-        return await this.queryToolResponse(toolCallId, jqQuery);
+        return await this.queryToolResponse(toolCallId, jqQuery, options);
       },
       [grepToolResponseDefinition.function.name]: async (
         toolCallId: string,
@@ -298,8 +305,10 @@ export class ToolResponseCache {
       ) => {
         return await this.tailToolResponse(toolCallId, options);
       },
-      [listStoredToolResponsesDefinition.function.name]: async () => {
-        return await this.listStoredToolResponses();
+      [listStoredToolResponsesDefinition.function.name]: async (
+        options?: ListStoredToolResponsesOptions
+      ) => {
+        return await this.listStoredToolResponses(options);
       },
     });
   }

package/src/processors/tools/boundedToolResponse.ts

@@ -0,0 +1,49 @@
+export const DEFAULT_TOOL_RESPONSE_CHARACTERS = 20_000;
+export const MAX_TOOL_RESPONSE_CHARACTERS = 50_000;
+
+export function boundedInteger(
+  value: number | undefined,
+  fallback: number,
+  min: number,
+  max: number
+): number {
+  return Math.min(
+    max,
+    Math.max(min, Number.isFinite(value) ? Math.floor(value as number) : fallback)
+  );
+}
+
+/** Return a bounded character page with instructions for retrieving the next page. */
+export function paginateToolResponse(
+  value: string,
+  options?: { characterOffset?: number; maxCharacters?: number },
+  label = "response"
+): string {
+  const characterOffset = boundedInteger(
+    options?.characterOffset,
+    0,
+    0,
+    Number.MAX_SAFE_INTEGER
+  );
+  const maxCharacters = boundedInteger(
+    options?.maxCharacters,
+    DEFAULT_TOOL_RESPONSE_CHARACTERS,
+    1_000,
+    MAX_TOOL_RESPONSE_CHARACTERS
+  );
+  const footerReserve = 300;
+  const contentLimit = Math.max(1, maxCharacters - footerReserve);
+  const page = value.slice(characterOffset, characterOffset + contentLimit);
+  const end = characterOffset + page.length;
+  if (characterOffset === 0 && end >= value.length) {
+    return page;
+  }
+
+  const safeLabel = label.slice(0, 200);
+  const footer =
+    end < value.length
+      ? `\n\n[${safeLabel} characters ${characterOffset}-${Math.max(characterOffset, end - 1)} of ${value.length}. Repeat with characterOffset=${end} to continue; maxCharacters=${maxCharacters}.]`
+      : `\n\n[End of ${safeLabel}; characters ${characterOffset}-${Math.max(characterOffset, end - 1)} of ${value.length}.]`;
+
+  return (page + footer).slice(0, maxCharacters);
+}