@tyvm/knowhow 0.0.55 → 0.0.56

package/docs/input-queue-manager.md

@@ -0,0 +1,142 @@
+# Input Queue Manager
+
+## Problem
+
+When multiple `ask()` calls (used by `askHuman` tool and `ChatService.getInput`) are made concurrently before any resolve, each call would create its own readline interface listening to `process.stdin`. This caused input duplication - each character typed would be processed by multiple listeners, appearing doubled or tripled in the terminal.
+
+### Example Scenario
+
+```typescript
+// Agent asks a question
+const answer1 = ask("What is your name?");
+
+// Before user responds, agent asks another question
+const answer2 = ask("What is your age?");
+
+// Problem: User sees both questions and typed characters appear multiple times
+```
+
+## Solution
+
+Implemented a singleton `InputQueueManager` class that:
+
+1. **Queues all concurrent asks**: When multiple `ask()` calls happen, they're added to a queue
+2. **Maintains a single input stream**: Only one readline interface is active at a time
+3. **Updates the display**: When a new question is asked while waiting, the display updates to show the most recent question
+4. **Resolves all pending promises**: When the user presses Enter, all queued promises resolve with the same answer
+
+### Key Features
+
+- **Single input stream**: Only one `process.stdin` listener is active at any time
+- **Dynamic question updates**: The displayed question updates to the most recent one
+- **Preserved user input**: When the question changes, the user's typed text is preserved
+- **Cursor position maintained**: Cursor position is maintained relative to the typed text
+- **Autocomplete support**: Tab completion uses options from the most recent question
+- **History support**: Arrow key navigation uses history from the most recent question
+
+## Implementation Details
+
+```typescript
+class InputQueueManager {
+  private queue: Array<{
+    question: string;
+    options: string[];
+    history: string[];
+    resolve: (value: string) => void;
+  }> = [];
+  private currentReadline: any = null;
+  private isProcessing = false;
+  private currentLine = "";
+  private cursorPos = 0;
+
+  async ask(question, options, history): Promise<string> {
+    return new Promise((resolve) => {
+      this.queue.push({ question, options, history, resolve });
+      
+      if (!this.isProcessing) {
+        this.processNext();
+      } else {
+        this.updateDisplay(); // Update to show new question
+      }
+    });
+  }
+
+  private updateDisplay(): void {
+    // Clear line and show most recent question
+    const current = this.queue[this.queue.length - 1];
+    process.stdout.write('\r\x1b[K');
+    process.stdout.write(current.question + this.currentLine);
+  }
+
+  private async processNext(): Promise<void> {
+    // Process most recent question
+    const current = this.queue[this.queue.length - 1];
+    
+    // Set up single readline interface
+    this.currentReadline = readline.createInterface({...});
+    
+    // Handle input
+    process.stdin.on("data", dataHandler);
+  }
+
+  // On Enter press
+  private handleSubmit(answer: string): void {
+    // Resolve ALL pending promises with the same answer
+    while (this.queue.length > 0) {
+      const item = this.queue.shift();
+      item.resolve(answer);
+    }
+    
+    // Clean up and process next if any
+    cleanup();
+    this.processNext();
+  }
+}
+```
+
+## Usage
+
+The `ask()` function now automatically uses the singleton queue:
+
+```typescript
+import { ask } from "./utils";
+
+// Multiple concurrent calls are now safe
+const promise1 = ask("Question 1?");
+const promise2 = ask("Question 2?"); // Display updates to this
+const promise3 = ask("Question 3?"); // Display updates to this
+
+// User types "answer" and presses Enter
+// All three promises resolve with "answer"
+const [a1, a2, a3] = await Promise.all([promise1, promise2, promise3]);
+console.log(a1, a2, a3); // "answer", "answer", "answer"
+```
+
+## Testing
+
+Run the manual test to verify the behavior:
+
+```bash
+npx ts-node tests/manual/test-concurrent-ask.ts
+```
+
+Expected behavior:
+- You should see only the most recent question
+- Typing should not duplicate characters
+- Both promises resolve with the same answer
+
+## Benefits
+
+1. **No input duplication**: Characters appear once, as expected
+2. **Clean user experience**: User always sees the most relevant question
+3. **Backward compatible**: Existing code using `ask()` works without changes
+4. **Handles edge cases**: Properly cleans up resources and handles Ctrl+C
+5. **Maintains features**: Autocomplete, history, and cursor control all work correctly
+
+## Related Files
+
+- `src/utils/index.ts` - Implementation of InputQueueManager
+- `src/agents/tools/askHuman.ts` - Uses `ask()` via the queue
+- `src/chat/CliChatService.ts` - Uses `ask()` via the queue
+- `tests/unit/input-queue.test.ts` - Unit tests documenting behavior
+- `tests/manual/test-concurrent-ask.ts` - Manual test to verify fix

