@tyvm/knowhow 0.0.145 → 0.0.146

package/src/processors/tools/tailToolResponse.ts

@@ -1,7 +1,13 @@
 import { Tool } from "../../clients";
+import { boundedInteger, paginateToolResponse } from "./boundedToolResponse";
 
 export interface TailOptions {
   lines?: number;
+  endLine?: number;
+  lineCharacterOffset?: number;
+  maxLineCharacters?: number;
+  characterOffset?: number;
+  maxCharacters?: number;
 }
 
 /**
@@ -21,31 +27,71 @@ export async function executeTail(
         return name ? `${id} (${name})` : id;
       })
       .join("\n  - ");
-    return `Error: No tool response found for toolCallId "${toolCallId}". Call listStoredToolResponses to see all available responses with their tool names.\n\nAvailable toolCallIds:\n  - ${idList || "(none)"}`;
+    return paginateToolResponse(
+      `Error: No tool response found for toolCallId "${toolCallId}". Call listStoredToolResponses to see all available responses with their tool names.\n\nAvailable toolCallIds:\n  - ${idList || "(none)"}`,
+      {
+        characterOffset: options?.characterOffset,
+        maxCharacters: options?.maxCharacters,
+      },
+      "available toolCallId list"
+    );
   }
 
   try {
     const lines = data.split("\n");
-    const numLines = options?.lines ?? 10;
+    const numLines = boundedInteger(options?.lines, 10, 0, 1000);
 
-    // Handle edge case: 0 lines requested
     if (numLines <= 0) {
       return "";
     }
 
-    // Get the last n lines
-    const startIdx = Math.max(0, lines.length - numLines);
-    const tailLines = lines.slice(startIdx);
+    const endLine = boundedInteger(options?.endLine, lines.length, 1, lines.length);
+    const startIdx = Math.max(0, endLine - numLines);
+    const lineCharacterOffset = boundedInteger(
+      options?.lineCharacterOffset,
+      0,
+      0,
+      Number.MAX_SAFE_INTEGER
+    );
+    const maxLineCharacters = boundedInteger(
+      options?.maxLineCharacters,
+      4000,
+      100,
+      10_000
+    );
+    const longLines: number[] = [];
 
-    // Format with line numbers
-    const formatted = tailLines.map((line, idx) => {
-      const lineNum = startIdx + idx + 1;
-      return `${lineNum}: ${line}`;
+    const formatted = lines.slice(startIdx, endLine).map((line, idx) => {
+      const lineNumber = startIdx + idx + 1;
+      const visible = line.slice(
+        lineCharacterOffset,
+        lineCharacterOffset + maxLineCharacters
+      );
+      if (lineCharacterOffset + maxLineCharacters < line.length) {
+        longLines.push(lineNumber);
+      }
+      return `${lineNumber}: ${visible}`;
     });
 
-    return formatted.join("\n");
-  } catch (error: any) {
-    return `Tail Error: ${error.message}`;
+    const notes: string[] = [];
+    if (typeof options?.endLine === "number" && startIdx > 0) {
+      notes.push(`[Earlier lines available: repeat with options.endLine=${startIdx}.]`);
+    }
+    if (longLines.length > 0) notes.push(`[Long lines ${longLines.join(", ")} were sliced; repeat with options.lineCharacterOffset=${lineCharacterOffset + maxLineCharacters}.]`);
+    const rendered =
+      formatted.join("\n") +
+      (notes.length > 0 ? `\n\n${notes.join("\n")}` : "");
+    return paginateToolResponse(
+      rendered,
+      {
+        characterOffset: options?.characterOffset,
+        maxCharacters: options?.maxCharacters,
+      },
+      "tail result"
+    );
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    return `Tail Error: ${message.slice(0, 500)}`;
   }
 }
 
@@ -54,22 +100,44 @@ export const tailToolResponseDefinition: Tool = {
   function: {
     name: "tailToolResponse",
     description:
-      "Get the last n lines from a stored tool response. Similar to the Unix 'tail' command, useful when a tool response is too large and you only need to see the end. Returns the last n lines with line numbers.",
+      "Get a bounded page of lines from the end of a stored tool response. Use endLine to page backward and lineCharacterOffset to page through unusually long lines.",
     parameters: {
       type: "object",
       positional: true,
       properties: {
         toolCallId: {
           type: "string",
-          description: "The toolCallId of the stored tool response",
+          description: "The toolCallId of the stored tool response.",
         },
         options: {
           type: "object",
-          description: "Optional tail settings: lines (number, default: 10) - number of lines to return from the end",
+          description: "Optional tail and pagination settings.",
           properties: {
             lines: {
               type: "number",
-              description: "Number of lines to return from the end (default: 10)",
+              description: "Lines per page (default 10, maximum 1000).",
+            },
+            endLine: {
+              type: "number",
+              description:
+                "1-based inclusive line at which the page ends; use the returned value to page backward.",
+            },
+            lineCharacterOffset: {
+              type: "number",
+              description: "Character offset within each source line.",
+            },
+            maxLineCharacters: {
+              type: "number",
+              description:
+                "Characters shown per line (default 4000, maximum 10000).",
+            },
+            characterOffset: {
+              type: "number",
+              description: "Character offset within the rendered tail page.",
+            },
+            maxCharacters: {
+              type: "number",
+              description: "Response size (default 20000, hard maximum 50000).",
             },
           },
         },

package/src/services/LazyToolsService.ts

@@ -80,6 +80,13 @@ export class LazyToolsService extends ToolsService {
     return this.tools; // Returns filtered subset
   }
 
+  /** Rebuild the lazy catalog while preserving enable/disable preferences. */
+  resetTools(): void {
+    this.allTools = [];
+    super.resetTools();
+    this.registerLazyTools();
+  }
+
   // Enable tools matching glob patterns
   enableTools(patterns: string[]) {
     for (const pattern of patterns) {

package/src/services/Mcp.ts

@@ -388,8 +388,15 @@ export class McpService {
   }
 
   async closeAll() {
-    await this.closeTransports();
-    await this.closeClients();
+    await Promise.allSettled([this.closeTransports()]);
+    await Promise.allSettled([this.closeClients()]);
+    // Connections are recreated from freshly-read configuration after reload.
+    this.clients = [];
+    this.transports = [];
+    this.connected = [];
+    this.config = [];
+    this.tools = [];
+    this.toolAliases = {};
   }
 
   getClientIndex(clientName: string) {

package/src/services/RuntimeReloadService.ts

@@ -0,0 +1,31 @@
+export interface RuntimeReloadResult {
+  tools: number;
+  mcps: number;
+  modules: number;
+}
+
+/** Coordinates in-place runtime refreshes and coalesces concurrent requests. */
+export class RuntimeReloadService {
+  private handler?: () => Promise<RuntimeReloadResult>;
+  private pending?: Promise<RuntimeReloadResult>;
+
+  configure(handler: () => Promise<RuntimeReloadResult>): void {
+    this.handler = handler;
+  }
+
+  isConfigured(): boolean {
+    return !!this.handler;
+  }
+
+  reload(): Promise<RuntimeReloadResult> {
+    if (!this.handler) {
+      return Promise.reject(new Error("Runtime reload is unavailable for this command"));
+    }
+    if (!this.pending) {
+      this.pending = this.handler().finally(() => {
+        this.pending = undefined;
+      });
+    }
+    return this.pending;
+  }
+}

package/src/services/Tools.ts

@@ -79,6 +79,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,7 +40,11 @@ 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 {
@@ -56,6 +62,7 @@ let Singletons = {} as {
   MediaProcessor: MediaProcessorService;
   Conversion: ConversionService;
   Behaviors: BehaviorsService;
+  RuntimeReload: RuntimeReloadService;
 };
 
 export const services = (): typeof Singletons => {
@@ -88,6 +95,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();
 

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[];