@tyvm/knowhow 0.0.68 → 0.0.70

package/docs/shell-commands.md

@@ -0,0 +1,174 @@
+# Shell Command Execution
+
+Knowhow provides multiple ways to execute shell commands during chat sessions, both for interactive terminal use and for sending command output to the AI agent.
+
+## Quick Commands: `/!` and `/!!`
+
+Available in `agent` and `agent:attached` modes:
+
+### `/!` - Interactive Shell Command
+Execute a command and display output in the console. The command runs interactively, allowing you to interact with it if needed.
+
+```
+/! git status
+/! npm test
+/! terraform plan
+```
+
+Output is displayed to you but **not sent to the AI agent**.
+
+### `/!!` - Send Output to AI
+Execute a command and send the output to the AI agent for analysis.
+
+```
+/!! git diff
+/!! npm run lint
+/!! cat error.log
+```
+
+Output is displayed to you **and sent to the AI agent** for processing.
+
+## Custom Commands via Language Config
+
+You can define custom shell commands in `.knowhow/language.json` that integrate with the language plugin system.
+
+### Example: `/git` Command
+
+```json
+{
+  "/git": {
+    "events": [],
+    "handled": true,
+    "sources": [
+      {
+        "kind": "exec",
+        "data": [
+          "git status"
+        ]
+      }
+    ]
+  }
+}
+```
+
+This creates a `/git` command that runs `git status` when invoked.
+
+### Example: `/tfplan` Command
+
+```json
+{
+  "/tfplan": {
+    "events": [],
+    "handled": true,
+    "sources": [
+      {
+        "kind": "exec",
+        "data": [
+          "cd terraform && terraform plan"
+        ]
+      }
+    ]
+  }
+}
+```
+
+### The `handled` Property
+
+- **`handled: true`** - Command output is displayed to the user only, **not sent to the AI agent**
+- **`handled: false`** (default) - Command output is sent to the AI agent for processing
+
+This allows you to:
+- Use `handled: true` for commands where you just want to see output (like `/tfplan`)
+- Use `handled: false` for commands where you want the AI to analyze the output
+
+### Multiple Commands
+
+You can also chain multiple commands or execute more complex operations:
+
+```json
+{
+  "/deploy-status": {
+    "events": [],
+    "handled": false,
+    "sources": [
+      {
+        "kind": "exec",
+        "data": [
+          "kubectl get pods && kubectl get services"
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Exec Plugin
+
+The exec plugin is automatically enabled and allows language config entries to execute shell commands. It's used internally by the custom command system.
+
+### Plugin Configuration
+
+The exec plugin is enabled by default in `.knowhow/knowhow.json`:
+
+```json
+{
+  "plugins": {
+    "enabled": [
+      "exec",
+      // ... other plugins
+    ]
+  }
+}
+```
+
+## Use Cases
+
+### Development Workflow
+```json
+{
+  "/build": {
+    "handled": false,
+    "sources": [{ "kind": "exec", "data": ["npm run build"] }]
+  },
+  "/test": {
+    "handled": false,
+    "sources": [{ "kind": "exec", "data": ["npm test"] }]
+  }
+}
+```
+
+### Infrastructure Management
+```json
+{
+  "/infra": {
+    "handled": true,
+    "sources": [{ "kind": "exec", "data": ["terraform plan"] }]
+  },
+  "/pods": {
+    "handled": false,
+    "sources": [{ "kind": "exec", "data": ["kubectl get pods"] }]
+  }
+}
+```
+
+### Git Workflows
+```json
+{
+  "/changes": {
+    "handled": false,
+    "sources": [{ "kind": "exec", "data": ["git diff --cached"] }]
+  },
+  "/branches": {
+    "handled": true,
+    "sources": [{ "kind": "exec", "data": ["git branch -a"] }]
+  }
+}
+```
+
+## Security Notes
+
+- Commands are executed in your current working directory
+- Commands run with your user permissions
+- Be cautious with commands that modify system state
+- The exec plugin has a 10MB output buffer limit
+- Interactive commands work with `/!` but not with language config exec sources

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tyvm/knowhow",
-  "version": "0.0.68",
+  "version": "0.0.70",
   "description": "ai cli with plugins and agents",
   "main": "ts_build/src/index.js",
   "bin": {
@@ -40,7 +40,7 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.39.0",
     "@aws-sdk/client-s3": "^3.588.0",
-    "@tyvm/knowhow-tunnel": "0.0.2",
+    "@tyvm/knowhow-tunnel": "0.0.3",
     "@google/genai": "^0.14.1",
     "@inquirer/editor": "^4.2.18",
     "@linear/sdk": "^12.0.0",

package/src/agents/base/base.ts

@@ -758,9 +758,7 @@ export abstract class BaseAgent implements IAgent {
   logStatus() {
     const statusMessage = this.getStatusMessage();
     console.log(
-      `\n● ${this.name} status: $${this.getTotalCostUsd().toPrecision(
-        3
-      )}\n${statusMessage}`
+      `\n● ${this.name} status: ${statusMessage}`
     );
   }
 

package/src/agents/developer/developer.ts

@@ -8,15 +8,10 @@ export class DeveloperAgent extends BaseAgent {
 
   constructor(context: AgentContext) {
     super(context);
-    this.disableTool("patchFile");
-    this.disableTool("openFileInVim");
-    this.disableTool("sendVimInput");
-    this.disableTool("saveVimFile");
-
     this.setModelPreferences([
       {
-        model: Models.google.Gemini_20_Flash,
-        provider: "google",
+        model: Models.anthropic.Sonnet4_6,
+        provider: "anthropic",
       },
     ]);
   }
@@ -35,8 +30,21 @@ export class DeveloperAgent extends BaseAgent {
         You delegate some tasks to specialized agents. If a request doesn't require the use of a specialized agent, you can handle it yourself.
 
         # How to call other agents
-        You can use the agentCall tool to call other agents.
-        Do not try to use VIM/ or Patching tools directly. If you must write to a file yourself use writeFileChunk
+        You can use the startAgentTask tool to call other agents.
+        This is a wrapper for the shell command knowhow agent --input "your prompt"
+
+        If sync-fs is active:
+        When you start a knowhow agent, it will create a folder in .knowhow/processes/agents/
+        For that agent you can use the input.txt file to send it messages.
+
+        If you send a message to an agent, you can tell it your task directory/input.txt file path and they can write there to respond
+        Your task id is:
+        ${this.currentTaskId}
+
+        If you need to write a longer task, you can you knowhow agent --prompt-file <filepath>
+        This way you can write out specs and launch the agent on that
+
+        You can use the status.txt to pause an agent, or pause yourself and have another agent unpause you, or you can use shell commands to wait for an agent's status to change, with a timeout
 
         # Which Agent to Use:
         Researcher -
@@ -46,16 +54,13 @@ export class DeveloperAgent extends BaseAgent {
         - General Questions about codebase or file structure
 
         Patcher
+        - this is the default agent
         - For making modifications to files / code
         - Great for big files
 
-        # Thought process
-        1. Is the user asking you a question about the codebase or files? Foreward the question to the Researcher.
-        2. Do you need to make changes to files?
-          2.a Do we have enough information to know exactly what to modify? If not, ask the Researcher.
-          2.b If we know what to modify, ask Patcher to make the changes with all the context required.
-        3. If the agent you call has declared it has completed a task, you may need to check it's modifications to see if there's some follow up work required.
-        4. If the user is asking for a general task, like webbrowsing or terminal commands, or general questions you may accomplish this yourself.
+
+          If the user has asked you to do multiple things that are parallelizable, you can start an agent for each task
+          Each agent will have it's own log files. You can check the logs of each agent to see their progress.
         `,
       },
       {

package/src/agents/tools/agentCall.ts

@@ -1,5 +1,6 @@
 import { getConfig } from "../../config";
 import { services, ToolsService } from "../../services";
+import { getEnabledPlugins } from "../../types";
 
 export async function agentCall(agentName: string, userInput: string) {
   return new Promise(async (resolve, reject) => {
@@ -11,8 +12,9 @@ export async function agentCall(agentName: string, userInput: string) {
     const { Events, Plugins } = toolService.getContext();
 
     let fullPrompt = `${userInput}`;
-    if (config.plugins?.length) {
-      const pluginText = await Plugins.callMany(config.plugins, userInput);
+    const enabledPlugins = getEnabledPlugins(config.plugins);
+    if (enabledPlugins?.length) {
+      const pluginText = await Plugins.callMany(enabledPlugins, userInput);
       fullPrompt += `\n ${pluginText}`;
     }
 

package/src/agents/tools/fileSearch.ts

@@ -15,7 +15,11 @@ export async function fileSearch(searchTerm) {
   });
 
   const embeddings = await getConfiguredEmbeddings();
-  const embeddingFiles = embeddings.filter((embedding) =>
+  
+  // Ensure embeddings is always an array
+  const embeddingsArray = Array.isArray(embeddings) ? embeddings : [];
+  
+  const embeddingFiles = embeddingsArray.filter((embedding) =>
     embedding.id.toLowerCase().includes(searchTermLower)
   );
 

package/src/agents/tools/list.ts

@@ -390,40 +390,6 @@ export const includedTools = [
       description: "Create a completion using the knowhow AI client",
       parameters: {
         type: "object",
-        positional: true,
-        additionalProperties: false,
-        $defs: {
-          message: {
-            type: "object",
-            additionalProperties: false,
-            properties: {
-              role: {
-                type: "string",
-                enum: ["system", "user", "assistant", "tool"],
-              },
-              content: { type: "string" },
-            },
-            required: ["role", "content"],
-          },
-          toolLite: {
-            type: "object",
-            additionalProperties: false,
-            properties: {
-              type: { type: "string", enum: ["function"] },
-              function: {
-                type: "object",
-                additionalProperties: false,
-                properties: {
-                  name: { type: "string" },
-                  description: { type: "string" },
-                  parameters: { type: "object" },
-                },
-                required: ["name", "parameters"],
-              },
-            },
-            required: ["type", "function"],
-          },
-        },
         properties: {
           provider: {
             type: "string",
@@ -432,14 +398,27 @@ export const includedTools = [
           },
           options: {
             type: "object",
-            additionalProperties: false,
             description: "Provider-specific completion options",
             properties: {
               model: { type: "string", description: "The model to use" },
               messages: {
                 type: "array",
                 description: "The chat history for the completion",
-                items: { $ref: "#/$defs/message" },
+                items: {
+                  type: "object",
+                  properties: {
+                    role: {
+                      type: "string",
+                      enum: ["system", "user", "assistant", "tool"],
+                      description: "The role of the message sender",
+                    },
+                    content: {
+                      type: "string",
+                      description: "The content of the message",
+                    },
+                  },
+                  required: ["role", "content"],
+                },
                 minItems: 1,
               },
               max_tokens: {
@@ -450,7 +429,32 @@ export const includedTools = [
                 type: "array",
                 description:
                   "Tool definitions the model may call (non-recursive subset)",
-                items: { $ref: "#/$defs/toolLite" },
+                items: {
+                  type: "object",
+                  properties: {
+                    type: {
+                      type: "string",
+                      enum: ["function"],
+                      description: "The type of tool",
+                    },
+                    function: {
+                      type: "object",
+                      properties: {
+                        name: { type: "string", description: "Function name" },
+                        description: {
+                          type: "string",
+                          description: "Function description",
+                        },
+                        parameters: {
+                          type: "object",
+                          description: "Function parameters schema",
+                        },
+                      },
+                      required: ["name", "parameters"],
+                    },
+                  },
+                  required: ["type", "function"],
+                },
               },
             },
             required: ["model", "messages"],

package/src/agents/tools/startAgentTask.ts

@@ -1,8 +1,11 @@
 import { Tool } from "../../clients/types";
-import { execCommand } from "./execCommand";
+import * as fs from "fs";
+import * as path from "path";
+import { spawn } from "child_process";
 
 interface StartAgentTaskParams {
-  messageId: string;
+  messageId?: string;
+  syncFs?: boolean;
   prompt: string;
   provider?: string;
   model?: string;
@@ -11,56 +14,154 @@ interface StartAgentTaskParams {
   maxSpendLimit?: number;
 }
 
+const PROCESSES_DIR = path.join(process.cwd(), ".knowhow", "processes");
+const AGENTS_DIR = path.join(process.cwd(), ".knowhow", "processes", "agents");
+
+/**
+ * Generate a task ID matching the format used by SessionManager.generateTaskId()
+ * Format: {epochSeconds}-{words-from-prompt}
+ */
+function generateTaskId(prompt: string): string {
+  const words = prompt
+    .toLowerCase()
+    .replace(/[^\w\s]/g, "")
+    .split(/\s+/)
+    .filter((word) => word.length > 2)
+    .slice(0, 9);
+  const wordPart = words.join("-") || "task";
+  const epochSeconds = Math.floor(Date.now() / 1000);
+  return `${epochSeconds}-${wordPart}`;
+}
+
 /**
  * Creates a chat task in Knowhow based on a message ID and prompt.
- * This allows external agents to start tasks that can receive real-time updates.
+ * Spawns the knowhow CLI with the prompt piped via stdin to avoid
+ * shell escaping issues with special characters (quotes, backticks,
+ * newlines, template expressions, etc.).
+ *
+ * When syncFs is true, the agent creates a directory at:
+ *   .knowhow/processes/agents/{taskId}/
+ * with files: status.txt, input.txt, metadata.json
+ *
+ * To send follow-up messages to the agent, write content to:
+ *   .knowhow/processes/agents/{taskId}/input.txt
+ * The agent will pick up the new content and process it as a new message.
  */
-export async function startAgentTask(params: StartAgentTaskParams) {
+export async function startAgentTask(params: StartAgentTaskParams): Promise<string> {
   const {
     messageId,
     prompt,
+    syncFs,
     provider,
     model,
     agentName,
     maxTimeLimit,
     maxSpendLimit,
   } = params;
-
-  if (!messageId) {
-    throw new Error("messageId is required to create a chat task");
-  }
-
   if (!prompt) {
     throw new Error("prompt is required to create a chat task");
   }
 
-  const escapedPrompt = prompt.replace(/"/g, '\\"');
+  // Pre-generate taskId so we can return the agents dir path to the caller
+  const taskId = generateTaskId(prompt);
+  const agentTaskDir = path.join(AGENTS_DIR, taskId);
 
-  // Build the command with all optional parameters
-  let command = `knowhow agent --input "${escapedPrompt}" --message-id ${messageId}`;
+  // Build args array (no shell escaping needed - args are passed directly)
+  const args: string[] = ["agent"];
+
+  if (messageId) {
+    args.push("--message-id", messageId);
+  } else if (syncFs) {
+    args.push("--sync-fs");
+    // Pass the pre-generated taskId so the agent dir path is predictable
+    args.push("--task-id", taskId);
+  }
 
   if (provider) {
-    command += ` --provider ${provider}`;
+    args.push("--provider", provider);
   }
 
   if (model) {
-    command += ` --model "${model}"`;
+    args.push("--model", model);
   }
 
   if (agentName) {
-    command += ` --agent-name "${agentName}"`;
+    args.push("--agent-name", agentName);
   }
 
   if (maxTimeLimit !== undefined) {
-    command += ` --max-time-limit ${maxTimeLimit}`;
+    args.push("--max-time-limit", String(maxTimeLimit));
   }
 
   if (maxSpendLimit !== undefined) {
-    command += ` --max-spend-limit ${maxSpendLimit}`;
+    args.push("--max-spend-limit", String(maxSpendLimit));
   }
 
-  const timeout = maxTimeLimit || 60000;
-  return execCommand(command, timeout, true);
+  const timeoutMs = maxTimeLimit ? maxTimeLimit * 60 * 1000 : 60 * 60 * 1000;
+
+  // Set up log file for background process output
+  fs.mkdirSync(PROCESSES_DIR, { recursive: true });
+  const logBaseName = `knowhow_${Math.floor(Date.now() / 1000)}`;
+  const logPath = path.join(PROCESSES_DIR, `${logBaseName}.txt`);
+  const fd = fs.openSync(logPath, "w");
+
+  const header =
+    `CMD: knowhow ${args.join(" ")}\n` +
+    `START: ${new Date().toISOString()}\n` +
+    `---\n`;
+  fs.writeSync(fd, header);
+
+  // Spawn with prompt piped via stdin - no shell escaping issues
+  const child = spawn("knowhow", args, {
+    stdio: ["pipe", fd, fd],
+    detached: true,
+  });
+
+  const pid = child.pid!;
+  fs.writeSync(fd, `PID: ${pid}\n`);
+
+  // Write prompt to stdin and close it so the process reads it
+  child.stdin!.write(prompt, "utf8");
+  child.stdin!.end();
+
+  return new Promise<string>((resolve) => {
+    let settled = false;
+    const done = (msg: string) => {
+      if (settled) return;
+      settled = true;
+      try { fs.closeSync(fd); } catch {}
+      resolve(msg);
+    };
+
+    child.once("error", (e) => {
+      done(`Failed to start agent: ${String(e)}\nLogs: ${logPath}`);
+    });
+
+    const syncFsNote = syncFs
+      ? `\nTask ID: ${taskId}\nAgent dir: ${agentTaskDir}\n` +
+        `To send follow-up messages, write to: ${agentTaskDir}/input.txt\n` +
+        `To check status, read: ${agentTaskDir}/status.txt\n`
+      : "";
+
+    // Give the agent 30 seconds to finish before detaching
+    const detachTime = 30 * 1000; // 30 seconds
+    const tid = setTimeout(() => {
+      try { child.unref(); } catch {}
+      done(
+        `Agent started (pid=${pid}), running in background.\n` +
+        `Logs: ${logPath}\n` +
+        syncFsNote
+      );
+    }, detachTime);
+
+    child.once("exit", (code) => {
+      clearTimeout(tid);
+      done(
+        `Agent finished with exit code ${code}.\nLogs: ${logPath}\n` +
+        syncFsNote
+      );
+    });
+  });
 }
 
 export const startAgentTaskDefinition: Tool = {
@@ -68,14 +169,22 @@ export const startAgentTaskDefinition: Tool = {
   function: {
     name: "startAgentTask",
     description:
-      "Create a new chat task in Knowhow based on a message ID and prompt. This allows worker agents to start tasks and update knowhow's backend with all CLI agent options",
+      "Create a new chat task in Knowhow based on a message ID and prompt. This allows worker agents to start tasks and update knowhow's backend with all CLI agent options. " +
+      "When syncFs is true, the agent creates a directory at .knowhow/processes/agents/{taskId}/ with status.txt, input.txt, and metadata.json. " +
+      "You can send follow-up messages to the running agent by writing content to .knowhow/processes/agents/{taskId}/input.txt. " +
+      "The return value includes the taskId and agent directory path when syncFs is used.",
     parameters: {
       type: "object",
       properties: {
         messageId: {
           type: "string",
           description:
-            "The ID of the message in Knowhow to associate with this task",
+            "The ID of the message in Knowhow to associate with this task (optional)",
+        },
+        syncFs: {
+          type: "boolean",
+          description:
+            "Enable filesystem-based synchronization for the task. Use this when no messageId is available.",
         },
         prompt: {
           type: "string",
@@ -103,7 +212,7 @@ export const startAgentTaskDefinition: Tool = {
           description: "Cost limit for agent execution in dollars. Default: 10",
         },
       },
-      required: ["messageId", "prompt"],
+      required: ["prompt"],
     },
   },
 };