package/docs/multi-worker-management.md

@@ -0,0 +1,142 @@
+# Multi-Worker Management
+
+This feature allows you to manage and start multiple knowhow workers from different directories using a centralized registry.
+
+## Overview
+
+The multi-worker management system provides:
+- Registration of worker directories in a global config (`~/.knowhow/workers.json`)
+- A single command to start all registered workers simultaneously
+- Management commands to list, register, and unregister workers
+
+## Usage
+
+### Register a Worker
+
+Navigate to a project directory and register it as a worker:
+
+```bash
+cd /path/to/project1
+knowhow worker --register
+```
+
+This will:
+1. Register the current directory in `~/.knowhow/workers.json`
+2. Ensure the worker configuration is set up in the local `.knowhow/knowhow.json`
+
+### Start All Workers
+
+Start all registered workers at once:
+
+```bash
+knowhow workers
+```
+
+This command will:
+- Read all registered worker paths from the global config
+- Start each worker by executing `knowhow worker` in its directory
+- Keep all workers running until you press Ctrl+C
+- Gracefully shut down all workers on exit
+
+### List Registered Workers
+
+View all registered worker paths:
+
+```bash
+knowhow workers --list
+```
+
+Output example:
+```
+Registered workers (3):
+  1. /Users/username/project1
+  2. /Users/username/project2
+  3. /Users/username/project3
+```
+
+### Unregister a Worker
+
+Remove a worker from the registry:
+
+```bash
+knowhow workers --unregister /path/to/project
+```
+
+### Clear All Workers
+
+Remove all registered workers:
+
+```bash
+knowhow workers --clear
+```
+
+## Configuration
+
+The worker registry is stored in:
+```
+~/.knowhow/workers.json
+```
+
+Example format:
+```json
+{
+  "workers": [
+    "/Users/username/project1",
+    "/Users/username/project2",
+    "/Users/username/project3"
+  ]
+}
+```
+
+## Typical Workflow
+
+1. **Set up multiple projects as workers:**
+   ```bash
+   cd ~/project1
+   knowhow worker --register
+   
+   cd ~/project2
+   knowhow worker --register
+   
+   cd ~/project3
+   knowhow worker --register
+   ```
+
+2. **Start all workers:**
+   ```bash
+   knowhow workers
+   ```
+
+3. **Check worker status:**
+   ```bash
+   knowhow workers --list
+   ```
+
+4. **Stop all workers:**
+   Press `Ctrl+C` in the terminal where workers are running
+
+## Benefits
+
+- **Centralized Management**: Manage multiple workers from a single command
+- **Simplified Deployment**: No need to manually start workers in each directory
+- **Persistent Configuration**: Worker registrations persist across sessions
+- **Graceful Shutdown**: All workers shut down cleanly when stopped
+
+## Implementation Details
+
+### Files Created
+
+- `src/workerRegistry.ts` - Core registry management functions
+- `~/.knowhow/workers.json` - Global worker registry storage
+
+### CLI Commands Modified
+
+- `knowhow worker` - Added `--register` flag to register current directory
+- `knowhow workers` - New command with subcommands for management and starting workers
+
+### Process Management
+
+- Each worker runs as a child process
+- Workers inherit stdio from the parent process (you see all logs)
+- SIGINT/SIGTERM signals are properly handled for graceful shutdown
+- Workers are not detached, so they stop when the parent process stops

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tyvm/knowhow",
-  "version": "0.0.55",
+  "version": "0.0.56",
   "description": "ai cli with plugins and agents",
   "main": "ts_build/src/index.js",
   "bin": {

package/scripts/README.md

@@ -0,0 +1,119 @@
+# AI Keys Management Scripts
+
+These bash scripts help you temporarily unset and restore AI API keys in your terminal session. This is useful for testing CLI behavior without authentication or when you want to work in a clean environment.
+
+## Installation
+
+Add these functions to your `~/.bashrc` or `~/.zshrc`:
+
+```bash
+# AI Keys Management
+unset_keys() {
+    source /path/to/knowhow/scripts/unset_keys.sh
+}
+
+restore_keys() {
+    source /path/to/knowhow/scripts/restore_keys.sh
+}
+```
+
+Replace `/path/to/knowhow` with the actual path to your knowhow repository.
+
+Then reload your shell:
+```bash
+source ~/.bashrc  # or source ~/.zshrc
+```
+
+## Usage
+
+### Unset Keys
+
+Temporarily remove AI API keys from your current shell session:
+
+```bash
+unset_keys
+```
+
+This will:
+- Backup all your API keys to `BACKUP_*` environment variables
+- Unset the following environment variables:
+  - `OPENAI_KEY`
+  - `OPENAI_API_KEY`
+  - `ANTHROPIC_API_KEY`
+  - `ANTHROPIC_KEY`
+  - `GEMINI_API_KEY`
+  - `GOOGLE_API_KEY`
+  - `XAI_API_KEY`
+
+### Restore Keys
+
+Restore your API keys from the backup:
+
+```bash
+restore_keys
+```
+
+This will:
+- Read the backup from `BACKUP_*` environment variables
+- Restore all previously unset environment variables
+- Clear the `BACKUP_*` environment variables
+
+## Example Workflow
+
+```bash
+# Check that you have keys set
+echo $OPENAI_KEY
+# Output: sk-proj-...
+
+# Unset the keys for testing
+unset_keys
+# Output: ✓ Successfully backed up and unset 5 API key(s)
+
+# Verify keys are unset
+echo $OPENAI_KEY
+# Output: (empty)
+
+# Test your CLI without keys
+knowhow --help
+
+# Restore your keys when done
+restore_keys
+# Output: ✓ Successfully restored 5 API key(s)
+
+# Verify keys are restored
+echo $OPENAI_KEY
+# Output: sk-proj-...
+```
+
+## Notes
+
+- These commands only affect the **current terminal session**
+- The backup variables (`BACKUP_*`) are stored in the current shell session only
+- If you close your terminal before running `restore_keys`, the backups are **lost** and you'll need to restart your terminal or re-source your shell configuration to get your keys back from your original bashrc/zshrc
+- The scripts must be **sourced** (not executed) to affect your current shell environment
+
+## Troubleshooting
+
+### Keys lost after closing terminal
+
+If you close your terminal after running `unset_keys`, the backup environment variables are lost. To restore your keys, simply open a new terminal (which will reload your bashrc/zshrc with the original key values) or run:
+
+```bash
+source ~/.bashrc  # or source ~/.zshrc
+```
+
+### Permission denied
+
+Make sure the scripts are executable:
+
+```bash
+chmod +x scripts/unset_keys.sh scripts/restore_keys.sh
+```
+
+### Commands not found
+
+Make sure you've added the functions to your shell configuration and reloaded it:
+
+```bash
+source ~/.bashrc  # or source ~/.zshrc
+```

package/scripts/restore_keys.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+
+# restore_keys - Restore AI API keys that were backed up by unset_keys
+# Usage: source restore_keys.sh  OR  restore_keys (if added to bashrc)
+#
+# This script restores environment variables from BACKUP_* environment variables
+# created by unset_keys
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+restore_keys() {
+    echo -e "${BLUE}Restoring AI API keys...${NC}"
+
+    # List of environment variables to restore
+    local keys=(
+        "OPENAI_KEY"
+        "OPENAI_API_KEY"
+        "ANTHROPIC_API_KEY"
+        "ANTHROPIC_KEY"
+        "GEMINI_API_KEY"
+        "GOOGLE_API_KEY"
+        "XAI_API_KEY"
+    )
+
+    local restored=0
+
+    # Restore each key from its BACKUP_* variable
+    for key in "${keys[@]}"; do
+        local backup_var="BACKUP_${key}"
+        if [ -n "${!backup_var}" ]; then
+            export "${key}=${!backup_var}"
+            unset "$backup_var"
+            restored=$((restored + 1))
+        fi
+    done
+
+    if [ $restored -eq 0 ]; then
+        echo -e "${YELLOW}No backed up keys found to restore${NC}"
+        echo -e "${YELLOW}Run 'unset_keys' first to create backups${NC}"
+    else
+        echo -e "${GREEN}✓ Successfully restored ${restored} API key(s)${NC}"
+        echo -e "${BLUE}BACKUP_* variables cleared${NC}"
+    fi
+}
+
+# If script is sourced, run the function
+if [[ "${BASH_SOURCE[0]}" != "${0}" ]]; then
+    restore_keys
+else
+    echo -e "${RED}ERROR: This script must be sourced, not executed${NC}"
+    echo "Usage: source ${BASH_SOURCE[0]}"
+    echo "Or add to bashrc and run: restore_keys"
+    exit 1
+fi

package/scripts/unset_keys.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+
+# unset_keys - Temporarily unset AI API keys in current shell session
+# Usage: source unset_keys.sh  OR  unset_keys (if added to bashrc)
+#
+# This script backs up your current AI API keys to BACKUP_* environment variables
+# and then unsets the original keys, allowing you to test
+# CLI behavior without authentication.
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+unset_keys() {
+    echo -e "${BLUE}Backing up AI API keys to BACKUP_* variables and unsetting originals...${NC}"
+
+    # List of environment variables to backup and unset
+    local keys=(
+        "OPENAI_KEY"
+        "OPENAI_API_KEY"
+        "ANTHROPIC_API_KEY"
+        "ANTHROPIC_KEY"
+        "GEMINI_API_KEY"
+        "GOOGLE_API_KEY"
+        "XAI_API_KEY"
+    )
+
+    local backed_up=0
+
+    # Backup and unset each key
+    for key in "${keys[@]}"; do
+        if [ -n "${!key}" ]; then
+            # Save the key value to BACKUP_* environment variable
+            export "BACKUP_${key}=${!key}"
+            unset "$key"
+            backed_up=$((backed_up + 1))
+        fi
+    done
+
+    if [ $backed_up -eq 0 ]; then
+        echo -e "${YELLOW}No AI keys found to unset${NC}"
+    else
+        echo -e "${GREEN}✓ Successfully backed up and unset ${backed_up} API key(s)${NC}"
+        echo -e "${BLUE}Keys backed up to BACKUP_* environment variables${NC}"
+        echo -e "${YELLOW}Run 'restore_keys' to restore them${NC}"
+    fi
+}
+
+# If script is sourced, run the function
+if [[ "${BASH_SOURCE[0]}" != "${0}" ]]; then
+    unset_keys
+else
+    echo -e "${RED}ERROR: This script must be sourced, not executed${NC}"
+    echo "Usage: source ${BASH_SOURCE[0]}"
+    echo "Or add to bashrc and run: unset_keys"
+    exit 1
+fi

package/src/agents/tools/askHuman.ts

@@ -1,6 +1,8 @@
 import Marked from "marked";
 import { ask } from "../../utils";
 
+// Simple, CLI-agnostic implementation
+// CLI-specific behavior is handled via ToolsService override in AgentModule
 export async function askHuman(question: string) {
   console.log("AI has asked: ");
   console.log(Marked.parse(question), "\n");

package/src/agents/tools/startAgentTask.ts

@@ -59,7 +59,8 @@ export async function startAgentTask(params: StartAgentTaskParams) {
     command += ` --max-spend-limit ${maxSpendLimit}`;
   }
 
-  return execCommand(command, 60000, true);
+  const timeout = maxTimeLimit || 60000;
+  return execCommand(command, timeout, true);
 }
 
 export const startAgentTaskDefinition: Tool = {
@@ -106,4 +107,3 @@ export const startAgentTaskDefinition: Tool = {
     },
   },
 };
