ha-opencode 0.1.1 → 0.2.1

package/README.md

@@ -1,29 +1,44 @@
-# ha-opencode
+# OpenCode Home Assistant Plugin
 
-OpenCode plugin for Home Assistant integration via MQTT Discovery.
+[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://stephengolub.github.io/opencode-homeassistant)
+[![GitHub Release](https://img.shields.io/github/v/release/stephengolub/opencode-homeassistant)](https://github.com/stephengolub/opencode-homeassistant/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Exposes OpenCode session state as Home Assistant entities and allows bidirectional control (responding to permission requests, sending prompts, viewing history).
+OpenCode plugin that enables real-time integration with Home Assistant via native WebSocket connection.
+
+Monitor and control your OpenCode sessions directly from Home Assistant - get notified when tasks complete, approve permissions from your phone, and even send prompts remotely.
+
+**[Full Documentation](https://stephengolub.github.io/opencode-homeassistant)** | **[Home Assistant Integration](https://github.com/stephengolub/ha-opencode)**
 
 ## Features
 
-- **Session-Based Identity**: Each OpenCode session gets its own HA device and entities
-- **Real-time State Tracking**: Session state, model, current tool, tokens, and cost
-- **Permission Handling**: Approve/reject permission requests from HA or mobile notifications
-- **Send Prompts**: Send prompts to OpenCode sessions via MQTT
-- **Session History**: Retrieve conversation history on demand
-- **Agent Tracking**: Track primary agent and sub-agents being used
-- **Hostname Display**: Identify which machine the session is running on
-- **Automatic Cleanup**: Stale sessions (7+ days inactive) are automatically removed
+- **Native WebSocket**: Direct connection to Home Assistant - no MQTT broker required
+- **Secure Pairing**: Simple one-time pairing flow with secure token authentication
+- **Real-time Updates**: Instant session state, model, tool, token, and cost updates
+- **Permission Handling**: Approve/reject tool permissions from Home Assistant or mobile notifications
+- **Session History**: Retrieve full conversation history on demand
+- **Multi-session Support**: Each session gets its own device in Home Assistant
+- **Auto-reconnect**: Persistent connection with automatic reconnection
+
+## Requirements
+
+- [OpenCode](https://opencode.ai) AI coding assistant
+- [Home Assistant](https://www.home-assistant.io/) with the companion integration installed:
+  - **[ha-opencode](https://github.com/stephengolub/ha-opencode)** - Home Assistant integration (required)
 
 ## Installation
 
-### 1. Install the plugin
+### 1. Install the Plugin
 
 ```bash
-npm install --prefix ~/.config/opencode /path/to/ha-opencode
+# From npm (when published)
+npm install --prefix ~/.config/opencode ha-opencode
+
+# Or from local path
+npm install --prefix ~/.config/opencode /path/to/opencode-homeassistant
 ```
 
-### 2. Add to OpenCode config
+### 2. Add to OpenCode Config
 
 Add `"ha-opencode"` to the `plugins` array in `~/.config/opencode/opencode.json`:
 
@@ -33,223 +48,94 @@ Add `"ha-opencode"` to the `plugins` array in `~/.config/opencode/opencode.json`
 }
 ```
 
-### 3. Configure MQTT connection
-
-Via environment variables:
-
-```bash
-export OPENCODE_MQTT_HOST=your-mqtt-broker.local
-export OPENCODE_MQTT_PORT=1883
-export OPENCODE_MQTT_USERNAME=optional-username
-export OPENCODE_MQTT_PASSWORD=optional-password
-export OPENCODE_HA_DISCOVERY_PREFIX=homeassistant  # default
-```
-
-Or via `opencode.json`:
-
-```json
-{
-  "plugins": ["ha-opencode"],
-  "ha-opencode": {
-    "mqtt": {
-      "host": "your-mqtt-broker.local",
-      "port": 1883,
-      "username": "optional-username",
-      "password": "optional-password"
-    },
-    "ha": {
-      "discoveryPrefix": "homeassistant"
-    }
-  }
-}
-```
-
-Environment variables take precedence over JSON config.
-
-## Session-Based Identity
-
-Each OpenCode session creates a unique Home Assistant device:
-
-- **Session ID**: `ses_46b09b89bffevq6HeMNIkuvk4B` (generated by OpenCode)
-- **Device ID**: `opencode_46b09b89bffevq6HeMNIkuvk4B` (strips `ses_` prefix)
-- **Initial Name**: `OpenCode - {projectName} - Untitled`
-- **After Title**: `OpenCode - {projectName} - {sessionTitle}`
-
-This allows running multiple concurrent OpenCode sessions in the same directory, each with their own entities.
-
-## Entities Created
-
-Per OpenCode session (device), the following entities are created:
-
-| Entity | Type | Description |
-|--------|------|-------------|
-| `sensor.opencode_*_state` | Sensor | Session state (idle, working, waiting_permission, error) |
-| `sensor.opencode_*_session_title` | Sensor | Current session/conversation title |
-| `sensor.opencode_*_model` | Sensor | AI model being used (provider/model) |
-| `sensor.opencode_*_current_tool` | Sensor | Currently executing tool |
-| `sensor.opencode_*_tokens_input` | Sensor | Input token count |
-| `sensor.opencode_*_tokens_output` | Sensor | Output token count |
-| `sensor.opencode_*_cost` | Sensor | Session cost in USD |
-| `sensor.opencode_*_last_activity` | Sensor | Timestamp of last activity |
-| `sensor.opencode_*_permission` | Sensor | Permission request status |
-| `sensor.opencode_*_device_id` | Sensor | Device identifier with command/response topics |
-
-**Note**: The `*` in entity IDs represents the session ID (e.g., `sensor.opencode_46b09b89bffevq6HeMNIkuvk4B_state`).
-
-### State Entity Attributes
-
-The `state` entity includes these attributes:
-
-- `previous_state`: The state before the current one (for automation conditions)
-- `agent`: Primary agent selected by the user
-- `current_agent`: Sub-agent currently being used (if any)
-- `hostname`: Machine hostname where OpenCode is running
-- `error_message`: Error details when in error state
-
-### Device ID Entity Attributes
-
-The `device_id` entity includes:
-
-- `command_topic`: MQTT topic for sending commands
-- `response_topic`: MQTT topic for receiving responses
-- `state_topic_base`: Base topic for all state updates
-- `device_name`: Friendly device name
-- `session_id`: Full session ID (e.g., `ses_46b09b89bffevq6HeMNIkuvk4B`)
-- `project_name`: Project directory name
-
-## MQTT Topics
-
-For a session with ID `ses_46b09b89bffevq6HeMNIkuvk4B`:
-
-```
-# State topics
-opencode/opencode_46b09b89bffevq6HeMNIkuvk4B/state
-opencode/opencode_46b09b89bffevq6HeMNIkuvk4B/state/attributes
-opencode/opencode_46b09b89bffevq6HeMNIkuvk4B/session_title
-opencode/opencode_46b09b89bffevq6HeMNIkuvk4B/model
-opencode/opencode_46b09b89bffevq6HeMNIkuvk4B/availability
-
-# Commands & responses
-opencode/opencode_46b09b89bffevq6HeMNIkuvk4B/command
-opencode/opencode_46b09b89bffevq6HeMNIkuvk4B/response
-
-# HA Discovery
-homeassistant/sensor/opencode_46b09b89bffevq6HeMNIkuvk4B/state/config
-
-# Global cleanup response
-opencode/cleanup/response
-```
-
-## MQTT Commands
+### 3. Install the Home Assistant Integration
 
-Send commands to the `command_topic` (e.g., `opencode/opencode_46b09b89bffevq6HeMNIkuvk4B/command`):
+The plugin requires the companion Home Assistant integration. See [ha-opencode](https://github.com/stephengolub/ha-opencode) for installation instructions.
 
-### Permission Response
-
-```json
-{
-  "command": "permission_response",
-  "permission_id": "perm-123",
-  "response": "once"
-}
-```
+### 4. Pair with Home Assistant
 
-Response options: `"once"`, `"always"`, or `"reject"`
+1. In Home Assistant, go to Settings > Devices & Services
+2. Add the "OpenCode" integration
+3. A pairing code will be displayed (e.g., `ABC12DEF`)
+4. In OpenCode, use the `ha_pair` tool with:
+   - Your Home Assistant URL (e.g., `http://homeassistant.local:8123`)
+   - A [long-lived access token](https://www.home-assistant.io/docs/authentication/#your-account-profile)
+   - The pairing code
 
-### Send Prompt
+Once paired, the plugin will automatically reconnect on subsequent OpenCode sessions.
 
-```json
-{
-  "command": "prompt",
-  "text": "Your prompt text here",
-  "session_id": "optional-session-id"
-}
-```
+## Configuration
 
-### Get History
+The plugin stores connection configuration in `~/.config/opencode/ha-config.json` after pairing:
 
 ```json
 {
-  "command": "get_history",
-  "session_id": "optional-session-id",
-  "request_id": "optional-correlation-id"
+  "url": "ws://homeassistant.local:8123/api/websocket",
+  "accessToken": "your-access-token",
+  "instanceToken": "generated-during-pairing",
+  "instanceId": "instance_abc123"
 }
 ```
 
-### Get History Since
+You can also set the Home Assistant URL and access token via environment variables:
 
-```json
-{
-  "command": "get_history_since",
-  "since": "2024-01-01T00:00:00Z",
-  "session_id": "optional-session-id",
-  "request_id": "optional-correlation-id"
-}
+```bash
+export OPENCODE_HA_URL=http://homeassistant.local:8123
+export OPENCODE_HA_ACCESS_TOKEN=your-access-token
 ```
 
-### Cleanup Stale Sessions
+## How It Works
 
-```json
-{
-  "command": "cleanup_stale_sessions",
-  "max_age_days": 7
-}
 ```
-
-Response published to `opencode/cleanup/response`:
-
-```json
-{
-  "type": "cleanup_result",
-  "sessions_removed": 3,
-  "session_ids": ["opencode_abc123...", "opencode_def456..."],
-  "max_age_days": 7,
-  "timestamp": "2025-01-07T12:00:00Z"
-}
+┌─────────────────┐    WebSocket     ┌──────────────────┐
+│                 │◄────────────────►│                  │
+│    OpenCode     │                  │  Home Assistant  │
+│    + Plugin     │                  │  + Integration   │
+│                 │                  │                  │
+└─────────────────┘                  └──────────────────┘
+                                            │
+                                            ▼
+                                    ┌──────────────────┐
+                                    │  Lovelace Card   │
+                                    │  Mobile App      │
+                                    │  Automations     │
+                                    └──────────────────┘
 ```
 
-## Stale Session Cleanup
-
-Sessions that haven't been active for 7 days are automatically cleaned up:
-
-- **Automatic**: Runs on every plugin startup (async, non-blocking)
-- **Manual**: Send `cleanup_stale_sessions` command via MQTT
-
-Cleanup removes all HA entities for stale sessions by publishing empty configs to the discovery topics.
-
-## Home Assistant Blueprints
-
-Pre-built automation blueprints are available in the `blueprints/` directory:
-
-| Blueprint | Description |
-|-----------|-------------|
-| `opencode_state_notifications.yaml` | Mobile notifications for task complete, permission required, and errors |
-| `opencode_permission_response.yaml` | Handle approve/reject button taps from notifications |
-
-### Installing Blueprints
-
-1. Copy blueprints to your HA config:
-   ```bash
-   mkdir -p /path/to/ha/config/blueprints/automation/opencode
-   cp blueprints/*.yaml /path/to/ha/config/blueprints/automation/opencode/
-   ```
-
-2. Reload automations in HA (Developer Tools > YAML > Reload Automations)
-
-3. Create automations from blueprints:
-   - Settings > Automations > Create Automation > Use Blueprint
-   - Select the OpenCode blueprint
-   - Configure your mobile device and preferences
-
-See [ha-card/README.md](ha-card/README.md) for detailed blueprint configuration and automation examples.
-
-## Home Assistant Card
-
-A custom Lovelace card is included for displaying OpenCode sessions in Home Assistant.
-
-See [ha-card/README.md](ha-card/README.md) for installation and usage instructions.
-
-> **Note**: The card will be moved to a separate repository ([opencode-card](https://gitlab.com/opencode-home-assistant/opencode-card)) for HACS compatibility. The `ha-card/` directory is structured for easy extraction when that happens.
+1. **Plugin** connects to Home Assistant via WebSocket
+2. **Session updates** are sent in real-time (state, model, tokens, cost, permissions)
+3. **Commands** flow back from HA (send prompt, respond to permission, get history)
+4. **Events** are fired in HA for automations (state changes, permission requests)
+
+## Commands from Home Assistant
+
+The plugin responds to these commands sent via the Home Assistant integration:
+
+| Command | Description |
+|---------|-------------|
+| `send_prompt` | Send a text prompt to the current session |
+| `respond_permission` | Approve (once/always) or reject a permission request |
+| `get_history` | Retrieve session conversation history |
+| `get_agents` | Get list of available agents |
+
+## Session Data
+
+Each OpenCode session reports the following to Home Assistant:
+
+| Data | Description |
+|------|-------------|
+| `state` | Session state: `idle`, `working`, `waiting_permission`, `error` |
+| `title` | Session/conversation title |
+| `model` | AI model being used (e.g., `anthropic/claude-sonnet-4-20250514`) |
+| `current_tool` | Currently executing tool |
+| `tokens_input` | Total input tokens used |
+| `tokens_output` | Total output tokens used |
+| `cost` | Total session cost in USD |
+| `last_activity` | Timestamp of last activity |
+| `agent` | Primary agent selected |
+| `current_agent` | Sub-agent currently executing |
+| `hostname` | Machine hostname |
+| `permission` | Pending permission details (if any) |
 
 ## Development
 
@@ -274,41 +160,55 @@ npm run test:coverage
 
 ```
 src/
-  index.ts      Plugin entry point, defers setup until first session event
-  config.ts     Configuration loading (env vars + JSON)
-  mqtt.ts       MQTT client wrapper with wildcard support
-  discovery.ts  Session-based HA MQTT Discovery
-  state.ts      State tracking and publishing
-  commands.ts   MQTT command handler
-  cleanup.ts    Stale session cleanup
-  notify.ts     Terminal notification utilities (Kitty OSC 99)
-
-blueprints/
-  opencode_state_notifications.yaml    Mobile notification blueprint
-  opencode_permission_response.yaml    Permission action handler
-
-ha-card/
-  src/          Custom Lovelace card source
-  dist/         Built card JS
+  index.ts        Plugin entry point
+  websocket.ts    Home Assistant WebSocket client
+  state.ts        Session state tracking
+  commands.ts     Command handler (prompts, permissions, history)
+  ha-config.ts    Configuration storage
+  notify.ts       Terminal notifications (Kitty OSC 99)
+
+tests/
+  *.test.ts       Unit tests
 ```
 
 ## Troubleshooting
 
-### Too many entities in HA
+### Plugin not connecting
+
+1. Verify the Home Assistant integration is installed and configured
+2. Check that your access token is valid (test in Developer Tools > API)
+3. Look for connection errors in OpenCode output
+4. Try re-pairing: delete `~/.config/opencode/ha-config.json` and pair again
+
+### Permission responses not working
+
+1. Ensure the session is still active (not disconnected)
+2. Check Home Assistant logs for errors
+3. Verify the permission ID matches the pending permission
+
+### Notifications not appearing
 
-Each session creates a new set of entities. Use the cleanup command or rely on automatic cleanup to remove old sessions. Sessions inactive for 7+ days are automatically removed on plugin startup.
+This plugin uses Kitty terminal notifications (OSC 99). Supported terminals:
+- Kitty
+- iTerm2 (with notifications enabled)
 
-### Entity naming shows "Untitled"
+If your terminal doesn't support OSC 99, notifications will be silent.
 
-This is the initial name before session title is available. Once the session gets a proper title, the device name updates automatically.
+## Documentation
 
-### Automation not triggering
+Full documentation is available at **[stephengolub.github.io/opencode-homeassistant](https://stephengolub.github.io/opencode-homeassistant)**
 
-Check that `previous_state` attribute is available when state changes. Attributes are published BEFORE the state value to ensure they're available when automations trigger.
+- [Installation Guide](https://stephengolub.github.io/opencode-homeassistant/getting-started/installation/)
+- [Configuration](https://stephengolub.github.io/opencode-homeassistant/getting-started/configuration/)
+- [Pairing with Home Assistant](https://stephengolub.github.io/opencode-homeassistant/getting-started/pairing/)
+- [Session Tracking](https://stephengolub.github.io/opencode-homeassistant/features/session-tracking/)
+- [Commands](https://stephengolub.github.io/opencode-homeassistant/features/commands/)
+- [Permissions](https://stephengolub.github.io/opencode-homeassistant/features/permissions/)
 
-### Kitty notifications not working
+## Related Projects
 
-Ensure your terminal supports OSC 99 (Kitty, iTerm2) and that stdout is a TTY.
+- **[ha-opencode](https://github.com/stephengolub/ha-opencode)** - Home Assistant integration with Lovelace card and blueprints ([docs](https://stephengolub.github.io/ha-opencode))
+- **[OpenCode](https://opencode.ai)** - AI coding assistant
 
 ## License
 

package/dist/commands.d.ts

@@ -1,23 +1,25 @@
 import type { OpencodeClient } from "@opencode-ai/sdk";
-import type { MqttWrapper } from "./mqtt.js";
-import type { Discovery } from "./discovery.js";
+import type { HAWebSocketClient } from "./websocket.js";
 import type { StateTracker } from "./state.js";
-import type { HaConfig } from "./config.js";
 export declare class CommandHandler {
-    private readonly mqtt;
-    private readonly discovery;
+    private readonly wsClient;
     private readonly state;
     private readonly client;
-    private readonly haConfig;
-    constructor(mqtt: MqttWrapper, discovery: Discovery, state: StateTracker, client: OpencodeClient, haConfig: HaConfig);
-    start(): Promise<void>;
-    private handleMessage;
+    private readonly instanceToken;
+    constructor(wsClient: HAWebSocketClient, state: StateTracker, client: OpencodeClient, instanceToken: string);
+    /**
+     * Start listening for commands from Home Assistant.
+     */
+    start(): void;
+    private handleCommand;
     private processCommand;
-    private handleCleanup;
+    /**
+     * Handle state request from HA - send all current sessions.
+     */
+    private handleStateRequest;
     private handlePrompt;
     private handleGetAgents;
     private handleGetHistory;
-    private handleGetHistorySince;
     private fetchSessionHistory;
     private handlePermissionResponse;
 }

package/dist/commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AA2F5C,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAc;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;gBAGlC,IAAI,EAAE,WAAW,EACjB,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,QAAQ;IASd,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B,OAAO,CAAC,aAAa;YA4BP,cAAc;YAyBd,aAAa;YAkBb,YAAY;YAgCZ,eAAe;YA6Bf,gBAAgB;YA4BhB,qBAAqB;YAwCrB,mBAAmB;YAkFnB,wBAAwB;CA4CvC"}
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EACV,iBAAiB,EAMlB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAuB/C,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoB;IAC7C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;gBAGrC,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,cAAc,EACtB,aAAa,EAAE,MAAM;IAQvB;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb,OAAO,CAAC,aAAa;YAgBP,cAAc;IAgC5B;;OAEG;IACH,OAAO,CAAC,kBAAkB;YASZ,YAAY;YAuCZ,eAAe;YA6Bf,gBAAgB;YAqChB,mBAAmB;YA6FnB,wBAAwB;CAoDvC"}