@tyvm/knowhow 0.0.33 → 0.0.34

package/src/prompts/KnowhowConfigExamples.ts

@@ -0,0 +1,376 @@
+export default `
+
+Here is an overview of examples from various \`.knowhow/knowhow.json\` configuration files found, illustrating the configuration capabilities that Knowhow supports:
+
+---
+
+## General Configuration Template
+
+\`\`\`json
+{
+  "promptsDir": ".knowhow/prompts",
+  "plugins": [
+    "embeddings",
+    "language",
+    "vim",
+    "github",
+    "asana",
+    "jira",
+    "linear",
+    "download",
+    "figma"
+  ],
+  "sources": [
+    {
+      "input": "src/**/*.mdx",
+      "output": ".knowhow/docs/",
+      "prompt": "BasicCodeDocumenter"
+    }
+  ],
+
+  // Generate embeddings from a series of files on your machine
+  // Remote knowhow with the kb id allows you to leverage knowhow upload
+  "embedSources": [
+    {
+      "input": ".knowhow/docs/**/*.mdx",
+      "output": ".knowhow/embeddings",
+      "chunkSize": 2000,
+      "remoteType": "knowhow",
+      "remoteId": "141d9c4d-1589-4ccc-bf39-031f4259b89f"
+    }
+  ],
+
+  // Define aditional agents you can interact with via chat
+  "agents": [
+    {
+      "name": "linter",
+      "description": "Clean up your code",
+      "instructions": "Read the files that are loaded via vim plugin and provide debugging and linter suggestions"
+    }
+    {
+      "name": "Codebase Helper",
+      "description": "Helps you code",
+      "instructions": "Codebase helper, use files and tools to help us code",
+      "model": "gpt-4-1106-preview",
+      "tools": [
+        {
+          "type": "code_interpreter"
+        }
+      ],
+      "files": [
+        ".knowhow/docs/**/*.mdx"
+      ]
+    }
+  ]
+}
+\`\`\`
+
+## Video Download Support
+\`\`\`json
+  "embedSources": [
+    {
+      "input": "https://www.youtube.com/shorts/BYuMBK5Ll-s",
+      "output": ".knowhow/embeddings/video.json",
+      "chunkSize": 2000,
+      "kind": "download"
+    }
+  ],
+\`\`\`
+
+## MCP Setup
+
+\`\`\`json
+  "mcps": [
+    {
+      "name": "browser",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
+    }
+  ],
+\`\`\`
+
+## Expose Tools to Knowhow Site via workers
+After you've connected via \`knowhow login\` you can connect tools from your local machine
+Run \`knowhow worker\` to generate a block like below. Edit it to include the tools you want to expose.
+Then run \`knowhow worker\` again to connect
+\`\`\`json
+  "worker": {
+    "allowedTools": [
+      "embeddingSearch",
+      "finalAnswer",
+      "callPlugin",
+      "readFile",
+      "readBlocks",
+      "patchFile",
+      "lintFile",
+      "textSearch",
+      "fileSearch",
+      "writeFileChunk",
+      "createAiCompletion",
+      "listAllModels",
+      "listAllProviders",
+      "getPullRequest",
+      "getPullRequestBuildStatuses",
+      "getRunLogs",
+      "getPullRequestBuildFailureLogs",
+      "addLanguageTerm",
+      "getAllLanguageTerms",
+      "lookupLanguageTerm",
+      "mcp_0_puppeteer_navigate",
+      "mcp_0_puppeteer_screenshot",
+      "mcp_0_puppeteer_click",
+      "mcp_0_puppeteer_fill",
+      "mcp_0_puppeteer_select",
+      "mcp_0_puppeteer_hover",
+      "mcp_0_puppeteer_evaluate"
+    ]
+  },
+\`\`\`
+
+## Custom Models Via LMS Studio
+\`\`\`json
+  "modelProviders": [
+    {
+      "url": "http://localhost:1234",
+      "provider": "lms"
+    }
+  ],
+\`\`\`
+
+## Agent Tasks: rename all video files in a folder
+\`\`\`
+  "sources": [
+    {
+      "input": ".knowhow/downloads/**/*.webm",
+      "output": ".knowhow/organized/",
+      "prompt": "FSOrganizer",
+      "agent": "Developer"
+    }
+  ],
+\`\`\`
+
+Prompt Example:
+
+\`\`\`
+We have this file, we want to generate a nice name for it, please copy the file to .knowhow/org/{better file name}
+
+ {text}
+\`\`\`
+
+## knowhow generate: meeting transcripts
+\`\`\`json
+  "sources": [
+    {
+      "input": "./meetings/**/*.mov",
+      "output": "./meetings/ai-notes/",
+      "prompt": "MeetingNotes"
+    },
+    {
+      "input": "./meetings/TaskRelatedCall/transcript.txt",
+      "output": "./meetings/tasks/RewardsTasks.txt",
+      "prompt": "AsanaTasks"
+    },
+    {
+      "input": "./meetings/EngineeringCall/transcript.txt",
+      "output": "./meetings/tasks/SchemaChanges.txt",
+      "prompt": "Schema"
+    }
+  ],
+\`\`\`
+
+
+Use the source block alongside \`knowhow generate\` to process a pipeline of files, applying prompts to generate documentation or other artifacts. This example demonstrates the configuration for processing meeting recordings, and then running prompts on the resulting transcripts.
+
+I've been using \`CMD+SHIFT+5\` to record meetings and then using the \`sources\` block to process the recordings into notes and tasks.
+
+When a .mov or audio file is an input, it will automatically create a transcript.txt in the same directory, so we can leverage that txt input in the next step. The pipeline is useful for apply one or more prompts to one or more input files.
+
+## knowhow embed: documentation embeddings
+\`\`\`json
+  "embedSources": [
+    {
+      "input": "./documentation/docusaurus/docs/dev-docs/**/*.md",
+      "output": ".knowhow/embeddings/strapi-docs.json",
+      "chunkSize": 2000
+    }
+  ]
+\`\`\`
+
+## knowhow embed: codebase embeddings
+\`\`\`json
+
+  "embedSources": [
+    {
+      "input": "./packages/p2p/src/**/*.ts",
+      "output": ".knowhow/embeddings/p2p.json",
+      "chunkSize": 2000
+    },
+    {
+      "input": "./packages/openai_proxy/src/**/*.ts",
+      "output": ".knowhow/embeddings/openai_proxy.json",
+      "chunkSize": 2000
+    },
+    {
+      "input": "./packages/contracts/src/**/*.sol",
+      "output": ".knowhow/embeddings/contracts.json",
+      "chunkSize": 2000
+    }
+  ],
+\`\`\`
+You can use \`knowhow embed\` to generate json embeddings from a set of files. If you want to run a prompt on the input, before embedding, you set an optional \`prompt\` field to match the filename of the prompt stored in your \`.knowhow/prompts\` directory.
+
+These embeddings are leveraged by the chat in \`knowhow chat\` or by the agents to accomplish their tasks
+
+## knowhow embed: asana tasks
+\`\`\`
+  "embedSources": [
+    {
+      "input": "https://app.asana.com/0/111111111111111/list",
+      "output": ".knowhow/embeddings/asana.json",
+      "remote": "mybucket",
+      "remoteType": "s3",
+      "kind": "asana",
+      "chunkSize": 2000
+    }
+  ],
+\`\`\`
+
+
+Any plugin that implements the embedding function, can generate embeddings if you set the \`kind\` field to the plugin name. The \`remote\` field is optional, and if set, the embeddings will be uploaded to the specified S3 bucket via \`knowhow upload\`.
+
+You can download remote embeddings via \`knowhow download\` and use them in your local environment.
+
+For downloads we support the following remote options:
+- s3
+- github* - downloads files
+
+For uploads we support the following remote options:
+- s3
+- github* - use git lfs to commit the embeddings to your repository
+
+
+## knowhow embed: github embeddings
+\`\`\`
+  "embedSources": [
+    {
+      "input": "./src/**/*.ts",
+      "output": ".knowhow/embeddings/knowhow.json",
+      "chunkSize": 2000,
+      "remote": "micahriggan/knowhow",
+      "remoteType": "github"
+    }
+  ],
+\`\`\`
+Here's an example where you could download embeddings from github. As the code updates occasionally I'll run \`knowhow embed\` and commit the updated embeddings.
+
+## Plugins
+\`\`\`json
+{
+  "plugins": [
+    "embeddings",
+    "language",
+    "vim",
+    "github",
+    "asana",
+    "jira",
+    "linear",
+    "download",
+    "figma",
+    "notion"
+  ],
+}
+\`\`\`
+Plugins are used to resolve urls or other references to data that the AI can use. For example, the \`asana\` plugin can be used to resolve tasks and projects from Asana, and the \`figma\` plugin can be used to resolve design files from Figma.
+
+The language plugin allows you to define hotkeys that resolve to larger blocks of texts or files, or urls. For example, you can define a language entry \`#asana\` that resolves to a link to your current asana task, so that you can easily load that without pasting the link each time.
+
+
+## knowhow chat:
+After generating embeddings, you can use \`knowhow chat\` to speak with a base agent, that does not have any tools, but does have plugins.
+
+You can use \`agent\` once you're in a chat to start talking to a Developer agent, that has a prompt and tools designed to help develop software.
+You can use \`agents\` to see a list of configured agents you can speak with.
+If you need multi-line input you can use \`multi\` to open a multi-line editor.
+
+There are many commands you can call from a chat session, try TAB to see a list of available options.
+
+
+### knowhow chat: custom agents
+\`\`\`json
+  "assistants": [
+    {
+      "name": "linter",
+      "description": "Clean up your code",
+      "instructions": "Read the files that are loaded via vim plugin and provide debugging and linter suggestions"
+    }
+  ]
+\`\`\`
+You can configure new agents via the config above. This would create a new option when you use \`agents\` in a chat session.
+
+## Lint Commands
+
+\`\`\`json
+{
+  "lintCommands": {
+    "js": "eslint",
+    "ts": "tslint $1 && tsc -p tsconfig.json"
+  }
+}
+\`\`\`
+lintCommands are automatically run after an agent successfully patches a file, if the file extension matches. So you can configure the AI to receive feedback from tsc and the linter after modifying a TypeScript file. $1 will be replaced with the filepath that was patched.
+
+
+
+## Language Plugin
+
+Configured in \`.knowhow/language.json\`
+
+Knowhow has a language file, which allows you to define additional context that is included when you use certain phrases in your messages. For instance, you could load a Pull Request when you say "My PR", or load a file from the codebase when you reference it. Languages have "terms" which then load various sources into context. Sources currently can be files, text, or github links.
+
+I primarily use this to define terms like "frontend" or "backend" to load prompt files
+
+## Example Language Definition
+
+\`\`\`
+{
+  "ui,frontend,component,page": {
+    "sources": [
+      {
+        "data": [
+          "./.knowhow/prompts/frontend.mdx"
+        ],
+        "kind": "file"
+      }
+    ]
+  }
+}
+\`\`\`
+
+
+Here's and example of having a language term that triggers a plugin.
+This example would load the diff of a PR every time we said "my pr"
+\`\`\`
+{
+  "knowhow config": {
+    "sources": [
+      {
+        "kind": "file",
+        "data": [
+          ".knowhow/knowhow.json"
+        ]
+      }
+    ]
+  },
+  "My PR": {
+    "sources": [
+      {
+        "kind": "github",
+        "data": [
+          "https://github.com/tyvm-ai/knowhow/pulls/1"
+        ]
+      }
+    ]
+  }
+}
+\`\`\`
+`

