# Native Talk Integration

Talk AI can now receive bot invocations over Talk's **native in-process event**
(`OCA\Talk\Events\BotInvokeEvent`, Talk 21+) instead of the signed webhook.
Replies are posted by Talk itself after the invocation completes, so the app
never makes an HTTP request back into its own instance for the normal reply
path.

## How it works

- A listener (`lib/Listener/TalkNativeBotListener.php`) is registered for
  `BotInvokeEvent`. It only acts on invocations addressed to the shared Talk
  AI bot (matched by the registered bot URL) and routes them through the same
  pipeline as the webhook (`TalkHandler::handleMessage`).
- Replies are delivered through a `NativeEventResponseSink`, which queues
  answers on the event (`addAnswer()`). Talk posts them as bot-authored
  messages after the invocation completes.
- Because native events are posted only after the invocation finishes, the
  pipeline coalesces streaming partials into a single final reply for the
  native path (the webhook path still streams).
- The shared Talk bot is registered with the `event` feature flag (`4`). Talk
  requires this feature to be used alone; it dispatches the in-process event
  instead of posting to the webhook URL.

## Requirements

- Nextcloud Talk **21+** (the `BotInvokeEvent` class and the `event` feature
  flag). On older Talk the listener is a no-op and the webhook transport is
  used automatically.
- The shared Talk bot must be registered with the `event` feature. This happens
  automatically on app enable / settings save (see
  `TalkBotRegistrationService`), or manually with `occ` (below).

## Staging install

1. **Deploy the app** into the staging Nextcloud apps directory and build the
   frontend:

   ```bash
   cd /path/to/nextcloud/apps-extra
   git clone <your-repo> educai
   cd educai
   npm ci && npm run build
   ```

2. **Enable the app** (runs migrations + repair steps, which re-register the
   shared Talk bot with the `event` feature):

   ```bash
   sudo -u www-data php occ app:enable educai
   ```

3. **Configure** under **Administration settings → Talk AI**:
   - Primary API endpoint + API key (any OpenAI-compatible provider)
   - A default model (or allowed model list)
   - Webhook secret (`openssl rand -hex 32`)

   Saving the settings triggers bot registration.

4. **Verify the bot registration** has the `event` feature:

   ```bash
   sudo -u www-data php occ talk:bot:list
   ```

   You should see the `Talk AI` bot with `state = 1` and features
   `webhook, response, event`.

   If your environment blocks automatic registration, register manually:

   ```bash
   sudo -u www-data php occ talk:bot:uninstall "Talk AI"
   sudo -u www-data php occ talk:bot:install \
     -f event \
     "Talk AI" \
     "YOUR_WEBHOOK_SECRET" \
     "https://cloud.example.com/index.php/apps/educai/webhook/talk"
   ```

5. **Activate the bot in a Talk room** (conversation settings → "Talk AI" →
   activate), create a bot in the Talk AI app, and mention it.

## Confirming the native path is active

Watch the log while mentioning the bot:

```bash
tail -f /path/to/nextcloud/data/nextcloud.log | grep -i educai
```

A native invocation logs:

```
EducAI: Native Talk bot invocation received
Extracted Talk message data (room_token: "xxx", ...)
Bot detected (bot_id: 1, mention_name: @mybot)
Calling LLM API
```

and the reply appears as a bot-authored message **without** a
`Successfully sent reply to Talk` HTTP log line (that line is the webhook
transport). If you instead see `========== Talk AI Webhook Received ==========`
the invocation arrived over the webhook (e.g. the `event` flag is not set, or
Talk is older than 21).

## Notes / trade-offs

- **Synchronous processing.** Native events are dispatched within the request
  that sends the chat message, so the LLM call runs in that request's context.
  This is Talk's native behaviour; for very slow models the sender's request
  will wait. The webhook transport has the same characteristic (the webhook
  POST blocks until processing finishes).
- **No streaming over native.** Replies are coalesced to a single final
  message (Talk posts answers after the invocation completes). The webhook
  transport still streams partials.
- **Out-of-context replies** (rate-limit queue, test rooms) still use the
  signed Talk bot HTTP API, since no native event is in flight for those.
- **Rollback.** To revert to webhook-only, re-register the bot without the
  `event` flag:

  ```bash
  sudo -u www-data php occ talk:bot:uninstall "Talk AI"
  sudo -u www-data php occ talk:bot:install \
    -f webhook,response \
    "Talk AI" \
    "YOUR_WEBHOOK_SECRET" \
    "https://cloud.example.com/index.php/apps/educai/webhook/talk"
  ```