@tyvm/knowhow 0.0.107 → 0.0.108-dev.4a8ba55

package/src/clients/anthropic.ts

@@ -40,11 +40,11 @@ export class GenericAnthropicClient implements GenericClient {
     });
   }
 
-  handleToolCaching(tools: Anthropic.Tool[]) {
+  handleToolCaching(tools: Anthropic.Tool[], longTtl = false) {
     const lastTool = tools[tools.length - 1];
 
     if (lastTool) {
-      lastTool.cache_control = { type: "ephemeral" };
+      lastTool.cache_control = longTtl ? { type: "ephemeral", ttl: "1h" } as any : { type: "ephemeral" };
     }
   }
 
@@ -94,7 +94,7 @@ export class GenericAnthropicClient implements GenericClient {
     return cleaned;
   }
 
-  transformTools(tools?: Tool[]): Anthropic.Tool[] {
+  transformTools(tools?: Tool[], longTtl = false): Anthropic.Tool[] {
     if (!tools) {
       return [];
     }
@@ -104,7 +104,7 @@ export class GenericAnthropicClient implements GenericClient {
       input_schema: this.cleanSchemaForAnthropic(tool.function.parameters) as any,
     }));
 
-    this.handleToolCaching(transformed);
+    this.handleToolCaching(transformed, longTtl);
 
     return transformed;
   }
@@ -153,16 +153,16 @@ export class GenericAnthropicClient implements GenericClient {
     return messages;
   }
 
-  cacheLastContent(message: MessageParam) {
+  cacheLastContent(message: MessageParam, longTtl = false) {
     if (Array.isArray(message.content)) {
       const lastMessage = message.content[message.content.length - 1];
       if (
         lastMessage.type !== "thinking" &&
         lastMessage.type !== "redacted_thinking"
       ) {
-        lastMessage.cache_control = {
-          type: "ephemeral",
-        };
+        lastMessage.cache_control = longTtl
+          ? ({ type: "ephemeral", ttl: "1h" } as any)
+          : { type: "ephemeral" };
       }
     }
   }
@@ -179,7 +179,7 @@ export class GenericAnthropicClient implements GenericClient {
     }
   }
 