package/src/services/KnowhowClient.ts

@@ -1,5 +1,6 @@
 import axios from "axios";
 import fs from "fs";
+import { Message } from "../clients/types";
 import path from "path";
 import {
   CompletionOptions,
@@ -9,6 +10,29 @@ import {
 } from "src/clients";
 import { Config } from "../types";
 
+// Chat Task interfaces
+export interface CreateMessageTaskRequest {
+  messageId: string;
+  prompt: string;
+}
+
+export interface CreateMessageTaskResponse {
+  id: string;
+}
+
+export interface UpdateOrgTaskRequest {
+  threads: Message[][];
+  totalCostUsd: number;
+  inProgress: boolean;
+  result?: string;
+}
+
+export interface UpdateOrgTaskResponse {
+  threadCount: Message[][];
+  totalCostUsd: number;
+  inProgress: boolean;
+}
+
 export function loadKnowhowJwt(): string {
   const jwtFile = path.join(process.cwd(), ".knowhow", ".jwt");
   if (!fs.existsSync(jwtFile)) {
@@ -17,6 +41,9 @@ export function loadKnowhowJwt(): string {
   return fs.readFileSync(jwtFile, "utf-8").trim();
 }
 
+export const KNOWHOW_API_URL =
+  process.env.KNOWHOW_API_URL || "https://api.knowhow.tyvm.ai";
+
 export class KnowhowSimpleClient {
   headers = {};
 
@@ -72,8 +99,6 @@ export class KnowhowSimpleClient {
       }
     );
 
-    console.log(presignedUrlResp.data);
-
     const presignedUrl = presignedUrlResp.data.downloadUrl;
     return presignedUrl;
   }
@@ -106,5 +131,26 @@ export class KnowhowSimpleClient {
       headers: this.headers,
     });
   }
