@tyvm/knowhow 0.0.89 → 0.0.91

package/WORKER.md

@@ -1,373 +1,235 @@
-# Knowhow Workers Guide
+# `knowhow worker` — what it is
 
-Knowhow workers allow you to expose your local tools and development environment to the Knowhow platform, enabling remote agents to execute commands, access files, and leverage your local setup through a secure WebSocket connection.
+The `knowhow worker` command starts a **Knowhow Worker process** that exposes an **MCP (Model Context Protocol) server** backed by a curated set of **tools**.
 
----
+At a high level (from `src/worker.ts` + CLI wiring):
 
-## Quick Start
+1. Loads `knowhow.json` via `getConfig()`.
+2. Optionally runs **passkey setup / reset** flows (browser-based), then exits.
+3. Chooses an execution mode:
+   - **Host mode** (default), or
+   - **Docker sandbox mode** (`--sandbox`)
+4. In host mode, it connects to Knowhow’s API over **WebSockets** and serves MCP tools.
+5. In sandbox mode, it verifies Docker, rebuilds the worker image, then runs the worker inside Docker and forwards logs.
 
-### 1. Initial Setup
+> The CLI entry point (e.g. in `src/cli.ts`) mainly defines the subcommand surface and ensures shared services are initialized; the runtime behavior and config handling are implemented in `src/worker.ts`.
 
-First, authenticate with the Knowhow platform:
+---
 
-```bash
-knowhow login
-```
+## What the worker exposes
 
-This will open your browser and guide you through the authentication process.
+In **host mode**, the worker:
+- Starts an **MCP server** (`clientName = "knowhow-worker"`, `clientVersion = "1.1.1"`).
+- Registers the enabled tool set (see `worker.allowedTools` below).
+- Connects to the Knowhow backend WebSocket endpoint(s) so the backend can drive tool usage.
+- Reconnects continuously if the WebSocket connection drops.
 
-### 2. Generate Worker Configuration
+Key connection endpoints (host mode):
+- Worker WS: `${API_URL}/ws/worker`
+- Optional tunnel WS: `${API_URL}/ws/tunnel`
 
-Run the worker command to generate the initial configuration:
+WebSocket headers include:
+- `Authorization: Bearer <jwt>` (from `loadJwt()`)
+- `User-Agent: knowhow-worker/1.1.1/<hostname>`
+- `Root: <computed from WORKER_ROOT or cwd>`
+- Optional share visibility:
+  - `Shared: "true"` with `--share`
+  - `Shared: "false"` with `--unshare`
+  - no `Shared` header if neither flag is provided
 
-```bash
-knowhow worker
-```
+---
 
-This will:
-- Generate a `worker` configuration block in your `knowhow.json`
-- Display available tools that can be exposed
-- Create a secure connection to the Knowhow platform
+# CLI arguments supported by `knowhow worker`
 
-### 3. Configure Allowed Tools
+These flags are handled by the exported worker launcher in `src/worker.ts` (and exposed by the `worker` subcommand wiring).
 
-Edit your `knowhow.json` to specify which tools you want to expose:
+| Flag | Type | Effect |
+|------|------|--------|
+| `--register` | boolean | Registers the current directory as a worker path (`registerWorkerPath(process.cwd())`) and then exits. |
+| `--share` | boolean | Sets `Shared: "true"` header when connecting to the API (marks worker as shared). |
+| `--unshare` | boolean | Sets `Shared: "false"` header when connecting to the API (marks worker as private/unshared). |
+| `--sandbox` | boolean | Runs worker in Docker sandbox mode; persists `worker.sandbox = true` into config. |
+| `--no-sandbox` | boolean | Forces host mode; persists `worker.sandbox = false` into config. |
+| `--passkey` | boolean | Runs browser-based passkey setup (`PasskeySetupService().setup(jwt)`) and exits. |
+| `--passkey-reset` | boolean | Clears stored passkey credentials (`PasskeySetupService().reset()`) and exits. |
 
