@tyvm/knowhow 0.0.117 → 0.0.119

package/src/services/conversion/index.ts

@@ -0,0 +1,2 @@
+export * from "./types";
+export * from "./ConversionService";

package/src/services/conversion/types.ts

@@ -0,0 +1,79 @@
+import { AIClient } from "../../clients";
+
+export type Modality = "text" | "html" | "image" | "audio" | "video";
+
+export interface ConvertInput {
+  filePath: string;       // source file on disk
+  inputExt: string;       // e.g. "pdf"
+  /**
+   * When a previous chain step produced multiple files (e.g. one image per
+   * PDF page), they are forwarded here so the next converter can process all
+   * of them. filePath is set to files[0] for single-file converters.
+   */
+  files?: string[];
+  startPage?: number;
+  endPage?: number;
+  startLine?: number;
+  endLine?: number;
+  startTime?: number;
+  endTime?: number;
+}
+
+export interface ConvertResult {
+  outputType: Modality;
+  text?: string;          // for text/html
+  files?: string[];       // for image/audio/video
+  usd_cost?: number;
+}
+
+export interface ConverterContext {
+  clients: AIClient;
+  cacheDir: string;
+  /**
+   * Per-converter options forwarded from ConvertOptions.converterOptions[name].
+   * Lets individual converters accept their own settings (e.g. which model to
+   * use for image->text description, DPI for pdf->image, etc).
+   */
+  options?: Record<string, any>;
+}
+
+export interface Converter {
+  name: string;                   // unique
+  inputExts?: string[];           // e.g. ["pdf"]
+  inputModality?: Modality;       // OR an input modality (e.g. "image")
+  outputType: Modality;
+  /**
+   * If true, the ConversionService will cache the result of this converter to
+   * disk so repeated calls with the same input are fast. Defaults to false —
+   * caching is opt-in. Only enable for expensive converters (e.g. pdf->image,
+   * image->text via LLM) where re-running would be slow or costly.
+   */
+  cache?: boolean;
+  convert: (input: ConvertInput, ctx: ConverterContext) => Promise<ConvertResult>;
+}
+
+export interface ConvertOptions {
+  preferredConverters?: string[];
+  isGoodEnough?: (args: { filePath: string; result: ConvertResult }) => boolean;
+  force?: boolean;
+  startPage?: number;
+  endPage?: number;
+  startLine?: number;
+  endLine?: number;
+  startTime?: number;
+  endTime?: number;
+  onProgress?: (stage: string, fraction: number) => void;
+  /**
+   * Options scoped to a specific converter, keyed by converter name.
+   * e.g. { "image-to-text": { model: "gpt-4o" }, "pdf-to-img": { scale: 2 } }
+   */
+  converterOptions?: Record<string, Record<string, any>>;
+  /**
+   * Explicit intermediate modalities to route through before reaching the
+   * final targetType.  e.g. ["image"] means the chain must go through "image"
+   * first.  When provided, the ConversionService will stitch BFS sub-paths
+   * between each waypoint rather than picking the overall shortest path.
+   * CLI: --to image,text  → via=["image"], target="text"
+   */
+  via?: Modality[];
+}

package/src/services/index.ts

@@ -15,6 +15,8 @@ import { SessionManager } from "./SessionManager";
 import { TaskRegistry } from "./TaskRegistry";
 import { MediaProcessorService } from "./MediaProcessorService";
 
+import { ConversionService } from "./conversion/ConversionService";
+
 export * from "./AgentService";
 export * from "./EventService";
 export * from "./flags";
@@ -34,6 +36,7 @@ export * from "./SyncedAgentWatcher";
 export * from "./SyncerService";
 export * from "./watchers";
 export { Clients } from "../clients";
