# Runbook: Nextcloud Talk Assistant Bridge

## Purpose

Operate the v1 bridge that lets Deeso chat with the assistant through Nextcloud Talk.

## Current Status

Prototype code exists in:

```text
services/nextcloud-talk-assistant/
```

Deployed on the Nextcloud VM as:

```text
nextcloud-talk-assistant.service
```

It is safe by default:

- one configured Talk conversation
- allowed sender list
- JSON state
- pending draft approval flow
- no shell/admin command execution
- approved captures/tickets/project notes append to `Assistant/capture.md` in the bridge account's Nextcloud Files
- approved reminders create VTODO items in the `assistant-reminders` calendar for the bridge account
- approved `pi ...`, `ask pi ...`, and `move forward with ...` requests append to `Assistant/pi-requests.md` for Pi/human follow-up

## Deploy Layout on Nextcloud VM

```text
/opt/nextcloud-talk-assistant/nextcloud_talk_assistant.py
/etc/nextcloud-talk-assistant/config.json
/etc/nextcloud-talk-assistant/env
/var/lib/nextcloud-talk-assistant/state.json
/var/log/nextcloud-talk-assistant/bridge.log
```

## Secrets

Do not store app passwords in this repo.

`/etc/nextcloud-talk-assistant/env`:

```sh
NEXTCLOUD_APP_PASSWORD='...'
```

## Current Deployment Facts

- Nextcloud VM: `piagent@192.168.0.110`
- Working SSH key from repo: `.ssh/piagent_homelab`
- Bridge account: `piagent`
- Assistant reminders calendar: `assistant-reminders`
- Approved capture file: `Assistant/capture.md`
- `piagent` is not a Nextcloud admin; it is in group `ops`
- Nextcloud Talk app: `spreed` 23.0.4
- Nextcloud version: 33.0.3
- Service status command:

```sh
sudo systemctl status nextcloud-talk-assistant
```

- Logs:

```sh
sudo journalctl -u nextcloud-talk-assistant -f
sudo tail -f /var/log/nextcloud-talk-assistant/bridge.log
```

## Initial Deployment Steps

1. Confirm SSH access to the Nextcloud VM.

```sh
for key in .ssh/piagent_homelab .ssh/piagent_nextcloud; do
  echo "Testing $key"
  ssh -o BatchMode=yes -o ConnectTimeout=5 -o StrictHostKeyChecking=accept-new \
    -o UserKnownHostsFile=.ssh/known_hosts -i "$key" \
    piagent@192.168.0.110 'echo SSH_OK && hostname && whoami && id' && break
done
```

2. Confirm whether `piagent` is privileged in Nextcloud.
3. If privileged, create a dedicated least-privilege Talk bot user.
4. Create an app password for the bridge account.
5. Identify the Talk room/conversation token.
6. Copy files from `services/nextcloud-talk-assistant/` to `/opt/nextcloud-talk-assistant/`.
7. Create `/etc/nextcloud-talk-assistant/config.json` from the example.
8. Run one-shot test:

```sh
export NEXTCLOUD_APP_PASSWORD='...'
python3 /opt/nextcloud-talk-assistant/nextcloud_talk_assistant.py \
  --config /etc/nextcloud-talk-assistant/config.json \
  --once
```

9. Install systemd unit after the one-shot test succeeds.

## Test Commands in Talk

```text
help
status
capture this is a test idea
summary
edit: this is an edited test idea
approve
pi move forward with the Nextcloud tasks setup
approve
remind test reminder tomorrow
discard
```

Voice note test:

```text
Remind me to test voice notes tomorrow
```

Expected response starts with `I heard: ...`, then shows the pending draft summary.

## Controlled Pi Request Pull

Approved Talk requests such as `pi ...` are queued in Nextcloud Files at:

```text
Assistant/pi-requests.md
```

From this repository, list queued requests without importing them:

```sh
scripts/nextcloud_pi_request_queue.py
```

Import new requests into `inbox/capture.md`:

```sh
scripts/nextcloud_pi_request_queue.py --import
```

Notes:
- The script uses SSH to the Nextcloud VM and the existing remote bridge config/env.
- Nextcloud secrets are not stored locally in this repo.
- Imported request IDs are tracked in `.tokens/nextcloud-pi-request-queue-state.json`, which is ignored by git.
- This is currently a controlled pull workflow, not an autonomous daemon.

## Stop / Rollback

```sh
sudo systemctl stop nextcloud-talk-assistant
sudo systemctl disable nextcloud-talk-assistant
```

Then revoke the app password in Nextcloud.

## Voice Notes / Whisper

Current status:

- `ffmpeg` is installed on the Nextcloud VM.
- `faster-whisper` is installed in `/opt/nextcloud-talk-assistant/venv`.
- The bridge runs with that venv Python.
- Whisper model cache is under `/var/lib/nextcloud-talk-assistant`.
- `tiny` model has been preloaded once.

Implementation status:

- The bridge now attempts best-effort detection of audio attachments in Talk message payloads.
- If an audio attachment is found, it downloads the audio and transcribes with local `faster-whisper` before normal command/intent handling.
- Needs real-world validation by sending a Talk voice message from the client.