@tyvm/knowhow 0.0.97 → 0.0.99

package/src/clients/openai.ts

@@ -28,8 +28,20 @@ import {
   ChatCompletionToolMessageParam,
   ChatCompletionMessageToolCall,
 } from "openai/resources/chat";
+import { ResponseFunctionToolCall } from "openai/resources/responses/responses";
 
-import { EmbeddingModels, Models, OpenAiReasoningModels } from "../types";
+import {
+  EmbeddingModels,
+  Models,
+  OpenAiReasoningModels,
+  OpenAiResponsesOnlyModels,
+  OpenAiImageModels,
+  OpenAiVideoModels,
+  OpenAiTTSModels,
+  OpenAiTranscriptionModels,
+  OpenAiEmbeddingModels,
+} from "../types";
+import { ModelModality } from "./types";
 
 const config = getConfigSync();
 
@@ -87,6 +99,11 @@ export class GenericOpenAiClient implements GenericClient {
   async createChatCompletion(
     options: CompletionOptions
   ): Promise<CompletionResponse> {
+    // Route to Responses API for models that don't support Chat Completions
+    if (OpenAiResponsesOnlyModels.includes(options.model)) {
+      return this.createChatResponse(options);
+    }
+
     const openaiMessages = options.messages.map((msg) => {
       if (msg.role === "tool") {
         return {
@@ -133,6 +150,184 @@ export class GenericOpenAiClient implements GenericClient {
       usd_cost: usdCost,
     };
   }
+  /**
+   * Creates a completion using the OpenAI Responses API.
+   * Used for models that only support the Responses API (e.g. gpt-5.3-codex, gpt-5.4).
+   * Translates Chat Completions message format to Responses API format and maps the
+   * response back to CompletionResponse.
+   */
+  /**
+   * Attempts to repair truncated JSON arguments from the Responses API.
+   * Codex sometimes returns function_call arguments with truncated JSON strings.
+   * This tries to close open strings/objects to produce valid JSON.
+   */
+  private repairTruncatedJson(args: string): string {
+    try {
+      JSON.parse(args);
+      return args; // Already valid
+    } catch {
+      // Try to repair by closing open structures
+      let repaired = args.trimEnd();
+      // Count open/close braces and brackets
+      let depth = 0;
+      let inString = false;
+      let escaped = false;
+      for (const ch of repaired) {
+        if (escaped) { escaped = false; continue; }
+        if (ch === '\\' && inString) { escaped = true; continue; }
+        if (ch === '"') { inString = !inString; continue; }
+        if (!inString) {
+          if (ch === '{' || ch === '[') depth++;
+          else if (ch === '}' || ch === ']') depth--;
+        }
+      }
+      // If we're inside a string, close it
+      if (inString) repaired += '"';
+      // Close any open objects/arrays
+      for (let i = 0; i < depth; i++) repaired += '}';
+      try {
+        JSON.parse(repaired);
+        return repaired;
+      } catch {
+        return args; // Return original if repair failed
+      }
+    }
+  }
+
+  async createChatResponse(
+    options: CompletionOptions
+  ): Promise<CompletionResponse> {
+    // Extract system message to use as instructions
+    const systemMessages = options.messages.filter(
+      (m) => m.role === "system"
+    );
+    const nonSystemMessages = options.messages.filter(
+      (m) => m.role !== "system"
+    );
+    const instructions = systemMessages
+      .map((m) => (typeof m.content === "string" ? m.content : ""))
+      .join("\n")
+      .trim() || undefined;
+
+    // Convert chat messages to Responses API input items
+    // The Responses API accepts: user/assistant/system messages and function_call_output items
+    const input: any[] = nonSystemMessages.map((msg) => {
+      if (msg.role === "tool") {
+        // tool result → function_call_output
+        return {
+          type: "function_call_output",
+          call_id: msg.tool_call_id,
+          output: typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content),
+        };
+      }
+      if (msg.role === "assistant" && msg.tool_calls?.length) {
+        // assistant message with tool calls → function_call items
+        return msg.tool_calls.map((tc) => ({
+          type: "function_call",
+          // id must start with 'fc_'; call_id is the original call_ ID used for function_call_output matching
+          id: tc.id.startsWith("fc") ? tc.id : `fc_${tc.id}`,
+          call_id: tc.id,
+          name: tc.function.name,
+          arguments: tc.function.arguments,
+        }));
+      }
+      // Regular user/assistant message
+      return {
+        role: msg.role,
+        content: typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content),
+      };
+    }).flat();
+
+    // Convert Chat Completions tool definitions to Responses API FunctionTool format
+    const tools = options.tools?.map((tool) => ({
+      type: "function" as const,
+      name: tool.function.name,
+      description: tool.function.description,
+      parameters: tool.function.parameters as Record<string, unknown>,
+      strict: false,
+    }));
+
+    const response = await this.client.responses.create({
+      model: options.model as any,
+      input,
+      ...(instructions && { instructions }),
+      // Don't limit max_output_tokens for Responses API - codex truncates tool call arguments when limited
+      ...(OpenAiReasoningModels.includes(options.model) && {
+        max_output_tokens: Math.max(options.max_tokens || 0, 16000),
+        reasoning: { effort: this.reasoningEffort(options.messages) },
+      }),
+      ...(tools?.length && {
+        tools,
+        tool_choice: "auto",
+      }),
+      store: false,
+    } as any);
+
+    // Map Responses API usage to Chat Completions usage format
+    const usage = response.usage
+      ? {
+          prompt_tokens: response.usage.input_tokens,
+          completion_tokens: response.usage.output_tokens,
+          total_tokens:
+            response.usage.input_tokens + response.usage.output_tokens,
+        }
+      : undefined;
+
+    const usdCost = usage
+      ? this.calculateCost(options.model, usage)
+      : undefined;
+
+    // Collect text content and tool calls from the output items
+    let textContent: string | null = null;
+    const toolCalls: ChatCompletionMessageToolCall[] = [];
+
+    for (const item of response.output) {
+      if (item.type === "message") {
+        // ResponseOutputMessage
+        const msgItem = item as any;
+        for (const part of msgItem.content ?? []) {
+          if (part.type === "output_text") {
+            textContent = (textContent ?? "") + part.text;
+          }
+        }
+      } else if (item.type === "function_call") {
+        // ResponseFunctionToolCall
+        const fc = item as ResponseFunctionToolCall;
+        const repairedArgs = this.repairTruncatedJson(fc.arguments);
+        // Validate at the boundary - log if still invalid after repair
+        try {
+          JSON.parse(repairedArgs);
+        } catch (e) {
+          console.warn(`[Responses API] Invalid JSON arguments for ${fc.name} after repair: ${e.message}`);
+        }
+        toolCalls.push({
+          // Store call_id so function_call_output.call_id matches it in subsequent turns
+          id: fc.call_id,
+          type: "function",
+          function: {
+            name: fc.name,
+            arguments: repairedArgs,
+          },
+        });
+      }
+    }
+
+    return {
+      choices: [
+        {
+          message: {
+            role: "assistant",
+            content: textContent,
+            ...(toolCalls.length > 0 && { tool_calls: toolCalls }),
+          },
+        },
+      ],
+      model: options.model,
+      usage,
+      usd_cost: usdCost,
+    };
+  }
+
 
   pricesPerMillion() {
     return OpenAiTextPricing;
@@ -167,15 +362,23 @@ export class GenericOpenAiClient implements GenericClient {
     return total;
   }
 
-  async getModels() {
-    const models = await this.client.models.list();
-    return models.data.map((m) => {
-      return {
-        id: m.id,
-        object: m.object,
-        owned_by: m.owned_by,
+  async getModels(modality?: ModelModality): Promise<{ id: string }[]> {
+    if (modality) {
+      const map: Partial<Record<ModelModality, string[]>> = {
+        completion: Object.values(Models.openai),
+        embedding: OpenAiEmbeddingModels,
+        image: OpenAiImageModels,
+        audio: [...OpenAiTTSModels, ...OpenAiTranscriptionModels],
+        transcription: OpenAiTranscriptionModels,
+        video: OpenAiVideoModels,
       };
-    });
+      return (map[modality] ?? []).map((id) => ({ id }));
+    }
+    // No modality — live API call (backward compat)
+    const models = await this.client.models.list();
+    return models.data.map((m) => ({
+      id: m.id,
+    }));
   }
 
   async createEmbedding(options: EmbeddingOptions): Promise<EmbeddingResponse> {
@@ -213,7 +416,7 @@ export class GenericOpenAiClient implements GenericClient {
 
     // Calculate cost: $0.006 per minute for Whisper
     const duration = typeof response === "object" && "duration" in response && typeof response.duration === "number"
-      ? response.duration 
+      ? response.duration
       : undefined;
     const usdCost = duration ? (duration / 60) * 0.006 : undefined;
 

package/src/clients/types.ts

@@ -1,3 +1,5 @@
+export type ModelModality = "completion" | "embedding" | "image" | "audio" | "video" | "transcription";
+
 export type MessageContent =
   | { type: "text"; text: string }
   | { type: "image_url"; image_url: { url: string } }
@@ -257,7 +259,11 @@ export interface GenericClient {
   uploadFile?(options: FileUploadOptions): Promise<FileUploadResponse>;
   /** Download a file from the provider's file storage */
   downloadFile?(options: FileDownloadOptions): Promise<FileDownloadResponse>;
-  getModels(): Promise<{ id: string }[]>;
+  /**
+   * When modality is provided, return only models for that modality (static list).
+   * When omitted, return ALL models (backward compat — may do a live API call).
+   */
+  getModels(modality?: ModelModality): Promise<{ id: string; modality?: ModelModality[] }[]>;
   /**
    * Returns the context window limit and compression threshold for a given model,
    * or undefined if the model is not known to this client.

package/src/clients/xai.ts

@@ -27,7 +27,8 @@ import {
   ChatCompletionToolMessageParam,
 } from "openai/resources/chat";
 
-import { Models } from "../types";
+import { Models, XaiImageModels, XaiVideoModels } from "../types";
+import { ModelModality } from "./types";
 
 export class GenericXAIClient implements GenericClient {
   private client: OpenAI;
@@ -124,11 +125,17 @@ export class GenericXAIClient implements GenericClient {
     return total;
   }
 
-  async getModels() {
-    // XAI doesn't provide a model listing endpoint, so we'll return the static list
-    return Object.keys(Models.xai).map((key) => ({
-      id: Models.xai[key],
-    }));
+  async getModels(modality?: ModelModality): Promise<{ id: string }[]> {
+    if (modality) {
+      const map: Partial<Record<ModelModality, string[]>> = {
+        completion: Object.values(Models.xai),
+        image: XaiImageModels,
+        video: XaiVideoModels,
+      };
+      return (map[modality] ?? []).map((id) => ({ id }));
+    }
+    // No modality — return full static list (XAI has no /models endpoint)
+    return Object.values(Models.xai).map((id) => ({ id }));
   }
 
   async createEmbedding(options: EmbeddingOptions): Promise<EmbeddingResponse> {

package/src/cloudWorker.ts

@@ -0,0 +1,314 @@
+import * as fs from "fs";
+import * as path from "path";
+import { glob } from "glob";
+import { KnowhowSimpleClient, KNOWHOW_API_URL } from "./services/KnowhowClient";
+import { loadJwt } from "./login";
+import { getConfig, updateConfig, getLanguageConfig } from "./config";
+import { services } from "./services";
+import { Language, Config } from "./types";
+import { S3Service } from "./services/S3";
+
+export interface CloudWorkerOptions {
+  create?: boolean;
+  push?: string; // uid of existing cloud worker
+  name?: string; // optional name for create
+  apiUrl?: string;
+  dryRun?: boolean;
+}
+
+/**
+ * Represents a file to be synced to the remote cloud worker
+ */
+interface FileToSync {
+  localPath: string;
+  remotePath: string;
+  downloadLocalPath?: string; // override localPath used when worker downloads the file
+}
+
+/**
+ * Build the worker config JSON from the local knowhow config
+ */
+function buildWorkerConfigJson(config: Config, files: { remotePath: string; localPath: string; direction?: string }[]) {
+  return {
+    promptsDir: config.promptsDir,
+    modules: config.modules,
+    plugins: config.plugins,
+    lintCommands: config.lintCommands,
+    embedSources: config.embedSources,
+    sources: config.sources,
+    agents: config.agents,
+    files,
+    worker: {
+      tunnel: {
+        allowedPorts: config.worker?.tunnel?.allowedPorts ?? [],
+      },
+    },
+  };
+}
+
+/**
+ * Collect all files from the .knowhow directory that should be synced
+ */
+async function collectFilesToSync(projectName: string): Promise<FileToSync[]> {
+  const filesToSync: FileToSync[] = [];
+
+  // Helper to add file if it exists
+  const addIfExists = (localPath: string, remotePath: string) => {
+    if (fs.existsSync(localPath)) {
+      filesToSync.push({ localPath, remotePath });
+    }
+  };
+
+  // .knowhow/language.json
+  addIfExists(".knowhow/language.json", `${projectName}/.knowhow/language.json`);
+
+  // .knowhow/hashes.json
+  addIfExists(".knowhow/hashes.json", `${projectName}/.knowhow/hashes.json`);
+
+  // .knowhow/prompts/**/*
+  const promptFiles = await glob(".knowhow/prompts/**/*", { nodir: true });
+  for (const filePath of promptFiles) {
+    const relativeToDotKnowhow = filePath.replace(/^\.knowhow\//, "");
+    const remotePath = `${projectName}/.knowhow/${relativeToDotKnowhow}`;
+    filesToSync.push({ localPath: filePath, remotePath });
+  }
+
+  // .knowhow/scripts/**/* (if exists)
+  if (fs.existsSync(".knowhow/scripts")) {
+    const scriptFiles = await glob(".knowhow/scripts/**/*", { nodir: true });
+    for (const filePath of scriptFiles) {
+      const relativeToDotKnowhow = filePath.replace(/^\.knowhow\//, "");
+      const remotePath = `${projectName}/.knowhow/${relativeToDotKnowhow}`;
+      filesToSync.push({ localPath: filePath, remotePath });
+    }
+  }
+
+  // .knowhow/skills/**/* (if exists)
+  if (fs.existsSync(".knowhow/skills")) {
+    const skillFiles = await glob(".knowhow/skills/**/*", { nodir: true });
+    for (const filePath of skillFiles) {
+      const relativeToDotKnowhow = filePath.replace(/^\.knowhow\//, "");
+      const remotePath = `${projectName}/.knowhow/${relativeToDotKnowhow}`;
+      filesToSync.push({ localPath: filePath, remotePath });
+    }
+  }
+
+  return filesToSync;
+}
+
+/**
+ * Collect files referenced in language.json sources
+ */
+async function collectLanguageReferencedFiles(
+  language: Language,
+  projectName: string
+): Promise<FileToSync[]> {
+  const filesToSync: FileToSync[] = [];
+
+  for (const term of Object.keys(language)) {
+    const entry = language[term];
+    if (!entry.sources) continue;
+
+    for (const source of entry.sources) {
+      if (source.kind !== "file" || !source.data) continue;
+
+      for (const filePath of source.data) {
+        // Normalize the path (strip leading ./)
+        const normalizedPath = filePath.replace(/^\.\//, "");
+
+        // Skip the main knowhow config — it should not be synced to the language folder
+        // as it would overwrite the worker's own config
+        if (normalizedPath === ".knowhow/knowhow.json") continue;
+
+        if (fs.existsSync(normalizedPath)) {
+          const basename = path.basename(normalizedPath);
+          const remotePath = `${projectName}/.knowhow/language/${basename}`;
+          // localPath is the original path so the worker downloads it to the right place
+          filesToSync.push({ localPath: normalizedPath, remotePath, downloadLocalPath: normalizedPath });
+        }
+      }
+    }
+  }
+
+  return filesToSync;
+}
+
+/**
+ * Upload a single file to the cloud worker's file storage
+ */
+async function uploadSingleFile(
+  client: KnowhowSimpleClient,
+  s3Service: S3Service,
+  localPath: string,
+  remotePath: string,
+  dryRun: boolean
+): Promise<void> {
+  console.log(`  ⬆️  Uploading ${localPath} → ${remotePath}`);
+
+  if (dryRun) {
+    console.log(`     [DRY RUN] Would upload from ${localPath}`);
+    return;
+  }
+
+  if (!fs.existsSync(localPath)) {
+    console.warn(`     ⚠️  Local file not found, skipping: ${localPath}`);
+    return;
+  }
+
+  const presignedUrl = await client.getOrgFilePresignedUploadUrl(remotePath);
+  await s3Service.uploadToPresignedUrl(presignedUrl, localPath);
+  await client.markOrgFileUploadComplete(remotePath);
+
+  const stats = fs.statSync(localPath);
+  console.log(`     ✓ Uploaded ${stats.size} bytes`);
+}
+
+/**
+ * Main cloudWorker command handler
+ */
+export async function cloudWorker(options: CloudWorkerOptions) {
+  const {
+    create = false,
+    push,
+    name,
+    apiUrl = KNOWHOW_API_URL,
+    dryRun = false,
+  } = options;
+
+  if (!create && !push) {
+    console.error("❌ Please specify --create or --push <uid>");
+    process.exit(1);
+  }
+
+  // Load JWT token
+  const jwt = await loadJwt();
+  if (!jwt) {
+    console.error("❌ No JWT token found. Please run 'knowhow login' first.");
+    process.exit(1);
+  }
+
+  // Load local config
+  const config = await getConfig();
+  if (!config || Object.keys(config).length === 0) {
+    console.error("❌ No knowhow config found. Please run 'knowhow init' first.");
+    process.exit(1);
+  }
+
+  // Load language config
+  const language = await getLanguageConfig();
+
+  // Get project name from current directory
+  const projectName = path.basename(process.cwd());
+  console.log(`📁 Project name: ${projectName}`);
+
+  // Create API client
+  const client = new KnowhowSimpleClient(apiUrl, jwt);
+
+  // Get S3 service
+  const { AwsS3 } = services();
+
+  // Step 1: Collect all files to sync
+  console.log("\n📂 Collecting files to sync...");
+  const mainFiles = await collectFilesToSync(projectName);
+  const languageFiles = await collectLanguageReferencedFiles(language, projectName);
+
+  // Deduplicate by remotePath
+  const allFilesMap = new Map<string, FileToSync>();
+  for (const f of [...mainFiles, ...languageFiles]) {
+    allFilesMap.set(f.remotePath, f);
+  }
+  const allFiles = Array.from(allFilesMap.values());
+
+  console.log(`   Found ${allFiles.length} files to sync`);
+
+  if (dryRun) {
+    console.log("\n📋 Files that would be synced:");
+    for (const f of allFiles) {
+      console.log(`   ${f.localPath} → ${f.remotePath}`);
+    }
+  }
+
+  // Step 2: Build the config.files array for all synced files
+  const configFilesEntries = allFiles.map((f) => ({
+    remotePath: f.remotePath,
+    localPath: f.downloadLocalPath ?? f.localPath,
+    direction: "download" as const,
+  }));
+
+  // Step 3: Update config.files and save
+  console.log("\n💾 Updating config.files with sync entries...");
+  if (!dryRun) {
+    // Preserve any existing files entries not in our set
+    const existingFiles = config.files || [];
+    const newRemotePaths = new Set(configFilesEntries.map((e) => e.remotePath));
+
+    // Keep entries that don't overlap with new ones
+    const preserved = existingFiles.filter(
+      (e) => !newRemotePaths.has(e.remotePath)
+    );
+
+    config.files = [...preserved, ...configFilesEntries];
+    await updateConfig(config);
+    console.log(`   ✓ Updated config with ${config.files.length} file entries`);
+  } else {
+    console.log(`   [DRY RUN] Would update config with ${configFilesEntries.length} file entries`);
+  }
+
+  // Step 4: Build workerConfigJson
+  const workerConfigJson = buildWorkerConfigJson(config, configFilesEntries);
+
+  // Step 5: Upload all files
+  console.log(`\n🚀 Uploading ${allFiles.length} files...`);
+  let successCount = 0;
+  let failCount = 0;
+
+  for (const file of allFiles) {
+    try {
+      await uploadSingleFile(client, AwsS3, file.localPath, file.remotePath, dryRun);
+      successCount++;
+    } catch (error) {
+      console.error(`  ❌ Failed to upload ${file.localPath}: ${error.message}`);
+      failCount++;
+    }
+  }
+
+  console.log(`\n   ✓ Upload complete: ${successCount} succeeded, ${failCount} failed`);
+
+  // Step 6: Create or update cloud worker
+  if (create) {
+    const workerName = name || `${projectName}-worker`;
+    console.log(`\n🌩️  Creating cloud worker "${workerName}"...`);
+
+    if (dryRun) {
+      console.log(`   [DRY RUN] Would create cloud worker with name: ${workerName}`);
+      console.log(`   [DRY RUN] workerConfigJson:`, JSON.stringify(workerConfigJson, null, 2));
+    } else {
+      const result = await client.createCloudWorker({
+        name: workerName,
+        workerConfigJson,
+      });
+      const createdWorker = result.data;
+      console.log(`   ✓ Cloud worker created!`);
+      console.log(`   ID: ${createdWorker.id}`);
+      console.log(`   Name: ${createdWorker.name}`);
+      console.log(`\n💡 To push updates later, run:`);
+      console.log(`   knowhow cloudworker --push ${createdWorker.id}`);
+    }
+  } else if (push) {
+    console.log(`\n🌩️  Updating cloud worker "${push}"...`);
+
+    if (dryRun) {
+      console.log(`   [DRY RUN] Would update cloud worker ${push}`);
+      console.log(`   [DRY RUN] workerConfigJson:`, JSON.stringify(workerConfigJson, null, 2));
+    } else {
+      await client.updateCloudWorker(push, { workerConfigJson });
+      console.log(`   ✓ Cloud worker updated!`);
+    }
+  }
+
+  if (failCount > 0) {
+    console.warn(`\n⚠️  ${failCount} file(s) failed to upload.`);
+  } else {
+    console.log(`\n✅ Cloud worker sync complete!`);
+  }
+}

package/src/config.ts

@@ -4,6 +4,7 @@ import * as os from "os";
 import gitignoreToGlob from "gitignore-to-glob";
 import { Prompts } from "./prompts";
 import { promisify } from "util";
+import { KNOWHOW_API_URL } from "./services/KnowhowClient";
 import {
   Config,
   Language,
@@ -85,7 +86,14 @@ const defaultConfig = {
     },
   ],
 
-  modelProviders: [{ url: "http://localhost:1234", provider: "lms" }],
+  modelProviders: [
+    { provider: "openai", envKey: "OPENAI_API_KEY" },
+    { provider: "anthropic", envKey: "ANTHROPIC_API_KEY" },
+    { provider: "google", envKey: "GEMINI_API_KEY" },
+    { provider: "xai", envKey: "XAI_API_KEY" },
+    { provider: "knowhow" },
+    { provider: "lms", url: "http://localhost:1234" },
+  ],
 
   ycmd: {
     enabled: false,

package/src/processors/TokenCompressor.ts

@@ -241,7 +241,14 @@ export class TokenCompressor implements JsonCompressorStorage {
   public async compressMessage(message: Message) {
     // Compress content if it's a string
     if (typeof message.content === "string") {
-      message.content = this.compressContent(message.content);
+      const compressed = this.compressContent(message.content);
+      // If this is a tool message with a tool_call_id, append it to the compressed content
+      // so the agent knows which toolCallId to use for grepToolResponse/jqToolResponse/tailToolResponse
+      if (message.role === "tool" && message.tool_call_id && compressed !== message.content) {
+        message.content = compressed + `\n[toolCallId: ${message.tool_call_id}]`;
+      } else {
+        message.content = compressed;
+      }
     }
     // Handle array content (multimodal)
     else if (Array.isArray(message.content)) {