comm-bridge

Files (68)

• SKILL.md
• init-db.sql
• package-lock.json
• package.json
• c4-checkpoint.md · references/
• c4-control.md · references/
• c4-db.md · references/
• c4-fetch.md · references/
• c4-receive.md · references/
• c4-send.md · references/
• hooks.md · references/
• c4-checkpoint-cli.test.js · scripts/__tests__/
• c4-config-runtime.test.js · scripts/__tests__/
• c4-control-cli.test.js · scripts/__tests__/
• c4-conversations-budget.test.js · scripts/__tests__/
• c4-db-checkpoint.test.js · scripts/__tests__/
• c4-db-cli.test.js · scripts/__tests__/
• c4-db-control.test.js · scripts/__tests__/
• c4-dispatcher-pure.test.js · scripts/__tests__/
• c4-fetch-cli.test.js · scripts/__tests__/
• c4-receive.test.js · scripts/__tests__/
• c4-send-cli.test.js · scripts/__tests__/
• c4-session-init-cli.test.js · scripts/__tests__/
• c4-utils-spill.test.js · scripts/__tests__/
• enter-capture.test.js · scripts/__tests__/
• first-failure-notice.test.js · scripts/__tests__/
• c4-v0.1.0.sql · scripts/__tests__/fixtures/migration-history/
• c4-v0.4.11.sql · scripts/__tests__/fixtures/migration-history/
• c4-v0.5.2.sql · scripts/__tests__/fixtures/migration-history/
• c4-v0.9.0-v1.sql · scripts/__tests__/fixtures/migration-history/
• provenance.json · scripts/__tests__/fixtures/migration-history/
• scheduler-v0.1.0.sql · scripts/__tests__/fixtures/migration-history/
• scheduler-v0.9.0-v1.sql · scripts/__tests__/fixtures/migration-history/
• web-console-v0.5.3.sql · scripts/__tests__/fixtures/migration-history/
• web-console-v0.9.0-v1.sql · scripts/__tests__/fixtures/migration-history/
• migration-chain.test.js · scripts/__tests__/
• periodic-enter.test.js · scripts/__tests__/
• runtime-process-identity.test.js · scripts/__tests__/
• session-delivery.test.js · scripts/__tests__/
• session-format.test.js · scripts/__tests__/
• sqlite-schema.test.js · scripts/__tests__/
• status-notice-templates.test.js · scripts/__tests__/
• status-notice.test.js · scripts/__tests__/
• c4-checkpoint.js · scripts/
• c4-config.js · scripts/
• c4-control.js · scripts/
• c4-db.js · scripts/
• c4-diagnostic.js · scripts/
• c4-dispatcher.js · scripts/
• c4-fetch.js · scripts/
• c4-migrations.js · scripts/
• c4-receive.js · scripts/
• c4-schema.js · scripts/
• c4-send.js · scripts/
• c4-session-init.js · scripts/
• c4-utils.js · scripts/
• c4-validate.js · scripts/
• first-failure-notice.js · scripts/
• periodic-enter.js · scripts/
• runtime-delivery.js · scripts/
• …and 8 more

SKILL.md (first lines)

# Communication Bridge (C4)

Central message hub - ALL communication with Claude goes through C4.

## Architecture

```
Web Console ──┐
Telegram    ───┼──► C4 Bridge ◄──► Claude
Lark        ───┘
```

## Components

| Script | Purpose | Reference |
|--------|---------|-----------|
| `c4-receive.js` | External → Claude (queue incoming messages) | [c4-receive](references/c4-receive.md) |
| `c4-send.js` | Claude → External (route outgoing messages) | [c4-send](references/c4-send.md) |
| `c4-control.js` | System control plane (heartbeat, maintenance) | [c4-control](references/c4-control.md) |
| `c4-dispatcher.js` | PM2 daemon: polls pending queue, delivers to tmux | — |
| `c4-session-init.js` | Hook (session start): context + Memory Sync trigger | [hooks](references/hooks.md) |
| `c4-fetch.js` | Fetch conversations by id range | [c4-fetch](references/c4-fetch.md) |
| `c4-db.js` | Database module and CLI for querying conversations and checkpoints | [c4-db](references/c4-db.md) |
| `c4-checkpoint.js` | Create/query checkpoints (sync boundaries) | [c4-checkpoint](references/c4-checkpoint.md) |

## Sending Messages

```bash
# Send to Telegram DM
cat <<'EOF' | node ~/zylos/.claude/skills/comm-bridge/scripts/c4-send.js telegram 8101553026
Hello! Quotes, $vars, **markdown** — all safe via stdin.
EOF

# Send to Lark group thread
cat <<'EOF' | node ~/zylos/.claude/skills/comm-bridge/scripts/c4-send.js lark "chat_xxx|type:group|root:msg_yyy"
Report ready.
EOF
```

Always pipe messages via stdin heredoc — never pass as CLI arguments. See [c4-send](references/c4-send.md) for full reference.
Treat the heredoc wrapper as fixed shell syntax: only the message body goes between the start line and the closing terminator line, and the terminator itself must never be copied into the actual outgoing message.

## Database

SQLite at `~/zylos/comm-bridge/c4.db`:
- `conversations`: All messages (in/out) with priority, status, retry tracking
- `checkpoints`: Recovery points with conversation id ranges
- `control_queue`: System control messages (heartbeat, maintenance) with priority, ack deadlines, and status lifecycle

## Health & Status

The activity monitor writes `~/zylos/activity-monitor/agent-status.json` which includes a `health` field:

| Value | Meaning |
|-------|---------|
| `ok` | System healthy, messages accepted normally |
| `recovering` | Legacy persisted liveness state; normalized to unavailable at runtime |
| `down` | Legacy persisted liveness state; normalized to unavailable at runtime |

**Fail-open semantics**: If the status file is missing or malformed, health is assumed `ok` — intake is never blocked by a read failure.

When health is not `ok`, `c4-receive.js` asks the activity monitor MessageRouter how to route the current message. Unhealthy messages are recorded as delivered and receive an immediate status reply when replies are enabled; `--no-reply` messages are accepted silently. If the MessageRouter IPC is unavailable, `c4-receive.js` falls back to the status file with the same delivered/current-message behavior.

## Keystroke Delivery

The dispatcher supports `[KEYSTROKE]` control messages for sending raw keystrokes to the tmux session. This is an **ops-level capability** — no source gating is applied.

When a control message content starts with `[KEYSTROKE]`, the dispatcher:
- Extracts the key name (e.g., `Enter`, `Tab`, `Escape`)
- Sends it directly via `tmux send-keys` (no buffer paste, no "Meanwhile" prefix, no verification)
- Auto-acks the control immediately after delivery

Example: the permission auto-approve hook enqueues `[KEYSTROKE]Enter` at priority 0 with bypass-state to auto-confirm Claude Code's permission prompts.

Any process with access to `c4-control.js` can enqueue keystroke controls. This mirrors the existing reality that any process can call `tmux send-keys` directly — the C4 queue adds priority ordering and delivery guarantees, not access control.

## Service Management

```bash
pm2 status c4-dispatcher
pm2 logs c4-dispatcher
pm2 restart c4-dispatcher
```

From zylos-ai/zylos-core, MIT.

More from zylos-ai/zylos-core