@tyvm/knowhow 0.0.146 → 0.0.148

package/src/services/AgentSyncFs.ts

@@ -3,6 +3,7 @@
  * Handles synchronization via filesystem files in .knowhow/processes/agents/taskId/
  */
 import { BaseAgent } from "../agents/base/base";
+import { TraceAll } from "../util/Trace";
 import { promises as fs } from "fs";
 import * as path from "path";
 import { watch } from "fs";
@@ -19,6 +20,7 @@ export interface FsSyncOptions {
  * AgentSyncFs handles filesystem-based synchronization for agent tasks
  * Creates files in .knowhow/processes/agents/{taskId}/ for status and input
  */
+@TraceAll()
 export class AgentSyncFs {
   /** Shared cleanup interval across all instances to avoid duplicate cleanup runs */
   private static sharedCleanupInterval: NodeJS.Timeout | null = null;
@@ -122,12 +124,83 @@ export class AgentSyncFs {
 
     try {
       const metadataPath = path.join(this.taskPath, "metadata.json");
-      await fs.writeFile(metadataPath, JSON.stringify(data, null, 2), "utf8");
+      // Thread/status updates are partial snapshots. Merge them so stable
+      // orchestration identity written by createTask (taskId, pid and parent)
+      // is never discarded by a later update.
+      let existing: Record<string, unknown> = {};
+      try {
+        existing = JSON.parse(await fs.readFile(metadataPath, "utf8"));
+      } catch { /* first write or an interrupted legacy write */ }
+      await fs.writeFile(
+        metadataPath,
+        JSON.stringify({ ...existing, ...data }, null, 2),
+        "utf8"
+      );
     } catch (error) {
       console.error(`❌ Failed to write metadata:`, error);
     }
   }
 
+  /**
+   * Persist the remote identity alongside the local task. Keeping the local
+   * slug and remote UUID as separate fields lets resume reconnect without ever
+   * mistaking one for the other.
+   */
+  static async persistRemoteIdentity(
+    taskId: string,
+    remoteTaskId: string,
+    remoteMessageId?: string
+  ): Promise<void> {
+    const taskPath = path.join(AgentSyncFs.sharedBasePath, taskId);
+    await AgentSyncFs.writeRemoteIdentity(
+      taskPath,
+      remoteTaskId,
+      remoteMessageId
+    );
+  }
+
+  async setRemoteIdentity(
+    remoteTaskId: string,
+    remoteMessageId?: string
+  ): Promise<void> {
+    if (!this.taskPath) return;
+    await AgentSyncFs.writeRemoteIdentity(this.taskPath, remoteTaskId, remoteMessageId);
+  }
+
+  private static async writeRemoteIdentity(
+    taskPath: string,
+    remoteTaskId: string,
+    remoteMessageId?: string
+  ): Promise<void> {
+    try {
+      const metadataPath = path.join(taskPath, "metadata.json");
+      let metadata: any = {};
+      try {
+        metadata = JSON.parse(await fs.readFile(metadataPath, "utf8"));
+      } catch {
+        // The normal path already created metadata, but recover if it was
+        // removed or malformed while the task was running.
+      }
+
+      metadata.remoteTaskId = remoteTaskId;
+      // Preserve the established session field name for compatibility with
+      // callers that already read knowhowTaskId.
+      metadata.knowhowTaskId = remoteTaskId;
+      if (remoteMessageId) {
+        metadata.remoteMessageId = remoteMessageId;
+        metadata.knowhowMessageId = remoteMessageId;
+      }
+
+      await fs.writeFile(
+        metadataPath,
+        JSON.stringify(metadata, null, 2),
+        "utf8"
+      );
+    } catch (error) {
+      console.error(`❌ Failed to persist remote task identity:`, error);
+    }
+  }
+
   /**
    * Append a token usage entry (including the full message chain sent for
    * that call) to usage.json. This is intended for debugging cache-hit
@@ -217,6 +290,9 @@ export class AgentSyncFs {
       // thread messages via `_reasoning_details` / `reasoning_summary`.)
       metadata.reasoningEffort = agent.getReasoningEffort?.();
       metadata.summarizeReasoning = agent.getSummarizeReasoning?.();
+      // Tool schemas are part of the provider cache prefix. Preserve the exact
+      // request-visible list so resume/fork can recreate the same request.
+      metadata.enabledTools = agent.getEnabledToolNames();
       metadata.inProgress = inProgress;
       metadata.lastUpdate = new Date().toISOString();
 

package/src/services/AgentSyncKnowhowWeb.ts

@@ -10,6 +10,7 @@ import {
 } from "./KnowhowClient";
 import { BaseAgent } from "../agents/base/base";
 import { wait } from "../utils";
+import { TraceAll } from "../util/Trace";
 
 export interface SyncOptions {
   messageId?: string;
@@ -27,6 +28,7 @@ export interface TaskSyncState {
  * AgentSynchronization handles all communication with the Knowhow API
  * for task creation, updates, status polling, and message synchronization
  */
+@TraceAll()
 export class AgentSyncKnowhowWeb {
   private client: KnowhowSimpleClient;
   private baseUrl: string;
@@ -36,6 +38,7 @@ export class AgentSyncKnowhowWeb {
   private agent: BaseAgent | undefined;
   private threadUpdateHandler: ((...args: any[]) => void) | undefined;
   private doneHandler: ((...args: any[]) => void) | undefined;
+  private syncErrorLogged = false;
   /**
    * Tracks the most recent in-flight thread update API call.
    * The done handler awaits this before sending the finalization call,
@@ -48,6 +51,17 @@ export class AgentSyncKnowhowWeb {
     this.client = new KnowhowSimpleClient(baseUrl);
   }
 
+  /**
+   * Remote outages can make both the update and pending-message requests fail
+   * on every thread event. Report the first failure for this task, then stay
+   * quiet so an unavailable optional sync service does not flood the chat.
+   */
+  private reportSyncErrorOnce(message: string, error: unknown): void {
+    if (this.syncErrorLogged) return;
+    this.syncErrorLogged = true;
+    console.error(message, error);
+  }
+
   /**
    * Create a new chat task in Knowhow
    */
@@ -68,7 +82,7 @@ export class AgentSyncKnowhowWeb {
       console.log(`✅ Created Knowhow chat task: ${knowhowTaskId}`);
       return knowhowTaskId;
     } catch (error) {
-      console.error(`❌ Failed to create Knowhow chat task:`, error);
+      this.reportSyncErrorOnce(`❌ Failed to create Knowhow chat task:`, error);
       return undefined;
     }
   }
@@ -95,7 +109,7 @@ export class AgentSyncKnowhowWeb {
       });
       console.log(`✅ Updated Knowhow chat task: ${knowhowTaskId}`);
     } catch (error) {
-      console.error(`❌ Failed to update Knowhow chat task:`, error);
+      this.reportSyncErrorOnce(`❌ Failed to update Knowhow chat task:`, error);
     }
   }
 
