@tyvm/knowhow 0.0.159 → 0.0.161

package/src/services/Tools.ts

@@ -1,580 +0,0 @@
-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";
-import { EventService } from "./EventService";
-import { AIClient } from "../clients";
-import { Tool, ToolCall } from "../clients/types";
-import {
-  ToolOverrideRegistration,
-  ToolWrapperRegistration,
-  ToolOverrideFunction,
-  ToolWrapper,
-  createPatternMatcher,
-} from "./types";
-import { PluginService } from "../plugins/plugins";
-import { McpService } from "./Mcp";
-import { BehaviorsService } from "./BehaviorsService";
-
-/**
- * Per-invocation context passed into a tool call as `_ctx`.
- *
- * This is threaded through `callTool` and delivered to the tool implementation
- * as the LAST positional argument (for positional tools) or merged onto the
- * args object under the `_ctx` key (for non-positional tools).
- *
- * It enables self-referential tools: the calling agent can pass itself in via
- * `caller`, so tools can read `caller.getCurrentTaskId()`, call
- * `caller.addPendingUserMessage(...)`, subscribe to its events, etc. — without
- * relying on shared mutable state on the ToolsService (which would break under
- * concurrent tool usage).
- */
-export interface ToolCallContext {
-  /** The agent (or other entity) that initiated this tool call. */
-  caller?: any;
-  /** The task id of the calling agent, if known. */
-  taskId?: string;
-  /** The task id of the parent agent that spawned the calling agent, if any. */
-  parentTaskId?: string;
-  /** Arbitrary additional per-call context. */
-  [key: string]: any;
-}
-
-export interface ToolContext {
-  Agents?: AgentService;
-  Events?: EventService;
-  Clients?: AIClient;
-  Tools?: ToolsService;
-  Plugins?: PluginService;
-  Mcp?: McpService;
-  Behaviors?: BehaviorsService;
-  ComputerUse?: import("./modules/computerUse").ComputerUseService;
-  metadata?: { [key: string]: any };
-}
-
-/*
- *
- * This ToolService design allows an agent to start with every tool
- *
- * Drawbacks:
- * some providers have limits on how many tools you can use
- * larger context bloat from having every tool defined in system prompt
- *
- */
-@TraceAll()
-export class ToolsService {
-  private context: ToolContext = {};
-
-  tools = [] as Tool[];
-  private overrides: ToolOverrideRegistration[] = [];
-  private wrappers: ToolWrapperRegistration[] = [];
-  private originalFunctions: { [key: string]: (...args: any[]) => any } = {};
-
-  functions = {};
-
-  constructor(context?: ToolContext) {
-    if (context) {
-      this.context = { ...context, Tools: this };
-    } else {
-      this.context = { Tools: this };
-    }
-  }
-
-  /**
-   * 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;
-  }
-
-  setContext(context: ToolContext): void {
-    this.context = { ...context, Tools: this };
-  }
-
-  addContext<K extends keyof ToolContext, V extends ToolContext[K]>(
-    key: K,
-    value: V
-  ): void {
-    this.context[key] = value;
-  }
-
-  getTools() {
-    return this.tools;
-  }
-
-  getToolsByNames(names: string[]) {
-    return this.tools.filter((tool) =>
-      names.some((name) => name && tool.function.name.endsWith(name))
-    );
-  }
-
-  copyToolsFrom(toolNames: string[], toolsService: ToolsService) {
-    const tools = toolsService.getToolsByNames(toolNames);
-    this.addTools(tools);
-
-    for (const name of toolNames) {
-      const fn = toolsService.getFunction(name);
-      if (!fn) {
-        continue;
-      }
-
-      this.setFunction(name, fn);
-    }
-  }
-
-  getToolNames() {
-    return this.tools.map((tool) => tool.function.name);
-  }
-
-  /**
-   * Return every registered function implementation. Unlike getToolNames(),
-   * this is not a prompt-visibility list; lazy tool services may intentionally
-   * hide definitions from the model while keeping their functions callable by
-   * trusted programmatic consumers such as the script runtime.
-   */
-  getFunctionNames(): string[] {
-    return Object.keys(this.functions).filter((name) => typeof this.functions[name] === "function");
-  }
-
-  getTool(name: string): Tool {
-    return this.tools.find(
-      (tool) =>
-        name &&
-        (tool.function.name === name || tool.function.name.endsWith(name))
-    );
-  }
-
-  getFunction(name: string) {
-    // Apply overrides and wrappers before returning (even if no base function exists)
-    const tool = this.getTool(name);
-    const functionName = tool ? tool.function.name : name;
-    if (this.functions[functionName] || this.originalFunctions[functionName]) {
-      this.applyOverridesAndWrappers(functionName);
-    } else {
-      // Check if there are overrides for this name even without a base function
-      const matchingOverride = this.findMatchingOverride(functionName);
-      if (matchingOverride) {
-        this.functions[functionName] = matchingOverride.override;
-      } else {
-        return undefined;
-      }
-    }
-    return this.functions[functionName];
-  }
-
-  setFunction(name: string, func: (...args: any) => any) {
-    // Always update the original function when setFunction is called
-    this.originalFunctions[name] = func.bind(this);
-
-    // Set the function (bound) and apply any overrides/wrappers
-    this.functions[name] = func.bind(this);
-    this.applyOverridesAndWrappers(name);
-  }
-
-  setFunctions(names: string[], funcs: ((...args: any) => any)[]) {
-    for (let i = 0; i < names.length; i++) {
-      if (!names[i] || typeof funcs[i] !== "function") {
-        console.warn("Ignoring invalid function entry at index", i, "with name", names[i]);
-        continue;
-      }
-      this.setFunction(names[i], funcs[i]);
-    }
-  }
-
-  addTool(tool: Tool) {
-    this.tools.push(tool);
-  }
-
-  addTools(tools: Tool[]) {
-    // Prevent duplicate tool names
-    const existingTools = this.getToolNames();
-    const filteredTools = tools.filter(
-      (tool) => !existingTools.includes(tool.function.name)
-    );
-
-    this.tools.push(...filteredTools);
-  }
-
-  addFunctions(fns: { [fnName: string]: (...args: any) => any }) {
-    for (const fnName of Object.keys(fns)) {
-      if (typeof fns[fnName] !== "function") {
-        // Skip non-function entries
-        continue;
-      }
-      this.setFunction(fnName, fns[fnName]);
-    }
-  }
-
-  defineTools(
-    tools: Tool[],
-    functions: { [fnName: string]: ((...args: any) => any) | any }
-  ) {
-    this.addTools(tools);
-    this.addFunctions(functions);
-  }
-
-  async callTool(
-    toolCall: ToolCall,
-    enabledTools = this.getToolNames(),
-    callContext?: ToolCallContext
-  ) {
-    const functionName = toolCall.function.name;
-    let functionArgs: any;
-
-    try {
-      try {
-        functionArgs =
-          typeof toolCall.function.arguments === "string"
-            ? JSON.parse(restoreEscapedNewLines(toolCall.function.arguments))
-            : toolCall.function.arguments;
-      } catch (error) {
-        throw new Error(
-          `Invalid JSON in tool call arguments: ${error.message}`
-        );
-      }
-
-      // Check if tool is enabled
-      if (!enabledTools.some((t) => t.endsWith(functionName))) {
-        const options = enabledTools.join(", ");
-        throw new Error(
-          `Function ${functionName} not enabled, options are ${options}`
-        );
-      }
-
-      // Check if tool definition exists
-      const toolDefinition = this.getTool(functionName);
-      if (!toolDefinition) {
-        throw new Error(`Tool ${functionName} not found`);
-      }
-
-      // Check if function implementation exists
-      // toolDefinition holds the real fn name
-      const toolName = toolDefinition.function.name;
-      const functionToCall = this.getFunction(toolName);
-      if (!functionToCall) {
-        const options = enabledTools.join(", ");
-        throw new Error(
-          `Function ${toolName} not found, options are ${options}`
-        );
-      }
-
-      // Prepare function arguments
-      const properties = toolDefinition?.function?.parameters?.properties || {};
-      const isPositional =
-        toolDefinition?.function?.parameters?.positional || false;
-      const usesContext =
-        toolDefinition?.function?.parameters?.usesContext || false;
-
-      // Thread the per-call context (`_ctx`) into the invocation so tools can be
-      // self-referential (e.g. read the calling agent off `_ctx.caller`).
-      // Only tools that opt-in via `usesContext: true` receive `_ctx`. This keeps
-      // the context (which holds non-serializable, circular references like the
-      // calling agent / AI client) out of tools that don't need it — notably MCP
-      // tools, whose args are serialized to JSON and sent over the wire.
-      // - positional tools receive `_ctx` as the LAST positional argument
-      // - non-positional tools receive it merged onto the args object as `_ctx`
-      const ctx: ToolCallContext = { ...(callContext || {}), Tools: this };
-
-      const positionalArgs = isPositional
-        ? Object.keys(properties).map((p) => functionArgs[p])
-        : functionArgs;
-
-      const fnArgs = isPositional
-        ? usesContext
-          ? [...positionalArgs, ctx]
-          : positionalArgs
-        : usesContext
-        ? { ...functionArgs, _ctx: ctx }
-        : functionArgs;
-
-      // Execute the function
-      const rawResponse = isPositional
-        ? functionToCall.call(this, ...fnArgs)
-        : functionToCall.call(this, fnArgs);
-      const functionResponse = await Promise.resolve(rawResponse).catch((e) => {
-        throw new Error("ERROR: " + e.message);
-      });
-
-      // Helper function to convert objects to JSON
-      const toJsonIfObject = (arg: any) => {
-        if (arg === null) {
-          return "null";
-        }
-        if (arg === undefined) {
-          return "undefined";
-        }
-        if (typeof arg === "object") {
-          return JSON.stringify(arg, null, 2);
-        }
-        return arg;
-      };
-
-      let toolMessages = [];
-
-      // Handle special case for parallel tool use
-      if (functionName === "multi_tool_use.parallel") {
-        // Extract tool_calls array from arguments
-        // Use the original (un-`_ctx`-augmented) args for extraction.
-        const toolCallsArg = Array.isArray(functionArgs)
-          ? functionArgs
-          : [functionArgs];
-        const toolCalls = Array.isArray(toolCallsArg) ? toolCallsArg : [];
-
-        const calls = toolCalls as {
-          recipient_name: string;
-          parameters: any;
-        }[];
-
-        toolMessages = calls.map((call, index) => {
-          return {
-            tool_call_id: `call_parallel_${index}`,
-            role: "tool",
-            name: call.recipient_name.split(".").pop(),
-            content: toJsonIfObject(functionResponse[index]) || "Done",
-          };
-        });
-      } else {
-        toolMessages = [
-          {
-            tool_call_id: toolCall.id,
-            role: "tool",
-            name: functionName,
-            content: toJsonIfObject(functionResponse) || "Done",
-          },
-        ];
-      }
-
-      return {
-        toolMessages,
-        toolCallId: toolCall.id,
-        functionName,
-        functionArgs,
-        functionResp: this.unwrapMcpResponse(functionResponse) || "Done",
-      };
-    } catch (error) {
-      console.log(error.message);
-      const toolMessages = [
-        {
-          tool_call_id: toolCall.id,
-          role: "tool",
-          name: "error",
-          content: error.message,
-        },
-      ];
-
-      return {
-        toolMessages,
-        toolCallId: toolCall.id,
-        functionName,
-        functionArgs,
-        functionResp: undefined,
-      };
-    }
-  }
-
-  // Tool Override Methods
-  registerOverride(
-    pattern: string | RegExp,
-    override: ToolOverrideFunction,
-    priority: number = 0
-  ): void {
-    this.overrides.push({ pattern, override, priority });
-    this.overrides.sort((a, b) => b.priority - a.priority);
-
-    // Re-apply overrides to existing functions
-    for (const toolName of this.getToolNames()) {
-      if (this.functions[toolName]) {
-        this.applyOverridesAndWrappers(toolName);
-      }
-    }
-  }
-
-  registerWrapper(
-    pattern: string | RegExp,
-    wrapper: ToolWrapper,
-    priority: number = 0
-  ): void {
-    this.wrappers.push({ pattern, wrapper, priority });
-
-    // Sort wrappers by priority first
-    this.wrappers.sort((a, b) => b.priority - a.priority);
-
-    // Re-apply wrappers to existing functions
-    for (const toolName of this.getToolNames()) {
-      if (this.functions[toolName]) {
-        this.applyOverridesAndWrappers(toolName);
-      }
-    }
-  }
-
-  removeOverride(pattern: string | RegExp): void {
-    this.overrides = this.overrides.filter((reg) => reg.pattern !== pattern);
-    // Re-apply functions after removing override
-    for (const toolName of this.getToolNames()) {
-      if (this.originalFunctions[toolName]) {
-        this.setFunction(toolName, this.originalFunctions[toolName]);
-      }
-    }
-  }
-
-  removeWrapper(pattern: string | RegExp): void {
-    this.wrappers = this.wrappers.filter((reg) => reg.pattern !== pattern);
-    // Re-apply functions after removing wrapper
-    for (const toolName of this.getToolNames()) {
-      if (this.originalFunctions[toolName]) {
-        this.setFunction(toolName, this.originalFunctions[toolName]);
-      }
-    }
-  }
-
-  private applyOverridesAndWrappers(name: string): void {
-    if (!this.originalFunctions[name]) {
-      // Store original function if not already stored
-      this.originalFunctions[name] = this.functions[name];
-    }
-
-    const originalFunc = this.originalFunctions[name];
-
-    // Overrides basically replace the function entirely
-    const matchingOverride = this.findMatchingOverride(name);
-    if (matchingOverride) {
-      // Create a wrapper function that calls the override with correct arguments
-      this.functions[name] = ((...args: any[]) => {
-        // Call the override function with originalArgs array and tool definition
-        const toolDefinition = this.getTool(name);
-        // Override functions expect (originalArgs: any[], originalTool: Tool)
-        return matchingOverride.override.call(this, args, toolDefinition);
-      }).bind(this);
-      return;
-    }
-
-    // Wrappers are like russian dolls,
-    // each wrapper gets the previous function as its "inner" function to call, and can modify arguments and return value as needed
-    // the first wrapper gets the original function, the second wrapper gets the first wrapper as its inner function, etc
-    const wrappers = this.findMatchingWrappers(name);
-    if (wrappers.length > 0) {
-      let wrappedFunction = originalFunc;
-
-      // Apply wrappers in priority order
-      for (const wrapperReg of wrappers) {
-        const innerFunc = wrappedFunction;
-        wrappedFunction = ((...args: any[]) => {
-          const toolDefinition = this.getTool(name);
-          return wrapperReg.wrapper(innerFunc, args, toolDefinition);
-        }).bind(this);
-      }
-
-      this.functions[name] = wrappedFunction.bind(this);
-    } else {
-      // No wrappers, use current function (might be override or original)
-      this.functions[name] = originalFunc;
-    }
-  }
-
-  private findMatchingOverride(
-    toolName: string
-  ): ToolOverrideRegistration | null {
-    let bestMatch: ToolOverrideRegistration | null = null;
-    let highestPriority = -1;
-
-    for (const registration of this.overrides) {
-      const matcher = createPatternMatcher(registration.pattern);
-      if (matcher.matches(toolName)) {
-        if (registration.priority > highestPriority) {
-          highestPriority = registration.priority;
-          bestMatch = registration;
-        }
-      }
-    }
-
-    return bestMatch;
-  }
-
-  private findMatchingWrappers(toolName: string): ToolWrapperRegistration[] {
-    const matchingWrappers: ToolWrapperRegistration[] = [];
-    for (const registration of this.wrappers) {
-      const matcher = createPatternMatcher(registration.pattern);
-      if (matcher.matches(toolName)) {
-        matchingWrappers.push(registration);
-      }
-    }
-    return matchingWrappers;
-  }
-
-  /**
-   * Tries to parse a string as JSON, returns null if it fails
-   */
-  private tryParseJson(value: string): any | null {
-    try {
-      return JSON.parse(value);
-    } catch {
-      return null;
-    }
-  }
-
-  /**
-   * Unwraps nested MCP-style tool responses.
-   *
-   * Handles responses shaped like:
-   *   { content: [{ type: "text", text: "<json string>" }] }
-   *
-   * If the `text` field is itself JSON (or contains another layer of the same
-   * structure), this method unwraps recursively until there is nothing more
-   * to unwrap.
-   *
-   * @param response - The raw tool response value (any type)
-   * @returns The innermost unwrapped value
-   */
-  unwrapMcpResponse(response: any): any {
-    // Only objects can have the content-array wrapper
-    if (response === null || typeof response !== "object") {
-      return response;
-    }
-
-    const { content } = response;
-    if (!Array.isArray(content) || content.length === 0) {
-      return response;
-    }
-
-    const firstItem = content[0];
-    if (
-      !firstItem ||
-      firstItem.type !== "text" ||
-      typeof firstItem.text !== "string"
-    ) {
-      return response;
-    }
-
-    // Try to parse the text as JSON
-    const parsed = this.tryParseJson(firstItem.text);
-    if (parsed === null) {
-      // text is not JSON – return the text string as the unwrapped value
-      return firstItem.text;
-    }
-
-    // Recursively unwrap in case there are more layers
-    return this.unwrapMcpResponse(parsed);
-  }
-
-  getOriginalFunction(name: string): ((...args: any[]) => any) | undefined {
-    return this.originalFunctions[name];
-  }
-
-  clearOverrides(): void {
-    this.overrides = [];
-    this.wrappers = [];
-    // Restore original functions
-    for (const [name, originalFunc] of Object.entries(this.originalFunctions)) {
-      this.functions[name] = originalFunc;
-    }
-  }
-}

package/src/services/TracingService.ts

@@ -1,116 +0,0 @@
-/**
- * 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);
-  },
-};