@openacp/cli 0.5.2 → 0.6.0

package/dist/chunk-5NBWM7P6.js

@@ -0,0 +1,438 @@
+// src/core/channel.ts
+var ChannelAdapter = class {
+  constructor(core, config) {
+    this.core = core;
+    this.config = config;
+  }
+  async deleteSessionThread(_sessionId) {
+  }
+  // Skill commands — override in adapters that support dynamic commands
+  async sendSkillCommands(_sessionId, _commands) {
+  }
+  async cleanupSkillCommands(_sessionId) {
+  }
+};
+
+// src/product-guide.ts
+var PRODUCT_GUIDE = `
+# OpenACP \u2014 Product Guide
+
+OpenACP lets you chat with AI coding agents (like Claude Code) through messaging platforms (Telegram, Discord).
+You type messages in your chat platform, the agent reads/writes/runs code in your project folder, and results stream back in real time.
+
+---
+
+## Quick Start
+
+1. Start OpenACP: \`openacp\` (or \`openacp start\` for background daemon)
+2. Open your messaging platform (Telegram group or Discord server) \u2014 you'll see the Assistant topic/thread
+3. Tap/click \u{1F195} New Session or type /new
+4. Pick an agent and a project folder
+5. Chat in the session topic/thread \u2014 the agent works on your code
+
+---
+
+## Core Concepts
+
+### Sessions
+A session = one conversation with one AI agent working in one project folder.
+Each session gets its own topic (Telegram) or forum thread (Discord). Chat there to give instructions to the agent.
+
+### Agents
+An agent is an AI coding tool (e.g., Claude Code, Gemini, Cursor, Codex, etc.).
+OpenACP supports 28+ agents from the official ACP Registry (agentclientprotocol.com).
+You can install multiple agents and choose which one to use per session.
+The default agent is used when you don't specify one.
+
+### Agent Management
+- Browse agents: \`/agents\` in your chat platform or \`openacp agents\` in CLI
+- Install: tap the install button in /agents, or \`openacp agents install <name>\`
+- Uninstall: \`openacp agents uninstall <name>\`
+- Setup/login: \`openacp agents run <name> -- <args>\` (e.g., \`openacp agents run gemini -- auth login\`)
+- Details: \`openacp agents info <name>\` shows version, dependencies, and setup steps
+
+Some agents need additional setup before they can be used:
+- Claude: requires \`claude login\`
+- Gemini: requires \`openacp agents run gemini -- auth login\`
+- Codex: requires setting \`OPENAI_API_KEY\` environment variable
+- GitHub Copilot: requires \`openacp agents run copilot -- auth login\`
+
+Agents are installed in three ways depending on the agent:
+- **npx** \u2014 Node.js agents, downloaded automatically on first use
+- **uvx** \u2014 Python agents, downloaded automatically on first use
+- **binary** \u2014 Platform-specific binaries, downloaded to \`~/.openacp/agents/\`
+
+### Project Folder (Workspace)
+The directory where the agent reads, writes, and runs code.
+When creating a session, you choose which folder the agent works in.
+You can type a full path like \`~/code/my-project\` or just a name like \`my-project\` (it becomes \`<base-dir>/my-project\`).
+
+### System Topics
+- **Assistant** \u2014 Always-on helper that can answer questions, create sessions, check status, troubleshoot
+- **Notifications** \u2014 System alerts (permission requests, session errors, completions)
+
+---
+
+## Creating Sessions
+
+### From menu
+Tap \u{1F195} New Session \u2192 choose agent (if multiple) \u2192 choose project folder \u2192 confirm
+
+### From command
+- \`/new\` \u2014 Interactive flow (asks agent + folder)
+- \`/new claude ~/code/my-project\` \u2014 Create directly with specific agent and folder
+
+### From Assistant topic
+Just ask: "Create a session for my-project with claude" \u2014 the assistant handles it
+
+### Quick new chat
+\`/newchat\` in a session topic \u2014 creates new session with same agent and folder as current one
+
+---
+
+## Working with Sessions
+
+### Chat
+Type messages in the session topic. The agent responds with code changes, explanations, tool outputs.
+
+### What you see while the agent works
+- **\u{1F4AD} Thinking indicator** \u2014 Shows when the agent is reasoning, with elapsed time
+- **Text responses** \u2014 Streamed in real time, updated every few seconds
+- **Tool calls** \u2014 When the agent runs commands or edits files, you see tool name, input, status, and output
+- **\u{1F4CB} Plan card** \u2014 Visual task progress with completed/in-progress/pending items and progress bar
+- **"View File" / "View Diff" buttons** \u2014 Opens in browser with Monaco editor (requires tunnel)
+
+### Session lifecycle
+1. **Creating** \u2014 Topic created, agent spawning
+2. **Warming up** \u2014 Agent primes its cache (happens automatically, invisible to you)
+3. **Active** \u2014 Ready for your messages
+4. **Auto-naming** \u2014 After your first message, the session gets a descriptive name (agent summarizes in ~5 words). The topic title updates automatically.
+5. **Finished/Error** \u2014 Session completed or hit an error
+
+### Agent skills
+Some agents provide slash commands (e.g., /compact, /review). Available skills are pinned in the session topic.
+
+### Permission requests
+When the agent wants to run a command, it asks for permission.
+You see buttons: \u2705 Allow, \u274C Reject (and sometimes "Always Allow").
+A notification also appears in the Notifications topic with a link to the request.
+
+### Dangerous mode
+Auto-approves ALL permission requests \u2014 the agent runs any command without asking.
+- Enable: \`/enable_dangerous\` or tap the \u2620\uFE0F button in the session
+- Disable: \`/disable_dangerous\` or tap the \u{1F510} button
+- \u26A0\uFE0F Use with caution \u2014 the agent can execute anything
+
+### Session timeout
+Idle sessions are automatically cancelled after a configurable timeout (default: 60 minutes).
+Configure via \`security.sessionTimeoutMinutes\` in config.
+
+---
+
+## Session Transfer (Handoff)
+
+### Chat \u2192 Terminal
+1. Type \`/handoff\` in a session topic/thread
+2. You get a command like \`claude --resume <SESSION_ID>\`
+3. Copy and run it in your terminal \u2014 the session continues there with full conversation history
+
+### Terminal \u2192 Chat
+1. First time: run \`openacp integrate claude\` to install the handoff skill (one-time setup)
+2. In Claude Code, use the /openacp:handoff slash command
+3. The session appears as a new topic/thread and you can continue chatting there
+
+### How it works
+- The agent session ID is shared between platforms
+- Conversation history is preserved \u2014 pick up where you left off
+- The agent that supports resume (e.g., Claude with \`--resume\`) handles the actual transfer
+
+---
+
+## Managing Sessions
+
+### Status
+- \`/status\` \u2014 Shows active sessions count and details
+- Ask the Assistant: "What sessions are running?"
+
+### List all sessions
+- \`/sessions\` \u2014 Shows all sessions with status (active, finished, error)
+
+### Cancel
+- \`/cancel\` in a session topic \u2014 cancels that session
+- Ask the Assistant: "Cancel the stuck session"
+
+### Cleanup
+- From \`/sessions\` \u2192 tap cleanup buttons (finished, errors, all)
+- Ask the Assistant: "Clean up old sessions"
+
+---
+
+## Assistant Topic
+
+The Assistant is an always-on AI helper in its own topic. It can:
+- Answer questions about OpenACP
+- Create sessions for you
+- Check status and health
+- Cancel sessions
+- Clean up old sessions
+- Troubleshoot issues
+- Manage configuration
+
+Just chat naturally: "How do I create a session?", "What's the status?", "Something is stuck"
+
+### Clear history
+\`/clear\` in the Assistant topic \u2014 resets the conversation
+
+---
+
+## System Commands
+
+| Command | Where | What it does |
+|---------|-------|-------------|
+| \`/new [agent] [path]\` | Anywhere | Create new session |
+| \`/newchat\` | Session topic | New session, same agent + folder |
+| \`/cancel\` | Session topic | Cancel current session |
+| \`/status\` | Anywhere | Show status |
+| \`/sessions\` | Anywhere | List all sessions |
+| \`/agents\` | Anywhere | Browse & install agents from ACP Registry |
+| \`/install <name>\` | Anywhere | Install an agent |
+| \`/enable_dangerous\` | Session topic | Auto-approve all permissions |
+| \`/disable_dangerous\` | Session topic | Restore permission prompts |
+| \`/handoff\` | Session topic | Transfer session to terminal |
+| \`/clear\` | Assistant topic | Clear assistant history |
+| \`/menu\` | Anywhere | Show action menu |
+| \`/help\` | Anywhere | Show help |
+| \`/restart\` | Anywhere | Restart OpenACP |
+| \`/update\` | Anywhere | Update to latest version |
+| \`/integrate\` | Anywhere | Manage agent integrations |
+
+---
+
+## Menu Buttons
+
+| Button | Action |
+|--------|--------|
+| \u{1F195} New Session | Create new session (interactive) |
+| \u{1F4CB} Sessions | List all sessions with cleanup options |
+| \u{1F4CA} Status | Show active/total session count |
+| \u{1F916} Agents | List available agents |
+| \u{1F517} Integrate | Manage agent integrations |
+| \u2753 Help | Show help text |
+| \u{1F504} Restart | Restart OpenACP |
+| \u2B06\uFE0F Update | Check and install updates |
+
+---
+
+## CLI Commands
+
+### Server
+- \`openacp\` \u2014 Start (uses configured mode: foreground or daemon)
+- \`openacp start\` \u2014 Start as background daemon
+- \`openacp stop\` \u2014 Stop daemon
+- \`openacp status\` \u2014 Show daemon status
+- \`openacp logs\` \u2014 Tail daemon logs
+- \`openacp --foreground\` \u2014 Force foreground mode (useful for debugging or containers)
+
+### Auto-start (run on boot)
+- macOS: installs a LaunchAgent in \`~/Library/LaunchAgents/\`
+- Linux: installs a systemd user service in \`~/.config/systemd/user/\`
+- Enabled automatically when you start the daemon. Remove with \`openacp stop\`.
+
+### Configuration
+- \`openacp config\` \u2014 Interactive config editor
+- \`openacp reset\` \u2014 Delete all data and start fresh
+
+### Agent Management (CLI)
+- \`openacp agents\` \u2014 List all agents (installed + available from ACP Registry)
+- \`openacp agents install <name>\` \u2014 Install an agent
+- \`openacp agents uninstall <name>\` \u2014 Remove an agent
+- \`openacp agents info <name>\` \u2014 Show details, dependencies, and setup guide
+- \`openacp agents run <name> [-- args]\` \u2014 Run agent CLI directly (for login, config, etc.)
+- \`openacp agents refresh\` \u2014 Force-refresh registry cache
+
+### Plugins
+- \`openacp install <package>\` \u2014 Install adapter plugin
+- \`openacp uninstall <package>\` \u2014 Remove adapter plugin
+- \`openacp plugins\` \u2014 List installed plugins
+
+### Integration
+- \`openacp integrate <agent>\` \u2014 Install agent integration (e.g., Claude handoff skill)
+- \`openacp integrate <agent> --uninstall\` \u2014 Remove integration
+
+### API (requires running daemon)
+\`openacp api <command>\` \u2014 Interact with running daemon:
+
+| Command | Description |
+|---------|-------------|
+| \`status\` | List active sessions |
+| \`session <id>\` | Session details |
+| \`new <agent> <path>\` | Create session |
+| \`send <id> "text"\` | Send prompt |
+| \`cancel <id>\` | Cancel session |
+| \`dangerous <id> on/off\` | Toggle dangerous mode |
+| \`topics [--status x,y]\` | List topics |
+| \`delete-topic <id> [--force]\` | Delete topic |
+| \`cleanup [--status x,y]\` | Cleanup old topics |
+| \`agents\` | List agents |
+| \`health\` | System health |
+| \`config\` | Show config |
+| \`config set <key> <value>\` | Update config |
+| \`adapters\` | List adapters |
+| \`tunnel\` | Tunnel status |
+| \`notify "message"\` | Send notification |
+| \`version\` | Daemon version |
+| \`restart\` | Restart daemon |
+
+---
+
+## File Viewer (Tunnel)
+
+When tunnel is enabled, file edits and diffs get "View" buttons that open in your browser:
+- **Monaco Editor** \u2014 Full VS Code editor with syntax highlighting
+- **Diff viewer** \u2014 Side-by-side or inline comparison
+- **Line highlighting** \u2014 Click lines to highlight
+- Dark/light theme toggle
+
+### Setup
+Enable in config: set \`tunnel.enabled\` to \`true\`.
+Providers: Cloudflare (default, free), ngrok, bore, Tailscale Funnel.
+
+### Port Tunneling
+
+Expose any local port (dev servers, APIs, etc.) to the internet:
+
+**CLI commands** (agent can call these directly):
+- \`openacp tunnel add <port> --label <name>\` \u2014 Create tunnel to a local port
+- \`openacp tunnel list\` \u2014 List active tunnels
+- \`openacp tunnel stop <port>\` \u2014 Stop a tunnel
+- \`openacp tunnel stop-all\` \u2014 Stop all user tunnels
+
+**Telegram commands**:
+- \`/tunnel <port> [label]\` \u2014 Create tunnel
+- \`/tunnels\` \u2014 List active tunnels
+- \`/tunnel stop <port>\` \u2014 Stop tunnel
+
+Example: after starting a dev server on port 3000, run \`openacp tunnel add 3000 --label my-app\` to get a public URL.
+
+---
+
+## Configuration
+
+Config file: \`~/.openacp/config.json\`
+
+### Channels
+- **channels.telegram.botToken** \u2014 Your Telegram bot token
+- **channels.telegram.chatId** \u2014 Your Telegram supergroup ID
+- **channels.discord.botToken** \u2014 Your Discord bot token
+- **channels.discord.guildId** \u2014 Your Discord server (guild) ID
+
+### Agents
+- **defaultAgent** \u2014 Which agent to use by default
+- Agents are managed via \`/agents\` (Telegram) or \`openacp agents\` (CLI)
+- Installed agents are stored in \`~/.openacp/agents.json\`
+- Agent list is fetched from the ACP Registry CDN and cached locally (24h)
+
+### Workspace
+- **workspace.baseDir** \u2014 Base directory for project folders (default: \`~/openacp-workspace\`)
+
+### Security
+- **security.allowedUserIds** \u2014 Restrict who can use the bot (empty = everyone)
+- **security.maxConcurrentSessions** \u2014 Max parallel sessions (default: 5)
+- **security.sessionTimeoutMinutes** \u2014 Auto-cancel idle sessions (default: 60)
+
+### Tunnel / File Viewer
+- **tunnel.enabled** \u2014 Enable file viewer tunnel
+- **tunnel.provider** \u2014 Tunnel provider: cloudflare (default, free), ngrok, bore, tailscale
+- **tunnel.port** \u2014 Local port for tunnel server (default: 3100)
+- **tunnel.auth.enabled** \u2014 Enable authentication for tunnel URLs
+- **tunnel.auth.token** \u2014 Auth token for tunnel access
+- **tunnel.storeTtlMinutes** \u2014 How long viewer links stay cached (default: 60)
+
+### Logging
+- **logging.level** \u2014 Log level: silent, debug, info, warn, error, fatal (default: info)
+- **logging.logDir** \u2014 Log directory (default: \`~/.openacp/logs\`)
+- **logging.maxFileSize** \u2014 Max log file size before rotation
+- **logging.maxFiles** \u2014 Max number of rotated log files
+- **logging.sessionLogRetentionDays** \u2014 Auto-delete old session logs (default: 30)
+
+### Data Retention
+- **sessionStore.ttlDays** \u2014 How long session records persist (default: 30). Old records are cleaned up automatically.
+
+### Environment variables
+Override config with env vars:
+- \`OPENACP_TELEGRAM_BOT_TOKEN\`
+- \`OPENACP_TELEGRAM_CHAT_ID\`
+- \`OPENACP_DISCORD_BOT_TOKEN\`
+- \`OPENACP_DISCORD_GUILD_ID\`
+- \`OPENACP_DEFAULT_AGENT\`
+- \`OPENACP_RUN_MODE\` \u2014 foreground or daemon
+- \`OPENACP_API_PORT\` \u2014 API server port (default: 21420)
+- \`OPENACP_TUNNEL_ENABLED\`
+- \`OPENACP_TUNNEL_PORT\`
+- \`OPENACP_TUNNEL_PROVIDER\`
+- \`OPENACP_LOG_LEVEL\`
+- \`OPENACP_LOG_DIR\`
+- \`OPENACP_DEBUG\` \u2014 Sets log level to debug
+
+---
+
+## Troubleshooting
+
+### Session stuck / not responding
+- Check status: ask Assistant "Is anything stuck?"
+- Cancel and create new: \`/cancel\` then \`/new\`
+- Check system health: Assistant can run health check
+
+### Agent not found
+- Check available agents: \`/agents\` or \`openacp agents\`
+- Install missing agent: \`openacp agents install <name>\`
+- Some agents need login first: \`openacp agents info <name>\` to see setup steps
+- Run agent CLI for setup: \`openacp agents run <name> -- <args>\`
+
+### Permission request not showing
+- Check Notifications topic for the alert
+- Try \`/enable_dangerous\` to auto-approve (if you trust the agent)
+
+### Session disappeared after restart
+- Sessions persist across restarts
+- Send a message in the old topic \u2014 it auto-resumes
+- If topic was deleted, the session record may still exist in status
+
+### Bot not responding at all
+- Check daemon: \`openacp status\`
+- Check logs: \`openacp logs\`
+- Restart: \`openacp start\` or \`/restart\`
+
+### Messages going to wrong topic
+- Each session is bound to a specific topic/thread
+- If you see messages appearing in the Assistant topic instead of the session topic, try creating a new session
+
+### Viewing logs
+- Session-specific logs: \`~/.openacp/logs/sessions/\`
+- System logs: \`openacp logs\` to tail live
+- Set \`OPENACP_DEBUG=true\` for verbose output
+
+---
+
+## Data & Storage
+
+All data is stored in \`~/.openacp/\`:
+- \`config.json\` \u2014 Configuration
+- \`agents.json\` \u2014 Installed agents (managed by AgentCatalog)
+- \`registry-cache.json\` \u2014 Cached ACP Registry data (refreshes every 24h)
+- \`agents/\` \u2014 Downloaded binary agents
+- \`sessions/\` \u2014 Session records and state
+- \`topics/\` \u2014 Topic-to-session mappings
+- \`logs/\` \u2014 System and session logs
+- \`plugins/\` \u2014 Installed adapter plugins
+- \`openacp.pid\` \u2014 Daemon PID file
+
+Session records auto-cleanup: 30 days (configurable via \`sessionStore.ttlDays\`).
+Session logs auto-cleanup: 30 days (configurable via \`logging.sessionLogRetentionDays\`).
+`;
+
+export {
+  ChannelAdapter,
+  PRODUCT_GUIDE
+};
+//# sourceMappingURL=chunk-5NBWM7P6.js.map