-

package/src/ai.ts

@@ -73,7 +73,9 @@ export async function summarizeTexts(
 
     console.log(content);
 
-    const summary = await singlePrompt(content, model, agent);
+    const summary = await singlePrompt(content, model, agent).catch((err) => {
+      return `Text of length ${text.length} could not be summarized due to error: ${err.message}`;
+    });
     summaries.push(summary);
   }
 

package/src/chat/CliChatService.ts

@@ -206,8 +206,8 @@ export class CliChatService implements ChatService {
       value = await editor({ message: prompt });
       this.context.multilineMode = false; // Disable after use like original
     } else {
-      // Use saved input history for scrollback instead of current chat history
-      const history = this.inputHistory.slice().reverse();
+      // Use saved input history for scrollback (InputQueueManager handles reverse access)
+      const history = this.inputHistory.slice();
       value = await ask(prompt, options, history);
     }
 

package/src/chat/modules/AgentModule.ts

@@ -1,7 +1,10 @@
 /**
  * Agent Chat Module - Handles agent interactions
  */
-import { KnowhowSimpleClient } from "../../services/KnowhowClient";
+import {
+  KnowhowSimpleClient,
+  KNOWHOW_API_URL,
+} from "../../services/KnowhowClient";
 import * as fs from "fs";
 import * as path from "path";
 
