@tyvm/knowhow 0.0.145 → 0.0.147

package/src/services/Tools.ts

@@ -1,4 +1,5 @@
 import { ChatCompletionTool } from "openai/resources/chat";
+import { TraceAll } from "../util/Trace";
 import { replaceEscapedNewLines, restoreEscapedNewLines } from "../utils";
 import { includedTools } from "../agents/tools/list";
 import { AgentService } from "./AgentService";
@@ -61,6 +62,7 @@ export interface ToolContext {
  * larger context bloat from having every tool defined in system prompt
  *
  */
+@TraceAll()
 export class ToolsService {
   private context: ToolContext = {};
 
@@ -79,6 +81,17 @@ export class ToolsService {
     }
   }
 
+  /**
+   * Remove every registered tool and handler while retaining service context,
+   * wrappers, and overrides. Runtime reload uses this before rebuilding the
+   * catalog from built-ins, MCP servers, and configured modules.
+   */
+  resetTools(): void {
+    this.tools = [];
+    this.functions = {};
+    this.originalFunctions = {};
+  }
+
   getContext(): ToolContext {
     return this.context;
   }

package/src/services/TracingService.ts

@@ -0,0 +1,116 @@
+/**
+ * TracingService — a zero-dependency, no-op-by-default tracing abstraction
+ * for the @tyvm/knowhow core package.
+ *
+ * The core package ships with NO OpenTelemetry dependencies. This service
+ * defines the interface that the decorators in `src/util/Trace.ts` call into,
+ * and holds a singleton "current tracer" that starts as a no-op.
+ *
+ * A module (e.g. @tyvm/knowhow-module-tracing) can call
+ * `TracingService.register(impl)` during its `init()` to swap in a real OTEL
+ * implementation. After that, every @Trace / @TraceAll / tracify call in the
+ * knowhow codebase will produce real spans — with zero changes to the core.
+ */
+
+export interface SpanHandle {
+  /** Set a string/number/boolean attribute on the span. */
+  setAttribute(key: string, value: string | number | boolean): void;
+  /** Mark the span as errored and record the exception. */
+  recordError(err: unknown): void;
+  /** End the span (records wall-clock end time). */
+  end(): void;
+}
+
+export interface TracerImpl {
+  /**
+   * Start a span. The implementation is responsible for making it a child of
+   * the currently-active span (via OpenTelemetry context propagation or
+   * equivalent).
+   *
+   * @param name        Span name, e.g. "ClassName.methodName"
+   * @param attributes  Initial attributes to attach
+   */
+  startSpan(
+    name: string,
+    attributes?: Record<string, string | number | boolean>
+  ): SpanHandle;
+
+  /**
+   * Run `fn` with the given span active so that child spans created inside it
+   * are automatically parented to this one.
+   *
+   * If context propagation is not supported, implementations can simply call
+   * `fn()` directly.
+   */
+  withSpan<T>(span: SpanHandle, fn: () => T): T;
+}
+
+// ─── No-op implementation used until a real tracer is registered ─────────────
+
+const noopSpan: SpanHandle = {
+  setAttribute() {},
+  recordError() {},
+  end() {},
+};
+
+const noopTracer: TracerImpl = {
+  startSpan() {
+    return noopSpan;
+  },
+  withSpan(_span, fn) {
+    return fn();
+  },
+};
+
+// ─── Singleton state ──────────────────────────────────────────────────────────
+
+let _impl: TracerImpl = noopTracer;
+
+/**
+ * TracingService — access point for the current tracer implementation.
+ *
+ * Usage in decorators / instrumentation code:
+ * ```ts
+ * import { TracingService } from '../services/TracingService';
+ * const span = TracingService.startSpan('MyClass.myMethod');
+ * ```
+ *
+ * Usage in a module to plug in a real OTEL tracer:
+ * ```ts
+ * import { TracingService } from '@tyvm/knowhow/...';
+ * TracingService.register(myOtelTracerImpl);
+ * ```
+ */
+export const TracingService = {
+  /**
+   * Register a real tracer implementation. Called by the tracing module during
+   * `init()`. The registration is global and immediate — all subsequent
+   * decorator/tracify calls will use this implementation.
+   */
+  register(impl: TracerImpl): void {
+    _impl = impl;
+  },
+
+  /** Reset to the no-op tracer (useful for tests). */
+  reset(): void {
+    _impl = noopTracer;
+  },
+
+  /** Whether a real (non-no-op) tracer has been registered. */
+  isEnabled(): boolean {
+    return _impl !== noopTracer;
+  },
+
+  /** Start a span using the current implementation. */
+  startSpan(
+    name: string,
+    attributes?: Record<string, string | number | boolean>
+  ): SpanHandle {
+    return _impl.startSpan(name, attributes);
+  },
+
+  /** Run a function with a span active (context propagation). */
+  withSpan<T>(span: SpanHandle, fn: () => T): T {
+    return _impl.withSpan(span, fn);
+  },
+};

package/src/services/index.ts

@@ -15,8 +15,10 @@ import { SessionManager } from "./SessionManager";
 import { TaskRegistry } from "./TaskRegistry";
 import { MediaProcessorService } from "./MediaProcessorService";
 import { BehaviorsService } from "./BehaviorsService";
+import { RuntimeReloadService } from "./RuntimeReloadService";
 
 import { ConversionService } from "./conversion/ConversionService";
+import { TracingService } from "./TracingService";
 
 export * from "./AgentService";
 export * from "./EventService";
@@ -38,13 +40,18 @@ export * from "./SyncedAgentWatcher";
 export * from "./SyncerService";
 export * from "./watchers";
 export { Clients } from "../clients";
+export * from "../util/Trace";
+export { TracingService } from "./TracingService";
+export type { TracerImpl, SpanHandle } from "./TracingService";
 export * from "./conversion";
+export * from "./RuntimeReloadService";
 export { BehaviorsService } from "./BehaviorsService";
 
 let Singletons = {} as {
   Tools: ToolsService;
   Events: EventService;
   Agents: AgentService;
+  Tracing: typeof TracingService;
   Embeddings: EmbeddingsService;
   Flags: FlagsService;
   Mcp: McpService;
@@ -56,6 +63,7 @@ let Singletons = {} as {
   MediaProcessor: MediaProcessorService;
   Conversion: ConversionService;
   Behaviors: BehaviorsService;
+  RuntimeReload: RuntimeReloadService;
 };
 
 export const services = (): typeof Singletons => {
@@ -76,6 +84,7 @@ export const services = (): typeof Singletons => {
     Singletons = {
       Agents,
       AwsS3: new S3Service(),
+      Tracing: TracingService,
       Clients,
       Docker: new DockerService(),
       Events,
@@ -88,6 +97,7 @@ export const services = (): typeof Singletons => {
       Tools,
       knowhowApiClient: new KnowhowSimpleClient(),
       Behaviors,
+      RuntimeReload: new RuntimeReloadService(),
     };
 
     Singletons.Tools.setContext({

package/src/services/modules/index.ts

@@ -39,6 +39,13 @@ function globalResolvePaths(): string[] {
 }
 
 export class ModulesService {
+  private _loadedModules: {
+    modulePath: string;
+    resolvedPath: string;
+    module: KnowhowModule;
+    params: any;
+  }[] = [];
+
   async getDefaultContext() {
     return { ...services() };
   }
@@ -87,6 +94,7 @@ export class ModulesService {
     //     best driver during phase 2.
     const loadedModules: {
       modulePath: string;
+      resolvedPath: string;
       module: KnowhowModule;
     }[] = [];
 
@@ -128,6 +136,7 @@ export class ModulesService {
       // global install).
       let importedModule: KnowhowModule;
       let loaded = false;
+      let selectedResolvedPath = modulePath;
       const errors: { candidate: string; error: Error }[] = [];
       for (const resolvedPath of candidates) {
         try {
@@ -147,6 +156,7 @@ export class ModulesService {
               context: context as ModuleContext,
             });
           }
+          selectedResolvedPath = resolvedPath;
           loaded = true;
           break;
         } catch (err: any) {
@@ -168,12 +178,17 @@ export class ModulesService {
         );
         continue;
       }
-      loadedModules.push({ modulePath, module: importedModule });
+      loadedModules.push({
+        modulePath,
+        resolvedPath: selectedResolvedPath,
+        module: importedModule,
+      });
     }
 
     // Phase 2: init every successfully-loaded module now that all `register`
     // phases have run and injected their services into `context`.
-    for (const { modulePath, module: importedModule } of loadedModules) {
+    for (const { modulePath, resolvedPath, module: importedModule } of loadedModules) {
+      const initParams = { config, cwd: process.cwd(), context: context as ModuleContext };
       try {
         await importedModule.init({
           config,
@@ -190,6 +205,8 @@ export class ModulesService {
         );
         continue;
       }
+      this._loadedModules.push({ modulePath, resolvedPath, module: importedModule, params: initParams });
+
       // Only register tools/agents/plugins/clients if the relevant services
       // are available in context (they may not be during early CLI command registration)
       if (context.Agents) {
@@ -226,6 +243,32 @@ export class ModulesService {
     }
   }
 
+  /**
+   * Call `destroy()` on every successfully-initialized module, in reverse
+   * initialization order (last-in, first-out). Errors are caught and logged
+   * so one broken module does not prevent others from cleaning up.
+   */
+  async destroyModules() {
+    const toDestroy = [...this._loadedModules].reverse();
+    // Clear first so repeated shutdown/reload attempts cannot destroy twice.
+    this._loadedModules = [];
+    for (const { modulePath, resolvedPath, module: mod, params } of toDestroy) {
+      if (typeof mod.destroy === "function") {
+        try {
+          await mod.destroy(params);
+        } catch (err: any) {
+          process.stderr.write(
+            `\n⚠️  Error in module destroy "${modulePath}": ${err?.message || err}\n\n`
+          );
+        }
+      }
+      // Re-require the entry point so source/configuration changes are visible.
+      if (require.cache[resolvedPath]) {
+        delete require.cache[resolvedPath];
+      }
+    }
+  }
+
   async loadModulesFromConfig(context?: ModuleContext) {
     const config = await getConfig();
 
@@ -241,9 +284,12 @@ export class ModulesService {
 
     // Load global-config modules resolving against the global install's
     // node_modules (~/.knowhow/node_modules) first.
+    // Pass a merged config so that keys defined in the global config (e.g.
+    // `tracing`) are visible to globally-declared modules during init().
+    // Local config keys take precedence so that local overrides still work.
     if (globalModules.length > 0) {
       await this.loadModulesFrom(
-        { ...config, modules: globalModules },
+        { ...globalConfig, ...config, modules: globalModules },
         context,
         globalResolvePaths()
       );

package/src/services/modules/types.ts

@@ -16,6 +16,7 @@ import { ConversionService } from "../conversion/ConversionService";
 import { BehaviorsService } from "../BehaviorsService";
 import { ComputerUseService } from "./computerUse";
 
+import { TracingService as TracingServiceType } from "../TracingService";
 /*
  *
  * A a module should allow the dynamic composition of npm modules that are installed globally by referencing an array of config
@@ -66,6 +67,7 @@ export interface ModuleContext {
   Behaviors?: BehaviorsService;
   ComputerUse?: ComputerUseService;
   [key: string]: any;
+  Tracing?: typeof TracingServiceType;
 }
 
 export interface KnowhowModule {
@@ -89,6 +91,12 @@ export interface KnowhowModule {
    * services registered by other modules' `register` phase, etc.).
    */
   init: (params: InitParams) => Promise<void>;
+  /**
+   * Phase 3 (optional): called when the CLI is shutting down. Use this to
+   * cleanly release resources — close connections, flush buffers, stop
+   * watchers, etc. Mirror of `init`.
+   */
+  destroy?: (params: InitParams) => Promise<void>;
   commands: ModuleChatCommand[];
   tools: ModuleTool[];
   agents: ModuleAgent[];

package/src/types.ts

@@ -75,6 +75,8 @@ export type Config = {
   promptsDir: string;
   lintCommands?: { [fileExtension: string]: string };
   orgId?: string;
+  /** Private Ed25519 identity selected with `knowhow login --identity`. */
+  cliIdentityPath?: string;
   syncRemote?: boolean;
   micCommand?: string;
   defaultMic?: string;

package/src/util/Trace.ts

@@ -0,0 +1,236 @@
+/**
+ * Trace.ts — Method / class decorators and `tracify()` helper for the
+ * @tyvm/knowhow package.
+ *
+ * These decorators are zero-cost when no tracer is registered (the default).
+ * Once `@tyvm/knowhow-module-tracing` (or any other module) calls
+ * `TracingService.register(impl)`, every decorated method starts emitting
+ * real spans automatically — no code changes required.
+ *
+ * API mirrors the backend's `Trace.ts` so patterns learned there carry over:
+ *
+ *   @Trace()            — wrap a single method
+ *   @TraceAll()         — wrap every public method on a class
+ *   tracify(obj, ns)    — wrap an already-constructed instance
+ *
+ * @example
+ * import { Trace, TraceAll, tracify } from '../util/Trace';
+ *
+ * @TraceAll()
+ * export class MessageProcessor {
+ *   async process(msg: Message) { ... }  // → span "MessageProcessor.process"
+ * }
+ *
+ * @Trace()
+ * async fetchEmbeddings(text: string) { ... }  // → span "ClassName.fetchEmbeddings"
+ *
+ * export const myClient = tracify(new SomeClient(), 'someClient');
+ */
+
+import { TracingService } from "../services/TracingService";
+
+// ─── Shared span lifecycle helper ─────────────────────────────────────────────
+
+function runWithSpan<T>(
+  spanName: string,
+  attributes: Record<string, string | number | boolean>,
+  fn: () => T
+): T {
+  const span = TracingService.startSpan(spanName, attributes);
+
+  const finish = (err?: unknown) => {
+    if (err !== undefined) {
+      span.recordError(err);
+    }
+    span.end();
+  };
+
+  try {
+    const result = TracingService.withSpan(span, fn);
+
+    if (result instanceof Promise) {
+      return result.then(
+        (value) => {
+          finish();
+          return value;
+        },
+        (err) => {
+          finish(err);
+          throw err;
+        }
+      ) as unknown as T;
+    }
+
+    finish();
+    return result;
+  } catch (err) {
+    finish(err);
+    throw err;
+  }
+}
+
+// ─── @Trace() — single-method decorator ──────────────────────────────────────
+
+export interface TraceOptions {
+  /** Override the span name (default: `ClassName.methodName`) */
+  spanName?: string;
+  /** Additional static attributes attached to every span */
+  attributes?: Record<string, string | number | boolean>;
+}
+
+/**
+ * @Trace() method decorator — wraps the decorated method in a tracing span.
+ *
+ * Span name defaults to `ClassName.methodName`. Errors are recorded on the
+ * span and re-thrown. Works with both sync and async methods.
+ *
+ * @example
+ * @Trace()
+ * async fetchEmbeddings(text: string) { ... }
+ *
+ * @Trace({ spanName: 'embeddings.fetch', attributes: { 'peer.service': 'openai' } })
+ * async fetchEmbeddings(text: string) { ... }
+ */
+export function Trace(options: TraceOptions = {}) {
+  return function (
+    target: object,
+    propertyKey: string,
+    descriptor: PropertyDescriptor
+  ): PropertyDescriptor {
+    const originalMethod = descriptor.value as (...args: unknown[]) => unknown;
+    const className = (target as any).constructor?.name ?? "Unknown";
+    const resolvedSpanName =
+      options.spanName ?? `${className}.${propertyKey}`;
+    const staticAttrs: Record<string, string | number | boolean> = {
+      "code.function": propertyKey,
+      "code.namespace": className,
+      ...options.attributes,
+    };
+
+    descriptor.value = function (this: unknown, ...args: unknown[]) {
+      return runWithSpan(resolvedSpanName, staticAttrs, () =>
+        originalMethod.apply(this, args)
+      );
+    };
+
+    return descriptor;
+  };
+}
+
+// ─── @TraceAll() — class decorator ───────────────────────────────────────────
+
+export interface TraceAllOptions {
+  /** Additional static attributes attached to every span */
+  attributes?: Record<string, string | number | boolean>;
+  /** Method names to skip (in addition to constructor and `_`-prefixed) */
+  skip?: string[];
+}
+
+/**
+ * @TraceAll() class decorator — wraps every public method on the class in a
+ * tracing span named `ClassName.methodName`.
+ *
+ * Skips the constructor and any methods whose name starts with `_`.
+ *
+ * @example
+ * @TraceAll()
+ * export class MessageProcessor {
+ *   async process(msg: Message) { ... }  // → span "MessageProcessor.process"
+ * }
+ */
+export function TraceAll(options: TraceAllOptions = {}) {
+  const skip = new Set(options.skip ?? []);
+
+  return function <T extends abstract new (...args: unknown[]) => object>(
+    constructor: T
+  ): T {
+    const className = constructor.name;
+    const proto = constructor.prototype as Record<string, unknown>;
+
+    for (const key of Object.getOwnPropertyNames(proto)) {
+      if (key === "constructor") continue;
+      if (key.startsWith("_")) continue;
+      if (skip.has(key)) continue;
+
+      const descriptor = Object.getOwnPropertyDescriptor(proto, key);
+      if (!descriptor || typeof descriptor.value !== "function") continue;
+
+      const originalMethod = descriptor.value as (
+        ...args: unknown[]
+      ) => unknown;
+      const spanName = `${className}.${key}`;
+      const staticAttrs: Record<string, string | number | boolean> = {
+        "code.function": key,
+        "code.namespace": className,
+        ...options.attributes,
+      };
+
+      descriptor.value = function (this: unknown, ...args: unknown[]) {
+        return runWithSpan(spanName, staticAttrs, () =>
+          originalMethod.apply(this, args)
+        );
+      };
+
+      Object.defineProperty(proto, key, descriptor);
+    }
+
+    return constructor;
+  };
+}
+
+// ─── tracify() — instance-level wrapper ──────────────────────────────────────
+
+/**
+ * tracify — wraps every method on an already-constructed object instance in a
+ * tracing span.
+ *
+ * Ideal for third-party singletons (SDK clients etc.) that cannot be decorated
+ * at the class level.
+ *
+ * @param instance   The object whose methods should be traced.
+ * @param namespace  Prefix for span names, e.g. "embeddingsClient".
+ * @param options    Optional extra attributes / skip list.
+ *
+ * @example
+ * export const embeddingsClient = tracify(new OpenAI(), 'openai');
+ */
+export function tracify<T extends object>(
+  instance: T,
+  namespace: string,
+  options: TraceAllOptions = {}
+): T {
+  const skip = new Set(options.skip ?? []);
+
+  return new Proxy(instance, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+      const methodName = typeof prop === "string" ? prop : String(prop);
+
+      // Pass symbols through unwrapped
+      if (typeof prop === "symbol") return value;
+
+      // Skip private / user-skipped names
+      if (methodName.startsWith("_") || skip.has(methodName)) return value;
+
+      // Recursively wrap nested objects (e.g. prisma.user.findMany)
+      if (value !== null && typeof value === "object") {
+        return tracify(value as object, `${namespace}.${methodName}`, options);
+      }
+
+      if (typeof value !== "function") return value;
+
+      const spanName = `${namespace}.${methodName}`;
+      const staticAttrs: Record<string, string | number | boolean> = {
+        "code.function": methodName,
+        "code.namespace": namespace,
+        ...options.attributes,
+      };
+
+      return function (this: unknown, ...args: unknown[]) {
+        return runWithSpan(spanName, staticAttrs, () =>
+          (value as Function).apply(target, args)
+        );
+      };
+    },
+  });
+}

package/src/utils/http.ts

@@ -21,6 +21,15 @@ export class HttpError extends Error {
   }
 }
 
+/**
+ * Optional, non-enumerable hook carried by an authenticated headers object.
+ * The hook may replace an expired credential before one safe 401 retry.
+ */
+export const HTTP_UNAUTHORIZED_HANDLER = Symbol("httpUnauthorizedHandler");
+export type RefreshableHeaders = Record<string, string> & {
+  [HTTP_UNAUTHORIZED_HANDLER]?: () => Promise<void>;
+};
+
 async function parseBody<T>(response: Response, responseType?: string): Promise<T> {
   if (responseType === "arraybuffer") {
     return (await response.arrayBuffer()) as unknown as T;
@@ -41,13 +50,14 @@ async function request<T = any>(
   url: string,
   options: {
     method?: string;
-    headers?: Record<string, string>;
+    headers?: RefreshableHeaders;
     body?: any;
     responseType?: "json" | "arraybuffer" | "stream" | "text";
     params?: Record<string, any>;
     /** Timeout in milliseconds. Default: 30000 (30s). Use 0 to disable. */
     timeout?: number;
-  } = {}
+  } = {},
+  mayRefresh = true
 ): Promise<HttpResponse<T>> {
   const { method = "GET", headers = {}, body, responseType, params, timeout = 30000 } = options;
 
@@ -102,6 +112,12 @@ async function request<T = any>(
   }
 
   if (!response.ok) {
+    const refresh = headers[HTTP_UNAUTHORIZED_HANDLER];
+    if (response.status === 401 && mayRefresh && refresh) {
+      await refresh();
+      return request<T>(url, options, false);
+    }
+
     const text = await response.text().catch(() => "");
     let parsedBody: any;
     try {

package/tests/clients/fireworks.test.ts

@@ -0,0 +1,65 @@
+import http from "../../src/utils/http";
+import { GenericFireworksClient } from "../../src/clients/fireworks";
+import { FireworksModels } from "../../src/clients/pricing/fireworks";
+
+jest.mock("../../src/utils/http", () => ({
+  __esModule: true,
+  default: { post: jest.fn() },
+}));
+
+const post = http.post as jest.MockedFunction<typeof http.post>;
+
+describe("GenericFireworksClient", () => {
+  beforeEach(() => {
+    post.mockReset();
+    post.mockResolvedValue({
+      data: {
+        choices: [{ message: { role: "assistant", content: "ok" } }],
+        model: FireworksModels.DeepseekV4Flash,
+        usage: { prompt_tokens: 2, completion_tokens: 1, total_tokens: 3 },
+      },
+    } as any);
+  });
+
+  it("removes non-Fireworks options and tool return metadata", async () => {
+    const client = new GenericFireworksClient("test-key");
+
+    await client.createChatCompletion({
+      model: FireworksModels.DeepseekV4Flash,
+      messages: [{ role: "user", content: "hello" }],
+      max_tokens: 100,
+      reasoning_summary: true,
+      long_ttl_cache: true,
+      tools: [{
+        type: "function",
+        function: {
+          name: "lookup",
+          description: "Look something up",
+          parameters: { type: "object", properties: {} },
+          returns: { type: "string" },
+        } as any,
+      }],
+    });
+
+    expect(post).toHaveBeenCalledTimes(1);
+    const [url, body, requestOptions] = post.mock.calls[0];
+    expect(url).toBe("https://api.fireworks.ai/inference/v1/chat/completions");
+    expect(requestOptions).toMatchObject({
+      headers: { Authorization: "Bearer test-key" },
+    });
+    expect(body).toMatchObject({
+      model: FireworksModels.DeepseekV4Flash,
+      messages: [{ role: "user", content: "hello" }],
+      max_tokens: 100,
+      tool_choice: "auto",
+    });
+    const serializedBody = JSON.parse(JSON.stringify(body));
+    expect(serializedBody).not.toHaveProperty("reasoning_summary");
+    expect(serializedBody).not.toHaveProperty("long_ttl_cache");
+    expect(serializedBody.tools[0].function).toEqual({
+      name: "lookup",
+      description: "Look something up",
+      parameters: { type: "object", properties: {} },
+    });
+  });
+});