@@ -167,7 +181,10 @@ export class AgentSyncKnowhowWeb {
       await this.client.markMessagesAsProcessed(knowhowTaskId, messageIds);
       console.log(`✅ Marked ${messageIds.length} message(s) as processed`);
     } catch (error) {
-      console.error(`❌ Error checking/processing pending messages:`, error);
+      this.reportSyncErrorOnce(
+        `❌ Error checking/processing pending messages:`,
+        error
+      );
       // Continue execution even if synchronization fails
     }
   }
@@ -226,7 +243,7 @@ export class AgentSyncKnowhowWeb {
         }
         // Still paused, continue waiting
       } catch (error) {
-        console.error(`❌ Error polling task status:`, error);
+        this.reportSyncErrorOnce(`❌ Error polling task status:`, error);
         // Continue polling even on errors
       }
     }
@@ -350,6 +367,7 @@ export class AgentSyncKnowhowWeb {
     this.eventHandlersSetup = false;
     this.finalizationPromise = null;
     this.pendingThreadUpdatePromise = null;
+    this.syncErrorLogged = false;
   }
 
   /**

package/src/services/BehaviorsService.ts

@@ -4,6 +4,7 @@ import * as os from "os";
 import { KnowhowSimpleClient } from "./KnowhowClient";
 import { createHash } from "crypto";
 import { getConfig } from "../config";
+import { TraceAll } from "../util/Trace";
 
 const BEHAVIORS_DIR = ".knowhow/behaviors";
 const LOCAL_SKILLS_DIRS = [".agents/skills", ".knowhow/skills"];
@@ -30,6 +31,7 @@ export interface Behavior {
  * In-memory singleton for behaviors/skills.
  * Call initFromDisk() once at startup; tools then read from memory.
  */
