# Hermes LINE User Gateway via chatmux

A standalone Hermes platform plugin for a **personal LINE account**, backed by [chatmux](https://github.com/echoedinvoker/chatmux). Includes source, account-free tests, example configuration, and deployment documentation so another agent can review and adapt the integration.

> **Unofficial integration — account risk:** chatmux uses `@evex/linejs`, not the official LINE Messaging API. LINE may restrict or suspend the connected account. Use a dedicated account. If an official bot meets your needs, prefer the official API instead.

## Architecture

```text
LINE personal account
  ↕ unofficial LINE protocol / E2EE
chatmux LINE adapter (Node.js + tsx + linejs)
  ↕ stdio JSON-RPC
chatmux daemon (Bun, JSONL + SQLite/FTS5)
  ↕ MCP Streamable HTTP — numeric loopback only
this plugin (platform key: line_user)
  ├─ exact authorization / activation rules
  ├─ durable cursor + inbox + outbox
  ├─ optional native-mention / reply projection
  └─ Hermes session and profile routing
       ↕
Hermes agent / tools / memory
```

chatmux owns LINE login tokens, E2EE keys, reconnects, message storage, and actual network sends. This plugin does not log into LINE. Hermes's official Messaging API platform remains the separate `line` platform.

## What is included

- Observe-first configuration; outbound disabled by default.
- Exact DM/group allowlists, activation prefixes, and outbound target gates.
- Atomic event cursor/inbox persistence before agent dispatch.
- Read acknowledgement after durable acceptance, not after model completion.
- Durable outbound operations with **no blind retry after ambiguous sends**.
- Optional native group mentions and replies-to-agent triggers through a read-only chatmux SQLite projection.
- Named-profile routing for native-mention groups, with fail-closed profile checks.
- CLI diagnostics, inbox/outbox inspection, explicit cursor reset, and macOS LaunchAgent rendering.

## Important limits

- This is an experimental integration, not an official or universally compatible LINE connector.
- Native group handling depends on both chatmux's SQLite schema and Hermes internal APIs, including `gateway.run._profile_runtime_scope` and `agent.secret_scope`. Verify these on your Hermes checkout before activation; do not remove isolation checks to bypass incompatibility.
- Native-mention groups currently expose the fixed toolsets `web` and `memory`; this is not a configurable general-purpose group tool policy.
- chatmux's send API has no caller idempotency key / operation-status query. Exactly-once delivery is **not** promised; ambiguous sends require operator reconciliation.
- Static media/stickers are not supported as agent prompts. No native reply rendering, typing, or reaction support is promised.
- Adding chatmux as an MCP server alone does not provide automatic message-triggered agent runs. This plugin supplies that consumer loop for Hermes; other runtimes need their own consumer.
- Local message storage contains decrypted content. Loopback is a host-level trust boundary, not authentication against other local processes.

## Install from source

Prerequisites: a compatible Hermes installation, Git, Python 3.11–3.14, and separately installed chatmux with its Node/Bun dependencies. Review both projects before connecting an account.

```bash
git clone https://github.com/tardis7575/hermes-chatmux-line-gateway.git
cd hermes-chatmux-line-gateway

# Directory discovery: use the intended Hermes profile's plugins directory.
mkdir -p ~/.hermes/plugins
ln -s "$PWD" ~/.hermes/plugins/line_user-platform
hermes plugins list --plain --no-bundled
```

Do not install into multiple profile directories or change a running gateway unintentionally. Alternatively build a wheel with `uv build` and install it into the **same environment as Hermes**; a separate venv will not make the plugin discoverable to an existing Hermes process.

1. Review [account setup and live canaries](docs/live-acceptance.md).
2. Start chatmux interactively for the initial QR login; credentials stay in chatmux's protected data directory.
3. Copy the relevant settings from [examples/hermes.config.yaml](examples/hermes.config.yaml) into the intended profile. Begin in `observe` mode with sending disabled.
4. Discover exact IDs locally; never infer an ID from a display name.
5. Follow [install / activation / rollback](docs/install-rollback.md). Enable only after reviewing scope; restart only the intended gateway.
6. Prove one authorized DM and one group canary, then test restart, network loss, and ambiguous-send handling before relying on it.

No live account credentials, chat history, real chat IDs, or operator deployment reports are included. Fixtures use synthetic identities.

## For another agent runtime

Use chatmux's MCP tools directly: `read_events`, `list_chats`, `read_messages`, `get_status`, `send_message`, and `mark_read`. Discover live schemas with `tools/list` rather than assuming a fixed SDK signature.

Build a persistent consumer that:

1. Establishes the current event head on first use without replaying history.
2. Saves opaque cursors unchanged, atomically with accepted work.
3. Enforces allowlists and activation rules outside the LLM.
4. Serializes work per conversation and isolates sessions/memory.
5. Saves outbound intent before sending and holds ambiguous outcomes.
6. Coordinates sends across consumers sharing an account.

Native mention metadata is currently resolved from chatmux's local projection, not a portable MCP-only contract. See [architecture](docs/architecture.md) and [protocol](docs/protocol-contract.md).

## Development

```bash
uv sync --extra test
uv run python -m pytest -ra
uv build
```

Standalone tests do not require a LINE login. Tests requiring Hermes or a chatmux checkout must be explicitly provisioned; skipped integrations are **not** evidence of live delivery. See [compatibility and verification](docs/compatibility.md).

## Documentation

- [Architecture](docs/architecture.md)
- [Protocol contract](docs/protocol-contract.md)
- [Delivery semantics](docs/delivery-semantics.md)
- [Install and rollback](docs/install-rollback.md)
- [Live acceptance](docs/live-acceptance.md)
- [macOS operations](docs/macos-operations.md)
- [Troubleshooting](docs/troubleshooting.md)
- [Security](SECURITY.md)

MIT licensed. This repository contains the consumer/plugin, not a vendored copy of chatmux or linejs; those projects retain their respective licenses.