@tyvm/knowhow 0.0.144 → 0.0.146

package/src/types.ts

@@ -86,6 +86,9 @@ export type Config = {
   chat?: {
     rootModule?: string;
     renderer?: string;
+    defaultAgent?: string;
+    defaultModel?: string;
+    defaultProvider?: string;
     modules?: string[];
   };
   modules: 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 { 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/tests/clients/contextLimits.test.ts

@@ -9,6 +9,8 @@ import {
   GeminiTextPricing,
   AnthropicTextPricing,
   XaiTextPricing,
+  FireworksTextPricing,
+  FireworksEmbeddingPricing,
 } from "../../src/clients/pricing";
 
 // Model ids explicitly marked deprecated across all pricing tables. Deprecated
@@ -21,6 +23,8 @@ const deprecatedModelIds = new Set<string>(
     ...GeminiTextPricing,
     ...AnthropicTextPricing,
     ...XaiTextPricing,
+    ...FireworksTextPricing,
+    ...FireworksEmbeddingPricing,
   } as Record<string, { deprecated?: boolean }>)
     .filter(([, p]) => p && p.deprecated === true)
     .map(([id]) => id)

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: {} },
+    });
+  });
+});

package/tests/clients/openai.images.test.ts

@@ -0,0 +1,105 @@
+import { GenericOpenAiClient } from "../../src/clients/openai";
+import { Message } from "../../src/clients/types";
+
+describe("GenericOpenAiClient image message conversion", () => {
+  const imageUrl = "data:image/jpeg;base64,/9j/4AAQSkZJRg==";
+  let client: GenericOpenAiClient;
+
+  beforeEach(() => {
+    client = new GenericOpenAiClient("test-key");
+  });
+
+  it("moves tool image output to a user message for Chat Completions", () => {
+    const messages: Message[] = [{
+      role: "tool",
+      tool_call_id: "call_1",
+      name: "loadImageAsBase64",
+      content: [{
+        type: "image_url",
+        image_url: { url: imageUrl, detail: "high" },
+      }],
+    }];
+
+    const converted = client.toChatCompletionMessages(messages);
+
+    expect(converted).toEqual([
+      {
+        role: "tool",
+        tool_call_id: "call_1",
+        content: [{
+          type: "text",
+          text: "Image output attached in the following user message.",
+        }],
+      },
+      {
+        role: "user",
+        content: [{
+          type: "image_url",
+          image_url: { url: imageUrl, detail: "high" },
+        }],
+      },
+    ]);
+  });
+
+  it("uses input_image parts for the Responses API", () => {
+    const converted = client.toResponseContent([
+      { type: "text", text: "Screenshot" },
+      { type: "image_url", image_url: { url: imageUrl, detail: "low" } },
+    ]);
+
+    expect(converted).toEqual([
+      { type: "input_text", text: "Screenshot" },
+      { type: "input_image", image_url: imageUrl, detail: "low" },
+    ]);
+  });
+
+  it.each([
+    { type: "audio_url", audio_url: { url: "data:audio/wav;base64,UklGRg==" } },
+    { type: "video_url", video_url: { url: "data:video/mp4;base64,AAAAIGZ0eXA=" } },
+  ] as const)("rejects unsupported $type Responses API content instead of dropping it", (part) => {
+    expect(() => client.toResponseContent([
+      { type: "text", text: "Media" },
+      part,
+    ])).toThrow(
+      `OpenAI Responses API conversion does not support ${part.type} content.`
+    );
+  });
+
+  it("attaches a tool image as input_image in a Responses API request", async () => {
+    const create = jest.fn().mockResolvedValue({
+      id: "resp_1",
+      output: [],
+      usage: undefined,
+    });
+    (client as any).client = { responses: { create } };
+
+    await client.createChatResponse({
+      model: "gpt-5.4",
+      reasoning_effort: "none",
+      messages: [{
+        role: "tool",
+        tool_call_id: "call_1",
+        content: [{
+          type: "image_url",
+          image_url: { url: imageUrl, detail: "auto" },
+        }],
+      }],
+    });
+
+    expect(create.mock.calls[0][0].input).toEqual([
+      {
+        type: "function_call_output",
+        call_id: "call_1",
+        output: "Image output attached in the following user message.",
+      },
+      {
+        role: "user",
+        content: [{
+          type: "input_image",
+          image_url: imageUrl,
+          detail: "auto",
+        }],
+      },
+    ]);
+  });
+});

package/tests/clients/pricing.test.ts