+export * from "./conversion";
 
 let Singletons = {} as {
   Tools: ToolsService;
@@ -48,6 +51,7 @@ let Singletons = {} as {
   Plugins: PluginService;
   Clients: AIClient;
   MediaProcessor: MediaProcessorService;
+  Conversion: ConversionService;
 };
 
 export const services = (): typeof Singletons => {
@@ -55,6 +59,8 @@ export const services = (): typeof Singletons => {
     const Tools = new ToolsService();
     const Events = new EventService();
     const Agents = new AgentService(Tools, Events);
+    const MediaProcessor = new MediaProcessorService(Clients);
+    const Conversion = new ConversionService(Clients, MediaProcessor);
     const Plugins = new PluginService({
       Agents,
       Events,
@@ -71,7 +77,8 @@ export const services = (): typeof Singletons => {
       Embeddings: new EmbeddingsService(),
       Flags: new FlagsService(),
       Mcp: new McpService(),
-      MediaProcessor: new MediaProcessorService(Clients),
+      MediaProcessor,
+      Conversion,
       Plugins,
       Tools,
       knowhowApiClient: new KnowhowSimpleClient(),

package/src/services/modules/types.ts

@@ -12,6 +12,7 @@ import { ToolsService } from "../Tools";
 import { MediaProcessorService } from "../MediaProcessorService";
 import { TunnelHandler } from "@tyvm/knowhow-tunnel";
 import { EventService } from "../EventService";
+import { ConversionService } from "../conversion/ConversionService";
 
 /*
  *
@@ -57,6 +58,7 @@ export interface ModuleContext {
   Tools: ToolsService;
   Events: EventService;
   MediaProcessor?: MediaProcessorService;
+  Conversion?: ConversionService;
   Tunnel?: TunnelHandler;
   Program?: Command;
 }

package/src/services/watchers/FsSyncer.ts

@@ -143,6 +143,12 @@ export class FsSyncedAgentWatcher implements SyncedAgentWatcher {
     console.log(`🛑 Killed remote agent: ${this.taskId}`);
   }
 
+  async interrupt(message?: string): Promise<void> {
+    const inputPath = path.join(this.taskPath, "input.txt");
+    await fsPromises.writeFile(inputPath, `/poke ${message || ""}`.trim(), "utf8");
+    console.log(`🫵 Interrupt written to input for agent: ${this.taskId}`);
+  }
+
   private async readMetadata(): Promise<any> {
     try {
       const metaPath = path.join(this.taskPath, "metadata.json");

package/src/services/watchers/RemoteSyncer.ts

@@ -150,4 +150,9 @@ export class WebSyncedAgentWatcher implements SyncedAgentWatcher {
     await this.client.killAgent(this.taskId);
     console.log(`🛑 Killed remote web agent: ${this.taskId}`);
   }
+
+  async interrupt(message?: string): Promise<void> {
+    await this.client.sendMessageToAgent(this.taskId, `/poke ${message || ""}`.trim());
+    console.log(`🫵 Interrupt sent to remote web agent: ${this.taskId}`);
+  }
 }

package/src/types.ts

@@ -112,6 +112,7 @@ export type McpConfig = {
   params?: Partial<{ socket: WebSocket }>;
   authorization_token?: string;
   authorization_token_file?: string;
+  authorization_scheme?: "bearer" | "basic";
 };
 
 export type ModelProvider = {

package/tests/agents/tools/readFile.test.ts

@@ -0,0 +1,88 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { readFile } from "../../../src/agents/tools/readFile";
+
+/**
+ * These tests cover the readFile tool improvements:
+ *  - plain text output (no unified-diff / Index: wrapper)
+ *  - optional 1-based inclusive line ranges with real source line numbers
+ */
+describe("readFile tool", () => {
+  let tmpFile: string;
+  const fileLines = [
+    "import x from 'y';",
+    "",
+    "function add(a, b) {",
+    "  return a + b;",
+    "}",
+    "",
+    "export default add;",
+  ];
+
+  // Minimal ToolsService-like context so readFile can resolve getContext()
+  // without depending on the global singletons.
+  const fakeThis: any = {
+    getContext: () => ({ Events: undefined }),
+  };
+
+  beforeEach(() => {
+    tmpFile = path.join(
+      os.tmpdir(),
+      `readFile-test-${Date.now()}-${Math.random().toString(36).slice(2)}.ts`
+    );
+    fs.writeFileSync(tmpFile, fileLines.join("\n"), "utf8");
+  });
+
+  afterEach(() => {
+    if (fs.existsSync(tmpFile)) {
+      fs.unlinkSync(tmpFile);
+    }
+  });
+
+  it("returns plain text with no diff/patch wrapper", async () => {
+    const result = await readFile.call(fakeThis, tmpFile);
+
+    expect(result).toBe(fileLines.join("\n"));
+    // The old behavior wrapped reads in a unified diff; make sure that's gone.
+    expect(result).not.toContain("Index:");
+    expect(result).not.toContain("@@");
+    expect(result).not.toMatch(/^\+/m);
+  });
+
+  it("returns a line range with real source line numbers", async () => {
+    const result = await readFile.call(fakeThis, tmpFile, 3, 5);
+
+    expect(result).toBe(
+      ["3: function add(a, b) {", "4:   return a + b;", "5: }"].join("\n")
+    );
+  });
+
+  it("defaults toLine to the end of file when omitted", async () => {
+    const result = await readFile.call(fakeThis, tmpFile, 6);
+
+    expect(result).toBe(["6: ", "7: export default add;"].join("\n"));
+  });
+
+  it("clamps an out-of-range toLine to the last line", async () => {
+    const result = await readFile.call(fakeThis, tmpFile, 6, 9999);
+
+    expect(result).toBe(["6: ", "7: export default add;"].join("\n"));
+  });
+
+  it("throws when fromLine is greater than toLine", async () => {
+    await expect(readFile.call(fakeThis, tmpFile, 5, 2)).rejects.toThrow(
+      /Invalid line range/
+    );
+  });
+
+  it("throws a helpful error when the file does not exist", async () => {
+    const missing = path.join(
+      os.tmpdir(),
+      "definitely-not-here-xyz.unknownext"
+    );
+    await expect(readFile.call(fakeThis, missing)).rejects.toThrow(
+      /File not found/
+    );
+  });
+});

package/tests/clients/AIClient.test.ts

@@ -1,4 +1,9 @@
 import { AIClient } from "../../src/clients";
+
+// Prevent real HTTP calls during provider initialisation — resolveClient
+// returns null so all DEFAULT_PROVIDERS are skipped by registerModelProviders.
+jest.spyOn(AIClient.prototype as any, "resolveClient").mockReturnValue(null);
+
 import {
   GenericClient,
   CompletionOptions,

package/tests/clients/contextLimits.test.ts

@@ -0,0 +1,71 @@
+/**
+ * Tests that all models included in the Models object (anthropic, openai, google, xai)
+ * have a corresponding context limit recorded in ContextLimits.
+ */
+import { Models } from "../../src/types";
+import { ContextLimits, getModelContextLimit, DEFAULT_CONTEXT_LIMIT } from "../../src/clients/contextLimits";
+
+describe("ContextLimits", () => {
+  describe("coverage - all Models.* values have a recorded context limit", () => {
+    const providers = Object.keys(Models) as Array<keyof typeof Models>;
+
+    for (const provider of providers) {
+      describe(`Models.${provider}`, () => {
+        const providerModels = Models[provider] as Record<string, string>;
+        const modelEntries = Object.entries(providerModels);
+
+        it(`should have at least one model defined for ${provider}`, () => {
+          expect(modelEntries.length).toBeGreaterThan(0);
+        });
+
+        for (const [key, modelId] of modelEntries) {
+          it(`${provider}.${key} (${modelId}) should have a context limit`, () => {
+            const limit = ContextLimits[modelId];
+            expect(limit).toBeDefined();
+            expect(typeof limit).toBe("number");
+            // Non-text models (image/video/audio) are recorded as 0; text models must be > 0
+            expect(limit).toBeGreaterThanOrEqual(0);
+            expect(Number.isFinite(limit)).toBe(true);
+          });
+        }
+      });
+    }
+  });
+
+  describe("getModelContextLimit", () => {
+    it("returns the correct limit for a known OpenAI model", () => {
+      expect(getModelContextLimit(Models.openai.GPT_4o)).toBe(128_000);
+    });
+
+    it("returns the correct limit for a known Anthropic model", () => {
+      expect(getModelContextLimit(Models.anthropic.Opus4)).toBe(200_000);
+    });
+
+    it("returns the correct limit for a known Google model", () => {
+      expect(getModelContextLimit(Models.google.Gemini_15_Pro)).toBe(2_000_000);
+    });
+
+    it("returns the correct limit for a known xAI model", () => {
+      expect(getModelContextLimit(Models.xai.Grok3Beta)).toBe(131_072);
+    });
+
+    it("returns DEFAULT_CONTEXT_LIMIT for an unknown model", () => {
+      expect(getModelContextLimit("unknown-model-xyz")).toBe(DEFAULT_CONTEXT_LIMIT);
+    });
+
+    it("DEFAULT_CONTEXT_LIMIT is a positive number", () => {
+      expect(DEFAULT_CONTEXT_LIMIT).toBeGreaterThan(0);
+    });
+  });
+
+  describe("ContextLimits values are all valid numbers", () => {
+    it("all recorded limits are non-negative finite numbers", () => {
+      for (const [model, limit] of Object.entries(ContextLimits)) {
+        expect(typeof limit).toBe("number");
+        // 0 is allowed for non-text models (image/video/audio)
+        expect(limit).toBeGreaterThanOrEqual(0);
+        expect(Number.isFinite(limit)).toBe(true);
+      }
+    });
+  });
+});

package/tests/patching/patchFileOutput.test.ts

@@ -0,0 +1,217 @@
+import { patchFile } from "../../src/agents/tools/patch";
+import * as fs from "fs";
+
+const mockToolService = {
+  getContext: () => ({ Events: null }),
+};
+const boundPatch = (patchFile as any).bind(mockToolService);
+
+describe("patchFile return messaging", () => {
+  const testFile = "/tmp/patch-test-output.ts";
+
+  beforeEach(() => {
+    fs.writeFileSync(testFile, `function hello() {\n  const a = 1;\n  const b = 2;\n  return a + b;\n}\n`);
+  });
+
+  it("clean patch shows stats and preview", async () => {
+    const result = await boundPatch(testFile, `@@ -2,3 +2,4 @@
+   const a = 1;
+   const b = 2;
++  const c = 3;
+   return a + b;
+`);
+    console.log("CLEAN RESULT:\n", result);
+    expect(result).toContain("✅ Original patch applied cleanly.");
+    expect(result).toContain("1/1 hunks applied.");
+    expect(result).toContain("+ ");
+  });
+
+  it("wrong line numbers auto-corrected patch shows warning", async () => {
+    // This patch has severely wrong line numbers - the diff library can't apply it directly
+    // but fixPatch can re-anchor it using the deletion content
+    const result = await boundPatch(testFile, `@@ -999,5 +999,5 @@
+   const a = 1;
+   const b = 2;
+-  return a + b;
++  return a + b + c;
+   }
+`);
+    console.log("FIXED RESULT:\n", result);
+    // Either it was auto-corrected (⚠️) or applied cleanly via fuzzy match (✅)
+    // Either way it should succeed and show a change
+    expect(result).not.toContain("❌ Patch failed");
+    expect(result).toContain("lines");
+    // The change summary should show the replacement
+    expect(result).toContain("return a + b + c");
+  });
+
+  it("bad context lines returns descriptive failure", async () => {
+    const result = await boundPatch(testFile, `@@ -1,3 +1,4 @@
+   NONEXISTENT_LINE_1;
+   NONEXISTENT_LINE_2;
++  new line here;
+   NONEXISTENT_LINE_3;
+`);
+    console.log("FAIL RESULT:\n", result);
+    expect(result).toContain("❌ Patch failed");
+    expect(result).toContain("hunk(s) attempted");
+    expect(result).toContain("Tip:");
+  });
+});
+
+/**
+ * Regression for a real-world mangling bug observed while patching
+ * `src/clients/anthropic.ts`.
+ *
+ * The patch inserted several new `const` declaration lines right after an
+ * `else {` opening brace AND replaced two property lines that live *inside* a
+ * nested `source: { ... }` object literal. The auto-correction (fixPatch /
+ * fixSingleHunk) re-anchored the hunk incorrectly: it
+ *   1. dropped the newly added `const` declaration lines, and
+ *   2. moved the replaced `media_type` / `data` lines OUTSIDE of the
+ *      `source: { ... }` object (placing them after its closing `},`),
+ * which produced syntactically broken / scope-corrupted output.
+ *
+ * This test reproduces the exact shape (leading-context additions + nested
+ * object property replacement in the same hunk) and asserts the result is
+ * structurally coherent.
+ */
+describe("patchFile nested-object + leading-context additions regression", () => {
+  const testFile = "/tmp/patch-nested-object-regression.ts";
+
+  const original = `        if (isUrl) {
+          return {
+            type: "image",
+            source: {
+              type: "url" as const,
+              url: e.image_url.url,
+            },
+          } as Anthropic.ContentBlockParam;
+        } else {
+          return {
+            type: "image",
+            source: {
+              type: "base64" as const,
+              media_type: "image/jpeg",
+              data: e.image_url.url,
+            },
+          } as Anthropic.ContentBlockParam;
+        }
+`;
+
+  beforeEach(() => {
+    fs.writeFileSync(testFile, original);
+  });
+
+  it("inserts new const lines after `else {` and replaces nested props in-place without corrupting scope", async () => {
+    // Patch: add 3 const declarations after the `else {` line, and replace the
+    // two property lines inside the nested `source: { ... }` object.
+    const patch = `@@ -9,9 +9,15 @@
+         } else {
++          const dataUrlMatch = e.image_url.url.match(/^data:([^;]+);base64,(.*)$/s);
++          const mediaType = dataUrlMatch ? dataUrlMatch[1] : "image/jpeg";
++          const data = dataUrlMatch ? dataUrlMatch[2] : e.image_url.url;
+           return {
+             type: "image",
+             source: {
+               type: "base64" as const,
+-              media_type: "image/jpeg",
+-              data: e.image_url.url,
++              media_type: mediaType,
++              data,
+             },
+           } as Anthropic.ContentBlockParam;
+         }
+`;
+
+    const result = await boundPatch(testFile, patch);
+    console.log("NESTED REGRESSION RESULT:\n", result);
+
+    expect(result).not.toContain("❌ Patch failed");
+
+    const updated = fs.readFileSync(testFile, "utf8");
+    console.log("UPDATED FILE:\n", updated);
+
+    // 1. The new const declarations must be present (they were dropped by the bug).
+    expect(updated).toContain("const dataUrlMatch =");
+    expect(updated).toContain("const mediaType =");
+    expect(updated).toContain("const data =");
+
+    // 2. The replacements must have happened.
+    expect(updated).toContain("media_type: mediaType,");
+    expect(updated).toContain("data,");
+    expect(updated).not.toContain('media_type: "image/jpeg",\n              data: e.image_url.url,');
+
+    // 3. CRITICAL: the replaced property lines must remain INSIDE the
+    //    `source: { ... }` object, i.e. they must appear BEFORE the object's
+    //    closing `},`. The bug moved them after it.
+    const base64Idx = updated.indexOf('type: "base64" as const,');
+    const mediaTypeIdx = updated.indexOf("media_type: mediaType,");
+    const dataIdx = updated.indexOf("\n              data,");
+    // The `source` object closes with the first `},` that follows the
+    // base64 source type line.
+    const sourceCloseIdx = updated.indexOf("},", base64Idx);
+
+    expect(base64Idx).toBeGreaterThan(-1);
+    expect(mediaTypeIdx).toBeGreaterThan(-1);
+    expect(dataIdx).toBeGreaterThan(-1);
+    expect(sourceCloseIdx).toBeGreaterThan(-1);
+
+    // media_type and data must come BEFORE the source object's closing brace.
+    expect(mediaTypeIdx).toBeLessThan(sourceCloseIdx);
+    expect(dataIdx).toBeLessThan(sourceCloseIdx);
+
+    // 4. Brace balance sanity: the number of `{` and `}` must be unchanged
+    //    relative to the original (we didn't add or remove any braces).
+    const countChar = (s: string, c: string) => s.split(c).length - 1;
+    expect(countChar(updated, "{")).toBe(countChar(original, "{"));
+    expect(countChar(updated, "}")).toBe(countChar(original, "}"));
+  });
+
+  it("survives auto-correction (wrong line numbers + short context) without corrupting scope", async () => {
+    // This mirrors the *actual* hand-written patch that got mangled: wrong
+    // header line numbers and minimal context, which forces the fixPatch /
+    // fixSingleHunk re-anchoring path. The bug dropped the added const lines
+    // and moved the replaced props outside the `source: { ... }` object.
+    const patch = `@@ -200,8 +200,14 @@
+         } else {
++          const dataUrlMatch = e.image_url.url.match(/^data:([^;]+);base64,(.*)$/s);
++          const mediaType = dataUrlMatch ? dataUrlMatch[1] : "image/jpeg";
++          const data = dataUrlMatch ? dataUrlMatch[2] : e.image_url.url;
+           return {
+             type: "image",
+             source: {
+               type: "base64" as const,
+-              media_type: "image/jpeg",
+-              data: e.image_url.url,
++              media_type: mediaType,
++              data,
+             },
+ `;
+
+    const result = await boundPatch(testFile, patch);
+    console.log("AUTOCORRECT REGRESSION RESULT:\n", result);
+    expect(result).not.toContain("❌ Patch failed");
+
+    const updated = fs.readFileSync(testFile, "utf8");
+    console.log("AUTOCORRECT UPDATED FILE:\n", updated);
+
+    // Added const lines must survive.
+    expect(updated).toContain("const dataUrlMatch =");
+    expect(updated).toContain("const mediaType =");
+    expect(updated).toContain("const data =");
+
+    // Replaced props must stay inside the source object.
+    const base64Idx = updated.indexOf('type: "base64" as const,');
+    const mediaTypeIdx = updated.indexOf("media_type: mediaType,");
+    const sourceCloseIdx = updated.indexOf("},", base64Idx);
+    expect(mediaTypeIdx).toBeGreaterThan(-1);
+    expect(sourceCloseIdx).toBeGreaterThan(-1);
+    expect(mediaTypeIdx).toBeLessThan(sourceCloseIdx);
+
+    // Brace balance unchanged.
+    const countChar = (s: string, c: string) => s.split(c).length - 1;
+    expect(countChar(updated, "{")).toBe(countChar(original, "{"));
+    expect(countChar(updated, "}")).toBe(countChar(original, "}"));
+  });
+});