@tyvm/knowhow 0.0.145 → 0.0.146

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/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/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

package/tests/manual/clients/completions.test.ts

@@ -17,6 +17,7 @@ import { OpenAiChatModels, OpenAiReasoningModels, OpenAiResponsesOnlyModels } fr
 import { AnthropicTextModels, AnthropicLimitedAvailabilityModels } from "../../../src/clients/pricing/anthropic";
 import { GoogleTextModels } from "../../../src/clients/pricing/google";
 import { XaiTextModels, XaiDeprecatedTextModels } from "../../../src/clients/pricing/xai";
+import { FireworksTextPricing } from "../../../src/clients/pricing/fireworks";
 
 const OUTPUT_FILE = path.join(__dirname, "completions.json");
 const PROMPT = "Say hello in 5 words.";
@@ -29,6 +30,7 @@ interface ModelEntry {
   provider: string;
   model: string;
   envKey: string;
+  reasoningEffort?: "low";
 }
 
 function openaiEntries(models: string[]): ModelEntry[] {
@@ -47,19 +49,35 @@ function xaiEntries(models: string[]): ModelEntry[] {
   return models.map((model) => ({ provider: "xai", model, envKey: "XAI_API_KEY" }));
 }
 
+function fireworksEntries(): ModelEntry[] {
+  return Object.entries(FireworksTextPricing)
+    .filter(([, pricing]) => !pricing.deprecated)
+    .map(([model]) => ({
+      provider: "fireworks",
+      model,
+      envKey: "FIREWORKS_API_KEY",
+      // Fireworks model support for reasoning_effort is model-specific. This
+      // suite exercises the request shape used by Patcher without that flag.
+    }));
+}
+
 const TEST_MODELS: ModelEntry[] = [
   // OpenAI — all active chat + reasoning models + responses-API models
   // Deduplicate since some models appear in multiple lists
-  ...openaiEntries([...new Set([...OpenAiChatModels, ...OpenAiReasoningModels, ...OpenAiResponsesOnlyModels])]),
+  ...openaiEntries([...new Set([...OpenAiChatModels, ...OpenAiReasoningModels, ...OpenAiResponsesOnlyModels])])
+    .map((entry) => ({ ...entry, reasoningEffort: "low" as const })),
 
   // Anthropic — active text models (limited availability excluded)
-  ...anthropicEntries(AnthropicTextModels),
+  ...anthropicEntries(AnthropicTextModels).map((entry) => ({ ...entry, reasoningEffort: "low" as const })),
 
   // Google — all active text models
-  ...googleEntries(GoogleTextModels),
+  ...googleEntries(GoogleTextModels).map((entry) => ({ ...entry, reasoningEffort: "low" as const })),
 
   // XAI — active text models (deprecated grok-2 models excluded)
-  ...xaiEntries(XaiTextModels),
+  ...xaiEntries(XaiTextModels).map((entry) => ({ ...entry, reasoningEffort: "low" as const })),
+
+  // Fireworks — all active catalog models
+  ...fireworksEntries(),
 ];
 
 // ─── Persistence helpers ──────────────────────────────────────────────────────
@@ -118,7 +136,7 @@ describe("Text Completions – multi-provider model verification", () => {
     console.log(`   Total records: ${Object.keys(results).length}`);
   });
 
-  for (const { provider, model, envKey } of TEST_MODELS) {
+  for (const { provider, model, envKey, reasoningEffort } of TEST_MODELS) {
     const key = recordKey(provider, model);
 
     test(`${provider} / ${model}`, async () => {
@@ -145,11 +163,10 @@ describe("Text Completions – multi-provider model verification", () => {
         model,
         messages: [{ role: "user", content: PROMPT }],
         max_tokens: 2000,
-        // Use low reasoning effort for all models that support it — keeps latency
-        // and cost down while still verifying the model responds successfully.
-        // For OpenAI this maps to reasoning_effort="low", for Gemini to
-        // thinkingLevel="low" or thinkingBudget=1024, etc.
-        reasoning_effort: "low",
+        // Exercise the summary option enabled by Patcher. Provider clients must
+        // translate or remove this internal option rather than forwarding it.
+        reasoning_summary: true,
+        reasoning_effort: reasoningEffort,
       });
       const durationMs = Date.now() - startMs;
 

package/tests/processors/TokenCompressor.test.ts

@@ -446,7 +446,7 @@ describe("TokenCompressor", () => {
       expect(result).toContain("Available keys:");
     });
 
-    it("should auto-stitch a multi-chunk chain into the full content", () => {
+    it("should auto-stitch and paginate a multi-chunk chain", () => {
       // Force a multi-chunk compression then expand the first key.
       const content = "a".repeat(40000);
       const placeholder = tokenCompressor.compressStringInChunks(content);
@@ -456,9 +456,23 @@ describe("TokenCompressor", () => {
       const functions = toolsServiceCalls[0][0];
       const result = functions.expandTokens(firstKey);
 
-      // Full content is returned in one call with no chunk-linking markers.
-      expect(result).toBe(content);
+      expect(result.length).toBeLessThanOrEqual(20_000);
+      expect(result).toContain("Repeat with characterOffset=");
       expect(result).not.toContain("NEXT_CHUNK_KEY");
+
+      const pages = [result];
+      let offsetMatch = result.match(/characterOffset=(\d+)/);
+      while (offsetMatch) {
+        const page = functions.expandTokens(
+          firstKey,
+          undefined,
+          undefined,
+          Number(offsetMatch[1])
+        );
+        pages.push(page);
+        offsetMatch = page.match(/Repeat with characterOffset=(\d+)/);
+      }
+      expect(pages.reduce((sum, page) => sum + (page.match(/^a+/)?.[0].length || 0), 0)).toBe(content.length);
     });
 
     it("should support a ranged read with real line numbers", () => {

package/tests/processors/tools/boundedRetrievalTools.test.ts

@@ -0,0 +1,68 @@
+import {
+  executeJqQuery,
+  jqToolResponseDefinition,
+} from "../../../src/processors/tools/jqToolResponse";
+import {
+  executeTail,
+  tailToolResponseDefinition,
+} from "../../../src/processors/tools/tailToolResponse";
+import {
+  executeListStoredToolResponses,
+  listStoredToolResponsesDefinition,
+} from "../../../src/processors/tools/listStoredToolResponses";
+
+describe("bounded retrieval tools", () => {
+  it("bounds and paginates JQ output", async () => {
+    const data = JSON.stringify(Array.from({ length: 100 }, (_, i) => `value-${i}-${"x".repeat(30)}`));
+    const first = await executeJqQuery(data, "jq-id", ".", ["jq-id"], {}, { maxCharacters: 1000 });
+    expect(first.length).toBeLessThanOrEqual(1000);
+    expect(first).toContain("Repeat with characterOffset=");
+
+    const offset = Number(first.match(/characterOffset=(\d+)/)?.[1]);
+    const next = await executeJqQuery(data, "jq-id", ".", ["jq-id"], {}, {
+      characterOffset: offset,
+      maxCharacters: 1000,
+    });
+    expect(next).not.toBe(first);
+  });
+
+  it("bounds tail line lengths and supports backward pagination", async () => {
+    const data = ["first", `second ${"a".repeat(5000)}`, "third"].join("\n");
+    const result = await executeTail(data, "tail-id", ["tail-id"], {
+      lines: 1,
+      endLine: 2,
+      maxLineCharacters: 1000,
+      maxCharacters: 2000,
+    });
+    expect(result.length).toBeLessThanOrEqual(2000);
+    expect(result).toContain("Earlier lines available");
+    expect(result).toContain("lineCharacterOffset=1000");
+  });
+
+  it("paginates stored response results", async () => {
+    const storage = { a: "one", b: "two", c: "three" };
+    const metadata = {
+      a: { toolCallId: "a", originalLength: 3, storedAt: 1 },
+      b: { toolCallId: "b", originalLength: 3, storedAt: 2 },
+      c: { toolCallId: "c", originalLength: 5, storedAt: 3 },
+    };
+    const result = await executeListStoredToolResponses(storage, metadata, {}, {
+      maxResults: 1,
+      resultOffset: 1,
+    });
+    expect(result).toContain("Tool Call ID: b");
+    expect(result).not.toContain("Tool Call ID: c");
+    expect(result).toContain("resultOffset=2");
+  });
+
+  it("exposes pagination controls in each tool schema", () => {
+    const jqOptions = (jqToolResponseDefinition.function.parameters.properties as any).options;
+    const tailOptions = (tailToolResponseDefinition.function.parameters.properties as any).options;
+    const listOptions = (listStoredToolResponsesDefinition.function.parameters.properties as any).options;
+    expect(jqOptions.properties.characterOffset).toBeDefined();
+    expect(tailOptions.properties.endLine).toBeDefined();
+    expect(tailOptions.properties.maxCharacters).toBeDefined();
+    expect(listOptions.properties.resultOffset).toBeDefined();
+    expect(listOptions.properties.maxCharacters).toBeDefined();
+  });
+});

package/tests/processors/tools/grepToolResponse.test.ts

@@ -1,4 +1,7 @@
-import { executeGrep } from "../../../src/processors/tools/grepToolResponse";
+import {
+  executeGrep,
+  grepToolResponseDefinition,
+} from "../../../src/processors/tools/grepToolResponse";
 
 /**
  * Verifies grepToolResponse operates on the decompressed/plain stored content
@@ -69,4 +72,88 @@ describe("executeGrep", () => {
 
     expect(result).toContain("No matches found");
   });
+
+  it("bounds the total response and advertises the next result page", async () => {
+    const manyMatches = Array.from(
+      { length: 20 },
+      (_, index) => `match ${index} ${"x".repeat(200)}`
+    ).join("\n");
+
+    const result = await executeGrep(
+      manyMatches,
+      toolCallId,
+      "match",
+      [toolCallId],
+      { maxCharacters: 1000, maxResults: 20 }
+    );
+
+    expect(result.length).toBeLessThanOrEqual(1000);
+    expect(result).toContain("More matches available");
+    expect(result).toMatch(/resultOffset=\d+/);
+  });
+
+  it("keeps a large log grep under the default response limit", async () => {
+    const logMatches = Array.from(
+      { length: 500 },
+      (_, index) => `${index}: ${JSON.stringify({ level: 30, message: "sandbox runner", detail: "x".repeat(500) })}`
+    ).join("\n");
+
+    const result = await executeGrep(
+      logMatches,
+      toolCallId,
+      "runner|sandbox",
+      [toolCallId]
+    );
+
+    expect(result.length).toBeLessThanOrEqual(20_000);
+    expect(result).toContain("More matches available");
+  });
+
+  it("paginates matches using resultOffset", async () => {
+    const result = await executeGrep(
+      ["match zero", "match one", "match two"].join("\n"),
+      toolCallId,
+      "match",
+      [toolCallId],
+      { maxResults: 1, resultOffset: 1 }
+    );
+
+    expect(result).not.toContain("match zero");
+    expect(result).toContain("match one");
+    expect(result).not.toContain("match two");
+    expect(result).toContain("resultOffset=2");
+  });
+
+  it("slices very long matching lines and lets callers page within the line", async () => {
+    const longLine = `prefix-${"a".repeat(5000)}-suffix`;
+    const firstPage = await executeGrep(
+      longLine,
+      toolCallId,
+      "prefix",
+      [toolCallId]
+    );
+
+    expect(firstPage.length).toBeLessThan(10_000);
+    expect(firstPage).toContain("line 1 truncated");
+    expect(firstPage).toContain("lineCharacterOffset=4000");
+    expect(firstPage).not.toContain("-suffix");
+
+    const secondPage = await executeGrep(
+      longLine,
+      toolCallId,
+      "prefix",
+      [toolCallId],
+      { lineCharacterOffset: 4000 }
+    );
+
+    expect(secondPage).toContain("-suffix");
+    expect(secondPage).toContain("End of matches");
+  });
+
+  it("exposes pagination controls in the tool schema", () => {
+    const options = (grepToolResponseDefinition.function.parameters.properties as any).options;
+    expect(options.properties.resultOffset).toBeDefined();
+    expect(options.properties.lineCharacterOffset).toBeDefined();
+    expect(options.properties.maxCharacters).toBeDefined();
+  });
 });