ha-opencode 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Stephen Golub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,315 @@
+# ha-opencode
+
+OpenCode plugin for Home Assistant integration via MQTT Discovery.
+
+Exposes OpenCode session state as Home Assistant entities and allows bidirectional control (responding to permission requests, sending prompts, viewing history).
+
+## 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
+
+## Installation
+
+### 1. Install the plugin
+
+```bash
+npm install --prefix ~/.config/opencode /path/to/ha-opencode
+```
+
+### 2. Add to OpenCode config
+
+Add `"ha-opencode"` to the `plugins` array in `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "plugins": ["ha-opencode"]
+}
+```
+
+### 3. Configure MQTT connection
+
+Via environment variables:
+
+```bash
+export MQTT_HOST=your-mqtt-broker.local
+export MQTT_PORT=1883
+export MQTT_USERNAME=optional-username
+export MQTT_PASSWORD=optional-password
+export 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
+
+Send commands to the `command_topic` (e.g., `opencode/opencode_46b09b89bffevq6HeMNIkuvk4B/command`):
+
+### Permission Response
+
+```json
+{
+  "command": "permission_response",
+  "permission_id": "perm-123",
+  "response": "once"
+}
+```
+
+Response options: `"once"`, `"always"`, or `"reject"`
+
+### Send Prompt
+
+```json
+{
+  "command": "prompt",
+  "text": "Your prompt text here",
+  "session_id": "optional-session-id"
+}
+```
+
+### Get History
+
+```json
+{
+  "command": "get_history",
+  "session_id": "optional-session-id",
+  "request_id": "optional-correlation-id"
+}
+```
+
+### Get History Since
+
+```json
+{
+  "command": "get_history_since",
+  "since": "2024-01-01T00:00:00Z",
+  "session_id": "optional-session-id",
+  "request_id": "optional-correlation-id"
+}
+```
+
+### Cleanup Stale Sessions
+
+```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"
+}
+```
+
+## 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.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build TypeScript
+npm run build
+
+# Watch mode
+npm run dev
+
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+```
+
+### Project Structure
+
+```
+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
+```
+
+## Troubleshooting
+
+### Too many entities in HA
+
+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.
+
+### Entity naming shows "Untitled"
+
+This is the initial name before session title is available. Once the session gets a proper title, the device name updates automatically.
+
+### Automation not triggering
+
+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.
+
+### Kitty notifications not working
+
+Ensure your terminal supports OSC 99 (Kitty, iTerm2) and that stdout is a TTY.
+
+## License
+
+MIT

package/blueprints/opencode_permission_response.yaml

@@ -0,0 +1,81 @@
+blueprint:
+  name: OpenCode Permission Response Handler
+  description: >
+    Handles approve/reject actions from OpenCode permission notifications.
+    
+    This blueprint listens for notification actions (button taps) and sends
+    the appropriate permission response via MQTT.
+    
+    Works with both iOS and Android via the Home Assistant Companion app.
+    
+    Use this together with the OpenCode State Notifications blueprint.
+  domain: automation
+  author: ha-opencode
+  source_url: https://github.com/your-repo/ha-opencode/blob/main/blueprints/opencode_permission_response.yaml
+  input: {}
+
+mode: parallel
+max_exceeded: silent
+
+trigger:
+  - platform: event
+    event_type: mobile_app_notification_action
+
+variables:
+  # Get the action string
+  action: "{{ trigger.event.data.action | default('') }}"
+  
+  # Check if this is an OpenCode action
+  is_opencode_action: >
+    {{ action.startswith('OPENCODE_APPROVE_') or action.startswith('OPENCODE_REJECT_') }}
+  
+  is_approve: "{{ action.startswith('OPENCODE_APPROVE_') }}"
+  response: "{{ 'once' if is_approve else 'reject' }}"
+  
+  # Get data passed from the notification
+  # iOS uses action_data, Android might use data directly
+  action_data: >
+    {% if trigger.event.data.action_data is defined %}
+      {{ trigger.event.data.action_data }}
+    {% elif trigger.event.data.data is defined %}
+      {{ trigger.event.data.data }}
+    {% else %}
+      {}
+    {% endif %}
+  
+  command_topic: "{{ action_data.command_topic | default('') }}"
+  permission_id: "{{ action_data.permission_id | default('') }}"
+  device_id: "{{ action_data.device_id | default('') }}"
+
+condition:
+  - condition: template
+    value_template: "{{ is_opencode_action }}"
+
+action:
+  # Log for debugging
+  - service: system_log.write
+    data:
+      message: >
+        OpenCode permission response: action={{ action }}, is_approve={{ is_approve }}, 
+        response={{ response }}, command_topic={{ command_topic }}, 
+        permission_id={{ permission_id }}, device_id={{ device_id }},
+        action_data={{ action_data }}
+      level: info
+      logger: ha-opencode.permission
+
+  # Check we have required data before publishing
+  - condition: template
+    value_template: "{{ command_topic != '' and permission_id != '' }}"
+
+  - service: mqtt.publish
+    data:
+      topic: "{{ command_topic }}"
+      payload: >
+        {"command": "permission_response", "permission_id": "{{ permission_id }}", "response": "{{ response }}"}
+
+  # Log success
+  - service: system_log.write
+    data:
+      message: "OpenCode permission {{ response }} sent for {{ permission_id }}"
+      level: info
+      logger: ha-opencode.permission

