honker/docs/plan.md

Honker ACP Bridge — Implementation Plan

Current State

What's implemented today:

• ✅ Initialize ACP connection to Goose (goose acp over stdio)
• ✅ Create new sessions (one per Signal contact)
• ✅ Send text prompts and collect text responses
• ✅ Interactive permission requests over Signal (numbered options)
• ✅ Signal-cli lifecycle management and socket communication

---

Phase 1: Essential — Make the Bridge Robust

1.1 Terminal Execution (Client ← Agent)

Priority: HIGH — Goose cannot function without this

Goose's primary tool is running shell commands. The ACP protocol has the agent ask the client to execute commands via create_terminal, then polls output with terminal_output and wait_for_terminal_exit.

Currently we return None for all terminal methods, which means Goose can't run any commands. We need to:

• create_terminal(command, args, cwd, env) → spawn a real subprocess, return a terminal_id
• terminal_output(terminal_id) → return accumulated stdout/stderr
• wait_for_terminal_exit(terminal_id) → await process completion, return exit code
• release_terminal(terminal_id) → clean up
• kill_terminal(terminal_id) → kill the subprocess

Implementation: a TerminalManager class that tracks running subprocesses keyed by terminal_id.

1.2 File System Operations (Client ← Agent)

Priority: HIGH — Goose cannot edit code without this

The agent asks the client to read/write files:

• read_text_file(path, line, limit) → read from the local filesystem, return content
• write_text_file(path, content) → write to the local filesystem

Currently we return None, so Goose can't read or write files. These should be straightforward to implement against the local filesystem.

We should also advertise these capabilities in ClientCapabilities during initialize:

ClientCapabilities(
    fs=FileSystemCapabilities(read_text_file=True, write_text_file=True),
    terminal=True,
)

1.3 Cancellation

Priority: MEDIUM

Allow Signal users to cancel a running prompt. The user could send a special command (e.g. /cancel) while a prompt is in progress. We'd call conn.cancel(session_id) to tell Goose to stop.

The PromptResponse.stop_reason already distinguishes cancelled from end_turn, max_tokens, refusal, and max_turn_requests — we should handle each appropriately in the reply.

1.4 Stop Reason Handling

Priority: MEDIUM

Currently we only look at the response text. We should handle all stop reasons:

• end_turn — normal completion (current behavior)
• max_tokens — context limit hit; notify user
• max_turn_requests — agent hit its turn limit; notify user
• refusal — agent refused the request; notify user
• cancelled — user cancelled; acknowledge

---

Phase 2: Enriched Feedback

2.1 Tool Call Notifications

Priority: MEDIUM

Forward tool activity as status messages so the Signal user knows what Goose is doing while working. On ToolCallStart, send a brief message like: "🔧 Running: ls -la /src"

On ToolCallProgress with status updates, optionally send progress. We need to be careful not to spam — batch or throttle these.

2.2 Agent Thoughts

Priority: LOW-MEDIUM

AgentThoughtChunk contains the agent's chain-of-thought reasoning. Could forward these optionally (config flag) as italicized or prefixed messages. Useful for debugging but noisy for everyday use.

2.3 Plan Updates

Priority: LOW-MEDIUM

AgentPlanUpdate sends a structured plan with entries (content, priority, status). Could render as a checklist:

📋 Plan:
  ✅ Read the project structure
  🔄 Implement the new feature
  ⬚ Write tests
  ⬚ Update documentation

2.4 Usage/Cost Updates

Priority: LOW

UsageUpdate reports token usage (size, used) and optional Cost (amount, currency). Could send periodic summaries or on-demand via a /usage command.

---

Phase 3: Session Management

3.1 Session Persistence (Load/Resume)

Priority: MEDIUM

Goose supports load_session and resume_session. We could persist the session_id→contact mapping in SQLite (as the README mentions) and restore sessions across honker restarts.

• load_session(cwd, session_id) — restore conversation history
• resume_session(cwd, session_id) — resume an interrupted session
• list_sessions() — list available sessions
• close_session(session_id) — explicitly end a session

User commands: /sessions, /load <id>, /new (force new session)

3.2 Session Commands

Priority: MEDIUM

Signal user sends special commands (prefix with /):

• /new — start a fresh session
• /sessions — list previous sessions
• /load <id> — resume a previous session
• /cancel — cancel current prompt
• /mode <mode> — change session mode (via set_session_mode)
• /model <model> — change model (via set_session_model)
• /usage — show token usage / cost

3.3 Session Modes

Priority: LOW

Goose supports modes (e.g., "auto" vs "manual" approval). set_session_mode and CurrentModeUpdate notifications. Could expose via /mode command.

3.4 Session Configuration

Priority: LOW

set_config_option lets the client change boolean/select config options. ConfigOptionUpdate notifications report changes. Could expose via a /config command.

---

Phase 4: Rich Content

4.1 Image Support (Input)

Priority: MEDIUM

Signal users can send images. signal-cli provides attachment data. ACP supports ImageContentBlock in prompts (with base64 data and mime_type). We could forward Signal image attachments to Goose as image content blocks.

4.2 Image Support (Output)

Priority: LOW

If Goose responds with ImageContentBlock in agent messages, we could send them as Signal attachments. Less common but possible.

4.3 File/Resource Content

Priority: LOW

ResourceContentBlock and EmbeddedResourceContentBlock in agent messages. Could send file contents as Signal attachments or inline code blocks.

4.4 Audio Support

Priority: LOW

ACP has AudioContentBlock. Signal supports voice messages. Theoretically bridgeable but Goose doesn't currently use audio.

---

Phase 5: Advanced / Optional

5.1 Multi-User Concurrency

Priority: MEDIUM

Currently each contact gets their own session, and prompts run as async tasks. But there's no protection against a user sending a second message while the first is still processing. Options:

• Queue messages per-user (process sequentially)
• Allow concurrent prompts (may confuse Goose session state)
• Tell the user "please wait" if a prompt is in progress

5.2 Group Messaging

Priority: LOW

Signal groups could map to shared Goose sessions. Would need the account number (already in config) for group message handling. signal-cli has different envelope structure for group messages.

5.3 Extension Methods

Priority: LOW

ext_method and ext_notification are catch-alls for custom protocol extensions. Log them for now; implement specific ones if Goose uses them.

5.4 MCP Server Configuration

Priority: LOW

new_session accepts mcp_servers to connect external tool servers. Could be configured per-contact or globally in honker config.

---

Decisions Made

1. Terminal execution: Permission gate is enough. No additional sandboxing.
2. Tool call notifications: Light — send "🔧 Running: ..." on tool start. Goose already keeps extensive logs at ~/.local/state/goose/logs/.
3. Agent thoughts: Opt-in via config flag (forward_thoughts: true).
4. Cancellation UX: /cancel plus general /command prefix convention.
5. Multi-user concurrency: "Please wait" — reject concurrent prompts per user.
6. Image attachments: Yes, wire up in Phase 1.
7. Working directory: Global config option (working_directory).