@tyvm/knowhow 0.0.117 → 0.0.119

package/src/agents/tools/readFile.ts

@@ -3,7 +3,6 @@ import { fileExists } from "../../utils";
 import { services, ToolsService } from "../../services";
 import { getConfiguredEmbeddings } from "../../embeddings";
 import { fileSearch } from "./fileSearch";
-import { createPatch } from "diff";
 
 /*
  *export function readFile(filePath: string): string {
@@ -18,7 +17,23 @@ import { createPatch } from "diff";
  *}
  */
 
-export async function readFile(filePath: string): Promise<string> {
+/**
+ * Reads the contents of a file and returns them as plain text.
+ *
+ * Optionally accepts a 1-based, inclusive line range so callers can pull just
+ * the region they care about in a single call. When a range is supplied the
+ * returned content is prefixed with real source line numbers so the output can
+ * be mapped straight back to an editable location.
+ *
+ * @param filePath The path to the file to read
+ * @param fromLine Optional 1-based start line (inclusive)
+ * @param toLine Optional 1-based end line (inclusive)
+ */
+export async function readFile(
+  filePath: string,
+  fromLine?: number,
+  toLine?: number
+): Promise<string> {
   // Get context from bound ToolsService
   const toolService = (
     this instanceof ToolsService ? this : services().Tools
@@ -48,9 +63,9 @@ export async function readFile(filePath: string): Promise<string> {
   }
 
   const text = fs.readFileSync(filePath, "utf8");
-  const patch = createPatch(filePath, "", text);
 
-  // Emit post-read non-blocking event
+  // Emit post-read non-blocking event with the full file content so listeners
+  // (e.g. indexers) always see the complete file regardless of any range slice.
   if (context.Events) {
     await context.Events.emitNonBlocking("file:post-read", {
       filePath,
@@ -58,5 +73,33 @@ export async function readFile(filePath: string): Promise<string> {
     });
   }
 
-  return patch;
+  const hasRange =
+    typeof fromLine === "number" || typeof toLine === "number";
+
+  if (!hasRange) {
+    return text;
+  }
+
+  // Build a ranged read with real, 1-based source line numbers.
+  const lines = text.split("\n");
+  const totalLines = lines.length;
+
+  const start = Math.max(1, typeof fromLine === "number" ? fromLine : 1);
+  const end = Math.min(
+    totalLines,
+    typeof toLine === "number" ? toLine : totalLines
+  );
+
+  if (start > end) {
+    throw new Error(
+      `Invalid line range for ${filePath}: fromLine (${start}) is greater than toLine (${end}). File has ${totalLines} lines.`
+    );
+  }
+
+  const numbered = [];
+  for (let i = start; i <= end; i++) {
+    numbered.push(`${i}: ${lines[i - 1]}`);
+  }
+
+  return numbered.join("\n");
 }

package/src/chat/modules/AgentModule.ts

@@ -122,6 +122,18 @@ export class AgentModule extends BaseChatModule {
           }
         },
       },
+      {
+        name: "poke",
+        description: "Interrupt the agent's current tool call or AI completion, so it can continue with the next step",
+        modes: ["agent:attached"],
+        handler: async (args: string[]): Promise<void> => {
+          if (this.attachedAgent) {
+            const message = args.length > 0 ? args.join(" ") : undefined;
+            this.attachedAgent.interrupt(message);
+            console.log("Agent interrupted — it will continue with the next step.");
+          }
+        },
+      },
       {
         name: "detach",
         description: "Detach from the currently attached agent",

package/src/cli.ts

@@ -10,6 +10,7 @@ import { ModulesService } from "./services/modules";
 
 // Command registrars
 import { addModulesCommand } from "./commands/modules";
+import { addMcpCommands } from "./commands/mcp";
 import {
   addWorkerCommand,
   addWorkersCommand,
@@ -35,6 +36,7 @@ import {
   addChatCommand,
   addGithubCredentialsCommand,
 } from "./commands/misc";
+import { addConvertCommand } from "./commands/convert";
 
 // Handle unhandled promise rejections gracefully — particularly from MCP SDK
 // which fires errors via event emitters that can bypass Promise.allSettled.
@@ -96,6 +98,8 @@ async function main() {
   addCloudWorkerCommand(program);
   addGithubCredentialsCommand(program);
   addModulesCommand(program);
+  addMcpCommands(program);
+  addConvertCommand(program);
 
   // Load global modules early (before parse) so they can register CLI subcommands.
   // We pass only the Program in context — no services are spun up at this stage.

package/src/clients/anthropic.ts

@@ -329,12 +329,22 @@ export class GenericAnthropicClient implements GenericClient {
             },
           } as Anthropic.ContentBlockParam;
         } else {
+          // Data URL or raw base64. Anthropic's base64 source expects the
+          // media_type separately and the data WITHOUT the
+          // "data:<mime>;base64," prefix. Parse it out here.
+          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.replace(/^data:[^,]*,/, "");
           return {
             type: "image",
             source: {
               type: "base64" as const,
-              media_type: "image/jpeg",
-              data: e.image_url.url,
+              media_type: mediaType,
+              data,
             },
           } as Anthropic.ContentBlockParam;
         }

package/src/clients/contextLimits.ts

@@ -10,6 +10,7 @@ import { Models, EmbeddingModels } from "../types";
  */
 export const ContextLimits: Record<string, number> = {
   // ─── OpenAI ───────────────────────────────────────────────────────────────
+  [Models.openai.GPT_55]: 1_000_000,
   [Models.openai.GPT_54]: 1_000_000,
   [Models.openai.GPT_54_Mini]: 400_000,
   [Models.openai.GPT_54_Nano]: 400_000,
@@ -40,8 +41,49 @@ export const ContextLimits: Record<string, number> = {
   [Models.openai.o3_Pro]: 200_000,
   [Models.openai.o3_Mini]: 200_000,
   [Models.openai.o4_Mini]: 200_000,
+  // ─── OpenAI (aliases / deprecated / non-text) ─────────────────────────────
+  [Models.openai.GPT_55_Pro]: 1_000_000,
+  [Models.openai.GPT_53_Codex_Spark]: 1_000_000,
+  [Models.openai.GPT_52_Chat]: 1_000_000,
+  [Models.openai.GPT_52_Codex]: 1_000_000,
+  [Models.openai.GPT_52_Pro]: 1_000_000,
+  [Models.openai.GPT_51_Chat]: 1_000_000,
+  [Models.openai.GPT_51_Codex]: 1_000_000,
+  [Models.openai.GPT_51_Codex_Max]: 1_000_000,
+  [Models.openai.GPT_51_Codex_Mini]: 1_000_000,
+  [Models.openai.GPT_5_Pro]: 1_000_000,
+  [Models.openai.GPT_5_Chat]: 1_000_000,
+  [Models.openai.GPT_5_Codex]: 1_000_000,
+  [Models.openai.o1_Preview]: 128_000,
+  [Models.openai.o3_Deep_Research]: 200_000,
+  [Models.openai.o4_Mini_Deep_Research]: 200_000,
+  [Models.openai.GPT_4o_Transcribe]: 128_000,
+  [Models.openai.GPT_4o_Mini_Transcribe]: 128_000,
+  [Models.openai.GPT_Realtime_15]: 128_000,
+  [Models.openai.GPT_Realtime_Mini]: 128_000,
+  [Models.openai.GPT_4o_2024_05_13]: 128_000,
+  [Models.openai.GPT_4o_2024_11_20]: 128_000,
+  [Models.openai.GPT_35_Turbo]: 16_385,
+  [Models.openai.GPT_4]: 8_192,
+  [Models.openai.GPT_4_Turbo]: 128_000,
+  // OpenAI image/video/audio models — no text context window
+  [Models.openai.GPT_Image_2]: 0,
+  [Models.openai.GPT_Image_15]: 0,
+  [Models.openai.GPT_Image_1]: 0,
+  [Models.openai.GPT_Image_1_Mini]: 0,
+  [Models.openai.ChatGPT_Image]: 0,
+  [Models.openai.TTS_1]: 0,
+  [Models.openai.Whisper_1]: 0,
+  [Models.openai.DALL_E_3]: 0,
+  [Models.openai.DALL_E_2]: 0,
+  [Models.openai.Sora]: 0,
+  [Models.openai.Sora_2]: 0,
+  [Models.openai.Sora_2_Pro]: 0,
 
   // ─── Anthropic ────────────────────────────────────────────────────────────
+  [Models.anthropic.Opus4_8Fast]: 1_000_000,
+  [Models.anthropic.Opus4_8]: 1_000_000,
+  [Models.anthropic.Opus4_7]: 1_000_000,
   [Models.anthropic.Opus4_6]: 1_000_000,
   [Models.anthropic.Opus4_6Fast]: 1_000_000,
   [Models.anthropic.Sonnet4_6]: 1_000_000,
@@ -57,10 +99,18 @@ export const ContextLimits: Record<string, number> = {
   [Models.anthropic.Haiku3]: 200_000,
   [Models.anthropic.Haiku3_5]: 200_000,
 
+  // ─── Anthropic (aliases / deprecated) ────────────────────────────────────
+  [Models.anthropic.Sonnet3_5_20240620]: 200_000,
+  [Models.anthropic.Haiku3_5_Latest]: 200_000,
+  [Models.anthropic.Sonnet3]: 200_000,
+  [Models.anthropic.Opus4_0]: 200_000,
+  [Models.anthropic.Sonnet4_0]: 200_000,
+
   // ─── Google ───────────────────────────────────────────────────────────────
   [Models.google.Gemini_31_Pro_Preview]: 1_000_000,
   [Models.google.Gemini_31_Flash_Image_Preview]: 1_000_000,
   [Models.google.Gemini_31_Flash_Lite_Preview]: 1_000_000,
+  [Models.google.Gemini_31_Flash_Live_Preview]: 1_000_000,
   [Models.google.Gemini_3_Flash_Preview]: 1_000_000,
   [Models.google.Gemini_3_Pro_Image_Preview]: 1_000_000,
   [Models.google.Gemini_25_Pro]: 1_000_000,
@@ -70,9 +120,20 @@ export const ContextLimits: Record<string, number> = {
   [Models.google.Gemini_25_Pro_Preview]: 1_000_000,
   [Models.google.Gemini_25_Flash_Image]: 1_000_000,
   [Models.google.Gemini_25_Flash_Live]: 1_000_000,
+  [Models.google.Gemini_25_Flash_Preview_0417]: 1_000_000,
+  [Models.google.Gemini_25_Flash_Image_Preview]: 1_000_000,
   [Models.google.Gemini_25_Flash_Native_Audio]: 1_000_000,
   [Models.google.Gemini_25_Flash_TTS]: 1_000_000,
   [Models.google.Gemini_25_Pro_TTS]: 1_000_000,
+  // Google image/video generation models — no text context window; use 0
+  [Models.google.Imagen_3]: 0,
+  [Models.google.Imagen_4_Fast]: 0,
+  [Models.google.Imagen_4_Ultra]: 0,
+  [Models.google.Veo_2]: 0,
+  [Models.google.Veo_3]: 0,
+  [Models.google.Veo_3_Fast]: 0,
+  [Models.google.Veo_3_1]: 0,
+  [Models.google.Veo_3_1_Fast]: 0,
   [Models.google.Gemini_20_Flash]: 1_000_000,
   [Models.google.Gemini_20_Flash_Preview_Image_Generation]: 1_000_000,
   [Models.google.Gemini_20_Flash_Live]: 1_000_000,
@@ -95,6 +156,22 @@ export const ContextLimits: Record<string, number> = {
   [Models.xai.Grok3MiniFastBeta]: 131_072,
   [Models.xai.Grok21212]: 131_072,
   [Models.xai.Grok2Vision1212]: 131_072,
+  // ─── xAI (aliases / deprecated / image / video) ───────────────────────────
+  [Models.xai.Grok2Latest]: 131_072,
+  [Models.xai.Grok2VisionLatest]: 131_072,
+  [Models.xai.Grok3Latest]: 131_072,
+  [Models.xai.Grok3FastLatest]: 131_072,
+  [Models.xai.Grok3MiniLatest]: 131_072,
+  [Models.xai.Grok3MiniFastLatest]: 131_072,
+  [Models.xai.GrokBeta]: 131_072,
+  [Models.xai.GrokVisionBeta]: 131_072,
+  [Models.xai.Grok4_1_Fast]: 2_000_000,
+  [Models.xai.Grok4Fast]: 2_000_000,
+  [Models.xai.Grok4FastNonReasoning]: 2_000_000,
+  // xAI image/video models — no text context window
+  [Models.xai.GrokImagineImage]: 0,
+  [Models.xai.GrokImagineVideo]: 0,
+  [Models.xai.Grok2Image1212]: 0,
 };
 
 /** Default fallback context window limit (tokens) used when a model is not found. */

package/src/commands/convert.ts

@@ -0,0 +1,291 @@
+import { Command } from "commander";
+import * as fs from "fs";
+import * as path from "path";
+import { services } from "../services";
+import { ModulesService } from "../services/modules";
+import { getConfig } from "../config";
+import { Modality, ConvertOptions } from "../services/conversion/types";
+
+/**
+ * Load modules from config so that external converters (e.g. pdf-to-img) get
+ * registered into ConversionService before we run a conversion.
+ */
+async function setupConversionServices() {
+  const config = await getConfig();
+  const { Conversion } = services();
+
+  const allModulePaths = [
+    ...(config.modules || []),
+  ];
+
+  if (allModulePaths.length) {
+    const modulesService = new ModulesService();
+    await modulesService.loadModulesFrom(
+      { ...config, modules: allModulePaths },
+      {
+        Conversion,
+        Agents: services().Agents,
+        Embeddings: services().Embeddings,
+        Plugins: services().Plugins,
+        Clients: services().Clients,
+        Tools: services().Tools,
+        Events: services().Events,
+        MediaProcessor: services().MediaProcessor,
+      }
+    );
+  }
+
+  return { Conversion };
+}
+
+/**
+ * Modality short aliases accepted on the CLI.
+ * img, txt, vid, aud are short forms; full names also accepted.
+ */
+const MODALITY_ALIASES: Record<string, Modality> = {
+  img: "image",
+  image: "image",
+  txt: "text",
+  text: "text",
+  vid: "video",
+  video: "video",
+  aud: "audio",
+  audio: "audio",
+  html: "html",
+};
+
+/**
+ * Parse a comma-separated modality chain like "img,txt" or "image,text".
+ * Returns { via: Modality[], target: Modality }.
+ * Single value (e.g. "text") → { via: [], target: "text" }.
+ *
+ * Examples:
+ *   "text"      → via=[], target="text"
+ *   "img,txt"   → via=["image"], target="text"
+ *   "image,text"→ via=["image"], target="text"
+ */
+function parseModalityChain(raw: string): { via: Modality[]; target: Modality } {
+  const parts = raw.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+  const modalities: Modality[] = parts.map((p) => {
+    const m = MODALITY_ALIASES[p];
+    if (!m) {
+      throw new Error(
+        `Unknown modality "${p}". Valid values: text/txt, image/img, audio/aud, video/vid, html`
+      );
+    }
+    return m;
+  });
+  if (modalities.length === 0) throw new Error("--to requires at least one modality");
+  const target = modalities[modalities.length - 1];
+  const via = modalities.slice(0, -1);
+  return { via, target };
+}
+
+export function addConvertCommand(program: Command): void {
+  program
+    .command("convert")
+    .description("Convert a file between modalities (pdf, image, audio, video, text)")
+    .option("-i, --input <path>", "Source file path (required unless --list)")
+    .option("-o, --output <path>", "Output file or directory (optional; defaults to stdout for text)")
+    .option(
+      "--to <chain>",
+      "Target modality or explicit chain. Single: text|txt|image|img|audio|aud|video|vid|html. Chain (comma-separated): img,txt forces pdf→image→text path.",
+      "text"
+    )
+    .option("--from <modality>", "Override inferred input modality")
+    .option("--prefer <names>", "Comma-separated list of preferred converter names (used when --to is a single modality)")
+    .option("--force", "Ignore cache and re-run converters")
+    .option("--model <name>", "Model to use (injected into converterOptions for all converters, e.g. tts-1, dall-e-3, gpt-4o)")
+    .option("--start-page <n>", "First page (documents)", parseInt)
+    .option("--end-page <n>", "Last page (documents)", parseInt)
+    .option("--start-line <n>", "First line (text output)", parseInt)
+    .option("--end-line <n>", "Last line (text output)", parseInt)
+    .option("--start-time <n>", "Start time in seconds (audio/video)", parseFloat)
+    .option("--end-time <n>", "End time in seconds (audio/video)", parseFloat)
+    .option("--opt <spec>", "Per-converter option in format name.key=value (repeatable)", collect, [])
+    .option("--list", "List all registered converters and exit")
+    .option("--json", "Emit machine-readable JSON result")
+    .action(async (opts) => {
+      try {
+        const { Conversion } = await setupConversionServices();
+
+        // --list mode: print registered converters
+        if (opts.list) {
+          const converters = Conversion.list();
+          if (opts.json) {
+            console.log(JSON.stringify(converters.map(c => ({
+              name: c.name,
+              inputExts: c.inputExts,
+              inputModality: c.inputModality,
+              outputType: c.outputType,
+              cache: c.cache ?? false,
+            })), null, 2));
+          } else {
+            console.log("\n📦 Registered converters:\n");
+            for (const c of converters) {
+              const input = c.inputExts
+                ? c.inputExts.join(", ")
+                : c.inputModality ?? "?";
+              console.log(`  • ${c.name.padEnd(24)} ${input} → ${c.outputType}${c.cache ? " (cached)" : ""}`);
+            }
+            console.log();
+          }
+          return;
+        }
+
+        // Validate --input
+        if (!opts.input) {
+          console.error("Error: --input <path> is required (use --list to see converters)");
+          process.exit(1);
+        }
+
+        const inputPath = path.resolve(opts.input);
+        if (!fs.existsSync(inputPath)) {
+          console.error(`Error: input file not found: ${inputPath}`);
+          process.exit(1);
+        }
+
+        // Parse --to chain (e.g. "img,txt" → via=["image"], target="text")
+        let targetModality: Modality;
+        let viaModalities: Modality[] = [];
+        try {
+          const parsed = parseModalityChain(opts.to || "text");
+          targetModality = parsed.target;
+          viaModalities = parsed.via;
+        } catch (e: any) {
+          console.error(`Error: ${e.message}`);
+          process.exit(1);
+        }
+
+        // Parse --opt flags into converterOptions
+        const converterOptions: Record<string, Record<string, any>> = {};
+        for (const spec of (opts.opt as string[])) {
+          // format: converterName.key=value
+          const dotIdx = spec.indexOf(".");
+          const eqIdx = spec.indexOf("=");
+          if (dotIdx < 0 || eqIdx < 0 || eqIdx < dotIdx) {
+            console.error(`Error: --opt must be in format "converterName.key=value", got: ${spec}`);
+            process.exit(1);
+          }
+          const converterName = spec.slice(0, dotIdx);
+          const key = spec.slice(dotIdx + 1, eqIdx);
+          const rawValue = spec.slice(eqIdx + 1);
+          // Try to coerce to number/boolean, else keep as string
+          let value: any = rawValue;
+          if (rawValue === "true") value = true;
+          else if (rawValue === "false") value = false;
+          else if (!isNaN(Number(rawValue)) && rawValue !== "") value = Number(rawValue);
+
+          if (!converterOptions[converterName]) converterOptions[converterName] = {};
+          converterOptions[converterName][key] = value;
+        }
+
+        // --model injects model into all converter option scopes
+        // It can be overridden by a more specific --opt converterName.model=xxx
+        if (opts.model) {
+          const modelInjectedNames = [
+            "whisper", "ffmpeg-whisper",
+            "image-to-text",
+            "text-to-audio", "text-to-image", "text-to-video",
+            "image-to-video",
+          ];
+          for (const name of modelInjectedNames) {
+            if (!converterOptions[name]) converterOptions[name] = {};
+            if (!converterOptions[name].model) {
+              converterOptions[name].model = opts.model;
+            }
+          }
+        }
+
+        const preferredConverters = opts.prefer
+          ? opts.prefer.split(",").map((s: string) => s.trim()).filter(Boolean)
+          : [];
+
+        const chainDisplay = [...viaModalities, targetModality].join(" → ");
+        console.error(`🔄 Converting ${inputPath} → ${chainDisplay}...`);
+
+        const convertOpts: ConvertOptions = {
+          force: opts.force ?? false,
+          preferredConverters,
+          startPage: opts.startPage,
+          endPage: opts.endPage,
+          startLine: opts.startLine,
+          endLine: opts.endLine,
+          startTime: opts.startTime,
+          endTime: opts.endTime,
+          converterOptions,
+          onProgress: (stage, fraction) => {
+            const pct = Math.round(fraction * 100);
+            process.stderr.write(`\r  [${pct.toString().padStart(3)}%] ${stage}   `);
+          },
+          ...(viaModalities.length > 0 ? { via: viaModalities } : {}),
+        };
+
+        const result = await Conversion.convert(inputPath, targetModality, convertOpts);
+        process.stderr.write("\n");
+
+        if (opts.json) {
+          console.log(JSON.stringify(result, null, 2));
+          return;
+        }
+
+        // Text / HTML output
+        if (result.outputType === "text" || result.outputType === "html") {
+          if (opts.output) {
+            fs.writeFileSync(path.resolve(opts.output), result.text ?? "");
+            console.error(`✅ Written to ${opts.output}`);
+          } else {
+            process.stdout.write(result.text ?? "");
+            process.stdout.write("\n");
+          }
+          if (result.usd_cost) {
+            console.error(`💰 Cost: $${result.usd_cost.toFixed(6)}`);
+          }
+          return;
+        }
+
+        // File output (image, audio, video)
+        const files = result.files ?? [];
+        if (files.length === 0) {
+          console.error("⚠  Conversion produced no output files.");
+          return;
+        }
+
+        if (opts.output) {
+          const outPath = path.resolve(opts.output);
+          if (files.length === 1) {
+            fs.copyFileSync(files[0], outPath);
+            console.error(`✅ Written to ${outPath}`);
+          } else {
+            // Multiple files → write to directory
+            fs.mkdirSync(outPath, { recursive: true });
+            for (const f of files) {
+              const dest = path.join(outPath, path.basename(f));
+              fs.copyFileSync(f, dest);
+              console.log(dest);
+            }
+            console.error(`✅ ${files.length} files written to ${outPath}`);
+          }
+        } else {
+          // Print file paths to stdout
+          for (const f of files) {
+            console.log(f);
+          }
+        }
+
+        if (result.usd_cost) {
+          console.error(`💰 Cost: $${result.usd_cost.toFixed(6)}`);
+        }
+      } catch (err: any) {
+        console.error(`❌ Conversion failed: ${err.message}`);
+        if (process.env.DEBUG) console.error(err);
+        process.exit(1);
+      }
+    });
+}
+
+/** Commander helper: collect repeated option values into an array */
+function collect(val: string, acc: string[]): string[] {
+  acc.push(val);
+  return acc;
+}