@@ -641,7 +644,7 @@ ${reason}
       this.saveSession(taskId, taskInfo, []);
 
       // Create Knowhow chat task if messageId provided
-      const baseUrl = process.env.KNOWHOW_API_URL;
+      const baseUrl = KNOWHOW_API_URL;
       console.log(
         `Base URL for Knowhow API: ${baseUrl}, Message ID: ${options.messageId}`
       );
@@ -706,6 +709,26 @@ ${reason}
 
       // Set up message processors like in original startAgent
 
+      // Register an override for askHuman to use CLI input method
+      // This keeps the askHuman tool CLI-agnostic while enabling CLI-specific behavior
+      // through the override system, achieving better separation of concerns
+      agent.tools.registerOverride(
+        "askHuman",
+        async (originalArgs: any[], originalTool: any) => {
+          const question = originalArgs[0];
+
+          // Use CLI-specific input method from CliChatService
+          const chatService = this.chatService;
+          if (!chatService) {
+            throw new Error("ChatService not available in tools context");
+          }
+          console.log("AI has asked: ");
+          console.log(Marked.parse(question), "\n");
+          return await chatService.getInput("response: ");
+        },
+        10 // Priority level
+      );
+
       agent.messageProcessor.setProcessors("pre_call", [
         new ToolResponseCache(agent.tools).createProcessor(),
         new TokenCompressor(agent.tools).createProcessor((msg) =>

package/src/chat-old.ts

@@ -152,7 +152,7 @@ export async function getInput(
     value = await editor({ message: question });
     Flags.disable(ChatFlags.multi);
   } else {
-    const history = chatHistory.map((c) => c.input).reverse();
+    const history = chatHistory.map((c) => c.input);
     value = await ask(question, options, history);
   }
 
@@ -248,7 +248,7 @@ export async function chatLoop<E extends GptQuestionEmbedding>(
           provider = await ask(
             `\n\nCurrent Provider: ${provider}\nCurrent Model: ${model}\n\nWhich provider would you like to use: `,
             providers
-          );
+          ) as keyof typeof Clients.clients;
           model =
             ChatModelDefaults[provider] ||
             (await Clients.getRegisteredModels(provider))[0];