-```json
-{
-  "worker": {
-    "allowedTools": [
-      "readFile",
-      "writeFileChunk",
-      "patchFile",
-      "execCommand",
-      "textSearch",
-      "fileSearch",
-      "embeddingSearch"
-    ]
-  }
-}
-```
+## Sandbox selection priority (important)
 
-### 4. Start the Worker
+When not already inside Docker, sandbox mode is selected by this priority:
 
-Run the worker again to start the connection:
+1. `--sandbox` / `--no-sandbox` CLI flags (highest priority)
+2. `knowhow.json` config: `config.worker.sandbox`
+3. Default: `false` (host mode)
 
-```bash
-knowhow worker
-```
+### Special case: already inside Docker
+If `process.env.KNOWHOW_DOCKER === "true"`, the worker forces:
+- `options.sandbox = false`
+- `options.noSandbox = true`
 
-Your local tools are now available to Knowhow behaviors and agents!
+This prevents nested Docker execution.
 
 ---
 
-## Worker Architecture
+# `knowhow.json` config options supported (as used by `src/worker.ts`)
 
-### WebSocket Connection
+The worker primarily reads/writes under `config.worker.*`.
 
-Workers establish a secure WebSocket connection to the Knowhow platform:
+## 1) `worker.sandbox` (boolean)
+Controls which mode runs **when no CLI sandbox flags are provided**.
 
-- **Authentication**: Uses your login credentials for secure access
-- **Real-time Communication**: Enables instant tool execution requests
-- **Automatic Reconnection**: Handles network interruptions gracefully
-- **Tool Allowlisting**: Only exposed tools can be executed remotely
+- Updated by:
+  - `--sandbox` → `worker.sandbox = true`
+  - `--no-sandbox` → `worker.sandbox = false`
+
+---
 
-### MCP Integration
+## 2) `worker.allowedTools` (string[])
+Controls which tools are exposed to the MCP server.
 
-Workers leverage the Model Context Protocol (MCP) to expose tools:
+Behavior:
+- If missing, the worker:
+  1. populates it with `Tools.getToolNames()`
+  2. saves it back to `knowhow.json`
+  3. then exits early (so you can edit/curate the allowlist)
 
-- **Tool Registration**: Local tools are registered as MCP resources
-- **Parameter Validation**: Ensures proper argument types and requirements
-- **Error Handling**: Provides detailed error messages for debugging
-- **Response Formatting**: Standardizes tool outputs for agent consumption
+So: first run creates an allowlist; subsequent runs enforce it.
 
 ---
 
-## Configuration
+## 3) Passkey auth: `worker.auth.passkey`
+If configured, the worker starts in a **locked** state and wraps tool execution so tools fail unless unlocked.
 
-### Basic Worker Configuration
+The code implies an expected shape like:
 