package/blueprints/opencode_state_notifications.yaml

@@ -0,0 +1,191 @@
+blueprint:
+  name: OpenCode State Notifications
+  description: >
+    Send notifications to your mobile device when OpenCode sessions need attention.
+    Notifies when:
+    - A task completes (idle after working)
+    - Permission is required (with approve/reject buttons)
+    - An error occurs
+    
+    Works with both iOS and Android via the Home Assistant Companion app.
+    
+    Requires the Permission Response Handler blueprint to handle approve/reject actions.
+  domain: automation
+  author: ha-opencode
+  source_url: https://github.com/your-repo/ha-opencode/blob/main/blueprints/opencode_state_notifications.yaml
+  input:
+    notify_service:
+      name: Notification Service
+      description: >
+        The notification service to use (e.g., notify.mobile_app_your_phone).
+      selector:
+        text:
+      default: "notify.mobile_app_phone"
+    
+    notify_on_complete:
+      name: Notify on Task Complete
+      description: Send a notification when a task completes (idle after working).
+      default: true
+      selector:
+        boolean:
+    
+    notify_on_permission:
+      name: Notify on Permission Required
+      description: Send a notification with approve/reject buttons when permission is needed.
+      default: true
+      selector:
+        boolean:
+    
+    notify_on_error:
+      name: Notify on Error
+      description: Send a notification when an error occurs.
+      default: true
+      selector:
+        boolean:
+    
+    notification_channel:
+      name: Notification Channel (Android)
+      description: >
+        Android notification channel name. 
+        You can create channels in the Companion app settings.
+      default: "OpenCode"
+      selector:
+        text:
+    
+    dashboard_path:
+      name: Dashboard Path
+      description: >
+        Path to your OpenCode dashboard for click action (e.g., /lovelace/opencode).
+        Leave empty to use default behavior.
+      default: "/lovelace/opencode"
+      selector:
+        text:
+
+mode: parallel
+max_exceeded: silent
+
+trigger:
+  - platform: mqtt
+    topic: "opencode/+/state"
+    id: state_change
+
+variables:
+  # The new state from the MQTT payload
+  new_state: "{{ trigger.payload }}"
+  
+  # Extract device_id from topic: opencode/{device_id}/state
+  device_id: "{{ trigger.topic.split('/')[1] }}"
+  
+  # Build the state_topic_base for entity lookup
+  state_topic_base: "opencode/{{ device_id }}"
+  
+  # Find the device_id entity that has this state_topic_base in its attributes
+  device_id_entity: >
+    {% set ns = namespace(found='') %}
+    {% for entity in states.sensor %}
+      {% if entity.attributes.get('state_topic_base', '') == state_topic_base %}
+        {% set ns.found = entity.entity_id %}
+      {% endif %}
+    {% endfor %}
+    {{ ns.found }}
+  
+  # Check if we found the entity
+  entity_found: "{{ device_id_entity != '' }}"
+  
+  # Derive other entity IDs from the device_id entity (they share the same base)
+  entity_base: "{{ device_id_entity | replace('_device_id', '') if entity_found else '' }}"
+  state_entity: "{{ (entity_base ~ '_state') if entity_found else '' }}"
+  session_entity: "{{ (entity_base ~ '_session_title') if entity_found else '' }}"
+  
+  # Get values from entities (with defaults)
+  previous_state: "{{ state_attr(state_entity, 'previous_state') | default('unknown') if entity_found else 'unknown' }}"
+  project_name: "{{ state_attr(device_id_entity, 'device_name') | default('OpenCode') if entity_found else 'OpenCode' }}"
+  command_topic: "{{ state_attr(device_id_entity, 'command_topic') | default('') if entity_found else '' }}"
+  permission_id: "{{ state_attr(state_entity, 'permission_id') | default('') if entity_found else '' }}"
+  permission_title: "{{ state_attr(state_entity, 'permission_title') | default('Permission needed') if entity_found else 'Permission needed' }}"
+  error_message: "{{ state_attr(state_entity, 'error_message') | default('An error occurred') if entity_found else 'An error occurred' }}"
+  session_title: "{{ states(session_entity) | default('Task finished') if entity_found else 'Task finished' }}"
+  
+  # Determine if this is a transition we care about
+  was_working: "{{ previous_state == 'working' }}"
+
+action:
+  # Log for debugging (can be removed later)
+  - service: system_log.write
+    data:
+      message: >
+        OpenCode notification trigger: new_state={{ new_state }}, previous_state={{ previous_state }}, 
+        device_id={{ device_id }}, entity_found={{ entity_found }}, was_working={{ was_working }}
+      level: info
+      logger: ha-opencode.blueprint
+
+  - choose:
+      # Permission Required (always notify, regardless of previous state)
+      - conditions:
+          - condition: template
+            value_template: "{{ new_state == 'waiting_permission' }}"
+          - condition: template
+            value_template: !input notify_on_permission
+        sequence:
+          # Small delay to let permission attributes arrive
+          - delay:
+              milliseconds: 500
+          - service: !input notify_service
+            data:
+              title: "OpenCode: Permission Required"
+              message: "{{ project_name }}: {{ permission_title }}"
+              data:
+                tag: "opencode-permission-{{ device_id }}"
+                channel: !input notification_channel
+                importance: high
+                priority: high
+                ttl: 0
+                clickAction: !input dashboard_path
+                url: !input dashboard_path
+                actions:
+                  - action: "OPENCODE_APPROVE_{{ device_id }}"
+                    title: "Approve"
+                  - action: "OPENCODE_REJECT_{{ device_id }}"
+                    title: "Reject"
+                # Pass data needed for permission response
+                action_data:
+                  device_id: "{{ device_id }}"
+                  permission_id: "{{ permission_id }}"
+                  command_topic: "{{ command_topic }}"
+
+      # Error Occurred (only after working)
+      - conditions:
+          - condition: template
+            value_template: "{{ new_state == 'error' and was_working }}"
+          - condition: template
+            value_template: !input notify_on_error
+        sequence:
+          - service: !input notify_service
+            data:
+              title: "OpenCode: Error"
+              message: "{{ project_name }}: {{ error_message }}"
+              data:
+                tag: "opencode-error-{{ device_id }}"
+                channel: !input notification_channel
+                importance: high
+                priority: high
+                ttl: 0
+                clickAction: !input dashboard_path
+                url: !input dashboard_path
+
+      # Work Complete (idle after working)
+      - conditions:
+          - condition: template
+            value_template: "{{ new_state == 'idle' and was_working }}"
+          - condition: template
+            value_template: !input notify_on_complete
+        sequence:
+          - service: !input notify_service
+            data:
+              title: "OpenCode: Task Complete"
+              message: "{{ project_name }}: {{ session_title }}"
+              data:
+                tag: "opencode-complete-{{ device_id }}"
+                channel: !input notification_channel
+                clickAction: !input dashboard_path
+                url: !input dashboard_path