-  handleMessageCaching(groupedMessages: MessageParam[]) {
+  handleMessageCaching(groupedMessages: MessageParam[], longTtl = false) {
     this.handleClearingCache(groupedMessages);
 
     // find the last two messages and mark them as ephemeral
@@ -189,7 +189,7 @@ export class GenericAnthropicClient implements GenericClient {
 
     for (const m of lastTwoUserMessages) {
       if (Array.isArray(m.content)) {
-        this.cacheLastContent(m);
+        this.cacheLastContent(m, longTtl);
       }
     }
   }
@@ -203,7 +203,7 @@ export class GenericAnthropicClient implements GenericClient {
     }
   }
 
-  transformMessages(messages: Message[]): MessageParam[] {
+  transformMessages(messages: Message[], longTtl = false): MessageParam[] {
     const toolCalls = messages.flatMap((msg) => msg.tool_calls || []);
     const claudeMessages: MessageParam[] = messages
       .filter((msg) => msg.role !== "system")
@@ -302,7 +302,7 @@ export class GenericAnthropicClient implements GenericClient {
 
     const groupedMessages = this.combineMessages(claudeMessages);
 
-    this.handleMessageCaching(groupedMessages);
+    this.handleMessageCaching(groupedMessages, longTtl);
 
     return groupedMessages;
   }
@@ -349,14 +349,15 @@ export class GenericAnthropicClient implements GenericClient {
   async createChatCompletion(
     options: CompletionOptions
   ): Promise<CompletionResponse> {
+    const longTtl = !!options.long_ttl_cache;
     const systemMessage = options.messages
       .filter((msg) => msg.role === "system")
       .map((msg) => msg.content || "")
       .join("\n");
 
-    const claudeMessages = this.transformMessages(options.messages);
+    const claudeMessages = this.transformMessages(options.messages, longTtl);
 
-    const tools = this.transformTools(options.tools);
+    const tools = this.transformTools(options.tools, longTtl);
     try {
       const response = await this.client.messages.create({
         model: options.model,
@@ -365,7 +366,7 @@ export class GenericAnthropicClient implements GenericClient {
           ? [
               {
                 text: systemMessage,
-                cache_control: { type: "ephemeral" },
+                cache_control: longTtl ? ({ type: "ephemeral", ttl: "1h" } as any) : { type: "ephemeral" },
                 type: "text",
               },
             ]
@@ -413,6 +414,8 @@ export class GenericAnthropicClient implements GenericClient {
 
         model: options.model,
         usage: response.usage ? {
+          input_tokens: response.usage.input_tokens ?? 0,
+          output_tokens: response.usage.output_tokens ?? 0,
           prompt_tokens: response.usage.input_tokens ?? 0,
           completion_tokens: response.usage.output_tokens ?? 0,
           total_tokens: (response.usage.input_tokens ?? 0) + (response.usage.output_tokens ?? 0),
@@ -422,7 +425,7 @@ export class GenericAnthropicClient implements GenericClient {
         usd_cost: this.calculateCost(options.model, response.usage),
       };
     } catch (err) {
-      if ("headers" in err && err.headers["x-should-retry"] === "true") {
+      if ("headers" in err && err.headers?.["x-should-retry"] === "true") {
         console.warn("Retrying failed request", err);
         await wait(2500);
         return this.createChatCompletion(options);

package/src/clients/types.ts

@@ -1,4 +1,10 @@
-export type ModelModality = "completion" | "embedding" | "image" | "audio" | "video" | "transcription";
+export type ModelModality =
+  | "completion"
+  | "embedding"
+  | "image"
+  | "audio"
+  | "video"
+  | "transcription";
 
 export type MessageContent =
   | { type: "text"; text: string }
@@ -8,7 +14,7 @@ export type MessageContent =
 
 export interface Message {
   role: "system" | "user" | "assistant" | "tool";
-  content?: string | MessageContent[];
+  content?: string | MessageContent[] | null;
 
   name?: string;
   tool_call_id?: string;
@@ -16,7 +22,7 @@ export interface Message {
 }
 
 export interface OutputMessage extends Message {
-  content: string;
+  content?: string | null;
 }
 
 export interface ToolProp {
@@ -61,6 +67,13 @@ export interface CompletionOptions {
    *  Maps to: OpenAI reasoning_effort, xAI reasoning.effort, Gemini thinkingLevel/thinkingBudget, Anthropic thinking budget.
    *  "low" = minimal thinking, "medium" = balanced, "high" = maximum reasoning */
   reasoning_effort?: "low" | "medium" | "high";
+  /**
+   * When true, hints to the client that this task is long-running and it should
+   * use a long-TTL cache where available.
+   * - Anthropic: enables the `extended-cache-ttl-2025-02-19` beta and sets
+   *   `cache_control.ttl` to 3600 (1 hour) instead of the default 5-minute ephemeral cache.
+   */
+  long_ttl_cache?: boolean;
 }
 
 /**
@@ -73,6 +86,10 @@ export interface TokenUsage {
   prompt_tokens: number;
   /** Total output/completion tokens generated */
   completion_tokens: number;
+  /** Alternative field name for input tokens (some providers use this) */
+  input_tokens?: number;
+  /** Alternative field name for output tokens (some providers use this) */
+  output_tokens?: number;
   /** Convenience total (prompt + completion) */
   total_tokens?: number;
   /** Cache details */
@@ -290,7 +307,9 @@ export interface GenericClient {
    * 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[] }[]>;
+  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/cloudWorker.ts

@@ -4,9 +4,14 @@ 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 { Language, Config, McpConfig } from "./types";
 import { S3Service } from "./services/S3";
 
+export interface CloudWorkerPullOptions {
+  id: string;
+  apiUrl?: string;
+}
+
 export interface CloudWorkerOptions {
   create?: boolean;
   push?: string; // uid of existing cloud worker
@@ -330,3 +335,72 @@ export async function cloudWorker(options: CloudWorkerOptions) {
     console.log(`\n✅ Cloud worker sync complete!`);
   }
 }
+
+/**
+ * Pull the latest workerConfigJson from the cloud worker API and update the
+ * local knowhow.json config to match.
+ *
+ * This is the "pull" half of the config sync cycle.  After running this,
+ * you can reload the worker's MCPs (in-process) via the reloadConfig
+ * WebSocket message or by calling `knowhow worker` again.
+ *
+ * Merged fields from workerConfigJson:
+ *   - mcps        → overwrites config.mcps
+ *   - modules     → overwrites config.modules  (optional, only if present)
+ *   - plugins     → overwrites config.plugins  (optional, only if present)
+ *   - agents      → overwrites config.agents   (optional, only if present)
+ */
+export async function pullCloudWorkerConfig(options: CloudWorkerPullOptions) {
+  const { id, apiUrl = KNOWHOW_API_URL } = options;
+
+  // Load JWT
+  const jwt = await loadJwt();
+  if (!jwt) {
+    console.error("❌ No JWT token found. Please run 'knowhow login' first.");
+    process.exit(1);
+  }
+
+  const client = new KnowhowSimpleClient(apiUrl, jwt);
+
+  console.log(`🔄 Pulling config for cloud worker ${id}...`);
+
+  const resp = await client.getCloudWorker(id);
+  const remoteWorker = resp.data;
+
+  if (!remoteWorker) {
+    console.error(`❌ Cloud worker ${id} not found.`);
+    process.exit(1);
+  }
+
+  const remoteConfig = (remoteWorker.workerConfigJson ?? {}) as {
+    mcps?: McpConfig[];
+    modules?: string[];
+    plugins?: Config["plugins"];
+    agents?: Config["agents"];
+  };
+
+  // Load current local config
+  const localConfig = await getConfig();
+
+  // Merge remote fields into local config
+  if (remoteConfig.mcps !== undefined) {
+    localConfig.mcps = remoteConfig.mcps;
+  }
+  if (remoteConfig.modules !== undefined) {
+    localConfig.modules = remoteConfig.modules;
+  }
+  if (remoteConfig.plugins !== undefined) {
+    localConfig.plugins = remoteConfig.plugins;
+  }
+  if (remoteConfig.agents !== undefined) {
+    localConfig.agents = remoteConfig.agents;
+  }
+
+  await updateConfig(localConfig);
+
+  const mcpCount = remoteConfig.mcps?.length ?? 0;
+  console.log(`✅ Config pulled! ${mcpCount} MCP(s) now configured locally.`);
+  console.log(`   Run 'knowhow worker' or trigger reloadConfig to apply changes.`);
+
+  return { mcps: remoteConfig.mcps, modules: remoteConfig.modules };
+}

package/src/commands/agent.ts

@@ -0,0 +1,246 @@
+import { Command } from "commander";
+import { readPromptFile } from "../ai";
+import { AgentModule } from "../chat/modules/AgentModule";
+import { AskModule } from "../chat/modules/AskModule";
+import { SearchModule } from "../chat/modules/SearchModule";
+import { SessionsModule } from "../chat/modules/SessionsModule";
+import { SetupModule } from "../chat/modules/SetupModule";
+
+async function readStdin(): Promise<string> {
+  return new Promise((resolve) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+
+    if (process.stdin.isTTY) {
+      resolve("");
+      return;
+    }
+
+    process.stdin.on("readable", () => {
+      const chunk = process.stdin.read();
+      if (chunk !== null) data += chunk;
+    });
+
+    process.stdin.on("end", () => resolve(data.trim()));
+  });
+}
+
+export function addAgentCommand(program: Command, getChatService: () => any): void {
+  program
+    .command("agent")
+    .description("Spin up agents directly from CLI")
+    .option(
+      "--provider <provider>",
+      "AI provider (openai, anthropic, google, xai)"
+    )
+    .option("--model <model>", "Specific model for the provider")
+    .option("--agent-name <name>", "Which agent to use", "Patcher")
+    .option(
+      "--max-time-limit <minutes>",
+      "Time limit for agent execution (minutes)",
+      "30"
+    )
+    .option(
+      "--max-spend-limit <dollars>",
+      "Cost limit for agent execution (dollars)",
+      "10"
+    )
+    .option("--message-id <messageId>", "Knowhow message ID for task tracking")
+    .option("--sync-fs", "Enable filesystem-based synchronization")
+    .option(
+      "--task-id <taskId>",
+      "Pre-generated task ID (used with --sync-fs for predictable agent directory path)"
+    )
+    .option("--prompt-file <path>", "Custom prompt template file with {text}")
+    .option("--input <text>", "Task input (fallback to stdin if not provided)")
+    .option(
+      "--resume",
+      "Resume a previously started task using the --task-id (local FS or remote)"
+    )
+    .action(async (options) => {
+      try {
+        const { setupServices } = await import("./services");
+        await setupServices();
+        const chatService = getChatService();
+        const agentModule = new AgentModule();
+
+        if (options.resume) {
+          const threads = await agentModule.loadThreadsForTask(
+            options.taskId,
+            options.messageId
+          );
+          const resumeInput =
+            options.input || "Please continue from where you left off.";
+
+          await agentModule.initialize(chatService);
+          const { taskCompleted: resumed } =
+            await agentModule.resumeFromMessages({
+              agentName: options.agentName || "Patcher",
+              input: resumeInput,
+              threads,
+              messageId: options.messageId,
+              taskId: options.taskId,
+            });
+          await resumed;
+          return;
+        }
+
+        let input = options.input;
+
+        if (!input && !options.promptFile) {
+          input = await readStdin();
+        }
+
+        input = readPromptFile(options.promptFile, input);
+
+        if (!input) {
+          console.error(
+            "Error: No input provided. Use --input flag, pipe input via stdin, or provide --prompt-file."
+          );
+          process.exit(1);
+        }
+
+        await agentModule.initialize(chatService);
+        const { taskCompleted } = await agentModule.setupAgent({
+          ...options,
+          input,
+          maxTimeLimit: parseInt(options.maxTimeLimit, 10),
+          maxSpendLimit: parseFloat(options.maxSpendLimit),
+          run: true,
+        });
+        await taskCompleted;
+      } catch (error) {
+        console.error("Error running agent:", error);
+        process.exit(1);
+      }
+    });
+}
+
+export function addAskCommand(program: Command, getChatService: () => any, getConfig: () => any): void {
+  program
+    .command("ask")
+    .description("Direct AI questioning without agent overhead")
+    .option("--provider <provider>", "AI provider to use")
+    .option("--model <model>", "Specific model")
+    .option("--input <text>", "Question (fallback to stdin if not provided)")
+    .option("--prompt-file <path>", "Custom prompt template file")
+    .action(async (options) => {
+      try {
+        const { setupServices } = await import("./services");
+        await setupServices();
+        const chatService = getChatService();
+        const config = getConfig();
+        let input = options.input;
+
+        if (!input && !options.promptFile) {
+          input = await readStdin();
+        }
+
+        input = readPromptFile(options.promptFile, input);
+
+        if (!input) {
+          console.error(
+            "Error: No question provided. Use --input flag, pipe input via stdin, or provide --prompt-file."
+          );
+          process.exit(1);
+        }
+
+        const askModule = new AskModule();
+        await askModule.initialize(chatService);
+        await askModule.processAIQuery(input, {
+          plugins: config.plugins.enabled,
+          currentModel: options.model,
+          currentProvider: options.provider,
+          chatHistory: [],
+        });
+      } catch (error) {
+        console.error("Error asking AI:", error);
+        process.exit(1);
+      }
+    });
+}
+
+export function addSetupCommand(program: Command, getChatService: () => any): void {
+  program
+    .command("setup")
+    .description("Ask the agent to configure knowhow")
+    .action(async () => {
+      try {
+        const { setupServices } = await import("./services");
+        await setupServices();
+        const chatService = getChatService();
+        const agentModule = new AgentModule();
+        await agentModule.initialize(chatService);
+        const setupModule = new SetupModule(agentModule);
+        await setupModule.initialize(chatService);
+        await setupModule.handleSetupCommand([]);
+      } catch (error) {
+        console.error("Error running agent:", error);
+        process.exit(1);
+      }
+    });
+}
+
+export function addSearchCommand(program: Command): void {
+  program
+    .command("search")
+    .description("Search embeddings directly from CLI")
+    .option(
+      "--input <text>",
+      "Search query (fallback to stdin if not provided)"
+    )
+    .option(
+      "-e, --embedding <path>",
+      "Specific embedding path (default: all)",
+      "all"
+    )
+    .action(async (options) => {
+      try {
+        const { setupServices } = await import("./services");
+        await setupServices();
+        let input = options.input;
+        if (!input) {
+          input = await readStdin();
+          if (!input) {
+            console.error(
+              "Error: No search query provided. Use --input flag or pipe input via stdin."
+            );
+            process.exit(1);
+          }
+        }
+
+        await new SearchModule().searchEmbeddingsCLI(input, options.embedding);
+      } catch (error) {
+        console.error("Error searching embeddings:", error);
+        process.exit(1);
+      }
+    });
+}
+
+export function addSessionsCommand(program: Command, getChatService: () => any): void {
+  program
+    .command("sessions")
+    .description("Manage agent sessions from CLI")
+    .option(
+      "--all",
+      "Show all historical sessions (default: current process only)"
+    )
+    .option("--csv", "Output sessions as CSV")
+    .action(async (options) => {
+      try {
+        const chatService = getChatService();
+        const agentModule = new AgentModule();
+        await agentModule.initialize(chatService);
+        const sessionsModule = new SessionsModule(agentModule);
+        await sessionsModule.initialize(chatService);
+        await sessionsModule.logSessionTable(
+          options.all || false,
+          options.csv || false,
+          true
+        );
+      } catch (error) {
+        console.error("Error listing sessions:", error);
+        process.exit(1);
+      }
+    });
+}

package/src/commands/misc.ts

@@ -0,0 +1,169 @@
+import { Command } from "commander";
+import { execSync } from "child_process";
+import { version } from "../../package.json";
+import { generate, embed, upload, download, purge } from "../index";
+import { init } from "../config";
+import { login } from "../login";
+import { KnowhowSimpleClient } from "../services/KnowhowClient";
+import { startChat } from "../chat";
+
+export function addInitCommand(program: Command): void {
+  program
+    .command("init")
+    .description("Initialize knowhow configuration")
+    .action(async () => {
+      await init();
+    });
+}
+
+export function addLoginCommand(program: Command): void {
+  program
+    .command("login")
+    .description("Login to knowhow")
+    .option("--jwt", "Use manual JWT input instead of browser login")
+    .action(async (opts) => {
+      await login(opts.jwt);
+    });
+}
+
+export function addUpdateCommand(program: Command): void {
+  program
+    .command("update")
+    .description("Update knowhow to the latest version from npm")
+    .action(async () => {
+      try {
+        console.log("🔄 Checking for knowhow updates...");
+        console.log(`Current version: ${version}`);
+        console.log("📦 Installing latest version from npm...");
+        execSync("npm install -g @tyvm/knowhow@latest", {
+          stdio: "inherit",
+          encoding: "utf-8",
+        });
+        console.log("✓ knowhow has been updated successfully!");
+        console.log("Run 'knowhow --version' to see the new version.");
+      } catch (error) {
+        console.error("Error updating knowhow:", error.message);
+        process.exit(1);
+      }
+    });
+}
+
+export function addGenerateCommand(program: Command): void {
+  program
+    .command("generate")
+    .description("Generate documentation")
+    .action(async () => {
+      const { setupServices } = await import("./services");
+      await setupServices();
+      await generate();
+    });
+}
+
+export function addEmbedCommands(program: Command): void {
+  program
+    .command("embed")
+    .description("Create embeddings")
+    .action(async () => {
+      const { setupServices } = await import("./services");
+      await setupServices();
+      await embed();
+    });
+
+  program
+    .command("embed:purge")
+    .description("Purge embeddings matching a glob pattern")
+    .argument("<pattern>", "Glob pattern to match files for purging")
+    .action(async (pattern) => {
+      await purge(pattern);
+    });
+}
+
+export function addUploadCommand(program: Command): void {
+  program
+    .command("upload")
+    .description("Upload data")
+    .action(async () => {
+      await upload();
+    });
+}
+
+export function addDownloadCommand(program: Command): void {
+  program
+    .command("download")
+    .description("Download data")
+    .action(async () => {
+      await download();
+    });
+}
+
+export function addChatCommand(program: Command): void {
+  program
+    .command("chat")
+    .description("Start new chat interface")
+    .action(async () => {
+      const { setupServices } = await import("./services");
+      await setupServices();
+      await startChat();
+    });
+}
+
+export function addGithubCredentialsCommand(program: Command): void {
+  program
+    .command("github-credentials [action]")
+    .description(
+      "Git credential helper for GitHub. Use as: git config credential.helper 'knowhow github-credentials'"
+    )
+    .option(
+      "--repo <repo>",
+      "Repository in owner/repo format (e.g. myorg/myrepo)"
+    )
+    .action(async (action: string | undefined, options: { repo?: string }) => {
+      const client = new KnowhowSimpleClient();
+
+      let repo = options.repo;
+
+      if (action === "get") {
+        const lines: string[] = [];
+        const readline = await import("readline");
+        const rl = readline.createInterface({
+          input: process.stdin,
+          terminal: false,
+        });
+        await new Promise<void>((resolve) => {
+          rl.on("line", (line) => {
+            if (line.trim()) lines.push(line.trim());
+          });
+          rl.on("close", resolve);
+        });
+      } else if (action === "store" || action === "erase") {
+        process.exit(0);
+      }
+
+      if (!repo) {
+        try {
+          const remoteUrl = execSync("git remote get-url origin", {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+          }).trim();
+          const match =
+            remoteUrl.match(/github\.com[/:]([^/]+\/[^/]+?)(?:\.git)?$/) ||
+            remoteUrl.match(/github\.com\/([^/]+\/[^/]+)/);
+          if (match) {
+            repo = match[1];
+          }
+        } catch {
+          // Not in a git repo or no remote — proceed without repo
+        }
+      }
+
+      try {
+        const credential = await client.getGitCredential(repo || "");
+        process.stdout.write(
+          `protocol=${credential.protocol}\nhost=${credential.host}\nusername=${credential.username}\npassword=${credential.password}\n`
+        );
+      } catch (error) {
+        console.error("Failed to get git credentials:", error.message);
+        process.exit(1);
+      }
+    });
+}