-```json
-{
-  "worker": {
-    "allowedTools": [
-      "readFile",
-      "writeFileChunk",
-      "patchFile",
-      "lintFile",
-      "execCommand",
-      "textSearch",
-      "fileSearch",
-      "embeddingSearch"
-    ]
-  }
-}
+```ts
+config.worker.auth.passkey.publicKey
+config.worker.auth.passkey.credentialId
+config.worker.auth.sessionDurationHours // optional; defaults to ~3
 ```
 
-### Advanced Configuration
+Effects when enabled:
+- `WorkerPasskeyAuthService` is created.
+- Tool functions are wrapped:
+  - When locked: return an error object like `WORKER_LOCKED` / “unlock first”.
+  - When unlocked: execute the original tool function.
+- The worker registers additional auth tools:
+  - `unlock` (`makeUnlockTool`)
+  - `lock` (`makeLockTool`)
 
-```json
-{
-  "worker": {
-    "allowedTools": [
-      "readFile",
-      "writeFileChunk",
-      "patchFile",
-      "lintFile",
-      "execCommand",
-      "textSearch",
-      "fileSearch",
-      "embeddingSearch",
-      "createAiCompletion",
-      "listAllModels",
-      "callPlugin"
-    ]
-  }
-}
-```
+> Exact error message/response format depends on the auth service implementation, but the lock/unlock gating is explicit.
 
 ---
 
-## Available Tools
-
-### File Operations
+## 4) Tunnel configuration: `worker.tunnel.*`
+If enabled, the worker also opens a second WebSocket (`/ws/tunnel`) so the backend can reach allowed local services.
 
-#### Core File Tools
-- **`readFile`** - Read complete file contents
-- **`writeFileChunk`** - Write content to files (supports chunking for large files)
-- **`patchFile`** - Apply unified diff patches to files
-- **`readBlocks`** - Read specific blocks from files
+### `worker.tunnel.enabled` (boolean)
+- `true` → tunnel WS created
+- `false` / missing → tunneling disabled
 
-#### Search Tools
-- **`textSearch`** - Search for exact text matches across files
-- **`fileSearch`** - Search for files by path patterns
-- **`embeddingSearch`** - Semantic search using embeddings
+### `worker.tunnel.allowedPorts` (number[])
+- Restricts which ports can be used through the tunnel.
+- If tunnel is enabled but this list is empty, the worker logs a warning.
 
-### Development Tools
+### `worker.tunnel.localHost` (string, optional)
+Hostname for reaching local services.
 
-#### Code Quality
-- **`lintFile`** - Run linters on files based on extension
-- **`execCommand`** - Execute shell commands with timeout support
+- If not set:
+  - inside Docker (`KNOWHOW_DOCKER === "true"`): `host.docker.internal`
+  - otherwise: `127.0.0.1`
 
-#### AI Integration
-- **`createAiCompletion`** - Create AI completions using configured models
-- **`listAllModels`** - List available AI models
-- **`listAllProviders`** - List available AI providers
+### `worker.tunnel.portMapping` (object/map)
+The code treats it as a mapping:
 
-### Plugin System
-- **`callPlugin`** - Execute plugin functions
-- **`addLanguageTerm`** - Add language terms for context loading
-- **`getAllLanguageTerms`** - Retrieve all configured language terms
-- **`lookupLanguageTerm`** - Look up specific language terms
+- `config.worker.tunnel.portMapping[containerPort] = hostPort`
 
-### Integration Tools
+It logs these mappings and passes them to the tunnel handler.
 
-#### Version Control
-- **`getPullRequest`** - Fetch GitHub pull request information
-- **`getPullRequestBuildStatuses`** - Get build status for PRs
-- **`getRunLogs`** - Retrieve GitHub Actions run logs
-- **`getPullRequestBuildFailureLogs`** - Get failure logs from PR builds
+### `worker.tunnel.maxConcurrentStreams` (number, optional)
+- Passed to tunnel config
+- Default used in `src/worker.ts`: `50`
 
-### MCP Server Tools
-
-When MCP servers are configured, their tools become available with prefixed names:
-
-```json
-{
-  "mcps": [
-    {
-      "name": "browser",
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
-    }
-  ],
-  "worker": {
-    "allowedTools": [
-      "mcp_0_browser_navigate",
-      "mcp_0_browser_screenshot",
-      "mcp_0_browser_click",
-      "mcp_0_browser_fill",
-      "mcp_0_browser_select"
-    ]
-  }
-}
-```
+### `worker.tunnel.enableUrlRewriting` (boolean, optional)
+- Passed to tunnel config as:
+  - `config.worker.tunnel.enableUrlRewriting !== false`
+- So URL rewriting defaults to **enabled** unless explicitly set to `false`.
 
 ---
 
-## Security Considerations
-
-### Tool Allowlisting
+# Execution modes (host vs Docker sandbox)
+
+## Host mode (default)
+Key responsibilities:
+- Connect to `${API_URL}/ws/worker` using the JWT and headers (including optional `Shared`).
+- Optionally connect to `${API_URL}/ws/tunnel`.
+- Serve MCP tools via `mcpServer.createServer(...).withTools(toolsToUse)`.
+- If the worker WS reconnects:
+  - it resets MCP server state and re-registers the tool set.
+
+## Docker sandbox mode (`--sandbox`)
+When sandbox mode is selected:
+1. Check Docker availability.
+2. Build the worker Docker image.
+3. Load JWT.
+4. Run the worker in Docker (`Docker.runWorkerContainer(...)`) with:
+   - `workspaceDir: process.cwd()`
+   - `jwt`
+   - `apiUrl: API_URL`
+   - `config` passed into container
+   - `share` / `unshare` options
+5. Forward container logs and stop the container on exit.
 
-Only tools explicitly listed in `allowedTools` can be executed remotely:
+---
 
-```json
-{
-  "worker": {
-    "allowedTools": [
-      "readFile",      // ✅ Allowed
-      "writeFileChunk", // ✅ Allowed
-      // "execCommand" // ❌ Not allowed - commented out
-    ]
-  }
-}
+# Summary checklist
+
+- **Use `knowhow worker` to**: run a Knowhow Worker that exposes an MCP server and a filtered tool allowlist.
+- **Common CLI flags**:
+  - `--register`, `--share`, `--unshare`
+  - `--sandbox` / `--no-sandbox`
+  - `--passkey` / `--passkey-reset`
+- **Key config fields**:
+  - `worker.sandbox`
+  - `worker.allowedTools` (auto-populated on first run if missing)
+  - `worker.auth.passkey.*` (enables lock/unlock tool gating)
+  - `worker.tunnel.enabled`, `worker.tunnel.allowedPorts`, `worker.tunnel.localHost`, `worker.tunnel.portMapping`, `worker.tunnel.maxConcurrentStreams`, `worker.tunnel.enableUrlRewriting`
 ```
 
-### File System Access
-
-Workers respect the project directory boundaries:
-- **Limited Scope**: Only files within the project directory are accessible
-- **Path Validation**: Prevents directory traversal attacks
-- **Permission Checks**: Respects file system permissions
-
-### Command Execution
-
-When `execCommand` is enabled:
-- **Timeout Protection**: Commands have configurable timeouts
-- **Process Isolation**: Commands run in separate processes
-- **Error Handling**: Captures both stdout and stderr
-- **Security Warning**: Be cautious with command execution in untrusted environments
-
-### Network Security
+If you paste `src/worker.ts` (or the exact relevant portions) and `src/cli.ts`, I can tighten any remaining ambiguities (e.g., exact auth config field names and the precise tool/error response shapes).
+# Knowhow Workers Guide
 
-- **Encrypted Connection**: All communication uses WebSocket Secure (WSS)
-- **Authentication Required**: Valid Knowhow credentials required
-- **Session Management**: Automatic session expiration and renewal
+Knowhow workers allow you to expose your local tools and development environment to the Knowhow platform, enabling remote agents to execute commands, access files, and leverage your local setup through a secure WebSocket connection.
 
 ---
 
-## Integration with Knowhow Behaviors
-
-### Creating Worker-Enabled Behaviors
-
-Behaviors can leverage worker tools through the Knowhow platform:
-
-```json
-{
-  "name": "Code Reviewer",
-  "description": "Reviews code changes and provides feedback",
-  "instructions": "Use readFile to examine code, textSearch to find patterns, and writeFileChunk to create review comments",
-  "tools": ["worker_0_readFile", "worker_0_textSearch", "worker_0_writeFileChunk"],
-  "workers": ["worker_connection_id"]
-}
-```
-
-### Tool Usage in Agents
-
-Agents can call worker tools directly:
-
-```javascript
-// Agent can read local files
-const fileContent = await callTool('readFile', {
-  filePath: './src/components/Header.tsx'
-});
-
-// Search for patterns in codebase
-const searchResults = await callTool('textSearch', {
-  searchTerm: 'useState'
-});
-
-// Apply code changes
-await callTool('patchFile', {
-  filePath: './src/utils/helpers.ts',
-  patch: `--- a/src/utils/helpers.ts
-+++ b/src/utils/helpers.ts
-@@ -10,6 +10,7 @@
- export function formatDate(date: Date): string {
-+  if (!date) return '';
-   return date.toISOString().split('T')[0];
- }`
-});
-```
-
----
+## Quick Start
 
-## Command Line Usage
+### 1. Initial Setup
 
-### Basic Commands
+First, authenticate with the Knowhow platform:
 
 ```bash