package/dist/cleanup.d.ts

@@ -0,0 +1,30 @@
+import type { MqttWrapper } from "./mqtt.js";
+import type { HaConfig } from "./config.js";
+export interface CleanupConfig {
+    maxAgeDays: number;
+    haConfig: HaConfig;
+}
+export interface CleanupResult {
+    sessionsRemoved: number;
+    sessionIds: string[];
+}
+/**
+ * Clean up stale OpenCode sessions from Home Assistant.
+ * Removes entities for sessions that haven't been active in `maxAgeDays` days.
+ *
+ * @param mqtt - MQTT client wrapper
+ * @param config - Cleanup configuration
+ * @returns Result with count and IDs of removed sessions
+ */
+export declare function cleanupStaleSessions(mqtt: MqttWrapper, config: CleanupConfig): Promise<CleanupResult>;
+/**
+ * Manually trigger cleanup and publish results to MQTT.
+ * Called via the cleanup_stale_sessions command.
+ */
+export declare function cleanupStaleSessionsManual(mqtt: MqttWrapper, config: CleanupConfig): Promise<void>;
+/**
+ * Run cleanup in the background (non-blocking).
+ * Logs results but doesn't throw on error.
+ */
+export declare function runCleanupInBackground(mqtt: MqttWrapper, config: CleanupConfig): void;
+//# sourceMappingURL=cleanup.d.ts.map

package/dist/cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup.d.ts","sourceRoot":"","sources":["../src/cleanup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAG5C,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AA+ED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,aAAa,CAAC,CA8BxB;AAED;;;GAGG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,IAAI,CAAC,CAef;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,aAAa,GACpB,IAAI,CAYN"}