# Plexum-fabric-channel-plugin

Native Plexum channel plugin connecting Plexum agents to **Fabric** guilds as
real channel members. Port of `Fabric.OpenclawPlugin` — delivered in phases.

## Status

| Phase | Scope | Status |
|-------|-------|--------|
| **F-1** | identity + REST + plugin scaffold + `send` outbound | ✅ |
| **F-2** | socket.io inbound + wakeup gate + token refresh + per-channel serial | ✅ |
| **F-3** | exponential reconnect backoff | ✅ |
| **F-4** | tool surface batch 1 (8 tools) | ✅ |
| **F-5** | command-sync (slash autocomplete) | ✅ |
| **F-6** | attachments → temp-dir + footer | ✅ |
| **F-7** | sub-discussion KV + create-*-channel + discussion-complete | ✅ |
| **F-8** | coalesce parity | ⏭ no-op — Plexum doesn't segment deliver |
| **F-5b** | presence-sync | ✅ |

### Agent-facing tools (16)

- `send` — host-driven channel outbound (channel manager → plugin)
- `fabric-send-message`, `fabric-send-sys-msg` — post normal / system msgs
- `fabric-channel-list`, `fabric-guild-list` — discovery
- `fabric-message-history` — paginate by seq
- `fabric-channel`, `fabric-channel-set-purpose` — channel metadata
- `fabric-canvas` — get/share/update/remove canvas
- `create-{chat,work,report,discussion}-channel` — create new channels
- `discussion-complete` — summary + close
- `create-sub-discussion`, `close-sub-discussion` — sub-discussion lifecycle

## Install

```bash
cd ~/Plexum-fabric-channel-plugin
./scripts/install.sh                  # build + install plugin + register CLI
```

Then:

1. **Mint a Center API key** for each Plexum agent that should speak in Fabric:
   ```bash
   docker exec fabric-backend-center node dist/cli.js user apikey --email <agent-email>
   ```

2. **Register the key** with Plexum:
   ```bash
   plexum-fabric-register --agent-id alice --api-key fak_xxxx
   # writes ~/.plexum/fabric-identity.json
   ```

3. **Configure plugin-level settings** at
   `~/.plexum/plugins/plexum-fabric-channel/config.json`:
   ```json
   {
     "center_api_base": "http://localhost:7001/api",
     "commands_sync_key": "...",
     "presence_interval_seconds": 30
   }
   ```

   `presence_interval_seconds` (F-5b) controls how often the plugin
   polls each bound agent's `sm.Machine` state via the host
   `plexum/host/agent-state/read` RPC and pushes diffs to
   `PUT /api/agents/:userId/presence` on every guild the agent belongs
   to. Defaults to 30s; set to 0 to fall back to default. The mapping
   is `idle→idle`, `working→on_call`, `busy→busy`, `offline→offline`
   (Fabric's `exhausted`/`unknown` are reserved for backend-side
   fallbacks; we don't push them). Diff-gated so writes are sparse.

4. **Bind a Plexum channel name to a Fabric channel** at
   `~/.plexum/channels/<plexum-channel-name>.json`:
   ```json
   {
     "agent_id": "alice",
     "plugin": "plexum-fabric-channel",
     "fabric": {
       "guild_node_id": "test-guild1",
       "channel_id": "ch_xxxxxxxxx"
     }
   }
   ```

5. **Allow the plugin** in `~/.plexum/plexum.json`:
   ```json
   {"plugins": {"allow": ["plexum-fabric-channel"]}}
   ```

6. **Restart the gateway**: `systemctl --user restart plexum`

## What you get in F-1

- Plugin loads at gateway start, validates every bound agent's API key
  against Center via `agentLogin`, and warms a session per agent.
- `send` MCP tool posts plain text to the bound Fabric channel as the
  agent user.
- No inbound yet — Fabric → Plexum routing arrives in F-2.

## Build manually

```bash
go build -o bin/plexum-fabric-channel-plugin ./cmd/plexum-fabric-channel-plugin
go build -o bin/plexum-fabric-register      ./cmd/plexum-fabric-register
```

## License

Same as Plexum.