-# Authenticate with Knowhow
 knowhow login
-
-# Generate worker configuration
-knowhow worker
-
-# Start worker with default config
-knowhow worker
-```
-
-### Environment Variables
-
----
-
-## Troubleshooting
-
-### Common Issues
-
-#### Connection Problems
-
-**Issue**: Worker fails to connect
-```
-Error: WebSocket connection failed
 ```
 
-**Solutions**:
-1. Check internet connection
-2. Verify authentication: `knowhow login`
-3. Check firewall settings for WebSocket connections
-
-#### Authentication Errors
-
-**Issue**: Authentication failed
-```
-Error: Invalid credentials
-```
+This will open your browser and guide you through the authentication process.
 
-**Solutions**:
-1. Re-authenticate: `knowhow login`
-2. Check token expiration
-3. Verify organization permissions
+### 2. Generate Worker Configuration
 
-#### Tool Execution Failures
+Run the worker command to generate the initial configuration:
 
-**Issue**: Tool not found or not allowed
-```
-Error: Function readFile not enabled
+```bash
+knowhow worker
 ```
 
-**Solutions**:
-1. Add tool to `allowedTools` in `knowhow.json`
-2. Restart worker after configuration changes
-3. Verify tool name spelling
-
-## Best Practices
-
-### Security
-
-1. **Principle of Least Privilege**: Only expose necessary tools
-2. **Regular Audits**: Review `allowedTools` periodically
-3. **Environment Separation**: Use different configurations for dev/prod
-4. **Command Restrictions**: Be cautious with `execCommand` permissions
-
-### Development Workflow
-
-1. **Version Control**: Include `knowhow.json` in version control
-2. **Team Coordination**: Document tool requirements for team members
-3. **Testing**: Test worker configuration before deploying behaviors
-4. **Documentation**: Document custom tools and their usage
-
-### Maintenance
-1. **Regular Updates**: Keep Knowhow CLI updated
-2. **Log Monitoring**: Review worker logs for issues
-3. **Configuration Backup**: Backup working configurations
-4. **Health Checks**: Implement monitoring for worker connectivity
-
----
+This will:
+- Generate a `worker` configuration block in your `knowhow.json`
+- Display available tools that can be exposed
+- Create a secure connection to the Knowhow platform
 