package/dist/chunk-5NBWM7P6.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/core/channel.ts","../../src/product-guide.ts"],"sourcesContent":["import type { OutgoingMessage, PermissionRequest, NotificationMessage, AgentCommand } from './types.js'\n\nexport interface ChannelConfig {\n  enabled: boolean\n  [key: string]: unknown\n}\n\nexport interface IChannelAdapter {\n  start(): Promise<void>\n  stop(): Promise<void>\n\n  // Outgoing: core → channel\n  sendMessage(sessionId: string, content: OutgoingMessage): Promise<void>\n  sendPermissionRequest(sessionId: string, request: PermissionRequest): Promise<void>\n  sendNotification(notification: NotificationMessage): Promise<void>\n\n  // Session lifecycle on channel side\n  createSessionThread(sessionId: string, name: string): Promise<string>  // returns threadId\n  renameSessionThread(sessionId: string, newName: string): Promise<void>\n  deleteSessionThread(sessionId: string): Promise<void>\n\n  // Skill commands — optional\n  sendSkillCommands(sessionId: string, commands: AgentCommand[]): Promise<void>\n  cleanupSkillCommands(sessionId: string): Promise<void>\n}\n\n/**\n * Base class providing default no-op implementations for optional methods.\n * Adapters can extend this or implement IChannelAdapter directly.\n */\nexport abstract class ChannelAdapter<TCore = unknown> implements IChannelAdapter {\n  constructor(protected core: TCore, protected config: ChannelConfig) {}\n\n  abstract start(): Promise<void>\n  abstract stop(): Promise<void>\n\n  // Outgoing: core → channel\n  abstract sendMessage(sessionId: string, content: OutgoingMessage): Promise<void>\n  abstract sendPermissionRequest(sessionId: string, request: PermissionRequest): Promise<void>\n  abstract sendNotification(notification: NotificationMessage): Promise<void>\n\n  // Session lifecycle on channel side\n  abstract createSessionThread(sessionId: string, name: string): Promise<string>  // returns threadId\n  abstract renameSessionThread(sessionId: string, newName: string): Promise<void>\n  async deleteSessionThread(_sessionId: string): Promise<void> {}\n\n  // Skill commands — override in adapters that support dynamic commands\n  async sendSkillCommands(_sessionId: string, _commands: AgentCommand[]): Promise<void> {}\n  async cleanupSkillCommands(_sessionId: string): Promise<void> {}\n}\n","/**\n * OpenACP Product Guide — comprehensive reference for the AI assistant.\n * The assistant reads this at runtime to answer user questions about features.\n */\nexport const PRODUCT_GUIDE = `\n# OpenACP — Product Guide\n\nOpenACP lets you chat with AI coding agents (like Claude Code) through messaging platforms (Telegram, Discord).\nYou type messages in your chat platform, the agent reads/writes/runs code in your project folder, and results stream back in real time.\n\n---\n\n## Quick Start\n\n1. Start OpenACP: \\`openacp\\` (or \\`openacp start\\` for background daemon)\n2. Open your messaging platform (Telegram group or Discord server) — you'll see the Assistant topic/thread\n3. Tap/click 🆕 New Session or type /new\n4. Pick an agent and a project folder\n5. Chat in the session topic/thread — the agent works on your code\n\n---\n\n## Core Concepts\n\n### Sessions\nA session = one conversation with one AI agent working in one project folder.\nEach session gets its own topic (Telegram) or forum thread (Discord). Chat there to give instructions to the agent.\n\n### Agents\nAn agent is an AI coding tool (e.g., Claude Code, Gemini, Cursor, Codex, etc.).\nOpenACP supports 28+ agents from the official ACP Registry (agentclientprotocol.com).\nYou can install multiple agents and choose which one to use per session.\nThe default agent is used when you don't specify one.\n\n### Agent Management\n- Browse agents: \\`/agents\\` in your chat platform or \\`openacp agents\\` in CLI\n- Install: tap the install button in /agents, or \\`openacp agents install <name>\\`\n- Uninstall: \\`openacp agents uninstall <name>\\`\n- Setup/login: \\`openacp agents run <name> -- <args>\\` (e.g., \\`openacp agents run gemini -- auth login\\`)\n- Details: \\`openacp agents info <name>\\` shows version, dependencies, and setup steps\n\nSome agents need additional setup before they can be used:\n- Claude: requires \\`claude login\\`\n- Gemini: requires \\`openacp agents run gemini -- auth login\\`\n- Codex: requires setting \\`OPENAI_API_KEY\\` environment variable\n- GitHub Copilot: requires \\`openacp agents run copilot -- auth login\\`\n\nAgents are installed in three ways depending on the agent:\n- **npx** — Node.js agents, downloaded automatically on first use\n- **uvx** — Python agents, downloaded automatically on first use\n- **binary** — Platform-specific binaries, downloaded to \\`~/.openacp/agents/\\`\n\n### Project Folder (Workspace)\nThe directory where the agent reads, writes, and runs code.\nWhen creating a session, you choose which folder the agent works in.\nYou can type a full path like \\`~/code/my-project\\` or just a name like \\`my-project\\` (it becomes \\`<base-dir>/my-project\\`).\n\n### System Topics\n- **Assistant** — Always-on helper that can answer questions, create sessions, check status, troubleshoot\n- **Notifications** — System alerts (permission requests, session errors, completions)\n\n---\n\n## Creating Sessions\n\n### From menu\nTap 🆕 New Session → choose agent (if multiple) → choose project folder → confirm\n\n### From command\n- \\`/new\\` — Interactive flow (asks agent + folder)\n- \\`/new claude ~/code/my-project\\` — Create directly with specific agent and folder\n\n### From Assistant topic\nJust ask: \"Create a session for my-project with claude\" — the assistant handles it\n\n### Quick new chat\n\\`/newchat\\` in a session topic — creates new session with same agent and folder as current one\n\n---\n\n## Working with Sessions\n\n### Chat\nType messages in the session topic. The agent responds with code changes, explanations, tool outputs.\n\n### What you see while the agent works\n- **💭 Thinking indicator** — Shows when the agent is reasoning, with elapsed time\n- **Text responses** — Streamed in real time, updated every few seconds\n- **Tool calls** — When the agent runs commands or edits files, you see tool name, input, status, and output\n- **📋 Plan card** — Visual task progress with completed/in-progress/pending items and progress bar\n- **\"View File\" / \"View Diff\" buttons** — Opens in browser with Monaco editor (requires tunnel)\n\n### Session lifecycle\n1. **Creating** — Topic created, agent spawning\n2. **Warming up** — Agent primes its cache (happens automatically, invisible to you)\n3. **Active** — Ready for your messages\n4. **Auto-naming** — After your first message, the session gets a descriptive name (agent summarizes in ~5 words). The topic title updates automatically.\n5. **Finished/Error** — Session completed or hit an error\n\n### Agent skills\nSome agents provide slash commands (e.g., /compact, /review). Available skills are pinned in the session topic.\n\n### Permission requests\nWhen the agent wants to run a command, it asks for permission.\nYou see buttons: ✅ Allow, ❌ Reject (and sometimes \"Always Allow\").\nA notification also appears in the Notifications topic with a link to the request.\n\n### Dangerous mode\nAuto-approves ALL permission requests — the agent runs any command without asking.\n- Enable: \\`/enable_dangerous\\` or tap the ☠️ button in the session\n- Disable: \\`/disable_dangerous\\` or tap the 🔐 button\n- ⚠️ Use with caution — the agent can execute anything\n\n### Session timeout\nIdle sessions are automatically cancelled after a configurable timeout (default: 60 minutes).\nConfigure via \\`security.sessionTimeoutMinutes\\` in config.\n\n---\n\n## Session Transfer (Handoff)\n\n### Chat → Terminal\n1. Type \\`/handoff\\` in a session topic/thread\n2. You get a command like \\`claude --resume <SESSION_ID>\\`\n3. Copy and run it in your terminal — the session continues there with full conversation history\n\n### Terminal → Chat\n1. First time: run \\`openacp integrate claude\\` to install the handoff skill (one-time setup)\n2. In Claude Code, use the /openacp:handoff slash command\n3. The session appears as a new topic/thread and you can continue chatting there\n\n### How it works\n- The agent session ID is shared between platforms\n- Conversation history is preserved — pick up where you left off\n- The agent that supports resume (e.g., Claude with \\`--resume\\`) handles the actual transfer\n\n---\n\n## Managing Sessions\n\n### Status\n- \\`/status\\` — Shows active sessions count and details\n- Ask the Assistant: \"What sessions are running?\"\n\n### List all sessions\n- \\`/sessions\\` — Shows all sessions with status (active, finished, error)\n\n### Cancel\n- \\`/cancel\\` in a session topic — cancels that session\n- Ask the Assistant: \"Cancel the stuck session\"\n\n### Cleanup\n- From \\`/sessions\\` → tap cleanup buttons (finished, errors, all)\n- Ask the Assistant: \"Clean up old sessions\"\n\n---\n\n## Assistant Topic\n\nThe Assistant is an always-on AI helper in its own topic. It can:\n- Answer questions about OpenACP\n- Create sessions for you\n- Check status and health\n- Cancel sessions\n- Clean up old sessions\n- Troubleshoot issues\n- Manage configuration\n\nJust chat naturally: \"How do I create a session?\", \"What's the status?\", \"Something is stuck\"\n\n### Clear history\n\\`/clear\\` in the Assistant topic — resets the conversation\n\n---\n\n## System Commands\n\n| Command | Where | What it does |\n|---------|-------|-------------|\n| \\`/new [agent] [path]\\` | Anywhere | Create new session |\n| \\`/newchat\\` | Session topic | New session, same agent + folder |\n| \\`/cancel\\` | Session topic | Cancel current session |\n| \\`/status\\` | Anywhere | Show status |\n| \\`/sessions\\` | Anywhere | List all sessions |\n| \\`/agents\\` | Anywhere | Browse & install agents from ACP Registry |\n| \\`/install <name>\\` | Anywhere | Install an agent |\n| \\`/enable_dangerous\\` | Session topic | Auto-approve all permissions |\n| \\`/disable_dangerous\\` | Session topic | Restore permission prompts |\n| \\`/handoff\\` | Session topic | Transfer session to terminal |\n| \\`/clear\\` | Assistant topic | Clear assistant history |\n| \\`/menu\\` | Anywhere | Show action menu |\n| \\`/help\\` | Anywhere | Show help |\n| \\`/restart\\` | Anywhere | Restart OpenACP |\n| \\`/update\\` | Anywhere | Update to latest version |\n| \\`/integrate\\` | Anywhere | Manage agent integrations |\n\n---\n\n## Menu Buttons\n\n| Button | Action |\n|--------|--------|\n| 🆕 New Session | Create new session (interactive) |\n| 📋 Sessions | List all sessions with cleanup options |\n| 📊 Status | Show active/total session count |\n| 🤖 Agents | List available agents |\n| 🔗 Integrate | Manage agent integrations |\n| ❓ Help | Show help text |\n| 🔄 Restart | Restart OpenACP |\n| ⬆️ Update | Check and install updates |\n\n---\n\n## CLI Commands\n\n### Server\n- \\`openacp\\` — Start (uses configured mode: foreground or daemon)\n- \\`openacp start\\` — Start as background daemon\n- \\`openacp stop\\` — Stop daemon\n- \\`openacp status\\` — Show daemon status\n- \\`openacp logs\\` — Tail daemon logs\n- \\`openacp --foreground\\` — Force foreground mode (useful for debugging or containers)\n\n### Auto-start (run on boot)\n- macOS: installs a LaunchAgent in \\`~/Library/LaunchAgents/\\`\n- Linux: installs a systemd user service in \\`~/.config/systemd/user/\\`\n- Enabled automatically when you start the daemon. Remove with \\`openacp stop\\`.\n\n### Configuration\n- \\`openacp config\\` — Interactive config editor\n- \\`openacp reset\\` — Delete all data and start fresh\n\n### Agent Management (CLI)\n- \\`openacp agents\\` — List all agents (installed + available from ACP Registry)\n- \\`openacp agents install <name>\\` — Install an agent\n- \\`openacp agents uninstall <name>\\` — Remove an agent\n- \\`openacp agents info <name>\\` — Show details, dependencies, and setup guide\n- \\`openacp agents run <name> [-- args]\\` — Run agent CLI directly (for login, config, etc.)\n- \\`openacp agents refresh\\` — Force-refresh registry cache\n\n### Plugins\n- \\`openacp install <package>\\` — Install adapter plugin\n- \\`openacp uninstall <package>\\` — Remove adapter plugin\n- \\`openacp plugins\\` — List installed plugins\n\n### Integration\n- \\`openacp integrate <agent>\\` — Install agent integration (e.g., Claude handoff skill)\n- \\`openacp integrate <agent> --uninstall\\` — Remove integration\n\n### API (requires running daemon)\n\\`openacp api <command>\\` — Interact with running daemon:\n\n| Command | Description |\n|---------|-------------|\n| \\`status\\` | List active sessions |\n| \\`session <id>\\` | Session details |\n| \\`new <agent> <path>\\` | Create session |\n| \\`send <id> \"text\"\\` | Send prompt |\n| \\`cancel <id>\\` | Cancel session |\n| \\`dangerous <id> on/off\\` | Toggle dangerous mode |\n| \\`topics [--status x,y]\\` | List topics |\n| \\`delete-topic <id> [--force]\\` | Delete topic |\n| \\`cleanup [--status x,y]\\` | Cleanup old topics |\n| \\`agents\\` | List agents |\n| \\`health\\` | System health |\n| \\`config\\` | Show config |\n| \\`config set <key> <value>\\` | Update config |\n| \\`adapters\\` | List adapters |\n| \\`tunnel\\` | Tunnel status |\n| \\`notify \"message\"\\` | Send notification |\n| \\`version\\` | Daemon version |\n| \\`restart\\` | Restart daemon |\n\n---\n\n## File Viewer (Tunnel)\n\nWhen tunnel is enabled, file edits and diffs get \"View\" buttons that open in your browser:\n- **Monaco Editor** — Full VS Code editor with syntax highlighting\n- **Diff viewer** — Side-by-side or inline comparison\n- **Line highlighting** — Click lines to highlight\n- Dark/light theme toggle\n\n### Setup\nEnable in config: set \\`tunnel.enabled\\` to \\`true\\`.\nProviders: Cloudflare (default, free), ngrok, bore, Tailscale Funnel.\n\n### Port Tunneling\n\nExpose any local port (dev servers, APIs, etc.) to the internet:\n\n**CLI commands** (agent can call these directly):\n- \\`openacp tunnel add <port> --label <name>\\` — Create tunnel to a local port\n- \\`openacp tunnel list\\` — List active tunnels\n- \\`openacp tunnel stop <port>\\` — Stop a tunnel\n- \\`openacp tunnel stop-all\\` — Stop all user tunnels\n\n**Telegram commands**:\n- \\`/tunnel <port> [label]\\` — Create tunnel\n- \\`/tunnels\\` — List active tunnels\n- \\`/tunnel stop <port>\\` — Stop tunnel\n\nExample: after starting a dev server on port 3000, run \\`openacp tunnel add 3000 --label my-app\\` to get a public URL.\n\n---\n\n## Configuration\n\nConfig file: \\`~/.openacp/config.json\\`\n\n### Channels\n- **channels.telegram.botToken** — Your Telegram bot token\n- **channels.telegram.chatId** — Your Telegram supergroup ID\n- **channels.discord.botToken** — Your Discord bot token\n- **channels.discord.guildId** — Your Discord server (guild) ID\n\n### Agents\n- **defaultAgent** — Which agent to use by default\n- Agents are managed via \\`/agents\\` (Telegram) or \\`openacp agents\\` (CLI)\n- Installed agents are stored in \\`~/.openacp/agents.json\\`\n- Agent list is fetched from the ACP Registry CDN and cached locally (24h)\n\n### Workspace\n- **workspace.baseDir** — Base directory for project folders (default: \\`~/openacp-workspace\\`)\n\n### Security\n- **security.allowedUserIds** — Restrict who can use the bot (empty = everyone)\n- **security.maxConcurrentSessions** — Max parallel sessions (default: 5)\n- **security.sessionTimeoutMinutes** — Auto-cancel idle sessions (default: 60)\n\n### Tunnel / File Viewer\n- **tunnel.enabled** — Enable file viewer tunnel\n- **tunnel.provider** — Tunnel provider: cloudflare (default, free), ngrok, bore, tailscale\n- **tunnel.port** — Local port for tunnel server (default: 3100)\n- **tunnel.auth.enabled** — Enable authentication for tunnel URLs\n- **tunnel.auth.token** — Auth token for tunnel access\n- **tunnel.storeTtlMinutes** — How long viewer links stay cached (default: 60)\n\n### Logging\n- **logging.level** — Log level: silent, debug, info, warn, error, fatal (default: info)\n- **logging.logDir** — Log directory (default: \\`~/.openacp/logs\\`)\n- **logging.maxFileSize** — Max log file size before rotation\n- **logging.maxFiles** — Max number of rotated log files\n- **logging.sessionLogRetentionDays** — Auto-delete old session logs (default: 30)\n\n### Data Retention\n- **sessionStore.ttlDays** — How long session records persist (default: 30). Old records are cleaned up automatically.\n\n### Environment variables\nOverride config with env vars:\n- \\`OPENACP_TELEGRAM_BOT_TOKEN\\`\n- \\`OPENACP_TELEGRAM_CHAT_ID\\`\n- \\`OPENACP_DISCORD_BOT_TOKEN\\`\n- \\`OPENACP_DISCORD_GUILD_ID\\`\n- \\`OPENACP_DEFAULT_AGENT\\`\n- \\`OPENACP_RUN_MODE\\` — foreground or daemon\n- \\`OPENACP_API_PORT\\` — API server port (default: 21420)\n- \\`OPENACP_TUNNEL_ENABLED\\`\n- \\`OPENACP_TUNNEL_PORT\\`\n- \\`OPENACP_TUNNEL_PROVIDER\\`\n- \\`OPENACP_LOG_LEVEL\\`\n- \\`OPENACP_LOG_DIR\\`\n- \\`OPENACP_DEBUG\\` — Sets log level to debug\n\n---\n\n## Troubleshooting\n\n### Session stuck / not responding\n- Check status: ask Assistant \"Is anything stuck?\"\n- Cancel and create new: \\`/cancel\\` then \\`/new\\`\n- Check system health: Assistant can run health check\n\n### Agent not found\n- Check available agents: \\`/agents\\` or \\`openacp agents\\`\n- Install missing agent: \\`openacp agents install <name>\\`\n- Some agents need login first: \\`openacp agents info <name>\\` to see setup steps\n- Run agent CLI for setup: \\`openacp agents run <name> -- <args>\\`\n\n### Permission request not showing\n- Check Notifications topic for the alert\n- Try \\`/enable_dangerous\\` to auto-approve (if you trust the agent)\n\n### Session disappeared after restart\n- Sessions persist across restarts\n- Send a message in the old topic — it auto-resumes\n- If topic was deleted, the session record may still exist in status\n\n### Bot not responding at all\n- Check daemon: \\`openacp status\\`\n- Check logs: \\`openacp logs\\`\n- Restart: \\`openacp start\\` or \\`/restart\\`\n\n### Messages going to wrong topic\n- Each session is bound to a specific topic/thread\n- If you see messages appearing in the Assistant topic instead of the session topic, try creating a new session\n\n### Viewing logs\n- Session-specific logs: \\`~/.openacp/logs/sessions/\\`\n- System logs: \\`openacp logs\\` to tail live\n- Set \\`OPENACP_DEBUG=true\\` for verbose output\n\n---\n\n## Data & Storage\n\nAll data is stored in \\`~/.openacp/\\`:\n- \\`config.json\\` — Configuration\n- \\`agents.json\\` — Installed agents (managed by AgentCatalog)\n- \\`registry-cache.json\\` — Cached ACP Registry data (refreshes every 24h)\n- \\`agents/\\` — Downloaded binary agents\n- \\`sessions/\\` — Session records and state\n- \\`topics/\\` — Topic-to-session mappings\n- \\`logs/\\` — System and session logs\n- \\`plugins/\\` — Installed adapter plugins\n- \\`openacp.pid\\` — Daemon PID file\n\nSession records auto-cleanup: 30 days (configurable via \\`sessionStore.ttlDays\\`).\nSession logs auto-cleanup: 30 days (configurable via \\`logging.sessionLogRetentionDays\\`).\n`;\n"],"mappings":";AA8BO,IAAe,iBAAf,MAA0E;AAAA,EAC/E,YAAsB,MAAuB,QAAuB;AAA9C;AAAuB;AAAA,EAAwB;AAAA,EAarE,MAAM,oBAAoB,YAAmC;AAAA,EAAC;AAAA;AAAA,EAG9D,MAAM,kBAAkB,YAAoB,WAA0C;AAAA,EAAC;AAAA,EACvF,MAAM,qBAAqB,YAAmC;AAAA,EAAC;AACjE;;;AC7CO,IAAM,gBAAgB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;","names":[]}