+@TraceAll()
 export class BehaviorsService {
   private behaviors: Behavior[] = [];
   private skills: Behavior[] = [];

package/src/services/DockerService.ts

@@ -4,6 +4,7 @@ import * as os from "os";
 import { Config } from "../types";
 import { updateConfig } from "../config";
 import * as crypto from "crypto";
+import { TraceAll } from "../util/Trace";
 
 export interface DockerWorkerOptions {
   workspaceDir: string;
@@ -14,6 +15,7 @@ export interface DockerWorkerOptions {
   unshare?: boolean;
 }
 
+@TraceAll()
 export class DockerService {
   private static readonly IMAGE_NAME = "knowhow-worker";
   private static readonly CONTAINER_PREFIX = "knowhow-worker";

package/src/services/EmbeddingService.ts

@@ -1,4 +1,5 @@
 import * as path from "path";
+import { TraceAll } from "../util/Trace";
 import { globSync } from "glob";
 
 import {
@@ -38,6 +39,7 @@ interface EmbeddingServiceContext {
   plugins: PluginService;
 }
 
+@TraceAll()
 export class EmbeddingService {
   private config: Config;
   private embeddingClient: GenericClient;

package/src/services/EmbeddingsService.ts

@@ -20,6 +20,9 @@ export interface EmbeddingsResolver {
  * Modules can register a resolver for a given remoteType (e.g. "github", "s3")
  * via registerResolver(), and the core upload()/download() functions delegate to it.
  */
+import { TraceAll } from "../util/Trace";
+
+@TraceAll()
 export class EmbeddingsService {
   private resolvers = new Map<string, EmbeddingsResolver>();
 

package/src/services/ExtensionsService.ts

@@ -0,0 +1,25 @@
+export interface ModuleExtension {
+  type: string;
+  [key: string]: unknown;
+}
+
+interface RegisteredExtension extends ModuleExtension {
+  owner: string;
+}
+
+/** Process-local registry for optional, consumer-defined module capabilities. */
+export class ExtensionsService {
+  private extensions: RegisteredExtension[] = [];
+
+  register(owner: string, extension: ModuleExtension): void {
+    this.extensions.push({ ...extension, owner });
+  }
+
+  list<T extends ModuleExtension>(type: T["type"]): readonly T[] {
+    return this.extensions.filter((item) => item.type === type) as unknown as readonly T[];
+  }
+
+  removeOwner(owner: string): void {
+    this.extensions = this.extensions.filter((item) => item.owner !== owner);
+  }
+}

package/src/services/KnowhowClient.ts

@@ -1,6 +1,10 @@
 import { createHash } from "crypto";
-import http from "../utils/http";
+import { TraceAll } from "../util/Trace";
+import http, { HTTP_UNAUTHORIZED_HANDLER, RefreshableHeaders } from "../utils/http";
 import fs from "fs";
+import { getConfigSync } from "../config";
+import { exchangePublicKeyJwt, storeJwt } from "../auth/keyAuth";
+import { keyPairExists } from "../auth/keyManager";
 import { Message } from "../clients/types";
 import path from "path";
 import {
@@ -141,17 +145,32 @@ export function loadKnowhowJwt(): string {
 export const KNOWHOW_API_URL =
   process.env.KNOWHOW_API_URL || "https://api.knowhow.tyvm.ai";
 
+@TraceAll()
 export class KnowhowSimpleClient {
-  headers: Record<string, string> = {};
+  headers: RefreshableHeaders = {};
   jwtValidated = false;
+  private readonly canRefreshJwt: boolean;
+  private refreshPromise?: Promise<void>;
 
   constructor(
     private baseUrl = KNOWHOW_API_URL,
-    private jwt = loadKnowhowJwt()
+    jwt?: string
   ) {
-    this.setJwt(jwt);
+    // 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.setJwt(this.jwt);
+    if (this.canRefreshJwt) {
+      Object.defineProperty(this.headers, HTTP_UNAUTHORIZED_HANDLER, {
+        enumerable: false,
+        value: () => this.renewJwt(true),
+      });
+    }
   }
 
+  private jwt: string;
+
   /**
    * Reload the JWT from disk (useful after login refreshes the token).
    */
@@ -165,9 +184,45 @@ export class KnowhowSimpleClient {
 
   setJwt(jwt: string) {
     this.jwt = jwt;
-    this.headers = {
-      Authorization: `Bearer ${this.jwt}`,
-    };
+    // Keep this object stable: the HTTP wrapper retries with the same reference.
+    this.headers.Authorization = `Bearer ${this.jwt}`;
+  }
+
+  private jwtExpiresSoon(): boolean {
+    try {
+      const payload = JSON.parse(Buffer.from(this.jwt.split(".")[1], "base64url").toString("utf8"));
+      return typeof payload.exp === "number" && payload.exp * 1000 - Date.now() < 5 * 60 * 1000;
+    } catch {
+      return false;
+    }
+  }
+
+  private async renewJwt(force = false): Promise<void> {
+    if (!this.canRefreshJwt) return;
+    if (!force && !this.jwtExpiresSoon()) return;
+    if (this.refreshPromise) return this.refreshPromise;
+
+    this.refreshPromise = (async () => {
+      const config = getConfigSync();
+      const identityPath = config.cliIdentityPath;
+      if (!config.orgId || !keyPairExists(identityPath)) {
+        throw new Error("JWT expired and the CLI identity is unavailable. Please run `knowhow login` again.");
+      }
+      try {
+        const freshJwt = await exchangePublicKeyJwt(config.orgId, this.baseUrl, identityPath);
+        storeJwt(freshJwt);
+        this.setJwt(freshJwt);
+        this.jwtValidated = true;
+      } catch (error) {
+        throw new Error(
+          "Unable to renew the CLI session; the identity may have been revoked. Please run `knowhow login` again.",
+          { cause: error }
+        );
+      }
+    })().finally(() => {
+      this.refreshPromise = undefined;
+    });
+    return this.refreshPromise;
   }
 
   async checkJwt() {
@@ -175,6 +230,8 @@ export class KnowhowSimpleClient {
       throw new Error("No JWT found. Please login first.");
     }
 
+    await this.renewJwt();
+
     if (!this.jwtValidated) {
       try {
         this.jwtValidated = true;
@@ -186,6 +243,10 @@ export class KnowhowSimpleClient {
           return org.organizationId === orgId;
         });
       } catch (error) {
+        this.jwtValidated = false;
+        if (error instanceof Error && error.message.includes("renew the CLI session")) {
+          throw error;
+        }
         throw new Error("Invalid JWT. Please login again.");
       }
     }

package/src/services/LazyToolsService.ts

@@ -1,4 +1,5 @@
 import { minimatch } from "minimatch";
+import { TraceAll } from "../util/Trace";
 import { ToolsService, ToolContext, ToolCallContext } from "./Tools";
 import { Tool } from "../clients/types";
 import { ToolCall } from "../clients/types";
@@ -21,6 +22,7 @@ import { definitions } from "../agents/tools/lazy/definitions";
  * In web sessions where you get a new ToolService each interaction, then the cache busting is going to happen with each enable
  *
  */
+@TraceAll()
 export class LazyToolsService extends ToolsService {
   private allTools: Tool[] = [];
   // Start with lazy tools enabled by default
@@ -80,6 +82,15 @@ export class LazyToolsService extends ToolsService {
     return this.tools; // Returns filtered subset
   }
 
+  // Definitions remain resolvable even when omitted from the model prompt.
+  getTool(name: string): Tool {
+    return this.allTools.find(
+      (tool) =>
+        name &&
+        (tool.function.name === name || tool.function.name.endsWith(name))
+    );
+  }
+
   /** Rebuild the lazy catalog while preserving enable/disable preferences. */
   resetTools(): void {
     this.allTools = [];
@@ -104,6 +115,13 @@ export class LazyToolsService extends ToolsService {
     };
   }
 
+  /** Replace glob state with an exact persisted request-visible tool list. */
+  restoreEnabledTools(names: string[]): void {
+    this.enabledPatterns = [...new Set(names)];
+    this.disabledPatterns = [];
+    this.updateVisibleTools();
+  }
+
   // Disable tools matching glob patterns
   disableTools(patterns: string[]) {
     for (const pattern of patterns) {
@@ -146,32 +164,18 @@ export class LazyToolsService extends ToolsService {
     };
   }
 
-  // Override callTool to auto-enable tools that are in allTools but not yet enabled
+  // Prompt visibility is not authorization. Registered functions remain
+  // callable without changing which definitions are sent to the model.
   async callTool(
     toolCall: ToolCall,
     enabledTools?: string[],
     callContext?: ToolCallContext
   ) {
-    const functionName = toolCall.function.name;
-
-    // If the tool isn't currently visible but exists in allTools, auto-enable it.
-    // This handles the case where the agent explicitly calls a tool without first
-    // enabling it via listAvailableTools/enableTools.
-    const isCurrentlyEnabled = this.tools.some(
-      (t) => t.function.name === functionName
-    );
-    const existsInAll = this.allTools.some(
-      (t) => t.function.name === functionName
+    return super.callTool(
+      toolCall,
+      enabledTools ?? this.getFunctionNames(),
+      callContext
     );
-
-    if (!isCurrentlyEnabled && existsInAll) {
-      // Auto-enable by adding the tool name as an exact pattern
-      this.enableTools([functionName]);
-    }
-
-    // Always use the current enabled tool names after any auto-enable above,
-    // so the base class check sees the freshly-enabled tool in the allowed list.
-    return super.callTool(toolCall, this.getToolNames(), callContext);
   }
 
   // Internal: Update visible tools based on patterns

package/src/services/Mcp.ts

@@ -6,6 +6,7 @@ import fs from "fs";
 import { McpConfig } from "../types";
 import { Tool } from "../clients";
 import { getConfig } from "../config";
+import { TraceAll } from "../util/Trace";
 import { ToolsService } from "./Tools";
 import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import { CallToolResultSchema } from "@modelcontextprotocol/sdk/types.js";
@@ -36,6 +37,7 @@ export * from "./McpWebsocketTransport";
  * Each of the tools are namespaced with a prefix: mcp_index_servername_toolName
  * This services handles calls made to the namespaced function name, and finds the proper client to call the tool on.
  */
+@TraceAll()
 export class McpService {
   connected = [];
   transports: Transport[] = [];

package/src/services/McpServer.ts

@@ -6,9 +6,11 @@ import { Tool, ToolProp } from "../clients/types";
 import { ToolsService } from "./Tools";
 import { MCPWebSocketTransport } from "./McpWebsocketTransport";
 import { WebSocket } from "ws";
+import { TraceAll } from "../util/Trace";
 
 export type McpServerConfig = { name: string; version: string };
 
+@TraceAll()
 export class McpServerService {
   server: McpServer | null = null;
   constructor(private toolsService: ToolsService) {}

package/src/services/MessageProcessor.ts

@@ -1,4 +1,5 @@
 import { Message } from "../clients/types";
+import { TraceAll } from "../util/Trace";
 
 export type ProcessorLifecycle =
   | "initial_call"
@@ -17,6 +18,7 @@ export interface ProcessorRegistration {
   priority: number;
 }
 
+@TraceAll()
 export class MessageProcessor {
   private processors: Map<ProcessorLifecycle, ProcessorRegistration[]> =
     new Map();

package/src/services/MinimalToolsService.ts

@@ -5,6 +5,7 @@ import { inspectTools } from "../agents/tools/minimal/inspectTools";
 import { minimalDefinitions } from "../agents/tools/minimal/definitions";
 import { finalAnswer } from "../agents/tools/finalAnswer";
 import { includedTools } from "../agents/tools/list";
+import { TraceAll } from "../util/Trace";
 
 /*
  * MinimalToolsService
@@ -19,6 +20,7 @@ import { includedTools } from "../agents/tools/list";
  * - Works on all providers and older models (no provider-specific defer_loading needed).
  * - Agents discover tools via inspectTools() and call them via callTool().
  */
+@TraceAll()
 export class MinimalToolsService extends ToolsService {
   /** Full catalog of every registered tool (base + extended). */
   private allToolsCatalog: Tool[] = [];

package/src/services/SessionManager.ts

@@ -5,10 +5,12 @@ import * as fs from "fs";
 import * as fsPromises from "fs/promises";
 import * as path from "path";
 import { TaskInfo, ChatSession } from "../chat/types";
+import { TraceAll } from "../util/Trace";
 
 /**
  * SessionManager handles saving, loading, and managing agent sessions
  */
+@TraceAll()
 export class SessionManager {
   private sessionsDir: string;
 
@@ -69,6 +71,7 @@ export class SessionManager {
         provider: taskInfo.provider,
         reasoningEffort: taskInfo.reasoningEffort,
         summarizeReasoning: taskInfo.summarizeReasoning,
+        enabledTools: taskInfo.enabledTools,
       };
 
       fs.writeFileSync(sessionPath, JSON.stringify(session, null, 2));
@@ -115,6 +118,8 @@ export class SessionManager {
             session.reasoningEffort = taskInfo.reasoningEffort;
           if (taskInfo.summarizeReasoning !== undefined)
             session.summarizeReasoning = taskInfo.summarizeReasoning;
+          if (taskInfo.enabledTools !== undefined)
+            session.enabledTools = taskInfo.enabledTools;
         }
 
         fs.writeFileSync(sessionPath, JSON.stringify(session, null, 2));

package/src/services/SkillsService.ts

@@ -4,6 +4,7 @@ import * as os from "os";
 import { createHash } from "crypto";
 import * as https from "https";
 import { KnowhowSimpleClient } from "./KnowhowClient";
+import { TraceAll } from "../util/Trace";
 
 // Default local install dir (relative to cwd)
 const LOCAL_SKILLS_DIR = ".knowhow/skills";
@@ -233,6 +234,7 @@ export function parseSkillRef(
   return { owner, repo, skill, sourceUrl };
 }
 
+@TraceAll()
 export class SkillsService {
   private cwd: string;
   private isGlobal: boolean;

package/src/services/SyncedAgentWatcher.ts

@@ -5,6 +5,7 @@
 
 import { Message } from "../clients/types";
 import { EventService } from "./EventService";
+import { TraceAll } from "../util/Trace";
 
 export interface SyncedAgentWatcher {
   /** Start watching for changes, emitting agent events */
@@ -73,6 +74,7 @@ export interface AttachableAgent {
  * - agentEvents and eventTypes are delegated to the watcher
  * - "done" is emitted by the watcher when the remote agent completes
  */
+@TraceAll()
 export class WatcherBackedAgent implements AttachableAgent {
   public name: string;
   public agentEvents: EventService;