-## Examples
+### 3. Configure Allowed Tools
 
-### Development Environment Setup
+Edit your `knowhow.json` to specify which tools you want to expose:
 
 ```json
 {
@@ -376,30 +238,7 @@ Error: Function readFile not enabled
       "readFile",
       "writeFileChunk",
       "patchFile",
-      "textSearch",
-      "fileSearch",
-      "embeddingSearch",
       "execCommand",
-      "lintFile"
-    ]
-  },
-  "mcps": [
-    {
-      "name": "browser",
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
-    }
-  ]
-}
-```
-
-### Production Environment (Restricted)
-
-```json
-{
-  "worker": {
-    "allowedTools": [
-      "readFile",
       "textSearch",
       "fileSearch",
       "embeddingSearch"
@@ -408,18 +247,14 @@ Error: Function readFile not enabled
 }
 ```
 
-### Code Review Workflow
+### 4. Start the Worker
 
-```json
-{
-  "worker": {
-    "allowedTools": [
-      "readFile",
-      "textSearch",
-      "getPullRequest",
-      "getPullRequestBuildStatuses",
-      "lintFile"
-    ]
-  }
-}
+Run the worker again to start the connection:
+
+```bash
+knowhow worker
 ```
+
+Your local tools are now available to Knowhow behaviors and agents!
+
+