khabotcli 1.0.0

package/docs/guide/04-agents.md

@@ -0,0 +1,267 @@
+# Agent Configuration
+
+An agent is a folder in `.khabot/agents/<name>/` containing at minimum `agent.json` and `AGENT.md`.
+
+---
+
+## `agent.json` — Full Reference
+
+```json
+{
+  "name": "assistant",
+  "description": "General-purpose agent with file and shell access",
+  "model": "moonshotai/kimi-k2.5",
+  "temperature": 0.7,
+  "reasoning": "medium",
+  "maxTokens": 4096,
+  "memory": {
+    "enabled": true,
+    "maxLines": 300
+  },
+  "skillDiscovery": false,
+  "modes": {
+    "chat":      { ... },
+    "task":      { ... },
+    "subagent":  { ... },
+    "daemon":    { ... }
+  }
+}
+```
+
+### Top-level fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | ✓ | Agent identifier. Must match the folder name. |
+| `description` | string | | Human-readable description |
+| `model` | string | ✓ | LLM model string (e.g. `moonshotai/kimi-k2.5`) |
+| `temperature` | number | | 0–2. Sampling temperature. |
+| `reasoning` | string | | Reasoning level: "minimal", "low", "medium", "high" |
+| `maxTokens` | integer | | Max output tokens per LLM call |
+| `memory.enabled` | boolean | | Whether memory files are injected. Overrides settings-level default. |
+| `memory.maxLines` | integer | | Max lines to read from memory file |
+| `skillDiscovery` | boolean | | Auto-discover skill files in the agent's folder |
+
+---
+
+## Mode Configuration
+
+Every mode shares a common set of fields plus mode-specific ones.
+
+### Common mode fields
+
+```json
+{
+  "enabled": true,
+  "tools": ["read_file", "list_dir", "bash"],
+  "disallowedTools": ["write_file"],
+  "skills": ["my-skill"],
+  "autoLoadSkills": ["boot-skill"],
+  "mcpServers": ["my-mcp"],
+  "allowedAgents": ["coder", "writer"],
+  "disallowedAgents": []
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `enabled` | boolean | Whether this mode is active |
+| `tools` | string[] | Whitelist: only these tools are offered to the LLM. Equivalent to `permissions.allow`. |
+| `disallowedTools` | string[] | Blacklist: these tools are hidden from the LLM. Equivalent to `permissions.deny`. |
+| `skills` | string[] | Skill files to load (by name) |
+| `autoLoadSkills` | string[] | Skills auto-injected into the system prompt |
+| `mcpServers` | string[] | MCP server names to load tools from |
+| `allowedAgents` | string[] | Sub-agents this agent may spawn |
+| `disallowedAgents` | string[] | Sub-agents explicitly blocked |
+| `permissions.allow` | string[] | Runtime allow list — tools allowed to execute (checked at call time, supports glob patterns) |
+| `permissions.deny` | string[] | Runtime deny list — tools blocked from executing (checked at call time, wins over allow) |
+
+**`tools`/`disallowedTools` vs `permissions`**: `tools` and `disallowedTools` control which tools the LLM *sees* (the tool list sent in the API call). `permissions.allow`/`deny` control which tools are *allowed to execute* at runtime. You can use either, both, or combine them. See [Permissions](07-permissions.md).
+
+---
+
+## Chat Mode
+
+```json
+{
+  "modes": {
+    "chat": {
+      "enabled": true,
+      "permissions": {
+        "allow": ["read_file", "list_dir"],
+        "deny": []
+      }
+    }
+  }
+}
+```
+
+Chat mode is used by `POST /agents/:name/chat`. Each call is synchronous — the agent runs its full loop (including any tool calls) before returning.
+
+---
+
+## Task Mode
+
+```json
+{
+  "modes": {
+    "task": {
+      "enabled": true,
+      "maxIterations": 20,
+      "maxDurationSeconds": 120,
+      "onExhausted": "fail",
+      "permissions": {
+        "allow": ["read_file", "list_dir", "bash", "write_file", "web_search"],
+        "deny": []
+      }
+    }
+  }
+}
+```
+
+Task-specific fields:
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `maxIterations` | integer | settings default | Max LLM loop iterations (each tool call = 1 iteration) |
+| `maxDurationSeconds` | integer | settings default | Wall-clock time limit |
+| `onExhausted` | string | `"fail"` | What to do when limits are hit: `"fail"` (mark failed) or `"wait"` (pause, allow respond) |
+
+---
+
+## Subagent Mode
+
+```json
+{
+  "modes": {
+    "subagent": {
+      "enabled": true,
+      "maxIterations": 10,
+      "maxDurationSeconds": 60,
+      "permissions": {
+        "allow": ["read_file", "bash"]
+      }
+    }
+  }
+}
+```
+
+Subagent mode is triggered when another agent calls `agent_spawn` targeting this agent. It has the same fields as task mode. If not explicitly configured, subagent mode falls back to task mode config.
+
+---
+
+## Daemon Mode
+
+```json
+{
+  "modes": {
+    "daemon": {
+      "enabled": true,
+      "cron": "*/15 * * * *",
+      "maxIterations": 10,
+      "maxDurationSeconds": 60,
+      "conflictPolicy": "skip",
+      "heartbeatFile": ".khabot/heartbeats/monitor.md",
+      "alertRouting": "ops-agent",
+      "permissions": {
+        "allow": ["read_file", "bash", "web_fetch", "memory_write"]
+      }
+    }
+  }
+}
+```
+
+Daemon-specific fields:
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `cron` | string | | Cron expression. Required for auto-start. E.g. `"*/5 * * * *"` (every 5 min) |
+| `conflictPolicy` | string | `"skip"` | If a tick fires while the previous one is running: `"skip"`, `"queue"`, or `"restart"` |
+| `heartbeatFile` | string | `.khabot/heartbeats/<name>.md` | File containing daemon instructions, read each tick |
+| `alertRouting` | string \| string[] | | Agent name(s) to notify on error |
+
+See [Daemon Agents](10-daemons.md) for full setup guide.
+
+---
+
+## `AGENT.md`
+
+The agent's system prompt. Plain Markdown, loaded and injected at the top of every conversation.
+
+### Variable substitution
+
+| Variable | Value |
+|----------|-------|
+| `$AGENT_FOLDER` | Absolute path to this agent's folder |
+| `$PROJECT_ROOT` | Absolute path to the workspace root |
+
+### Tips
+
+- Keep it focused — describe the agent's role, constraints, and tool usage style.
+- Avoid putting volatile data (dates, paths) directly — use variables.
+- For long instructions, split between `AGENT.md` (capabilities) and `SOUL.md` (identity/tone).
+
+Example:
+```markdown
+You are Coder, a focused code analysis agent operating in $PROJECT_ROOT.
+
+You specialise in:
+- Reading and understanding source files
+- Identifying patterns, bugs, and improvements
+- Answering questions about code structure
+
+Rules:
+- Never write or modify files unless explicitly asked
+- Always cite the file path and line number when referencing code
+- Keep responses concise and technical
+```
+
+---
+
+## `SOUL.md`
+
+Optional. Same format as `AGENT.md`. Appended to the system prompt after `AGENT.md`. Useful for separating stable capabilities from swappable persona/tone.
+
+---
+
+## Complete Example
+
+`.khabot/agents/assistant/agent.json`:
+```json
+{
+  "name": "assistant",
+  "description": "General-purpose agent with file and shell access",
+  "model": "moonshotai/kimi-k2.5",
+  "temperature": 0.7,
+  "reasoning": "medium",
+  "memory": { "enabled": false },
+  "skillDiscovery": false,
+  "modes": {
+    "chat": {
+      "enabled": true,
+      "permissions": {
+        "allow": ["read_file", "list_dir", "bash", "grep", "glob"],
+        "deny": []
+      }
+    },
+    "task": {
+      "enabled": true,
+      "maxIterations": 20,
+      "maxDurationSeconds": 120,
+      "onExhausted": "fail",
+      "permissions": {
+        "allow": ["read_file", "list_dir", "bash", "grep", "glob", "write_file", "edit_file"],
+        "deny": []
+      }
+    }
+  }
+}
+```
+
+`.khabot/agents/assistant/AGENT.md`:
+```markdown
+You are Assistant, a capable general-purpose agent running in $PROJECT_ROOT.
+
+You can read, write, and analyse files, run shell commands, and search the web.
+Always explain what you are doing and why. Be direct and concise.
+```

package/docs/guide/05-cli.md

@@ -0,0 +1,290 @@
+# CLI Reference
+
+The `khabot` command controls the server and provides utilities for managing agents and credentials.
+
+---
+
+## Installation
+
+```bash
+# From the KhaBotCli repo directory:
+npm link                   # system-wide (requires npm prefix write access)
+# or
+ln -sf "$(pwd)/cli/index.js" ~/.local/bin/khabot
+chmod +x cli/index.js
+```
+
+Verify:
+```bash
+khabot --version
+# KhaBotCLI v0.1.0
+```
+
+---
+
+## Commands
+
+### `khabot start`
+
+Start the REST API server in the current (or specified) directory.
+
+```bash
+khabot start [--port <n>] [--folder <path>] [--secret <token>] [--ably]
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--port` | `5050` (or from settings.json) | Port to listen on |
+| `--folder` | current directory | Workspace directory (must contain `.khabot/`) |
+| `--secret` | none | Require `X-KhaBot-Secret: <token>` on all API requests |
+| `--ably` | false | Enable Ably remote access |
+
+**What happens on start:**
+1. Loads settings from all layers (global → project → local → CLI flags)
+2. Runs SQLite startup recovery (marks stale processing tasks as failed)
+3. Starts the daemon scheduler
+4. Auto-starts any daemon agents with a `cron` field configured
+5. Starts the Express HTTP server
+6. Writes `.khabot/runtime.pid`
+
+The process stays in the foreground. Use SIGINT (Ctrl+C) or `khabot stop` to shut down gracefully.
+
+**Examples:**
+```bash
+khabot start
+khabot start --port 5051 --folder ~/projects/my-bot
+khabot start --secret supersecret123
+```
+
+---
+
+### `khabot run`
+
+Run a one-shot task and print the result to stdout. The process exits when the task completes. Useful for scripting and automation.
+
+```bash
+khabot run --agent <name> --input "<text>" [--timeout <seconds>]
+```
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--agent` | ✓ | Agent name |
+| `--input` | ✓ | Task input text |
+| `--timeout` | | Override `maxDurationSeconds` for this run |
+
+**Output** (JSON to stdout):
+```json
+{
+  "taskId": "task_c0ab38d8377cdd47",
+  "status": "finished",
+  "output": "The project has 5 dependencies: ..."
+}
+```
+
+On failure, exits with code 1 and prints the error to stderr.
+
+**Examples:**
+```bash
+khabot run --agent hello --input "What is 2 + 2?"
+khabot run --agent coder --input "Summarise the main functions in src/index.js" --timeout 60
+```
+
+---
+
+### `khabot stop`
+
+Send SIGTERM to the running server. The server will clean up and exit gracefully.
+
+```bash
+khabot stop
+```
+
+Reads `.khabot/runtime.pid` to find the process. Must be run from the same workspace directory as `khabot start`.
+
+---
+
+### `khabot status`
+
+Check whether the server is running.
+
+```bash
+khabot status
+```
+
+Reads `.khabot/runtime.pid` and checks if the process exists.
+
+Output examples:
+```
+✓ Server is running (PID: 12345)
+! PID file exists but process 12345 is not running (stale PID file)
+! No running server (no PID file found)
+```
+
+---
+
+### `khabot agents`
+
+Manage agents in the current workspace.
+
+#### `khabot agents list`
+
+List all agents:
+```bash
+khabot agents list
+# or
+khabot agents
+```
+
+Output (table):
+```
+Agents (3)
+name         description                    model                    source
+hello        A simple conversational agent  moonshotai/kimi-k2.5     project
+assistant    General-purpose agent          moonshotai/kimi-k2.5     project
+coder        Code analysis agent            moonshotai/kimi-k2.5     project
+```
+
+#### `khabot agents inspect <name>`
+
+Show full details for a single agent including modes and the first 500 chars of `AGENT.md`:
+
+```bash
+khabot agents inspect assistant
+```
+
+#### `khabot agents create`
+
+Interactive agent creation wizard. Currently shows instructions to create manually.
+
+---
+
+### `khabot login`
+
+Save an API key to `auth.json`.
+
+```bash
+khabot login --key <api-key> [--global]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--key` | API key to save (required) |
+| `--global` | Save to `~/.khabot/auth.json` instead of `.khabot/auth.json` |
+
+After login, manually edit `auth.json` to set the `model` field.
+
+**Examples:**
+```bash
+khabot login --key sk-or-v1-...          # project-level
+khabot login --key sk-or-v1-... --global # global (shared across workspaces)
+```
+
+---
+
+### `khabot import`
+
+Import agents from other formats (Claude Code, raw JSON). Not yet fully implemented — shows the source path for manual processing.
+
+```bash
+khabot import --type <type> --source <path>
+```
+
+---
+
+## Global Flags
+
+| Flag | Description |
+|------|-------------|
+| `--help`, `-h` | Show usage |
+| `--version` | Show KhaBotCLI version |
+
+---
+
+## Interactive TUI Client
+
+The `connect.js` client in `KhaBotCli_TESTS/cli-app/` is a separate interactive tool for exploring and testing a running server.
+
+### Usage
+
+```bash
+# Open interactive menu (arrow keys or number keys)
+node connect.js
+
+# Jump straight to a chat REPL
+node connect.js chat <agent>
+
+# One-shot chat (print and exit)
+node connect.js chat <agent> "Your message here"
+
+# Run a task (live tool display)
+node connect.js task <agent> "Your task instructions"
+
+# Print tables and exit
+node connect.js status
+node connect.js agents
+node connect.js sessions
+node connect.js tasks
+
+# Custom server URL
+node connect.js --url http://localhost:5051 chat simple
+```
+
+### Interactive menu
+
+When run with no arguments, shows a full-screen menu:
+
+```
+┌──────────────────────────────────────────┐
+│  KhaBotCLI Connect  http://localhost:5051│
+├──────────────────────────────────────────┤
+│  Main Menu  http://localhost:5051        │
+├──────────────────────────────────────────┤
+│                                          │
+│  ❯ 1. 💬  Chat         Interactive …    │
+│    2. ⚡  Run a Task   Task with tools…  │
+│    3. 🤖  Agents       List available …  │
+│    4. 📋  Sessions     Recent chat …     │
+│    5. 📊  Tasks        Task history      │
+│    6. ℹ️   Status       Server info       │
+│    7. ✕   Quit                           │
+│                                          │
+├──────────────────────────────────────────┤
+│  [↑↓ / number] move  [Enter] select  …  │
+└──────────────────────────────────────────┘
+```
+
+**Navigation**: arrow keys or type the number, Enter to select, q to go back.
+
+### Chat REPL commands
+
+Inside the chat interface:
+
+| Command | Action |
+|---------|--------|
+| `/new` | Start a new session (clear history) |
+| `/clear` | Clear the display |
+| `/session` | Show current session ID |
+| `/back` or Ctrl+C | Return to menu |
+
+### Task runner — live tool display
+
+When running a task, tools are displayed as they execute:
+
+```
+│  Task ID: task_c0ab38d8377cdd47
+│──────────────────────────────────│
+│  🔧 list_dir  /tmp
+│     ✓ 75ms  .ICE-unix/ .X11-unix/…
+│  🔧 bash  ls -1 /tmp | wc -l
+│     ✓ 69ms  306
+│──────────────────────────────────│
+│  ✓ Done  — 3 iterations  tokens in:21918 out:394
+│  There are 306 files in /tmp.
+```
+
+### Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `KHABOT_URL` | Server URL (default: `http://localhost:5051`) |
+| `KHABOT_SECRET` | Auth secret header value |