@@ -30,6 +30,8 @@ import {
   GeminiTextPricing,
   AnthropicTextPricing,
   XaiTextPricing,
+  FireworksTextPricing,
+  FireworksEmbeddingPricing,
   ALL_MODEL_CATALOG,
   XaiImagePricing,
   XaiVideoPricing,
@@ -61,6 +63,8 @@ describe("Model Pricing Coverage", () => {
     ...GeminiTextPricing,
     ...AnthropicTextPricing,
     ...XaiTextPricing,
+    ...FireworksTextPricing,
+    ...FireworksEmbeddingPricing,
   };
 
   describe("Text completion models have pricing", () => {
@@ -166,6 +170,8 @@ describe("Model Catalog Coverage", () => {
       ...GeminiTextPricing,
       ...AnthropicTextPricing,
       ...XaiTextPricing,
+      ...FireworksTextPricing,
+      ...FireworksEmbeddingPricing,
     } as Record<string, { deprecated?: boolean }>)
       .filter(([, p]) => p && p.deprecated === true)
       .map(([id]) => id)

package/tests/clients/reasoningEffort.test.ts

@@ -0,0 +1,79 @@
+import { GenericAnthropicClient } from "../../src/clients/anthropic";
+import { GenericGeminiClient } from "../../src/clients/gemini";
+import { GenericOpenAiClient } from "../../src/clients/openai";
+import { AnthropicModels } from "../../src/clients/pricing";
+import {
+  REASONING_EFFORTS,
+  ReasoningEffort,
+  isReasoningEffort,
+} from "../../src/clients/types";
+import {
+  GoogleThinkingBudgetModels,
+  GoogleThinkingLevelModels,
+} from "../../src/types";
+import { GenericXAIClient } from "../../src/clients/xai";
+
+const options = (model: string, reasoning_effort: ReasoningEffort) => ({
+  model,
+  reasoning_effort,
+  messages: [],
+});
+
+describe("reasoning effort values", () => {
+  it("accepts the complete provider-neutral set and rejects other values", () => {
+    expect(REASONING_EFFORTS).toEqual([
+      "none",
+      "minimal",
+      "low",
+      "medium",
+      "high",
+      "xhigh",
+      "max",
+    ]);
+    REASONING_EFFORTS.forEach((effort) => expect(isReasoningEffort(effort)).toBe(true));
+    expect(isReasoningEffort("extra-high")).toBe(false);
+    expect(isReasoningEffort(undefined)).toBe(false);
+  });
+
+  it("maps provider-neutral values to OpenAI legacy and Responses spellings", () => {
+    const client = new GenericOpenAiClient("fake-key");
+    expect(client.resolveReasoningEffort(options("unknown", "none"))).toBe("low");
+    expect(client.resolveReasoningEffort(options("unknown", "minimal"))).toBe("low");
+    expect(client.resolveReasoningEffort(options("unknown", "xhigh"))).toBe("high");
+    expect(client.resolveReasoningEffort(options("unknown", "max"))).toBe("high");
+    expect(client.resolveReasoningEffortForModel(options("unknown", "max"))).toBe("xhigh");
+  });
+
+  it("maps all values to valid Gemini thinking levels and budgets", () => {
+    const client = new GenericGeminiClient("fake-key");
+    const levelModel = GoogleThinkingLevelModels[0];
+    const budgetModel = GoogleThinkingBudgetModels[0];
+
+    expect(client.buildThinkingConfig(options(levelModel, "none"))).toEqual({ thinkingLevel: "minimal" });
+    expect(client.buildThinkingConfig(options(levelModel, "minimal"))).toEqual({ thinkingLevel: "minimal" });
+    expect(client.buildThinkingConfig(options(levelModel, "xhigh"))).toEqual({ thinkingLevel: "high" });
+    expect(client.buildThinkingConfig(options(levelModel, "max"))).toEqual({ thinkingLevel: "high" });
+    expect(client.buildThinkingConfig(options(budgetModel, "none"))).toEqual({ thinkingBudget: 0 });
+    expect(client.buildThinkingConfig(options(budgetModel, "minimal"))).toEqual({ thinkingBudget: 512 });
+    expect(client.buildThinkingConfig(options(budgetModel, "medium"))).toEqual({ thinkingBudget: 8192 });
+    expect(client.buildThinkingConfig(options(budgetModel, "max"))).toEqual({ thinkingBudget: -1 });
+  });
+
+  it("maps provider-neutral values to Anthropic output effort", () => {
+    const client = new GenericAnthropicClient("fake-key");
+    expect(client.getEffortOutputConfig(AnthropicModels.Sonnet5, "none")).toBeUndefined();
+    expect(client.getEffortOutputConfig(AnthropicModels.Sonnet5, "minimal")).toEqual({ effort: "low" });
+    expect(client.getEffortOutputConfig(AnthropicModels.Sonnet5, "xhigh")).toEqual({ effort: "xhigh" });
+    expect(client.getEffortOutputConfig(AnthropicModels.Sonnet5, "max")).toEqual({ effort: "max" });
+    expect(client.getEffortOutputConfig("unsupported", "high")).toBeUndefined();
+  });
+
+  it("maps provider-neutral values to xAI legacy effort", () => {
+    const client = new GenericXAIClient("fake-key");
+    expect(client.resolveLegacyReasoningEffort("none")).toBeUndefined();
+    expect(client.resolveLegacyReasoningEffort("minimal")).toBe("low");
+    expect(client.resolveLegacyReasoningEffort("medium")).toBe("medium");
+    expect(client.resolveLegacyReasoningEffort("xhigh")).toBe("high");
+    expect(client.resolveLegacyReasoningEffort("max")).toBe("high");
+  });
+});

package/tests/compressor/toolResponseCache.test.ts

@@ -111,7 +111,8 @@ describe("ToolResponseCache - MCP Format Support", () => {
     it("should filter data array with ._data | map(select(.private == true))", async () => {
       const result = await cache.queryToolResponse(
         "github-repos",
-        "._data | map(select(.private == true))"
+        "._data | map(select(.private == true))",
+        { maxCharacters: 50_000 }
       );
       
       // Parse and verify filtering worked