-}
 
+  createChatTask(request: CreateMessageTaskRequest) {
+    this.checkJwt();
+    return axios.post<CreateMessageTaskResponse>(
+      `${this.baseUrl}/api/chat/tasks`,
+      request,
+      {
+        headers: this.headers,
+      }
+    );
+  }
+
+  updateChatTask(taskId: string, updates: UpdateOrgTaskRequest) {
+    this.checkJwt();
+    return axios.put<UpdateOrgTaskResponse>(
+      `${this.baseUrl}/api/chat/tasks/${taskId}`,
+      updates,
+      {
+        headers: this.headers,
+      }
+    );
+  }
+}

package/src/services/Mcp.ts

@@ -32,6 +32,13 @@ export const knowhowConfig = {
 export * from "./McpServer";
 export * from "./McpWebsocketTransport";
 
+/*
+ *
+ * McpService is a service that manages connections to multiple MCP servers.
+ * Allows us to connect the tools exposed by MCP servers to our internal ToolService, which agents can use.
+ * Each of the tools are namespaced with a prefix: mcp_index_servername_toolName
+ * This services handles calls made to the namespaced function name, and finds the proper client to call the tool on.
+ */
 export class McpService {
   connected = [];
   transports: Transport[] = [];
@@ -133,11 +140,11 @@ export class McpService {
     await Promise.all(
       this.transports.map(async (transport, index) => {
         this.connected[index] = false;
-        return transport.close();
+        return transport && transport.close();
       })
     );
 
-    this.transports = [];
+    // this.transports = [];
     this.connected = [];
   }
 
@@ -207,7 +214,7 @@ export class McpService {
 
     const realName = this.parseToolName(toolName);
     return async (args: any) => {
-      console.log("Calling tool", realName, "with args", args);
+      console.log("Calling tool via mcp client", realName, "with args", args);
       const tool = await client.callTool(
         {
           name: realName,
@@ -223,6 +230,38 @@ export class McpService {
     };
   }
 
+  /**
+   * Call a function and unwrap the MCP response content array with type casting
+   * @param toolName The name of the tool/function to call
+   * @param args The arguments to pass to the function
+   * @returns The parsed result with type T
+   */
+  async callFunction<T = any>(toolName: string, args: any = {}): Promise<T> {
+    try {
+      const fn = this.getFunction(toolName);
+      const result = await fn(args);
+
+      // Parse the MCP result
+      if (result.content && Array.isArray(result.content)) {
+        const textContent = result.content.find((c: any) => c.type === "text");
+        if (textContent && textContent.text) {
+          const parsedResult = JSON.parse(textContent.text);
+          return parsedResult as T;
+        }
+      }
+
+      throw new Error(
+        `Invalid response format from MCP service for tool ${toolName}`
+      );
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `Failed to call MCP function ${toolName}: ${errorMessage}`
+      );
+    }
+  }
+
   async getFunctions() {
     const tools = await this.getTools();
     return tools.map((tool) => {

package/src/services/McpServer.ts

@@ -25,7 +25,10 @@ export class McpServerService {
     return this;
   }
 
-  toZodSchema(properties: { [key: string]: ToolProp }): z.ZodObject<any> {
+  toZodSchema(
+    properties: { [key: string]: ToolProp },
+    required?: string[]
+  ): z.ZodObject<any> {
     const schema: Record<string, z.ZodTypeAny> = {};
     for (const [key, value] of Object.entries(properties)) {
       if (value.type === "string") {
@@ -35,19 +38,26 @@ export class McpServerService {
       } else if (value.type === "boolean") {
         schema[key] = z.boolean();
       } else if (value.type === "array" && value?.items?.properties) {
-        schema[key] = z.array(this.toZodSchema(value.items.properties));
+        schema[key] = z.array(this.toZodSchema(value.items.properties, required));
       } else if (value.type === "object" && value.properties) {
-        schema[key] = this.toZodSchema(value.properties);
+        schema[key] = this.toZodSchema(value.properties, required);
       } else {
         schema[key] = z.any();
       }
+      
+      // Make field optional if it's not in the required array
+      if (required && !required.includes(key)) {
+        schema[key] = schema[key].optional();
+      }
     }
+    
     return z.object(schema);
   }
 
   withTools(tools: Tool[]) {
     for (const tool of tools) {
       const props = tool.function.parameters.properties;
+      const required = tool.function.parameters.required;
 
       if (!props) {
         console.warn(`Tool ${tool.function.name} has no properties`);
@@ -62,7 +72,7 @@ export class McpServerService {
       console.log(`Registering tool ${tool.function.name}`);
       this.registeredTools.add(tool.function.name);
 
-      const shape = this.toZodSchema(props).shape;
+      const shape = this.toZodSchema(props, required).shape;
 
       this.server.tool(
         tool.function.name,

package/src/services/McpWebsocketTransport.ts

@@ -48,13 +48,27 @@ export class MCPWebSocketTransport implements Transport {
     return new Promise((resolve, reject) => {
       const json = JSON.stringify(message);
       console.log("MCPWs sending", json);
-      this._socket.send(json, (error?: Error) => {
-        if (error) {
-          this.onerror?.(error);
-          return reject(error);
-        }
-        resolve();
-      });
+
+      if (this._socket.readyState !== WebSocket.OPEN) {
+        return reject(
+          new Error(
+            `WebSocket is not open: readyState ${this._socket.readyState}`
+          )
+        );
+      }
+
+      try {
+        this._socket.send(json, (error?: Error) => {
+          if (error) {
+            this.onerror?.(error);
+            return reject(error);
+          }
+          resolve();
+        });
+      } catch (error) {
+        this.onerror?.(error as Error);
+        reject(error);
+      }
     });
   }
 

package/src/services/MessageProcessor.ts

@@ -1,6 +1,11 @@
 import { Message } from "../clients/types";
 
-export type ProcessorLifecycle = "initial_call" | "per_call" | "post_call";
+export type ProcessorLifecycle =
+  | "initial_call"
+  | "pre_call"
+  | "post_call"
+  | "pre_tools"
+  | "post_tools";
 
 export type MessageProcessorFunction = (
   originalMessages: Message[],
@@ -18,9 +23,7 @@ export class MessageProcessor {
 
   constructor() {
     // Initialize lifecycle maps
-    this.processors.set("initial_call", []);
-    this.processors.set("per_call", []);
-    this.processors.set("post_call", []);
+    this.clearProcessors();
   }
 
   setProcessors(
@@ -100,8 +103,10 @@ export class MessageProcessor {
     } else {
       this.processors.clear();
       this.processors.set("initial_call", []);
-      this.processors.set("per_call", []);
+      this.processors.set("pre_call", []);
       this.processors.set("post_call", []);
+      this.processors.set("pre_tools", []);
+      this.processors.set("post_tools", []);
     }
   }
 }

package/src/services/index.ts

@@ -1,3 +1,5 @@
+import { openai } from "../ai";
+import { DownloaderService } from "../plugins/downloader/downloader";
 import { Clients } from "../clients";
 import { Plugins } from "../plugins/plugins";
 import { AgentService } from "./AgentService";
@@ -31,6 +33,7 @@ let Singletons = {} as {
   knowhowApiClient: KnowhowSimpleClient;
   Plugins: typeof Plugins;
   Clients: typeof Clients;
+  Downloader: DownloaderService;
 };
 
 export const services = (): typeof Singletons => {
@@ -38,10 +41,12 @@ export const services = (): typeof Singletons => {
     const Tools = new ToolsService();
     const Events = new EventService();
     const Agents = new AgentService(Tools, Events);
+    const Downloader = new DownloaderService(openai, Clients);
     Singletons = {
       Tools,
       Events,
       Agents,
+      Downloader,
 
       Flags: new FlagsService(),
       GitHub: new GitHubService(),